Route Management

Centralized route management system for navigation, breadcrumbs, and page titles.

Overview

All application routes are centralized in $lib/routes.ts. This ensures:

• Type safety - Routes are typed constants, not magic strings

• Refactoring safety - Change a route once, updates everywhere

• IDE support - Autocomplete and "Find References" work correctly

• Consistency - Single source of truth for all navigation

Rule: Never use hardcoded route strings. Always import from $lib/routes.

Routes Constant

All routes are defined in the Routes object:

import { Routes } from '$lib/routes';

// Static routes
Routes.APP; // '/app'
Routes.APP_SETTINGS; // '/app/settings'
Routes.AUTH_LOGIN; // '/auth/login'
Routes.ADMIN_COMPLIANCE; // '/admin/compliance'

Route Categories

Category	Example Routes	Description
Auth	AUTH_LOGIN, AUTH_LOGOUT	Authentication flows
App	APP_SURVEYS, APP_ALERTS	Main application pages
App Settings	APP_SETTINGS_*	User/org settings
Admin	ADMIN_*	Platform admin pages
Onboarding	ONBOARDING_*	Tenant setup flow
API	API_SET_ACTIVE_TENANT	Internal API endpoints

Navigation

Using goto()

For client-side navigation:

import { goto } from '$app/navigation';
import { Routes, buildRoute } from '$lib/routes';

// Static route
goto(Routes.APP_SURVEYS);

// Dynamic route with ID
goto(buildRoute(Routes.APP_SURVEYS, surveyId));

// Route with query parameters
goto(buildRoute(Routes.APP_INTEGRATIONS, { query: { success: 'hibob' } }));

Using redirect()

For server-side redirects in +page.server.ts or +server.ts:

import { redirect } from '@sveltejs/kit';
import { Routes, buildRoute } from '$lib/routes';

// In load function
export const load = async ({ locals }) => {
	if (!locals.user) {
		redirect(302, Routes.AUTH_LOGIN);
	}
};

// With dynamic segment
redirect(302, buildRoute(Routes.APP_SURVEYS, surveyId));

Using <a> Tags

For declarative navigation in templates:

<script>
	import { Routes, buildRoute } from '$lib/routes';
</script>

<!-- Static route -->
<a href={Routes.APP_SETTINGS}>Settings</a>

<!-- Dynamic route -->
<a href={buildRoute(Routes.APP_SURVEYS, survey.id)}>
	{survey.name}
</a>

Building Routes

The buildRoute() function constructs URLs with path segments and query parameters.

Syntax

buildRoute(base: string, options?: string | RouteOptions): string

interface RouteOptions {
  path?: string | string[];           // Path segment(s) to append
  query?: Record<string, QueryValue>; // Query parameters
}

Examples

import { Routes, buildRoute } from '$lib/routes';

// Just base route
buildRoute(Routes.APP_ALERTS);
// => '/app/alerts'

// With path segment (shorthand)
buildRoute(Routes.APP_ALERTS, '123');
// => '/app/alerts/123'

// With path segment (explicit)
buildRoute(Routes.APP_ALERTS, { path: '123' });
// => '/app/alerts/123'

// With multiple path segments
buildRoute(Routes.APP_SETTINGS, { path: ['teams', 'engineering'] });
// => '/app/settings/teams/engineering'

// With query parameters only
buildRoute(Routes.APP_INTEGRATIONS, { query: { success: 'hibob', id: '456' } });
// => '/app/integrations?success=hibob&id=456'

// Combined path and query
buildRoute(Routes.APP_ALERTS, { path: '123', query: { tab: 'details' } });
// => '/app/alerts/123?tab=details'

Path Encoding

Path segments are automatically URL-encoded:

buildRoute(Routes.APP_SURVEYS, 'Survey Name With Spaces');
// => '/app/surveys/Survey%20Name%20With%20Spaces'

Breadcrumbs

The breadcrumb system automatically generates navigation breadcrumbs from the current URL.

How It Works

1. Route Configuration - Each route has metadata (label, detailLabel) in RouteConfig

2. URL Parsing - buildBreadcrumbs() parses the pathname into segments

3. Label Resolution - Each segment is matched to its configuration

4. Dynamic Segments - Unknown segments use the parent's detailLabel

Route Configuration

// In $lib/routes.ts
export const RouteConfig: Record<string, RouteMetadata> = {
	[Routes.APP_SURVEYS]: {
		label: 'Surveys', // Breadcrumb label for /app/surveys
		detailLabel: 'Survey Details' // Label for /app/surveys/:id
	},
	[Routes.APP]: {
		label: 'App',
		hiddenFromBreadcrumb: true // Don't show in breadcrumb trail
	}
};

