trailingSlash option values
The trailingSlash option can be one of 'never' (the default), 'always', or 'ignore'. By default, SvelteKit will remove trailing slashes from URLs — if you visit /about/, it will respond with a redirect to /about.
Svelte · SvelteKit · all subjects
routing
150 notes in this subject, read out of this brain and free to use. This is page 2 of 3.
trailingSlash can be set in layouts and server routes
The trailingSlash option can be exported from +layout.js, +layout.server.js, or +server.js files and will apply to all child pages.
Page options can be exported from layout and page files
Page options can be exported from +page.js, +page.server.js, +layout.js, or +layout.server.js files. To define an option for the whole app, export it from the root layout. Child layouts and pages override values set in parent layouts.
Layout groups with parentheses
Route groups are directories with names wrapped in parentheses, like (app) or (marketing). They do not affect the URL pathname, only the layout hierarchy. Routes inside (app) and (marketing) can have different layouts while living in different directory structures. You can also place a +page directly inside a group.
Breaking out of layout hierarchy
The root layout applies to all pages by default (rendering as {render children()} if omitted). To exclude certain routes from inheriting layouts, place them outside any layout groups. For example, in a structure with (app), (marketing), and admin groups, the /admin route does not inherit from (app) or (marketing) layouts.
+page@ syntax for breaking out of layouts
A page can break out of its current layout hierarchy using the +page@[segment] syntax. The segment can be a named route segment, a group name in parentheses, or empty string for root. Options for +page@[id].svelte, +page@item.svelte, +page@(app).svelte, and +page@.svelte reset to different layout levels. For example, +page@(app).svelte inherits only from the (app) layout and above.
+layout@ syntax for breaking out of parent layouts
Layouts can break out of their parent layout hierarchy using the same @[segment] technique as pages. A +layout@.svelte resets the hierarchy for all its child routes. This allows a layout to inherit only from the root layout, skipping intermediate parent layouts.
Accessing error object in +error.svelte template
In SvelteKit 2.12 and later with Svelte 5, access the error object in +error.svelte using $props(): let { error } = $props(); then use error.message or other properties. In SvelteKit versions before 2.12 or when using Svelte 4, use $app/stores instead of $app/state.
data-sveltekit-replacestate attribute effect
Adding a data-sveltekit-replacestate attribute to a link replaces the current history entry rather than creating a new one with pushState when the link is clicked.
data-sveltekit-preload-data attribute values
The data-sveltekit-preload-data attribute controls when SvelteKit preloads a page's data. It accepts two values: 'hover' means preloading starts when the mouse rests over a link on desktop or on touchstart on mobile; 'tap' means preloading starts on touchstart or mousedown events. The default template applies data-sveltekit-preload-data='hover' to the body element in src/app.html, enabling preloading on hover for all links by default.
data-sveltekit-preload-data saveData behavior
Data will never be preloaded if the user has chosen reduced data usage, meaning navigator.connection.saveData is true.
data-sveltekit-preload-code attribute values
The data-sveltekit-preload-code attribute controls when SvelteKit preloads a page's code. It accepts four values in decreasing eagerness: 'eager' means links are preloaded immediately; 'viewport' means links are preloaded once they enter the viewport; 'hover' preloads only code when hovering over a link; 'tap' preloads only code on tap or click. The viewport and eager values only apply to links present in the DOM immediately after navigation; links added later will not be preloaded until triggered by hover or tap.
data-sveltekit-preload-code priority over preload-data
The data-sveltekit-preload-code attribute only has an effect if it specifies a more eager value than any data-sveltekit-preload-data attribute present, since code preloading is a prerequisite for data preloading.
data-sveltekit-preload-code saveData behavior
The data-sveltekit-preload-code attribute will be ignored if the user has chosen reduced data usage, meaning navigator.connection.saveData is true.
data-sveltekit-reload attribute effect
Adding a data-sveltekit-reload attribute to a link causes a full-page navigation when the link is clicked instead of SvelteKit handling the navigation. Links with a rel='external' attribute receive the same treatment and are also ignored during prerendering.
data-sveltekit-keepfocus attribute effect
Adding a data-sveltekit-keepfocus attribute to a form or link causes the currently focused element to retain focus after navigation. This is useful for forms that submit as the user is typing. It should be avoided on links in general and only used on elements that still exist after navigation, as losing focus can create a confusing experience for assistive technology users.
data-sveltekit-noscroll attribute effect
Adding a data-sveltekit-noscroll attribute to a link prevents scrolling after the link is clicked. By default, SvelteKit mirrors the browser's default navigation behaviour by changing scroll position to 0,0 (unless the link includes a hash, in which case it scrolls to the matching element ID).
Disabling data-sveltekit-* attributes
Any data-sveltekit-* attribute can be disabled inside an element where it has been enabled by using the 'false' value. For example, data-sveltekit-preload-data='false' disables preloading within that element. Attributes can also be applied conditionally using Svelte syntax like data-sveltekit-preload-data={condition ? 'hover' : false}.
Link options apply to GET form elements
The data-sveltekit-* link options also apply to form elements with method='GET'.
Preload data via preloadData function
Data preloading can be invoked programmatically using the preloadData function from $app/navigation.
page.state legacy usage in SvelteKit 2.11 and earlier
In SvelteKit 2.11 and earlier, or when using Svelte 4, use $page.state from $app/stores instead of page.state from $app/state. The page.state from $app/state was added in SvelteKit 2.12.
Shallow routing with pushState
SvelteKit provides the pushState function from $app/navigation to create history entries without navigating. The first argument is the URL relative to the current URL (use empty string to stay on current URL), and the second argument is the new page state object. The page state can be accessed via page.state from $app/state and can be made type-safe by declaring an App.PageState interface in src/app.d.ts.
replaceState for shallow routing without history entry
The replaceState function from $app/navigation sets page state without creating a new history entry, unlike pushState which creates a new history entry.
preloadData for shallow routing modal patterns
The preloadData function from $app/navigation can be used inside click handlers to load data for another route without navigating. If the element or parent uses data-sveltekit-preload-data, the data will already be requested and preloadData will reuse that request. The function returns a result object with type and status properties; when type is 'loaded' and status is 200, the data is available in result.data.
History-driven modal example
To implement a history-driven modal using shallow routing, use pushState to create a history entry with modal state, then conditionally render the modal based on page.state. The modal can be dismissed by calling history.back() which will unset page.state.
page.state during server-side rendering and initial page load
During server-side rendering, page.state is always an empty object. The same is true for the first page the user lands on. If the user reloads the page or returns from another document, state will not be applied until they navigate.
Shallow routing requires JavaScript
Shallow routing is a feature that requires JavaScript to work. When using shallow routing, consider sensible fallback behavior for cases where JavaScript is not available.
goto() state parameter affects $page.state
In SvelteKit 2, the state object passed to goto() determines $page.state and must adhere to the App.PageState interface if declared.
goto() no longer accepts external URLs
In SvelteKit 2, the goto() function no longer accepts external URLs. To navigate to an external URL, use window.location.href = url instead.
resolvePath removed, replaced with resolveRoute in v2
SvelteKit 2 replaces resolvePath with resolveRoute, which is imported from $app/paths. resolveRoute takes base into account when resolving route IDs and parameters to pathnames, unlike the old resolvePath function.
Link attribute name changes
sapper:prefetch is now data-sveltekit-preload-data. sapper:noscroll is now data-sveltekit-noscroll.
Layout segment prop removed
Previously, layout components received a segment prop indicating the child segment. This has been removed. Use the more flexible $page.url.pathname or page.url.pathname to derive the segment you're interested in.
Relative URLs resolved against current page
In Sapper, relative URLs were resolved against the base URL. In SvelteKit, relative URLs are resolved against the current page or the destination page for fetch URLs in load functions. It is easier to use root-relative URLs starting with /.
Client-side routing in SvelteKit
By default, when you navigate to a new page (by clicking on a link or using the browser's forward or back buttons), SvelteKit will intercept the attempted navigation and handle it instead of allowing the browser to send a request to the server. SvelteKit will update the displayed contents on the client by rendering the component for the new page, which can make calls to necessary API endpoints. This process is called client-side routing. Client-side routing is used by default in SvelteKit, but can be skipped with the `data-sveltekit-reload` attribute.
dev export from $app/env
The dev export from $app/env is a boolean that indicates whether the dev server is running. It is not guaranteed to correspond to NODE_ENV or MODE. Type: const dev: boolean;
$app/env is an alias
$app/env is an alias of $app/environment, used when explicit environment variables are enabled.
browser export from $app/env
The browser export from $app/env is a boolean that is true if the app is running in the browser. Type: const browser: boolean;
building export from $app/env
The building export from $app/env is a boolean that is true when SvelteKit analyzes your app during the build step by running it. This also applies during prerendering. Type: const building: boolean;
version export from $app/env
The version export from $app/env is a string that contains the value of config.kit.version.name. Type: const version: string;
replaceState function for shallow routing
replaceState() programmatically replaces the current history entry with the given page.state, used for shallow routing. Pass an empty string '' as the first argument to use the current URL. Signature: function replaceState(url: string | URL, state: App.PageState): void;
afterNavigate lifecycle function
afterNavigate is a lifecycle function that runs the supplied callback when the current component mounts and also whenever navigation to a URL occurs. It must be called during component initialization and remains active as long as the component is mounted. Signature: function afterNavigate(callback: (navigation: import('@sveltejs/kit').AfterNavigate) => void): void;
beforeNavigate navigation interceptor
beforeNavigate is a navigation interceptor that triggers before navigating to a URL via link clicking, goto() calls, or browser back/forward controls. Calling cancel() prevents the navigation. For 'leave' navigations where the user closes the tab, cancel() triggers a native browser unload confirmation dialog. When navigation is not to a SvelteKit-owned route, navigation.to.route.id will be null. For unload navigations and link navigations where navigation.to.route is null, navigation.willUnload is true. Must be called during component initialization and remains active while the component is mounted. Signature: function beforeNavigate(callback: (navigation: import('@sveltejs/kit').BeforeNavigate) => void): void;
disableScrollHandling function
disableScrollHandling() disables SvelteKit's built-in scroll handling when called during page updates following navigation, such as in onMount, afterNavigate, or an action. This is generally discouraged as it breaks user expectations. Signature: function disableScrollHandling(): void;
goto programmatic navigation function
goto() allows programmatic navigation to a given route. It returns a Promise that resolves when SvelteKit navigates to the specified URL or rejects if navigation fails. For external URLs, use window.location = url instead. Options parameter accepts: replaceState (boolean), noScroll (boolean), keepFocus (boolean), invalidateAll (boolean), invalidate (array of string | URL | function), and state (App.PageState). Signature: function goto(url: string | URL, opts?: { replaceState?: boolean | undefined; noScroll?: boolean | undefined; keepFocus?: boolean | undefined; invalidateAll?: boolean | undefined; invalidate?: (string | URL | ((url: URL) => boolean))[] | undefined; state?: App.PageState | undefined; }): Promise<void>;
invalidate function for load dependencies
invalidate() causes any load functions belonging to the currently active page to re-run if they depend on the given URL via fetch or depends. It returns a Promise that resolves when the page is subsequently updated. The argument can be a string or URL that must resolve to the same URL passed to fetch or depends (including query parameters), or a function that receives the full URL and returns true to rerun load. Custom identifiers can be created using strings beginning with [a-z]+: pattern (e.g., 'custom:state'). Example: invalidate((url) => url.pathname === '/path') matches paths regardless of query parameters. Signature: function invalidate(resource: string | URL | ((url: URL) => boolean)): Promise<void>;
invalidateAll function
invalidateAll() causes all load and query functions belonging to the currently active page to re-run. It returns a Promise that resolves when the page is subsequently updated. Signature: function invalidateAll(): Promise<void>;
onNavigate lifecycle function
onNavigate is a lifecycle function that runs the supplied callback immediately before navigating to a new URL, except during full-page navigations. If a Promise is returned, SvelteKit waits for it to resolve before completing navigation, allowing use cases like document.startViewTransition. Avoid slow-resolving promises as navigation appears stalled. If a function (or a Promise that resolves to a function) is returned, it will be called once the DOM has updated. Must be called during component initialization and remains active while the component is mounted. Signature: function onNavigate(callback: (navigation: import('@sveltejs/kit').OnNavigate) => MaybePromise<(() => void) | void>): void;
preloadCode function
preloadCode() programmatically imports the code for routes that haven't yet been fetched, typically to speed up subsequent navigation. Routes can be specified by pathname pattern such as '/about' (matching src/routes/about/+page.svelte) or '/blog/*' (matching src/routes/blog/[slug]/+page.svelte). Unlike preloadData, this does not call load functions. Returns a Promise that resolves when the modules have been imported. Signature: function preloadCode(pathname: string): Promise<void>;
preloadData function
preloadData() programmatically preloads a page by ensuring the page's code is loaded and calling the page's load function. This matches SvelteKit's behavior when users tap or hover over <a> elements with data-sveltekit-preload-data attribute. If the next navigation is to the preloaded href, the load function values are used, making navigation instantaneous. Returns a Promise resolving to either: { type: 'loaded'; status: number; data: Record<string, any>; } or { type: 'redirect'; location: string; }. Signature: function preloadData(href: string): Promise<{ type: 'loaded'; status: number; data: Record<string, any>; } | { type: 'redirect'; location: string; }>;
pushState function for shallow routing
pushState() programmatically creates a new history entry with the given page.state, used for shallow routing. Pass an empty string '' as the first argument to use the current URL. Signature: function pushState(url: string | URL, state: App.PageState): void;
refreshAll function
refreshAll() causes all currently active remote functions to refresh and all load functions belonging to the currently active page to re-run unless disabled via the options argument. Returns a Promise that resolves when the page is subsequently updated. The optional parameter is { includeLoadFunctions?: boolean; }. Signature: function refreshAll({ includeLoadFunctions }?: { includeLoadFunctions?: boolean; }): Promise<void>;
$app/navigation exports
The $app/navigation module exports the following functions: afterNavigate, beforeNavigate, disableScrollHandling, goto, invalidate, invalidateAll, onNavigate, preloadCode, preloadData, pushState, refreshAll, and replaceState.
resolveRoute function deprecated, use resolve
The resolveRoute function is deprecated and should be replaced with the resolve() function. The function signature is: function resolveRoute<T extends RouteIdWithSearchOrHash | PathnameWithSearchOrHash>(...args: ResolveArgs<T>): ResolvedPathname.
match function matches path to route and extracts parameters
The match function matches a path or URL to a route ID and extracts any parameters. The function signature is: function match(url: Pathname | URL | (string & {})): Promise<{ id: RouteId; params: Record<string, string>; } | null>. It returns a promise that resolves to an object with id (RouteId) and params (Record<string, string>) or null if no match is found. Available since version 2.52.0.
resolve function for pathname and route ID resolution
The resolve function resolves a pathname by prefixing it with the base path, if any, or resolves a route ID by populating dynamic segments with parameters. During server rendering, the base path is relative and depends on the page being rendered. The function signature is: function resolve<T extends RouteIdWithSearchOrHash | PathnameWithSearchOrHash>(...args: ResolveArgs<T>): ResolvedPathname. Available since version 2.26.
ServerLoad generic type signature
ServerLoad type has signature type ServerLoad<Params = AppLayoutParams<'/'>, ParentData = Record<string, any>, OutputData = Record<string, any> | void, RouteId = AppRouteId | null> = (event: ServerLoadEvent<Params, ParentData, RouteId>) => MaybePromise<OutputData>. Should import PageServerLoad and LayoutServerLoad from ./$types instead of using directly.
ServerLoadEvent parent method
ServerLoadEvent has parent(): Promise<ParentData> method that returns data from parent +layout.server.js load functions. Be careful not to introduce waterfalls - call after fetching other data if only merging parent data.
ServerLoadEvent depends method
ServerLoadEvent has depends(...deps: string[]): void method declaring the load function has dependencies on URLs or custom identifiers. URLs can be absolute or relative (must be percent-encoded). Custom identifiers must be prefixed with lowercase letters and colon (URI spec conformant). Used with invalidate() to cause load to rerun. Fetch calls depends automatically.
ServerLoadEvent untrack method
ServerLoadEvent has untrack<T>(fn: () => T): T method to opt out of dependency tracking for synchronously called code within the callback. Example: untrack(() => url.pathname === '/') prevents path changes triggering rerun.
RequestEvent request property
RequestEvent has request property of type Request containing the original request object.