Reference
Modules
Edit this page on GitHubSvelteKit makes a number of modules available to your application.
$app/environmentpermalink
ts
import {browser ,building ,dev ,version } from '$app/environment';
browserpermalink
true
if the app is running in the browser.
ts
constbrowser : boolean;
buildingpermalink
SvelteKit analyses your app during the build
step by running it. During this process, building
is true
. This also applies during prerendering.
ts
constbuilding : boolean;
devpermalink
Whether the dev server is running. This is not guaranteed to correspond to NODE_ENV
or MODE
.
ts
constdev : boolean;
versionpermalink
The value of config.kit.version.name
.
ts
constversion : string;
$app/formspermalink
ts
import {applyAction ,deserialize ,enhance } from '$app/forms';
applyActionpermalink
This action updates the form
property of the current page with the given data and updates $page.status
.
In case of an error, it redirects to the nearest error page.
ts
functionapplyAction <Success extendsRecord <string, unknown> | undefined,Failure extendsRecord <string, unknown> | undefined>(result : import('@sveltejs/kit').ActionResult <Success ,Failure >):Promise <void>;
deserializepermalink
Use this function to deserialize the response from a form submission. Usage:
ts
import {deserialize } from '$app/forms';async functionhandleSubmit (event ) {constresponse = awaitfetch ('/form?/action', {method : 'POST',body : newFormData (event .target )});constresult =deserialize (awaitresponse .text ());// ...}
ts
functiondeserialize <Success extendsRecord <string, unknown> | undefined,Failure extendsRecord <string, unknown> | undefined>(result : string): import('@sveltejs/kit').ActionResult <Success ,Failure >;
enhancepermalink
This action enhances a <form>
element that otherwise would work without JavaScript.
The submit
function is called upon submission with the given FormData and the action
that should be triggered.
If cancel
is called, the form will not be submitted.
You can use the abort controller
to cancel the submission in case another one starts.
If a function is returned, that function is called with the response from the server.
If nothing is returned, the fallback will be used.
If this function or its return value isn't set, it
- falls back to updating the
form
prop with the returned data if the action is one same page as the form - updates
$page.status
- resets the
<form>
element and invalidates all data in case of successful submission with no redirect response - redirects in case of a redirect response
- redirects to the nearest error page in case of an unexpected error
If you provide a custom function with a callback and want to use the default behavior, invoke update
in your callback.
ts
functionenhance <Success extendsRecord <string, unknown> | undefined,Failure extendsRecord <string, unknown> | undefined>(form_element :HTMLFormElement ,submit ?: import('@sveltejs/kit').SubmitFunction <Success ,Failure >): {destroy (): void;};
$app/navigationpermalink
ts
import {afterNavigate ,beforeNavigate ,disableScrollHandling ,goto ,invalidate ,invalidateAll ,onNavigate ,preloadCode ,preloadData ,pushState ,replaceState } from '$app/navigation';
afterNavigatepermalink
A lifecycle function that runs the supplied callback
when the current component mounts, and also whenever we navigate to a new URL.
afterNavigate
must be called during a component initialization. It remains active as long as the component is mounted.
ts
functionafterNavigate (callback : (navigation : import('@sveltejs/kit').AfterNavigate ) => void): void;
beforeNavigatepermalink
A navigation interceptor that triggers before we navigate to a new URL, whether by clicking a link, calling goto(...)
, or using the browser back/forward controls.
Calling cancel()
will prevent the navigation from completing. If navigation.type === 'leave'
— meaning the user is navigating away from the app (or closing the tab) — calling cancel
will trigger the native browser unload confirmation dialog. In this case, the navigation may or may not be cancelled depending on the user's response.
When a navigation isn't to a SvelteKit-owned route (and therefore controlled by SvelteKit's client-side router), navigation.to.route.id
will be null
.
If the navigation will (if not cancelled) cause the document to unload — in other words 'leave'
navigations and 'link'
navigations where navigation.to.route === null
— navigation.willUnload
is true
.
beforeNavigate
must be called during a component initialization. It remains active as long as the component is mounted.
ts
functionbeforeNavigate (callback : (navigation : import('@sveltejs/kit').BeforeNavigate ) => void): void;
disableScrollHandlingpermalink
If called when the page is being updated following a navigation (in onMount
or afterNavigate
or an action, for example), this disables SvelteKit's built-in scroll handling.
This is generally discouraged, since it breaks user expectations.
ts
functiondisableScrollHandling (): void;
gotopermalink
Returns a Promise that resolves when SvelteKit navigates (or fails to navigate, in which case the promise rejects) to the specified url
.
For external URLs, use window.location = url
instead of calling goto(url)
.
ts
functiongoto (url : string |URL ,opts ?:| {replaceState ?: boolean | undefined;noScroll ?: boolean | undefined;keepFocus ?: boolean | undefined;invalidateAll ?: boolean | undefined;state ?:App .PageState | undefined;}| undefined):Promise <void>;
invalidatepermalink
Causes any load
functions belonging to the currently active page to re-run if they depend on the url
in question, via fetch
or depends
. Returns a Promise
that resolves when the page is subsequently updated.
If the argument is given as a string
or URL
, it must resolve to the same URL that was passed to fetch
or depends
(including query parameters).
To create a custom identifier, use a string beginning with [a-z]+:
(e.g. custom:state
) — this is a valid URL.
The function
argument can be used define a custom predicate. It receives the full URL
and causes load
to rerun if true
is returned.
This can be useful if you want to invalidate based on a pattern instead of a exact match.
ts
// Example: Match '/path' regardless of the query parametersimport {invalidate } from '$app/navigation';invalidate ((url ) =>url .pathname === '/path');
ts
functioninvalidate (resource : string |URL | ((url :URL ) => boolean)):Promise <void>;
invalidateAllpermalink
Causes all load
functions belonging to the currently active page to re-run. Returns a Promise
that resolves when the page is subsequently updated.
ts
functioninvalidateAll ():Promise <void>;
onNavigatepermalink
A lifecycle function that runs the supplied callback
immediately before we navigate to a new URL except during full-page navigations.
If you return a Promise
, SvelteKit will wait for it to resolve before completing the navigation. This allows you to — for example — use document.startViewTransition
. Avoid promises that are slow to resolve, since navigation will appear stalled to the user.
If a function (or a Promise
that resolves to a function) is returned from the callback, it will be called once the DOM has updated.
onNavigate
must be called during a component initialization. It remains active as long as the component is mounted.
ts
functiononNavigate (callback : (navigation : import('@sveltejs/kit').OnNavigate ) =>MaybePromise <(() => void) | void>): void;
preloadCodepermalink
Programmatically imports the code for routes that haven't yet been fetched. Typically, you might call this to speed up subsequent navigation.
You can specify routes by any matching pathname such as /about
(to match src/routes/about/+page.svelte
) or /blog/*
(to match src/routes/blog/[slug]/+page.svelte
).
Unlike preloadData
, this won't call load
functions.
Returns a Promise that resolves when the modules have been imported.
ts
functionpreloadCode (pathname : string):Promise <void>;
preloadDatapermalink
Programmatically preloads the given page, which means
- ensuring that the code for the page is loaded, and
- calling the page's load function with the appropriate options.
This is the same behaviour that SvelteKit triggers when the user taps or mouses over an <a>
element with data-sveltekit-preload-data
.
If the next navigation is to href
, the values returned from load will be used, making navigation instantaneous.
Returns a Promise that resolves with the result of running the new route's load
functions once the preload is complete.
ts
functionpreloadData (href : string):Promise <| {type : 'loaded';status : number;data :Record <string, any>;}| {type : 'redirect';location : string;}>;
pushStatepermalink
Programmatically create a new history entry with the given $page.state
. To use the current URL, you can pass ''
as the first argument. Used for shallow routing.
ts
functionpushState (url : string |URL ,state :App .PageState ): void;
replaceStatepermalink
Programmatically replace the current history entry with the given $page.state
. To use the current URL, you can pass ''
as the first argument. Used for shallow routing.
ts
functionreplaceState (url : string |URL ,state :App .PageState ): void;
$app/pathspermalink
ts
import {assets ,base ,resolveRoute } from '$app/paths';
assetspermalink
An absolute path that matches config.kit.paths.assets
.
If a value for
config.kit.paths.assets
is specified, it will be replaced with'/_svelte_kit_assets'
duringvite dev
orvite preview
, since the assets don't yet live at their eventual URL.
ts
letassets :| ''| `https://${string}`| `http://${string}`| '/_svelte_kit_assets';
basepermalink
A string that matches config.kit.paths.base
.
Example usage: <a href="{base}/your-page">Link</a>
ts
letbase : '' | `/${string}`;
resolveRoutepermalink
Populate a route ID with params to resolve a pathname.
ts
functionresolveRoute (id : string,params :Record <string, string | undefined>): string;
$app/serverpermalink
ts
import {read } from '$app/server';
readpermalink
Read the contents of an imported asset from the filesystem
ts
functionread (asset : string):Response ;
$app/storespermalink
ts
import {getStores ,navigating ,page ,updated } from '$app/stores';
getStorespermalink
ts
functiongetStores (): {page : typeofpage ;navigating : typeofnavigating ;updated : typeofupdated ;};
navigatingpermalink
A readable store.
When navigating starts, its value is a Navigation
object with from
, to
, type
and (if type === 'popstate'
) delta
properties.
When navigating finishes, its value reverts to null
.
On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time.
ts
constnavigating : import('svelte/store').Readable <import('@sveltejs/kit').Navigation | null>;
pagepermalink
A readable store whose value contains page data.
On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time.
ts
constpage : import('svelte/store').Readable <import('@sveltejs/kit').Page >;
updatedpermalink
A readable store whose initial value is false
. If version.pollInterval
is a non-zero value, SvelteKit will poll for new versions of the app and update the store value to true
when it detects one. updated.check()
will force an immediate check, regardless of polling.
On the server, this store can only be subscribed to during component initialization. In the browser, it can be subscribed to at any time.
ts
constupdated : import('svelte/store').Readable <boolean> & {check ():Promise <boolean>;};
$env/dynamic/privatepermalink
This module provides access to runtime environment variables, as defined by the platform you're running on. For example if you're using adapter-node
(or running vite preview
), this is equivalent to process.env
. This module only includes variables that do not begin with config.kit.env.publicPrefix
and do start with config.kit.env.privatePrefix
(if configured).
This module cannot be imported into client-side code.
Dynamic environment variables cannot be used during prerendering.
ts
import {env } from '$env/dynamic/private';console .log (env .DEPLOYMENT_SPECIFIC_VARIABLE );
In
dev
,$env/dynamic
always includes environment variables from.env
. Inprod
, this behavior will depend on your adapter.
$env/dynamic/publicpermalink
Similar to $env/dynamic/private
, but only includes variables that begin with config.kit.env.publicPrefix
(which defaults to PUBLIC_
), and can therefore safely be exposed to client-side code.
Note that public dynamic environment variables must all be sent from the server to the client, causing larger network requests — when possible, use $env/static/public
instead.
Dynamic environment variables cannot be used during prerendering.
ts
import {env } from '$env/dynamic/public';console .log (env .PUBLIC_DEPLOYMENT_SPECIFIC_VARIABLE );
$env/static/privatepermalink
Environment variables loaded by Vite from .env
files and process.env
. Like $env/dynamic/private
, this module cannot be imported into client-side code. This module only includes variables that do not begin with config.kit.env.publicPrefix
and do start with config.kit.env.privatePrefix
(if configured).
Unlike $env/dynamic/private
, the values exported from this module are statically injected into your bundle at build time, enabling optimisations like dead code elimination.
ts
import {API_KEY } from '$env/static/private';
Note that all environment variables referenced in your code should be declared (for example in an .env
file), even if they don't have a value until the app is deployed:
MY_FEATURE_FLAG=""
You can override .env
values from the command line like so:
MY_FEATURE_FLAG="enabled" npm run dev
$env/static/publicpermalink
Similar to $env/static/private
, except that it only includes environment variables that begin with config.kit.env.publicPrefix
(which defaults to PUBLIC_
), and can therefore safely be exposed to client-side code.
Values are replaced statically at build time.
ts
import {PUBLIC_BASE_URL } from '$env/static/public';
$libpermalink
This is a simple alias to src/lib
, or whatever directory is specified as config.kit.files.lib
. It allows you to access common components and utility modules without ../../../../
nonsense.
$lib/serverpermalink
A subdirectory of $lib
. SvelteKit will prevent you from importing any modules in $lib/server
into client-side code. See server-only modules.
$service-workerpermalink
ts
import {base ,build ,files ,prerendered ,version } from '$service-worker';
This module is only available to service workers.
basepermalink
The base
path of the deployment. Typically this is equivalent to config.kit.paths.base
, but it is calculated from location.pathname
meaning that it will continue to work correctly if the site is deployed to a subdirectory.
Note that there is a base
but no assets
, since service workers cannot be used if config.kit.paths.assets
is specified.
ts
constbase : string;
buildpermalink
An array of URL strings representing the files generated by Vite, suitable for caching with cache.addAll(build)
.
During development, this is an empty array.
ts
constbuild : string[];
filespermalink
An array of URL strings representing the files in your static directory, or whatever directory is specified by config.kit.files.assets
. You can customize which files are included from static
directory using config.kit.serviceWorker.files
ts
constfiles : string[];
prerenderedpermalink
An array of pathnames corresponding to prerendered pages and endpoints. During development, this is an empty array.
ts
constprerendered : string[];
versionpermalink
See config.kit.version
. It's useful for generating unique cache names inside your service worker, so that a later deployment of your app can invalidate old caches.
ts
constversion : string;
@sveltejs/kitpermalink
ts
import {VERSION ,error ,fail ,isHttpError ,isRedirect ,json ,redirect ,text } from '@sveltejs/kit';
VERSIONpermalink
ts
constVERSION : string;
errorpermalink
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it.
ts
functionerror (status : number,body :App .Error ): never;
errorpermalink
Throws an error with a HTTP status code and an optional message.
When called during request handling, this will cause SvelteKit to
return an error response without invoking handleError
.
Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it.
ts
functionerror (status : number,body ?: {message : string;} extendsApp .Error ?App .Error | string | undefined: never): never;
failpermalink
Create an ActionFailure
object.
ts
functionfail (status : number):ActionFailure <undefined>;
failpermalink
Create an ActionFailure
object.
ts
functionfail <T extendsRecord <string, unknown> | undefined = undefined>(status : number,data :T ):ActionFailure <T >;
isHttpErrorpermalink
Checks whether this is an error thrown by error
.
ts
functionisHttpError <T extends number>(e : unknown,status ?:T | undefined):e isHttpError_1 & {status :T extends undefined ? never :T ;};
isRedirectpermalink
Checks whether this is a redirect thrown by redirect
.
ts
functionisRedirect (e : unknown):e isRedirect_1 ;
jsonpermalink
Create a JSON Response
object from the supplied data.
ts
functionjson (data : any,init ?:ResponseInit | undefined):Response ;
redirectpermalink
Redirect a request. When called during request handling, SvelteKit will return a redirect response. Make sure you're not catching the thrown redirect, which would prevent SvelteKit from handling it.
ts
functionredirect (status :| 300| 301| 302| 303| 304| 305| 306| 307| 308| ({} & number),location : string |URL ): never;
textpermalink
Create a Response
object from the supplied body.
ts
functiontext (body : string,init ?:ResponseInit | undefined):Response ;
@sveltejs/kit/hookspermalink
ts
import {sequence } from '@sveltejs/kit/hooks';
sequencepermalink
A helper function for sequencing multiple handle
calls in a middleware-like manner.
The behavior for the handle
options is as follows:
transformPageChunk
is applied in reverse order and mergedpreload
is applied in forward order, the first option "wins" and nopreload
options after it are calledfilterSerializedResponseHeaders
behaves the same aspreload
ts
import {sequence } from '@sveltejs/kit/hooks';/// type: import('@sveltejs/kit').HandleBinding element 'html' implicitly has an 'any' type.7031Binding element 'html' implicitly has an 'any' type.async functionfirst ({event ,resolve }) {console .log ('first pre-processing');constresult = awaitresolve (event , {transformPageChunk : ({html }) => {// transforms are applied in reverse orderconsole .log ('first transform');returnhtml ;},preload : () => {// this one wins as it's the first defined in the chainconsole .log ('first preload');}});console .log ('first post-processing');returnBinding element 'event' implicitly has an 'any' type.Binding element 'resolve' implicitly has an 'any' type.7031result ;
7031Binding element 'event' implicitly has an 'any' type.Binding element 'resolve' implicitly has an 'any' type.}/// type: import('@sveltejs/kit').HandleBinding element 'html' implicitly has an 'any' type.7031Binding element 'html' implicitly has an 'any' type.async functionsecond ({event ,resolve }) {console .log ('second pre-processing');constresult = awaitresolve (event , {transformPageChunk : ({html }) => {console .log ('second transform');returnhtml ;},preload : () => {console .log ('second preload');},filterSerializedResponseHeaders : () => {// this one wins as it's the first defined in the chainconsole .log ('second filterSerializedResponseHeaders');}});console .log ('second post-processing');returnresult ;}export consthandle =sequence (first ,second );
ts
import {sequence } from '@sveltejs/kit/hooks';/// type: import('@sveltejs/kit').HandleBinding element 'html' implicitly has an 'any' type.7031Binding element 'html' implicitly has an 'any' type.async functionfirst ({event ,resolve }) {console .log ('first pre-processing');constresult = awaitresolve (event , {transformPageChunk : ({html }) => {// transforms are applied in reverse orderconsole .log ('first transform');returnhtml ;},preload : () => {// this one wins as it's the first defined in the chainconsole .log ('first preload');},});console .log ('first post-processing');returnBinding element 'event' implicitly has an 'any' type.Binding element 'resolve' implicitly has an 'any' type.7031result ;
7031Binding element 'event' implicitly has an 'any' type.Binding element 'resolve' implicitly has an 'any' type.}/// type: import('@sveltejs/kit').HandleBinding element 'html' implicitly has an 'any' type.7031Binding element 'html' implicitly has an 'any' type.async functionsecond ({event ,resolve }) {console .log ('second pre-processing');constresult = awaitresolve (event , {transformPageChunk : ({html }) => {console .log ('second transform');returnhtml ;},preload : () => {console .log ('second preload');},filterSerializedResponseHeaders : () => {// this one wins as it's the first defined in the chainconsole .log ('second filterSerializedResponseHeaders');},});console .log ('second post-processing');returnresult ;}export consthandle =sequence (first ,second );
The example above would print:
first pre-processing
first preload
second pre-processing
second filterSerializedResponseHeaders
second transform
first transform
second post-processing
first post-processing
ts
functionsequence (...handlers : import('@sveltejs/kit').Handle []): import('@sveltejs/kit').Handle ;
@sveltejs/kit/nodepermalink
ts
import {createReadableStream ,getRequest ,setResponse } from '@sveltejs/kit/node';
createReadableStreampermalink
Converts a file on disk to a readable stream
ts
functioncreateReadableStream (file : string):ReadableStream ;
getRequestpermalink
ts
functiongetRequest ({request ,base ,bodySizeLimit }: {request : import('http').IncomingMessage ;base : string;bodySizeLimit ?: number;}):Promise <Request >;
setResponsepermalink
ts
functionsetResponse (res : import('http').ServerResponse ,response :Response ):Promise <void>;
@sveltejs/kit/node/polyfillspermalink
ts
import {installPolyfills } from '@sveltejs/kit/node/polyfills';
installPolyfillspermalink
Make various web APIs available as globals:
crypto
File
ts
functioninstallPolyfills (): void;
@sveltejs/kit/vitepermalink
ts
import {sveltekit } from '@sveltejs/kit/vite';
sveltekitpermalink
Returns the SvelteKit Vite plugins.
ts
functionsveltekit ():Promise <import('vite').Plugin []>;