Generated Breadcrumbs

For URL /app/compliance/frameworks/abc123:

Compliance > Frameworks > Framework Details

Page Labels

Pages can set custom labels for dynamic breadcrumb segments using the breadcrumb context.

Setting a Page Label

<script lang="ts">
	import { useBreadcrumbs } from '$lib/stores/breadcrumb.svelte';

	const { data } = $props();
	const { setPageLabel } = useBreadcrumbs();

	// Set custom breadcrumb label when data loads
	$effect(() => {
		if (data.framework) {
			setPageLabel(data.framework.name); // Shows "SOC 2 Type II" instead of "Framework Details"
		}
	});
</script>

Using the Helper Hook

For simpler cases, use the usePageLabel hook:

<script lang="ts">
	import { usePageLabel } from '$lib/stores/breadcrumb.svelte';

	const { data } = $props();

	// Automatically updates when data changes
	usePageLabel(() => data.framework?.name ?? null);
</script>

Setting a Custom Page Title

Override the auto-generated document title:

<script lang="ts">
	import { useBreadcrumbs } from '$lib/stores/breadcrumb.svelte';

	const { setCustomTitle } = useBreadcrumbs();

	$effect(() => {
		setCustomTitle('Custom Dashboard Title | Refresh');
	});
</script>

Breadcrumb Context API

Method	Description
setPageLabel(label)	Set custom label for current page's breadcrumb
setCustomTitle(title)	Override the auto-generated page title
reset()	Clear all custom overrides
breadcrumbs	Current breadcrumb array (reactive)
pageTitle	Current page title (reactive)

Page Titles

Page titles are automatically generated from breadcrumbs:

Framework Details | Frameworks | Compliance | Refresh

The title is built by:

1. Taking the breadcrumb labels in reverse order (most specific first)

2. Appending the app name ("Refresh")

3. Joining with " | "

Automatic Title Sync

The layout calls useSyncDocumentTitle() to keep document.title in sync:

<!-- In +layout.svelte -->
<script lang="ts">
	import { createBreadcrumbContext, useSyncDocumentTitle } from '$lib/stores/breadcrumb.svelte';

	// Create context (required in layout)
	createBreadcrumbContext();

	// Sync document.title with breadcrumbs
	useSyncDocumentTitle();
</script>

Adding New Routes

When adding a new route:

1. Add Route Constant

// In $lib/routes.ts
export const Routes = {
	// ... existing routes
	APP_NEW_FEATURE: '/app/new-feature'
} as const;

2. Add Route Configuration (for breadcrumbs)

// In $lib/routes.ts
export const RouteConfig: Record<string, RouteMetadata> = {
	// ... existing config
	[Routes.APP_NEW_FEATURE]: {
		label: 'New Feature',
		detailLabel: 'Feature Details' // If route has dynamic children
	}
};

3. Use the Route

// Navigation
goto(Routes.APP_NEW_FEATURE);

// Links
<a href={Routes.APP_NEW_FEATURE}>New Feature</a>

// Dynamic
goto(buildRoute(Routes.APP_NEW_FEATURE, itemId));

Best Practices

Do

// Always import Routes
import { Routes, buildRoute } from '$lib/routes';

// Use constants for navigation
goto(Routes.APP_SURVEYS);

// Use buildRoute for dynamic paths
goto(buildRoute(Routes.APP_SURVEYS, surveyId));

// Set page labels for better UX
$effect(() => {
	if (data.item) {
		setPageLabel(data.item.name);
	}
});

Don't

// Never hardcode routes
goto('/app/surveys'); // Bad
goto(`/app/surveys/${id}`); // Bad

// Never use string concatenation
const url = Routes.APP_SURVEYS + '/' + id; // Bad

// Don't forget to handle null/undefined in page labels
setPageLabel(data.item.name); // May be undefined - handle it

Troubleshooting

Breadcrumb Not Updating

If setPageLabel() doesn't update the breadcrumb:

1. Check context exists - Ensure the layout calls createBreadcrumbContext()

2. Use $effect - Labels must be set in a reactive context

3. Check data loading - The label may be set before data loads

<!-- Correct pattern -->
$effect(() => {
  if (data.item) {  // Guard against undefined
    setPageLabel(data.item.name);
  }
});

Route Not Found

If a route constant doesn't exist:

1. Add it to Routes in $lib/routes.ts

2. Add configuration to RouteConfig for breadcrumb support

Related Documentation

• Code Standards - Naming conventions and TypeScript patterns

• SvelteKit Architecture - How routing fits into the app

---

Last updated: December 2024