```
# Service workers
Service workers act as proxy servers that handle network requests inside your app. This makes it possible to make your app work offline, but even if you don't need offline support (or can't realistically implement it because of the type of app you're building), it's often worth using service workers to speed up navigation by precaching your built JS and CSS.
In SvelteKit, if you have a `src/service-worker.js` file (or `src/service-worker/index.js`) it will be bundled and automatically registered. You can change the [location of your service worker](configuration#files) if you need to.
You can [disable automatic registration](configuration#serviceWorker) if you need to register the service worker with your own logic or use another solution. The default registration looks something like this:
```js
if ('serviceWorker' in navigator) {
addEventListener('load', function () {
navigator.serviceWorker.register('./path/to/service-worker.js');
});
}
```
## Inside the service worker
Inside the service worker you have access to the [`$service-worker` module]($service-worker), which provides you with the paths to all static assets, build files and prerendered pages. You're also provided with an app version string, which you can use for creating a unique cache name, and the deployment's `base` path. If your Vite config specifies `define` (used for global variable replacements), this will be applied to service workers as well as your server/client builds.
The following example caches the built app and any files in `static` eagerly, and caches all other requests as they happen. This would make each page work offline once visited.
```js
/// file: src/service-worker.js
// Disables access to DOM typings like `HTMLElement` which are not available
// inside a service worker and instantiates the correct globals
///
///
///
// Ensures that the `$service-worker` import has proper type definitions
///
// Only necessary if you have an import from `$env/static/public`
///
import { build, files, version } from '$service-worker';
// This gives `self` the correct types
const self = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (globalThis.self));
// Create a unique cache name for this deployment
const CACHE = `cache-${version}`;
const ASSETS = [
...build, // the app itself
...files // everything in `static`
];
self.addEventListener('install', (event) => {
// Create a new cache and add all files to it
async function addFilesToCache() {
const cache = await caches.open(CACHE);
await cache.addAll(ASSETS);
}
event.waitUntil(addFilesToCache());
});
self.addEventListener('activate', (event) => {
// Remove previous cached data from disk
async function deleteOldCaches() {
for (const key of await caches.keys()) {
if (key !== CACHE) await caches.delete(key);
}
}
event.waitUntil(deleteOldCaches());
});
self.addEventListener('fetch', (event) => {
// ignore POST requests etc
if (event.request.method !== 'GET') return;
async function respond() {
const url = new URL(event.request.url);
const cache = await caches.open(CACHE);
// `build`/`files` can always be served from the cache
if (ASSETS.includes(url.pathname)) {
const response = await cache.match(url.pathname);
if (response) {
return response;
}
}
// for everything else, try the network first, but
// fall back to the cache if we're offline
try {
const response = await fetch(event.request);
// if we're offline, fetch can return a value that is not a Response
// instead of throwing - and we can't pass this non-Response to respondWith
if (!(response instanceof Response)) {
throw new Error('invalid response from fetch');
}
if (response.status === 200) {
cache.put(event.request, response.clone());
}
return response;
} catch (err) {
const response = await cache.match(event.request);
if (response) {
return response;
}
// if there's no cache, then just error out
// as there is nothing we can do to respond to this request
throw err;
}
}
event.respondWith(respond());
});
```
> [!NOTE] Be careful when caching! In some cases, stale data might be worse than data that's unavailable while offline. Since browsers will empty caches if they get too full, you should also be careful about caching large assets like video files.
## During development
The service worker is bundled for production, but not during development. For that reason, only browsers that support [modules in service workers](https://web.dev/es-modules-in-sw) will be able to use them at dev time. If you are manually registering your service worker, you will need to pass the `{ type: 'module' }` option in development:
```js
import { dev } from '$app/environment';
navigator.serviceWorker.register('/service-worker.js', {
type: dev ? 'module' : 'classic'
});
```
> [!NOTE] `build` and `prerendered` are empty arrays during development
## Other solutions
SvelteKit's service worker implementation is designed to be easy to work with and is probably a good solution for most users. However, outside of SvelteKit, many PWA applications leverage the [Workbox](https://web.dev/learn/pwa/workbox) library. If you're used to using Workbox you may prefer [Vite PWA plugin](https://vite-pwa-org.netlify.app/frameworks/sveltekit.html).
## References
For more general information on service workers, we recommend [the MDN web docs](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers).
# Server-only modules
Like a good friend, SvelteKit keeps your secrets. When writing your backend and frontend in the same repository, it can be easy to accidentally import sensitive data into your front-end code (environment variables containing API keys, for example). SvelteKit provides a way to prevent this entirely: server-only modules.
## Private environment variables
The [`$env/static/private`]($env-static-private) and [`$env/dynamic/private`]($env-dynamic-private) modules can only be imported into modules that only run on the server, such as [`hooks.server.js`](hooks#Server-hooks) or [`+page.server.js`](routing#page-page.server.js).
## Server-only utilities
The [`$app/server`]($app-server) module, which contains a [`read`]($app-server#read) function for reading assets from the filesystem, can likewise only be imported by code that runs on the server.
## Your modules
You can make your own modules server-only in two ways:
- adding `.server` to the filename, e.g. `secrets.server.js`
- placing them in `$lib/server`, e.g. `$lib/server/secrets.js`
## How it works
Any time you have public-facing code that imports server-only code (whether directly or indirectly)...
```js
// @errors: 7005
/// file: $lib/server/secrets.js
export const atlantisCoordinates = [/* redacted */];
```
```js
// @errors: 2307 7006 7005
/// file: src/routes/utils.js
export { atlantisCoordinates } from '$lib/server/secrets.js';
export const add = (a, b) => a + b;
```
```html
/// file: src/routes/+page.svelte
```
...SvelteKit will error:
```
Cannot import $lib/server/secrets.ts into code that runs in the browser, as this could leak sensitive information.
src/routes/+page.svelte imports
src/routes/utils.js imports
$lib/server/secrets.ts
If you're only using the import as a type, change it to `import type`.
```
Even though the public-facing code — `src/routes/+page.svelte` — only uses the `add` export and not the secret `atlantisCoordinates` export, the secret code could end up in JavaScript that the browser downloads, and so the import chain is considered unsafe.
This feature also works with dynamic imports, even interpolated ones like ``await import(`./${foo}.js`)``.
> [!NOTE] Unit testing frameworks like Vitest do not distinguish between server-only and public-facing code. For this reason, illegal import detection is disabled when running tests, as determined by `process.env.TEST === 'true'`.
## Further reading
- [Tutorial: Environment variables](/tutorial/kit/env-static-private)
# Snapshots
Ephemeral DOM state — like scroll positions on sidebars, the content of `
` elements and so on — is discarded when you navigate from one page to another.
For example, if the user fills out a form but navigates away and then back before submitting, or if the user refreshes the page, the values they filled in will be lost. In cases where it's valuable to preserve that input, you can take a _snapshot_ of DOM state, which can then be restored if the user navigates back.
To do this, export a `snapshot` object with `capture` and `restore` methods from a `+page.svelte` or `+layout.svelte`:
```svelte
```
When you navigate away from this page, the `capture` function is called immediately before the page updates, and the returned value is associated with the current entry in the browser's history stack. If you navigate back, the `restore` function is called with the stored value as soon as the page is updated.
The data must be serializable as JSON so that it can be persisted to `sessionStorage`. This allows the state to be restored when the page is reloaded, or when the user navigates back from a different site.
> [!NOTE] Avoid returning very large objects from `capture` — once captured, objects will be retained in memory for the duration of the session, and in extreme cases may be too large to persist to `sessionStorage`.
# Shallow routing
As you navigate around a SvelteKit app, you create _history entries_. Clicking the back and forward buttons traverses through this list of entries, re-running any `load` functions and replacing page components as necessary.
Sometimes, it's useful to create history entries _without_ navigating. For example, you might want to show a modal dialog that the user can dismiss by navigating back. This is particularly valuable on mobile devices, where swipe gestures are often more natural than interacting directly with the UI. In these cases, a modal that is _not_ associated with a history entry can be a source of frustration, as a user may swipe backwards in an attempt to dismiss it and find themselves on the wrong page.
SvelteKit makes this possible with the [`pushState`]($app-navigation#pushState) and [`replaceState`]($app-navigation#replaceState) functions, which allow you to associate state with a history entry without navigating. For example, to implement a history-driven modal:
```svelte
{#if page.state.showModal}
history.back()} />
{/if}
```
The modal can be dismissed by navigating back (unsetting `page.state.showModal`) or by interacting with it in a way that causes the `close` callback to run, which will navigate back programmatically.
## API
The first argument to `pushState` is the URL, relative to the current URL. To stay on the current URL, use `''`.
The second argument is the new page state, which can be accessed via the [page object]($app-state#page) as `page.state`. You can make page state type-safe by declaring an [`App.PageState`](types#PageState) interface (usually in `src/app.d.ts`).
To set page state without creating a new history entry, use `replaceState` instead of `pushState`.
> [!LEGACY]
> `page.state` from `$app/state` was added in SvelteKit 2.12. If you're using an earlier version or are using Svelte 4, use `$page.state` from `$app/stores` instead.
## Loading data for a route
When shallow routing, you may want to render another `+page.svelte` inside the current page. For example, clicking on a photo thumbnail could pop up the detail view without navigating to the photo page.
For this to work, you need to load the data that the `+page.svelte` expects. A convenient way to do this is to use [`preloadData`]($app-navigation#preloadData) inside the `click` handler of an `` element. If the element (or a parent) uses [`data-sveltekit-preload-data`](link-options#data-sveltekit-preload-data), the data will have already been requested, and `preloadData` will reuse that request.
```svelte
{#each data.thumbnails as thumbnail}
{
if (innerWidth < 640 // bail if the screen is too small
|| e.shiftKey // or the link is opened in a new window
|| e.metaKey || e.ctrlKey // or a new tab (mac: metaKey, win/linux: ctrlKey)
// should also consider clicking with a mouse scroll wheel
) return;
// prevent navigation
e.preventDefault();
const { href } = e.currentTarget;
// run `load` functions (or rather, get the result of the `load` functions
// that are already running because of `data-sveltekit-preload-data`)
const result = await preloadData(href);
if (result.type === 'loaded' && result.status === 200) {
pushState(href, { selected: result.data });
} else {
// something bad happened! try navigating
goto(href);
}
}}
>
{/each}
{#if page.state.selected}
history.back()}>
{/if}
```
## Caveats
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 is a feature that requires JavaScript to work. Be mindful when using it and try to think of sensible fallback behavior in case JavaScript isn't available.
# Observability
Available since 2.31
Sometimes, you may need to observe how your application is behaving in order to improve performance or find the root cause of a pesky bug. To help with this, SvelteKit can emit server-side [OpenTelemetry](https://opentelemetry.io) spans for the following:
- The [`handle`](hooks#Server-hooks-handle) hook and `handle` functions running in a [`sequence`](@sveltejs-kit-hooks#sequence) (these will show up as children of each other and the root `handle` hook)
- Server [`load`](load) functions and universal `load` functions when they're run on the server
- [Form actions](form-actions)
- [Remote functions](remote-functions)
Just telling SvelteKit to emit spans won't get you far, though — you need to actually collect them somewhere to be able to view them. SvelteKit provides `src/instrumentation.server.ts` as a place to write your tracing setup and instrumentation code. It's guaranteed to be run prior to your application code being imported, providing your deployment platform supports it and your adapter is aware of it.
Both of these features are currently experimental, meaning they are likely to contain bugs and are subject to change without notice. You must opt in by adding the `kit.experimental.tracing.server` and `kit.experimental.instrumentation.server` option in your `svelte.config.js`:
```js
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
experimental: {
+++tracing: {
server: true
},
instrumentation: {
server: true
}+++
}
}
};
export default config;
```
> [!NOTE] Tracing — and more significantly, observability instrumentation — can have a nontrivial overhead. Before you go all-in on tracing, consider whether or not you really need it, or if it might be more appropriate to turn it on in development and preview environments only.
## Augmenting the built-in tracing
SvelteKit provides access to the `root` span and the `current` span on the request event. The root span is the one associated with your root `handle` function, and the current span could be associated with `handle`, `load`, a form action, or a remote function, depending on the context. You can annotate these spans with any attributes you wish to record:
```js
/// file: $lib/authenticate.ts
// @filename: ambient.d.ts
declare module '$lib/auth-core' {
export function getAuthenticatedUser(): Promise<{ id: string }>
}
// @filename: index.js
// ---cut---
import { getRequestEvent } from '$app/server';
import { getAuthenticatedUser } from '$lib/auth-core';
async function authenticate() {
const user = await getAuthenticatedUser();
const event = getRequestEvent();
event.tracing.root.setAttribute('userId', user.id);
}
```
## Development quickstart
To view your first trace, you'll need to set up a local collector. We'll use [Jaeger](https://www.jaegertracing.io/docs/getting-started/) in this example, as they provide an easy-to-use quickstart command. Once your collector is running locally:
- Turn on the experimental flags mentioned earlier in your `svelte.config.js` file
- Use your package manager to install the dependencies you'll need:
```sh
npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto import-in-the-middle
```
- Create `src/instrumentation.server.js` with the following:
```js
/// file: src/instrumentation.server.js
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { createAddHookMessageChannel } from 'import-in-the-middle';
import { register } from 'node:module';
const { registerOptions } = createAddHookMessageChannel();
register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions);
const sdk = new NodeSDK({
serviceName: 'test-sveltekit-tracing',
traceExporter: new OTLPTraceExporter(),
instrumentations: [getNodeAutoInstrumentations()]
});
sdk.start();
```
Now, server-side requests will begin generating traces, which you can view in Jaeger's web console at [localhost:16686](http://localhost:16686).
## `@opentelemetry/api`
SvelteKit uses `@opentelemetry/api` to generate its spans. This is declared as an optional peer dependency so that users not needing traces see no impact on install size or runtime performance. In most cases, if you're configuring your application to collect SvelteKit's spans, you'll end up installing a library like `@opentelemetry/sdk-node` or `@vercel/otel`, which in turn depend on `@opentelemetry/api`, which will satisfy SvelteKit's dependency as well. If you see an error from SvelteKit telling you it can't find `@opentelemetry/api`, it may just be because you haven't set up your trace collection yet. If you _have_ done that and are still seeing the error, you can install `@opentelemetry/api` yourself.
# Packaging
You can use SvelteKit to build apps as well as component libraries, using the `@sveltejs/package` package (`npx sv create` has an option to set this up for you).
When you're creating an app, the contents of `src/routes` is the public-facing stuff; [`src/lib`]($lib) contains your app's internal library.
A component library has the exact same structure as a SvelteKit app, except that `src/lib` is the public-facing bit, and your root `package.json` is used to publish the package. `src/routes` might be a documentation or demo site that accompanies the library, or it might just be a sandbox you use during development.
Running the `svelte-package` command from `@sveltejs/package` will take the contents of `src/lib` and generate a `dist` directory (which can be [configured](#Options)) containing the following:
- All the files in `src/lib`. Svelte components will be preprocessed, TypeScript files will be transpiled to JavaScript.
- Type definitions (`d.ts` files) which are generated for Svelte, JavaScript and TypeScript files. You need to install `typescript >= 4.0.0` for this. Type definitions are placed next to their implementation, hand-written `d.ts` files are copied over as is. You can [disable generation](#Options), but we strongly recommend against it — people using your library might use TypeScript, for which they require these type definition files.
> [!NOTE] `@sveltejs/package` version 1 generated a `package.json`. This is no longer the case and it will now use the `package.json` from your project and validate that it is correct instead. If you're still on version 1, see [this PR](https://github.com/sveltejs/kit/pull/8922) for migration instructions.
## Anatomy of a package.json
Since you're now building a library for public use, the contents of your `package.json` will become more important. Through it, you configure the entry points of your package, which files are published to npm, and which dependencies your library has. Let's go through the most important fields one by one.
### name
This is the name of your package. It will be available for others to install using that name, and visible on `https://npmjs.com/package/`.
```json
{
"name": "your-library"
}
```
Read more about it [here](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#name).
### license
Every package should have a license field so people know how they are allowed to use it. A very popular license which is also very permissive in terms of distribution and reuse without warranty is `MIT`.
```json
{
"license": "MIT"
}
```
Read more about it [here](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#license). Note that you should also include a `LICENSE` file in your package.
### files
This tells npm which files it will pack up and upload to npm. It should contain your output folder (`dist` by default). Your `package.json` and `README` and `LICENSE` will always be included, so you don't need to specify them.
```json
{
"files": ["dist"]
}
```
To exclude unnecessary files (such as unit tests, or modules that are only imported from `src/routes` etc) you can add them to an `.npmignore` file. This will result in smaller packages that are faster to install.
Read more about it [here](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#files).
### exports
The `"exports"` field contains the package's entry points. If you set up a new library project through `npx sv create`, it's set to a single export, the package root:
```json
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"svelte": "./dist/index.js"
}
}
}
```
This tells bundlers and tooling that your package only has one entry point, the root, and everything should be imported through that, like this:
```js
// @errors: 2307
import { Something } from 'your-library';
```
The `types` and `svelte` keys are [export conditions](https://nodejs.org/api/packages.html#conditional-exports). They tell tooling what file to import when they look up the `your-library` import:
- TypeScript sees the `types` condition and looks up the type definition file. If you don't publish type definitions, omit this condition.
- Svelte-aware tooling sees the `svelte` condition and knows this is a Svelte component library. If you publish a library that does not export any Svelte components and that could also work in non-Svelte projects (for example a Svelte store library), you can replace this condition with `default`.
> [!NOTE] Previous versions of `@sveltejs/package` also added a `package.json` export. This is no longer part of the template because all tooling can now deal with a `package.json` not being explicitly exported.
You can adjust `exports` to your liking and provide more entry points. For example, if instead of a `src/lib/index.js` file that re-exported components you wanted to expose a `src/lib/Foo.svelte` component directly, you could create the following export map...
```json
{
"exports": {
"./Foo.svelte": {
"types": "./dist/Foo.svelte.d.ts",
"svelte": "./dist/Foo.svelte"
}
}
}
```
...and a consumer of your library could import the component like so:
```js
// @filename: ambient.d.ts
declare module 'your-library/Foo.svelte';
// @filename: index.js
// ---cut---
import Foo from 'your-library/Foo.svelte';
```
> [!NOTE] Beware that doing this will need additional care if you provide type definitions. Read more about the caveat [here](#TypeScript)
In general, each key of the exports map is the path the user will have to use to import something from your package, and the value is the path to the file that will be imported or a map of export conditions which in turn contains these file paths.
Read more about `exports` [here](https://nodejs.org/docs/latest-v18.x/api/packages.html#package-entry-points).
### svelte
This is a legacy field that enabled tooling to recognise Svelte component libraries. It's no longer necessary when using the `svelte` [export condition](#Anatomy-of-a-package.json-exports), but for backwards compatibility with outdated tooling that doesn't yet know about export conditions it's good to keep it around. It should point towards your root entry point.
```json
{
"svelte": "./dist/index.js"
}
```
### sideEffects
The `sideEffects` field in `package.json` is used by bundlers to determine if a module may contain code that has side effects. A module is considered to have side effects if it makes changes that are observable from other scripts outside the module when it's imported. For example, side effects include modifying global variables or the prototype of built-in JavaScript objects. Because a side effect could potentially affect the behavior of other parts of the application, these files/modules will be included in the final bundle regardless of whether their exports are used in the application. It is a best practice to avoid side effects in your code.
Setting the `sideEffects` field in `package.json` can help the bundler to be more aggressive in eliminating unused exports from the final bundle, a process known as tree-shaking. This results in smaller and more efficient bundles. Different bundlers handle `sideEffects` in various manners. While not necessary for Vite, we recommend that libraries state that all CSS files have side effects so that your library will be [compatible with webpack](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free). This is the configuration that comes with newly created projects:
```json
/// file: package.json
{
"sideEffects": ["**/*.css"]
}
```
> [!NOTE] If the scripts in your library have side effects, ensure that you update the `sideEffects` field. All scripts are marked as side effect free by default in newly created projects. If a file with side effects is incorrectly marked as having no side effects, it can result in broken functionality.
If your package has files with side effects, you can specify them in an array:
```json
/// file: package.json
{
"sideEffects": [
"**/*.css",
"./dist/sideEffectfulFile.js"
]
}
```
This will treat only the specified files as having side effects.
## TypeScript
You should ship type definitions for your library even if you don't use TypeScript yourself so that people who do get proper intellisense when using your library. `@sveltejs/package` makes the process of generating types mostly opaque to you. By default, when packaging your library, type definitions are auto-generated for JavaScript, TypeScript and Svelte files. All you need to ensure is that the `types` condition in the [exports](#Anatomy-of-a-package.json-exports) map points to the correct files. When initialising a library project through `npx sv create`, this is automatically setup for the root export.
If you have something else than a root export however — for example providing a `your-library/foo` import — you need to take additional care for providing type definitions. Unfortunately, TypeScript by default will _not_ resolve the `types` condition for an export like `{ "./foo": { "types": "./dist/foo.d.ts", ... }}`. Instead, it will search for a `foo.d.ts` relative to the root of your library (i.e. `your-library/foo.d.ts` instead of `your-library/dist/foo.d.ts`). To fix this, you have two options:
The first option is to require people using your library to set the `moduleResolution` option in their `tsconfig.json` (or `jsconfig.json`) to `bundler` (available since TypeScript 5, the best and recommended option in the future), `node16` or `nodenext`. This opts TypeScript into actually looking at the exports map and resolving the types correctly.
The second option is to (ab)use the `typesVersions` feature from TypeScript to wire up the types. This is a field inside `package.json` TypeScript uses to check for different type definitions depending on the TypeScript version, and also contains a path mapping feature for that. We leverage that path mapping feature to get what we want. For the mentioned `foo` export above, the corresponding `typesVersions` looks like this:
```json
{
"exports": {
"./foo": {
"types": "./dist/foo.d.ts",
"svelte": "./dist/foo.js"
}
},
"typesVersions": {
">4.0": {
"foo": ["./dist/foo.d.ts"]
}
}
}
```
`>4.0` tells TypeScript to check the inner map if the used TypeScript version is greater than 4 (which should in practice always be true). The inner map tells TypeScript that the typings for `your-library/foo` are found within `./dist/foo.d.ts`, which essentially replicates the `exports` condition. You also have `*` as a wildcard at your disposal to make many type definitions at once available without repeating yourself. Note that if you opt into `typesVersions` you have to declare all type imports through it, including the root import (which is defined as `"index.d.ts": [..]`).
You can read more about that feature [here](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#version-selection-with-typesversions).
## Best practices
You should avoid using SvelteKit-specific modules like `$app/environment` in your packages unless you intend for them to only be consumable by other SvelteKit projects. E.g. rather than using `import { browser } from '$app/environment'` you could use `import { BROWSER } from 'esm-env'` ([see esm-env docs](https://github.com/benmccann/esm-env)). You may also wish to pass in things like the current URL or a navigation action as a prop rather than relying directly on `$app/state`, `$app/navigation`, etc. Writing your app in this more generic fashion will also make it easier to setup tools for testing, UI demos and so on.
Ensure that you add [aliases](configuration#alias) via `svelte.config.js` (not `vite.config.js` or `tsconfig.json`), so that they are processed by `svelte-package`.
You should think carefully about whether or not the changes you make to your package are a bug fix, a new feature, or a breaking change, and update the package version accordingly. Note that if you remove any paths from `exports` or any `export` conditions inside them from your existing library, that should be regarded as a breaking change.
```json
{
"exports": {
".": {
"types": "./dist/index.d.ts",
// changing `svelte` to `default` is a breaking change:
--- "svelte": "./dist/index.js"---
+++ "default": "./dist/index.js"+++
},
// removing this is a breaking change:
--- "./foo": {
"types": "./dist/foo.d.ts",
"svelte": "./dist/foo.js",
"default": "./dist/foo.js"
},---
// adding this is ok:
+++ "./bar": {
"types": "./dist/bar.d.ts",
"svelte": "./dist/bar.js",
"default": "./dist/bar.js"
}+++
}
}
```
## Source maps
You can create so-called declaration maps (`d.ts.map` files) by setting `"declarationMap": true` in your `tsconfig.json`. This will allow editors such as VS Code to go to the original `.ts` or `.svelte` file when using features like _Go to Definition_. This means you also need to publish your source files alongside your dist folder in a way that the relative path inside the declaration files leads to a file on disk. Assuming that you have all your library code inside `src/lib` as suggested by Svelte's CLI, this is as simple as adding `src/lib` to `files` in your `package.json`:
```json
{
"files": [
"dist",
"!dist/**/*.test.*",
"!dist/**/*.spec.*",
+++"src/lib",
"!src/lib/**/*.test.*",
"!src/lib/**/*.spec.*"+++
]
}
```
## Options
`svelte-package` accepts the following options:
- `-w`/`--watch` — watch files in `src/lib` for changes and rebuild the package
- `-i`/`--input` — the input directory which contains all the files of the package. Defaults to `src/lib`
- `-o`/`--output` — the output directory where the processed files are written to. Your `package.json`'s `exports` should point to files inside there, and the `files` array should include that folder. Defaults to `dist`
- `-p`/`--preserve-output` — prevent deletion of the output directory before packaging. Defaults to `false`, which means that the output directory will be emptied first
- `-t`/`--types` — whether or not to create type definitions (`d.ts` files). We strongly recommend doing this as it fosters ecosystem library quality. Defaults to `true`
- `--tsconfig` - the path to a tsconfig or jsconfig. When not provided, searches for the next upper tsconfig/jsconfig in the workspace path.
## Publishing
To publish the generated package:
```sh
npm publish
```
## Caveats
All relative file imports need to be fully specified, adhering to Node's ESM algorithm. This means that for a file like `src/lib/something/index.js`, you must include the filename with the extension:
```js
// @errors: 2307
import { something } from './something+++/index.js+++';
```
If you are using TypeScript, you need to import `.ts` files the same way, but using a `.js` file ending, _not_ a `.ts` file ending. (This is a TypeScript design decision outside our control.) Setting `"moduleResolution": "NodeNext"` in your `tsconfig.json` or `jsconfig.json` will help you with this.
All files except Svelte files (preprocessed) and TypeScript files (transpiled to JavaScript) are copied across as-is.
# Auth
Auth refers to authentication and authorization, which are common needs when building a web application. Authentication means verifying that the user is who they say they are based on their provided credentials. Authorization means determining which actions they are allowed to take.
## Sessions vs tokens
After the user has provided their credentials such as a username and password, we want to allow them to use the application without needing to provide their credentials again for future requests. Users are commonly authenticated on subsequent requests with either a session identifier or signed token such as a JSON Web Token (JWT).
Session IDs are most commonly stored in a database. They can be immediately revoked, but require a database query to be made on each request.
In contrast, JWT generally are not checked against a datastore, which means they cannot be immediately revoked. The advantage of this method is improved latency and reduced load on your datastore.
## Integration points
Auth [cookies](@sveltejs-kit#Cookies) can be checked inside [server hooks](hooks#Server-hooks). If a user is found matching the provided credentials, the user information can be stored in [`locals`](hooks#Server-hooks-locals).
## Guides
[Lucia](https://lucia-auth.com/) is a good reference for session-based web app auth. It contains example code snippets and projects for implementing session-based auth within SvelteKit and other JS projects. You can add code which follows the Lucia guide to your project with `npx sv create` when creating a new project or `npx sv add lucia` for an existing project.
An auth system is tightly coupled to a web framework because most of the code lies in validating user input, handling errors, and directing users to the appropriate next page. As a result, many of the generic JS auth libraries include one or more web frameworks within them. For this reason, many users will find it preferrable to follow a SvelteKit-specific guide such as the examples found in [Lucia](https://lucia-auth.com/) rather than having multiple web frameworks inside their project.
# Performance
Out of the box, SvelteKit does a lot of work to make your applications as performant as possible:
- Code-splitting, so that only the code you need for the current page is loaded
- Asset preloading, so that 'waterfalls' (of files requesting other files) are prevented
- File hashing, so that your assets can be cached forever
- Request coalescing, so that data fetched from separate server `load` functions is grouped into a single HTTP request
- Parallel loading, so that separate universal `load` functions fetch data simultaneously
- Data inlining, so that requests made with `fetch` during server rendering can be replayed in the browser without issuing a new request
- Conservative invalidation, so that `load` functions are only re-run when necessary
- Prerendering (configurable on a per-route basis, if necessary) so that pages without dynamic data can be served instantaneously
- Link preloading, so that data and code requirements for a client-side navigation are eagerly anticipated
Nevertheless, we can't (yet) eliminate all sources of slowness. To eke out maximum performance, you should be mindful of the following tips.
## Diagnosing issues
Google's [PageSpeed Insights](https://pagespeed.web.dev/) and (for more advanced analysis) [WebPageTest](https://www.webpagetest.org/) are excellent ways to understand the performance characteristics of a site that is already deployed to the internet.
Your browser also includes useful developer tools for analysing your site, whether deployed or running locally:
* Chrome - [Lighthouse](https://developer.chrome.com/docs/lighthouse/overview#devtools), [Network](https://developer.chrome.com/docs/devtools/network), and [Performance](https://developer.chrome.com/docs/devtools/performance) devtools
* Edge - [Lighthouse](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/lighthouse/lighthouse-tool), [Network](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/network/), and [Performance](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/evaluate-performance/) devtools
* Firefox - [Network](https://firefox-source-docs.mozilla.org/devtools-user/network_monitor/) and [Performance](https://hacks.mozilla.org/2022/03/performance-tool-in-firefox-devtools-reloaded/) devtools
* Safari - [enhancing the performance of your webpage](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/Web_Inspector_Tutorial/EnhancingyourWebpagesPerformance/EnhancingyourWebpagesPerformance.html)
Note that your site running locally in `dev` mode will exhibit different behaviour than your production app, so you should do performance testing in [preview](building-your-app#Preview-your-app) mode after building.
### Instrumenting
If you see in the network tab of your browser that an API call is taking a long time and you'd like to understand why, you may consider instrumenting your backend with a tool like [OpenTelemetry](https://opentelemetry.io/) or [Server-Timing headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing).
## Optimizing assets
### Images
Reducing the size of image files is often one of the most impactful changes you can make to a site's performance. Svelte provides the `@sveltejs/enhanced-img` package, detailed on the [images](images) page, for making this easier. Additionally, Lighthouse is useful for identifying the worst offenders.
### Videos
Video files can be very large, so extra care should be taken to ensure that they're optimized:
- Compress videos with tools such as [Handbrake](https://handbrake.fr/). Consider converting the videos to web-friendly formats such as `.webm` or `.mp4`.
- You can [lazy-load videos](https://web.dev/articles/lazy-loading-video) located below the fold with `preload="none"` (though note that this will slow down playback when the user _does_ initiate it).
- Strip the audio track out of muted videos using a tool like [FFmpeg](https://ffmpeg.org/).
### Fonts
SvelteKit automatically preloads critical `.js` and `.css` files when the user visits a page, but it does _not_ preload fonts by default, since this may cause unnecessary files (such as font weights that are referenced by your CSS but not actually used on the current page) to be downloaded. Having said that, preloading fonts correctly can make a big difference to how fast your site feels. In your [`handle`](hooks#Server-hooks-handle) hook, you can call `resolve` with a `preload` filter that includes your fonts.
You can reduce the size of font files by [subsetting](https://web.dev/learn/performance/optimize-web-fonts#subset_your_web_fonts) your fonts.
## Reducing code size
### Svelte version
We recommend running the latest version of Svelte. Svelte 5 is smaller and faster than Svelte 4, which is smaller and faster than Svelte 3.
### Packages
[`rollup-plugin-visualizer`](https://www.npmjs.com/package/rollup-plugin-visualizer) can be helpful for identifying which packages are contributing the most to the size of your site. You may also find opportunities to remove code by manually inspecting the build output (use `build: { minify: false }` in your [Vite config](https://vitejs.dev/config/build-options.html#build-minify) to make the output readable, but remember to undo that before deploying your app), or via the network tab of your browser's devtools.
### External scripts
Try to minimize the number of third-party scripts running in the browser. For example, instead of using JavaScript-based analytics consider using server-side implementations, such as those offered by many platforms with SvelteKit adapters including [Cloudflare](https://www.cloudflare.com/web-analytics/), [Netlify](https://docs.netlify.com/monitor-sites/site-analytics/), and [Vercel](https://vercel.com/docs/analytics).
To run third party scripts in a web worker (which avoids blocking the main thread), use [Partytown's SvelteKit integration](https://partytown.builder.io/sveltekit).
### Selective loading
Code imported with static `import` declarations will be automatically bundled with the rest of your page. If there is a piece of code you need only when some condition is met, use the dynamic `import(...)` form to selectively lazy-load the component.
## Navigation
### Preloading
You can speed up client-side navigations by eagerly preloading the necessary code and data, using [link options](link-options). This is configured by default on the `` element when you create a new SvelteKit app.
### Non-essential data
For slow-loading data that isn't needed immediately, the object returned from your `load` function can contain promises rather than the data itself. For server `load` functions, this will cause the data to [stream](load#Streaming-with-promises) in after the navigation (or initial page load).
### Preventing waterfalls
One of the biggest performance killers is what is referred to as a _waterfall_, which is a series of requests that is made sequentially. This can happen on the server or in the browser, but is especially costly when dealing with data that has to travel further or across slower networks, such as a mobile user making a call to a distant server.
In the browser, waterfalls can occur when your HTML kicks off request chains such as requesting JS which requests CSS which requests a background image and web font. SvelteKit will largely solve this class of problems for you by adding [`modulepreload`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/modulepreload) tags or headers, but you should view [the network tab in your devtools](#Diagnosing-issues) to check whether additional resources need to be preloaded.
- Pay special attention to this if you use [web fonts](#Optimizing-assets-Fonts) since they need to be handled manually.
- Enabling [single page app (SPA) mode](single-page-apps) will cause such waterfalls. With SPA mode, an empty page is generated, which fetches JavaScript, which ultimately loads and renders the page. This results in extra network round trips before a single pixel can be displayed.
Waterfalls can also occur on calls to the backend whether made from the browser or server. E.g. if a universal `load` function makes an API call to fetch the current user, then uses the details from that response to fetch a list of saved items, and then uses _that_ response to fetch the details for each item, the browser will end up making multiple sequential requests. This is deadly for performance, especially for users that are physically located far from your backend.
- Avoid this issue by using [server `load` functions](load#Universal-vs-server) to make requests to backend services that are dependencies from the server rather than from the browser. Note, however, that server `load` functions are also not immune to waterfalls (though they are much less costly since they rarely involve round trips with high latency). For example, if you query a database to get the current user and then use that data to make a second query for a list of saved items, it will typically be more performant to issue a single query with a database join.
## Hosting
Your frontend should be located in the same data center as your backend to minimize latency. For sites with no central backend, many SvelteKit adapters support deploying to the _edge_, which means handling each user's requests from a nearby server. This can reduce load times significantly. Some adapters even support [configuring deployment on a per-route basis](page-options#config). You should also consider serving images from a CDN (which are typically edge networks) — the hosts for many SvelteKit adapters will do this automatically.
Ensure your host uses HTTP/2 or newer. Vite's code splitting creates numerous small files for improved cacheability, which results in excellent performance, but this does assume that your files can be loaded in parallel with HTTP/2.
## Further reading
For the most part, building a performant SvelteKit app is the same as building any performant web app. You should be able to apply information from general performance resources such as [Core Web Vitals](https://web.dev/explore/learn-core-web-vitals) to any web experience you build.
# Icons
## CSS
A great way to use icons is to define them purely via CSS. Iconify offers support for [many popular icon sets](https://icon-sets.iconify.design/) that [can be included via CSS](https://iconify.design/docs/usage/css/). This method can also be used with popular CSS frameworks by leveraging the Iconify [Tailwind CSS plugin](https://iconify.design/docs/usage/css/tailwind/) or [UnoCSS plugin](https://iconify.design/docs/usage/css/unocss/). As opposed to libraries based on Svelte components, it doesn't require each icon to be imported into your `.svelte` file.
## Svelte
There are many [icon libraries for Svelte](/packages#icons). When choosing an icon library, it is recommended to avoid those that provide a `.svelte` file per icon, as these libraries can have thousands of `.svelte` files which really slow down [Vite's dependency optimization](https://vite.dev/guide/dep-pre-bundling.html). This can become especially pathological if the icons are imported both via an umbrella import and subpath import [as described in the `vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies).
# Images
Images can have a big impact on your app's performance. For best results, you should optimize them by doing the following:
- generate optimal formats like `.avif` and `.webp`
- create different sizes for different screens
- ensure that assets can be cached effectively
Doing this manually is tedious. There are a variety of techniques you can use, depending on your needs and preferences.
## Vite's built-in handling
[Vite will automatically process imported assets](https://vitejs.dev/guide/assets.html) for improved performance. This includes assets referenced via the CSS `url()` function. Hashes will be added to the filenames so that they can be cached, and assets smaller than `assetsInlineLimit` will be inlined. Vite's asset handling is most often used for images, but is also useful for video, audio, etc.
```svelte
` rather than `` tag will be replaced with an `` providing multiple image types and sizes. It's only possible to downscale images without losing quality, which means that you should provide the highest resolution image that you need — smaller versions will be generated for the various device types that may request an image.
You should provide your image at 2x resolution for HiDPI displays (a.k.a. retina displays). `` will automatically take care of serving smaller versions to smaller devices.
> [!NOTE] if you wish to use a [tag name CSS selector](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Styling_basics/Basic_selectors#type_selectors) in your `
```
### `srcset` and `sizes`
If you have a large image, such as a hero image taking the width of the design, you should specify `sizes` so that smaller versions are requested on smaller devices. E.g. if you have a 1280px image you may want to specify something like:
```svelte
` will generate small images for smaller devices and populate the `srcset` attribute.
The smallest picture generated automatically will have a width of 540px. If you'd like smaller images or would otherwise like to specify custom widths, you can do that with the `w` query parameter:
```svelte
` tags with multiple sources. Finally, some CDNs may generate images lazily, which could have a negative performance impact for sites with low traffic and frequently changing images.
CDNs can generally be used without any need for a library. However, there are a number of libraries with Svelte support that make it easier. [`@unpic/svelte`](https://unpic.pics/img/svelte/) is a CDN-agnostic library with support for a large number of providers. You may also find that specific CDNs like [Cloudinary](https://svelte.cloudinary.dev/) have Svelte support. Finally, some content management systems (CMS) which support Svelte (such as [Contentful](https://www.contentful.com/sveltekit-starter-guide/), [Storyblok](https://github.com/storyblok/storyblok-svelte), and [Contentstack](https://www.contentstack.com/docs/developers/sample-apps/build-a-starter-website-with-sveltekit-and-contentstack)) have built-in support for image handling.
## Best practices
- For each image type, use the appropriate solution from those discussed above. You can mix and match all three solutions in one project. For example, you may use Vite's built-in handling to provide images for `` tag) triggers a full page reload. When this happens, screen readers and other assistive technology will read out the new page's title so that users understand that the page has changed.
Since navigation between pages in SvelteKit happens without reloading the page (known as [client-side routing](glossary#Routing)), SvelteKit injects a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) onto the page that will read out the new page name after each navigation. This determines the page name to announce by inspecting the `` element.
Because of this behavior, every page in your app should have a unique, descriptive title. In SvelteKit, you can do this by placing a `<svelte:head>` element on each page:
```svelte
<!--- file: src/routes/+page.svelte --->
<svelte:head>
<title>Todo List
```
This will allow screen readers and other assistive technology to identify the new page after a navigation occurs. Providing a descriptive title is also important for [SEO](seo#Manual-setup-title-and-meta).
## Focus management
In traditional server-rendered applications, every navigation will reset focus to the top of the page. This ensures that people browsing the web with a keyboard or screen reader will start interacting with the page from the beginning.
To simulate this behavior during client-side routing, SvelteKit focuses the `` element after each navigation and [enhanced form submission](form-actions#Progressive-enhancement). There is one exception - if an element with the [`autofocus`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus) attribute is present, SvelteKit will focus that element instead. Make sure to [consider the implications for assistive technology](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autofocus#accessibility_considerations) when using that attribute.
If you want to customize SvelteKit's focus management, you can use the `afterNavigate` hook:
```js
/// ` and `<meta name="description">` elements inside a [`<svelte:head>`](../svelte/svelte-head). Guidance on how to write descriptive titles and descriptions, along with other suggestions on making content understandable by search engines, can be found on Google's [Lighthouse SEO audits](https://web.dev/lighthouse-seo/) documentation.
> [!NOTE] A common pattern is to return SEO-related `data` from page [`load`](load) functions, then use it (as [`page.data`]($app-state)) in a `<svelte:head>` in your root [layout](routing#layout).
### Sitemaps
[Sitemaps](https://developers.google.com/search/docs/advanced/sitemaps/build-sitemap) help search engines prioritize pages within your site, particularly when you have a large amount of content. You can create a sitemap dynamically using an endpoint:
```js
/// file: src/routes/sitemap.xml/+server.js
export async function GET() {
return new Response(
`
<?xml version="1.0" encoding="UTF-8" ?>
<urlset
xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml"
xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0"
xmlns:news="http://www.google.com/schemas/sitemap-news/0.9"
xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"
xmlns:video="http://www.google.com/schemas/sitemap-video/1.1"
>
<!-- <url> elements go here -->
</urlset>`.trim(),
{
headers: {
'Content-Type': 'application/xml'
}
}
);
}
```
### AMP
An unfortunate reality of modern web development is that it is sometimes necessary to create an [Accelerated Mobile Pages (AMP)](https://amp.dev/) version of your site. In SvelteKit this can be done by setting the [`inlineStyleThreshold`](configuration#inlineStyleThreshold) option...
```js
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
// since <link rel="stylesheet"> isn't
// allowed, inline all styles
inlineStyleThreshold: Infinity
}
};
export default config;
```
...disabling `csr` in your root `+layout.js`/`+layout.server.js`...
```js
/// file: src/routes/+layout.server.js
export const csr = false;
```
...adding `amp` to your `app.html`
```html
<html amp>
...
```
...and transforming the HTML using `transformPageChunk` along with `transform` imported from `@sveltejs/amp`:
```js
/// file: src/hooks.server.js
import * as amp from '@sveltejs/amp';
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
let buffer = '';
return await resolve(event, {
transformPageChunk: ({ html, done }) => {
buffer += html;
if (done) return amp.transform(buffer);
}
});
}
```
To prevent shipping any unused CSS as a result of transforming the page to amp, we can use [`dropcss`](https://www.npmjs.com/package/dropcss):
```js
// @filename: ambient.d.ts
declare module 'dropcss';
// @filename: index.js
// ---cut---
/// file: src/hooks.server.js
// @errors: 2307
import * as amp from '@sveltejs/amp';
import dropcss from 'dropcss';
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
let buffer = '';
return await resolve(event, {
transformPageChunk: ({ html, done }) => {
buffer += html;
if (done) {
let css = '';
const markup = amp
.transform(buffer)
.replace('⚡', 'amp') // dropcss can't handle this character
.replace(/<style amp-custom([^>]*?)>([^]+?)<\/style>/, (match, attributes, contents) => {
css = contents;
return `<style amp-custom${attributes}></style>`;
});
css = dropcss({ css, html: markup }).css;
return markup.replace('</style>', `${css}</style>`);
}
}
});
}
```
> [!NOTE] It's a good idea to use the `handle` hook to validate the transformed HTML using `amphtml-validator`, but only if you're prerendering pages since it's very slow.
# Frequently asked questions
## Other resources
Please see [the Svelte FAQ](../svelte/faq) and [`vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md) as well for the answers to questions deriving from those libraries.
## What can I make with SvelteKit?
See [the documentation regarding project types](project-types) for more details.
## How do I include details from package.json in my application?
If you'd like to include your application's version number or other information from `package.json` in your application, you can load JSON like so:
```ts
// @errors: 2732
/// file: svelte.config.js
import pkg from './package.json' with { type: 'json' };
```
## How do I fix the error I'm getting trying to include a package?
Most issues related to including a library are due to incorrect packaging. You can check if a library's packaging is compatible with Node.js by entering it into [the publint website](https://publint.dev/).
Here are a few things to keep in mind when checking if a library is packaged correctly:
- `exports` takes precedence over the other entry point fields such as `main` and `module`. Adding an `exports` field may not be backwards-compatible as it prevents deep imports.
- ESM files should end with `.mjs` unless `"type": "module"` is set in which any case CommonJS files should end with `.cjs`.
- `main` should be defined if `exports` is not. It should be either a CommonJS or ESM file and adhere to the previous bullet. If a `module` field is defined, it should refer to an ESM file.
- Svelte components should be distributed as uncompiled `.svelte` files with any JS in the package written as ESM only. Custom script and style languages, like TypeScript and SCSS, should be preprocessed as vanilla JS and CSS respectively. We recommend using [`svelte-package`](./packaging) for packaging Svelte libraries, which will do this for you.
Libraries work best in the browser with Vite when they distribute an ESM version, especially if they are dependencies of a Svelte component library. You may wish to suggest to library authors that they provide an ESM version. However, CommonJS (CJS) dependencies should work as well since, by default, [`vite-plugin-svelte` will ask Vite to pre-bundle them](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies) using `esbuild` to convert them to ESM.
If you are still encountering issues we recommend searching both [the Vite issue tracker](https://github.com/vitejs/vite/issues) and the issue tracker of the library in question. Sometimes issues can be worked around by fiddling with the [`optimizeDeps`](https://vitejs.dev/config/#dep-optimization-options) or [`ssr`](https://vitejs.dev/config/#ssr-options) config values though we recommend this as only a short-term workaround in favor of fixing the library in question.
## How do I use the view transitions API?
While SvelteKit does not have any specific integration with [view transitions](https://developer.chrome.com/docs/web-platform/view-transitions/), you can call `document.startViewTransition` in [`onNavigate`]($app-navigation#onNavigate) to trigger a view transition on every client-side navigation.
```js
// @errors: 2339 2810
import { onNavigate } from '$app/navigation';
onNavigate((navigation) => {
if (!document.startViewTransition) return;
return new Promise((resolve) => {
document.startViewTransition(async () => {
resolve();
await navigation.complete;
});
});
});
```
For more, see ["Unlocking view transitions"](/blog/view-transitions) on the Svelte blog.
## How do I set up a database?
Put the code to query your database in a [server route](./routing#server) - don't query the database in .svelte files. You can create a `db.js` or similar that sets up a connection immediately and makes the client accessible throughout the app as a singleton. You can execute any one-time setup code in `hooks.server.js` and import your database helpers into any endpoint that needs them.
You can use [the Svelte CLI](/docs/cli/overview) to automatically set up database integrations.
## How do I use a client-side library accessing `document` or `window`?
If you need access to the `document` or `window` variables or otherwise need code to run only on the client-side you can wrap it in a `browser` check:
```js
/// <reference types="@sveltejs/kit" />
// ---cut---
import { browser } from '$app/environment';
if (browser) {
// client-only code here
}
```
You can also run code in `onMount` if you'd like to run it after the component has been first rendered to the DOM:
```js
// @filename: ambient.d.ts
// @lib: ES2015
declare module 'some-browser-only-library';
// @filename: index.js
// ---cut---
import { onMount } from 'svelte';
onMount(async () => {
const { method } = await import('some-browser-only-library');
method('hello world');
});
```
If the library you'd like to use is side-effect free you can also statically import it and it will be tree-shaken out in the server-side build where `onMount` will be automatically replaced with a no-op:
```js
// @filename: ambient.d.ts
// @lib: ES2015
declare module 'some-browser-only-library';
// @filename: index.js
// ---cut---
import { onMount } from 'svelte';
import { method } from 'some-browser-only-library';
onMount(() => {
method('hello world');
});
```
Finally, you may also consider using an `{#await}` block:
```svelte
<!--- file: index.svelte --->
<script>
import { browser } from '$app/environment';
const ComponentConstructor = browser ?
import('some-browser-only-library').then((module) => module.Component) :
new Promise(() => {});
</script>
{#await ComponentConstructor}
<p>Loading...</p>
{:then component}
<svelte:component this={component} />
{:catch error}
<p>Something went wrong: {error.message}</p>
{/await}
```
## How do I use a different backend API server?
You can use [`event.fetch`](./load#Making-fetch-requests) to request data from an external API server, but be aware that you would need to deal with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), which will result in complications such as generally requiring requests to be preflighted resulting in higher latency. Requests to a separate subdomain may also increase latency due to an additional DNS lookup, TLS setup, etc. If you wish to use this method, you may find [`handleFetch`](./hooks#Server-hooks-handleFetch) helpful.
Another approach is to set up a proxy to bypass CORS headaches. In production, you would rewrite a path like `/api` to the API server; for local development, use Vite's [`server.proxy`](https://vitejs.dev/config/server-options.html#server-proxy) option.
How to setup rewrites in production will depend on your deployment platform. If rewrites aren't an option, you could alternatively add an [API route](./routing#server):
```js
/// file: src/routes/api/[...path]/+server.js
/** @type {import('./$types').RequestHandler} */
export function GET({ params, url }) {
return fetch(`https://example.com/${params.path + url.search}`);
}
```
(Note that you may also need to proxy `POST`/`PATCH` etc requests, and forward `request.headers`, depending on your needs.)
## How do I use middleware?
`adapter-node` builds a middleware that you can use with your own server for production mode. In dev, you can add middleware to Vite by using a Vite plugin. For example:
```js
// @errors: 2322
// @filename: ambient.d.ts
declare module '@sveltejs/kit/vite'; // TODO this feels unnecessary, why can't it 'see' the declarations?
// @filename: index.js
// ---cut---
import { sveltekit } from '@sveltejs/kit/vite';
/** @type {import('vite').Plugin} */
const myPlugin = {
name: 'log-request-middleware',
configureServer(server) {
server.middlewares.use((req, res, next) => {
console.log(`Got request ${req.url}`);
next();
});
}
};
/** @type {import('vite').UserConfig} */
const config = {
plugins: [myPlugin, sveltekit()]
};
export default config;
```
See [Vite's `configureServer` docs](https://vitejs.dev/guide/api-plugin.html#configureserver) for more details including how to control ordering.
## How do I use Yarn?
### Does it work with Yarn 2?
Sort of. The Plug'n'Play feature, aka 'pnp', is broken (it deviates from the Node module resolution algorithm, and [doesn't yet work with native JavaScript modules](https://github.com/yarnpkg/berry/issues/638) which SvelteKit — along with an [increasing number of packages](https://blog.sindresorhus.com/get-ready-for-esm-aa53530b3f77) — uses). You can use `nodeLinker: 'node-modules'` in your [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) file to disable pnp, but it's probably easier to just use npm or [pnpm](https://pnpm.io/), which is similarly fast and efficient but without the compatibility headaches.
### How do I use with Yarn 3?
Currently ESM Support within the latest Yarn (version 3) is considered [experimental](https://github.com/yarnpkg/berry/pull/2161).
The below seems to work although your results may vary. First create a new application:
```sh
yarn create svelte myapp
cd myapp
```
And enable Yarn Berry:
```sh
yarn set version berry
yarn install
```
One of the more interesting features of Yarn Berry is the ability to have a single global cache for packages, instead of having multiple copies for each project on the disk. However, setting `enableGlobalCache` to true causes building to fail, so it is recommended to add the following to the `.yarnrc.yml` file:
```yaml
nodeLinker: node-modules
```
This will cause packages to be downloaded into a local node_modules directory but avoids the above problem and is your best bet for using version 3 of Yarn at this point in time.
# Integrations
## `vitePreprocess`
[`vitePreprocess`](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/preprocess.md) preprocesses `<style>` and `<script>` tags in `.svelte` files.
```js
// svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
/** @type {import('@sveltejs/kit').Config} */
const config = {
preprocess: [
vitePreprocess({
style: true, // default value
script: false // default value
})
]
};
export default config;
```
### `style`
Use `vitePreprocess()` to enable CSS preprocessors in `<style>` tags: PostCSS, SCSS, Less, Stylus, and SugarSS.
### `script`
Use `vitePreprocess({ script: true })` if:
- your project is before Svelte 5
- you are using advanced TypeScript features that emit code _(check [`vitePreprocess`](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/preprocess.md) documentation)_
> [!NOTE]
TypeScript is supported natively in Svelte 5, so if you are using Svelte 5 and you don't need to use advanced TypeScript features that emit code, you probably don't need to use `vitePreprocess`.
## Add-ons
Run [`npx sv add`](/docs/cli/sv-add) to setup many different complex integrations with a single command including:
- prettier (formatting)
- eslint (linting)
- vitest (unit testing)
- playwright (e2e testing)
- lucia (auth)
- tailwind (CSS)
- drizzle (DB)
- paraglide (i18n)
- mdsvex (markdown)
- storybook (frontend workshop)
## Packages
Check out [the packages page](/packages) for a curated set of high quality Svelte packages. You can also see [sveltesociety.dev](https://sveltesociety.dev/) for additional libraries, templates, and resources.
## Additional integrations
### `svelte-preprocess`
`svelte-preprocess` has some additional functionality not found in `vitePreprocess` such as support for Pug, Babel, and global styles. However, `vitePreprocess` may be faster and require less configuration, so it is used by default. Note that CoffeeScript is [not supported](https://github.com/sveltejs/kit/issues/2920#issuecomment-996469815) by SvelteKit.
You will need to install `svelte-preprocess` with `npm i -D svelte-preprocess` and [add it to your `svelte.config.js`](https://github.com/sveltejs/svelte-preprocess/blob/main/docs/usage.md#with-svelte-config). After that, you will often need to [install the corresponding library](https://github.com/sveltejs/svelte-preprocess/blob/main/docs/getting-started.md) such as `npm i -D sass` or `npm i -D less`.
## Vite plugins
Since SvelteKit projects are built with Vite, you can use Vite plugins to enhance your project. See a list of available plugins at [`vitejs/awesome-vite`](https://github.com/vitejs/awesome-vite?tab=readme-ov-file#plugins).
## Integration FAQs
[The SvelteKit FAQ](./faq) answers many questions about how to do X with SvelteKit, which may be helpful if you still have questions.
# Breakpoint Debugging
In addition to the [`@debug`](../svelte/@debug) tag, you can also debug Svelte and SvelteKit projects using breakpoints within various tools and development environments. This includes both frontend and backend code.
The following guides assume your JavaScript runtime environment is Node.js.
## Visual Studio Code
With the built-in debug terminal, you can set up breakpoints in source files within VSCode.
1. Open the command palette: `CMD/Ctrl` + `Shift` + `P`.
2. Find and launch "Debug: JavaScript Debug Terminal".
3. Start your project using the debug terminal. For example: `npm run dev`.
4. Set some breakpoints in your client or server-side source code.
5. Trigger the breakpoint.
### Launch via debug pane
You may alternatively set up a `.vscode/launch.json` in your project. To set one up automatically:
1. Go to the "Run and Debug" pane.
2. In the "Run" select menu, choose "Node.js...".
3. Select the "run script" that corresponds to your project, such as "Run script: dev".
4. Press the "Start debugging" play button, or hit `F5` to begin breakpoint debugging.
Here's an example `launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"command": "npm run dev",
"name": "Run development server",
"request": "launch",
"type": "node-terminal"
}
]
}
```
Further reading: <https://code.visualstudio.com/docs/editor/debugging>.
## Other Editors
If you use a different editor, these community guides might be useful for you:
- [WebStorm Svelte: Debug Your Application](https://www.jetbrains.com/help/webstorm/svelte.html#ws_svelte_debug)
- [Debugging JavaScript Frameworks in Neovim](https://theosteiner.de/debugging-javascript-frameworks-in-neovim)
## Google Chrome and Microsoft Edge Developer Tools
It's possible to debug Node.js applications using a browser-based debugger.
> [!NOTE] Note this only works with debugging client-side SvelteKit source maps.
1. Run the `--inspect` flag when starting the Vite server with Node.js. For instance: `NODE_OPTIONS="--inspect" npm run dev`
2. Open your site in a new tab. Typically at `localhost:5173`.
3. Open your browser's dev tools, and click on the "Open dedicated DevTools for Node.js" icon near the top-left. It should display the Node.js logo.
4. Set up breakpoints and debug your application.
You may alternatively open the debugger devtools by navigating to `chrome://inspect` in Google Chrome, or `edge://inspect` in Microsoft Edge.
## References
- [Debugging Node.js](https://nodejs.org/en/learn/getting-started/debugging)
# Migrating to SvelteKit v2
Upgrading from SvelteKit version 1 to version 2 should be mostly seamless. There are a few breaking changes to note, which are listed here. You can use `npx sv migrate sveltekit-2` to migrate some of these changes automatically.
We highly recommend upgrading to the most recent 1.x version before upgrading to 2.0, so that you can take advantage of targeted deprecation warnings. We also recommend [updating to Svelte 4](../svelte/v4-migration-guide) first: Later versions of SvelteKit 1.x support it, and SvelteKit 2.0 requires it.
## `redirect` and `error` are no longer thrown by you
Previously, you had to `throw` the values returned from `error(...)` and `redirect(...)` yourself. In SvelteKit 2 this is no longer the case — calling the functions is sufficient.
```js
import { error } from '@sveltejs/kit'
// ...
---throw error(500, 'something went wrong');---
+++error(500, 'something went wrong');+++
```
`svelte-migrate` will do these changes automatically for you.
If the error or redirect is thrown inside a `try {...}` block (hint: don't do this!), you can distinguish them from unexpected errors using [`isHttpError`](@sveltejs-kit#isHttpError) and [`isRedirect`](@sveltejs-kit#isRedirect) imported from `@sveltejs/kit`.
## path is required when setting cookies
When receiving a `Set-Cookie` header that doesn't specify a `path`, browsers will [set the cookie path](https://www.rfc-editor.org/rfc/rfc6265#section-5.1.4) to the parent of the resource in question. This behaviour isn't particularly helpful or intuitive, and frequently results in bugs because the developer expected the cookie to apply to the domain as a whole.
As of SvelteKit 2.0, you need to set a `path` when calling `cookies.set(...)`, `cookies.delete(...)` or `cookies.serialize(...)` so that there's no ambiguity. Most of the time, you probably want to use `path: '/'`, but you can set it to whatever you like, including relative paths — `''` means 'the current path', `'.'` means 'the current directory'.
```js
/** @type {import('./$types').PageServerLoad} */
export function load({ cookies }) {
cookies.set(name, value, +++{ path: '/' }+++);
return { response }
}
```
`svelte-migrate` will add comments highlighting the locations that need to be adjusted.
## Top-level promises are no longer awaited
In SvelteKit version 1, if the top-level properties of the object returned from a `load` function were promises, they were automatically awaited. With the introduction of [streaming](/blog/streaming-snapshots-sveltekit) this behavior became a bit awkward as it forces you to nest your streamed data one level deep.
As of version 2, SvelteKit no longer differentiates between top-level and non-top-level promises. To get back the blocking behavior, use `await` (with `Promise.all` to prevent waterfalls, where appropriate):
```js
// @filename: ambient.d.ts
declare const url: string;
// @filename: index.js
// ---cut---
// If you have a single promise
/** @type {import('./$types').PageServerLoad} */
export +++async+++ function load({ fetch }) {
const response = +++await+++ fetch(url).then(r => r.json());
return { response }
}
```
```js
// @filename: ambient.d.ts
declare const url1: string;
declare const url2: string;
// @filename: index.js
// ---cut---
// If you have multiple promises
/** @type {import('./$types').PageServerLoad} */
export +++async+++ function load({ fetch }) {
--- const a = fetch(url1).then(r => r.json());---
--- const b = fetch(url2).then(r => r.json());---
+++ const [a, b] = await Promise.all([
fetch(url1).then(r => r.json()),
fetch(url2).then(r => r.json()),
]);+++
return { a, b };
}
```
## goto(...) changes
`goto(...)` no longer accepts external URLs. To navigate to an external URL, use `window.location.href = url`. The `state` object now determines `$page.state` and must adhere to the `App.PageState` interface, if declared. See [shallow routing](shallow-routing) for more details.
## paths are now relative by default
In SvelteKit 1, `%sveltekit.assets%` in your `app.html` was replaced with a relative path by default (i.e. `.` or `..` or `../..` etc, depending on the path being rendered) during server-side rendering unless the [`paths.relative`](configuration#paths) config option was explicitly set to `false`. The same was true for `base` and `assets` imported from `$app/paths`, but only if the `paths.relative` option was explicitly set to `true`.
This inconsistency is fixed in version 2. Paths are either always relative or always absolute, depending on the value of [`paths.relative`](configuration#paths). It defaults to `true` as this results in more portable apps: if the `base` is something other than the app expected (as is the case when viewed on the [Internet Archive](https://archive.org/), for example) or unknown at build time (as is the case when deploying to [IPFS](https://ipfs.tech/) and so on), fewer things are likely to break.
## Server fetches are not trackable anymore
Previously it was possible to track URLs from `fetch`es on the server in order to rerun load functions. This poses a possible security risk (private URLs leaking), and for this reason it was behind the `dangerZone.trackServerFetches` setting, which is now removed.
## `preloadCode` arguments must be prefixed with `base`
SvelteKit exposes two functions, [`preloadCode`]($app-navigation#preloadCode) and [`preloadData`]($app-navigation#preloadData), for programmatically loading the code and data associated with a particular path. In version 1, there was a subtle inconsistency — the path passed to `preloadCode` did not need to be prefixed with the `base` path (if set), while the path passed to `preloadData` did.
This is fixed in SvelteKit 2 — in both cases, the path should be prefixed with `base` if it is set.
Additionally, `preloadCode` now takes a single argument rather than _n_ arguments.
## `resolvePath` has been removed
SvelteKit 1 included a function called `resolvePath` which allows you to resolve a route ID (like `/blog/[slug]`) and a set of parameters (like `{ slug: 'hello' }`) to a pathname. Unfortunately the return value didn't include the `base` path, limiting its usefulness in cases where `base` was set.
For this reason, SvelteKit 2 replaces `resolvePath` with a (slightly better named) function called `resolveRoute`, which is imported from `$app/paths` and which takes `base` into account.
```js
---import { resolvePath } from '@sveltejs/kit';
import { base } from '$app/paths';---
+++import { resolveRoute } from '$app/paths';+++
---const path = base + resolvePath('/blog/[slug]', { slug });---
+++const path = resolveRoute('/blog/[slug]', { slug });+++
```
`svelte-migrate` will do the method replacement for you, though if you later prepend the result with `base`, you need to remove that yourself.
## Improved error handling
Errors are handled inconsistently in SvelteKit 1. Some errors trigger the `handleError` hook but there is no good way to discern their status (for example, the only way to tell a 404 from a 500 is by seeing if `event.route.id` is `null`), while others (such as 405 errors for `POST` requests to pages without actions) don't trigger `handleError` at all, but should. In the latter case, the resulting `$page.error` will deviate from the [`App.Error`](types#Error) type, if it is specified.
SvelteKit 2 cleans this up by calling `handleError` hooks with two new properties: `status` and `message`. For errors thrown from your code (or library code called by your code) the status will be `500` and the message will be `Internal Error`. While `error.message` may contain sensitive information that should not be exposed to users, `message` is safe.
## Dynamic environment variables cannot be used during prerendering
The `$env/dynamic/public` and `$env/dynamic/private` modules provide access to _run time_ environment variables, as opposed to the _build time_ environment variables exposed by `$env/static/public` and `$env/static/private`.
During prerendering in SvelteKit 1, they are one and the same. This means that prerendered pages that make use of 'dynamic' environment variables are really 'baking in' build time values, which is incorrect. Worse, `$env/dynamic/public` is populated in the browser with these stale values if the user happens to land on a prerendered page before navigating to dynamically-rendered pages.
Because of this, dynamic environment variables can no longer be read during prerendering in SvelteKit 2 — you should use the `static` modules instead. If the user lands on a prerendered page, SvelteKit will request up-to-date values for `$env/dynamic/public` from the server (by default from a module called `/_app/env.js`) instead of reading them from the server-rendered HTML.
## `form` and `data` have been removed from `use:enhance` callbacks
If you provide a callback to [`use:enhance`](form-actions#Progressive-enhancement-use:enhance), it will be called with an object containing various useful properties.
In SvelteKit 1, those properties included `form` and `data`. These were deprecated some time ago in favour of `formElement` and `formData`, and have been removed altogether in SvelteKit 2.
## Forms containing file inputs must use `multipart/form-data`
If a form contains an `<input type="file">` but does not have an `enctype="multipart/form-data"` attribute, non-JS submissions will omit the file. SvelteKit 2 will throw an error if it encounters a form like this during a `use:enhance` submission to ensure that your forms work correctly when JavaScript is not present.
## Generated `tsconfig.json` is more strict
Previously, the generated `tsconfig.json` was trying its best to still produce a somewhat valid config when your `tsconfig.json` included `paths` or `baseUrl`. In SvelteKit 2, the validation is more strict and will warn when you use either `paths` or `baseUrl` in your `tsconfig.json`. These settings are used to generate path aliases and you should use [the `alias` config](configuration#alias) option in your `svelte.config.js` instead, to also create a corresponding alias for the bundler.
## `getRequest` no longer throws errors
The `@sveltejs/kit/node` module exports helper functions for use in Node environments, including `getRequest` which turns a Node [`ClientRequest`](https://nodejs.org/api/http.html#class-httpclientrequest) into a standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.
In SvelteKit 1, `getRequest` could throw if the `Content-Length` header exceeded the specified size limit. In SvelteKit 2, the error will not be thrown until later, when the request body (if any) is being read. This enables better diagnostics and simpler code.
## `vitePreprocess` is no longer exported from `@sveltejs/kit/vite`
Since `@sveltejs/vite-plugin-svelte` is now a peer dependency, SvelteKit 2 no longer re-exports `vitePreprocess`. You should import it directly from `@sveltejs/vite-plugin-svelte`.
## Updated dependency requirements
SvelteKit 2 requires Node `18.13` or higher, and the following minimum dependency versions:
- `svelte@4`
- `vite@5`
- `typescript@5`
- `@sveltejs/vite-plugin-svelte@3` (this is now required as a `peerDependency` of SvelteKit — previously it was directly depended upon)
- `@sveltejs/adapter-cloudflare@3` (if you're using these adapters)
- `@sveltejs/adapter-cloudflare-workers@2`
- `@sveltejs/adapter-netlify@3`
- `@sveltejs/adapter-node@2`
- `@sveltejs/adapter-static@3`
- `@sveltejs/adapter-vercel@4`
`svelte-migrate` will update your `package.json` for you.
As part of the TypeScript upgrade, the generated `tsconfig.json` (the one your `tsconfig.json` extends from) now uses `"moduleResolution": "bundler"` (which is recommended by the TypeScript team, as it properly resolves types from packages with an `exports` map in package.json) and `verbatimModuleSyntax` (which replaces the existing `importsNotUsedAsValues ` and `preserveValueImports` flags — if you have those in your `tsconfig.json`, remove them. `svelte-migrate` will do this for you).
## SvelteKit 2.12: $app/stores deprecated
SvelteKit 2.12 introduced `$app/state` based on the [Svelte 5 runes API](/docs/svelte/what-are-runes). `$app/state` provides everything that `$app/stores` provides but with more flexibility as to where and how you use it. Most importantly, the `page` object is now fine-grained, e.g. updates to `page.state` will not invalidate `page.data` and vice-versa.
As a consequence, `$app/stores` is deprecated and subject to be removed in SvelteKit 3. We recommend [upgrading to Svelte 5](/docs/svelte/v5-migration-guide), if you haven't already, and then migrate away from `$app/stores`. Most of the replacements should be pretty simple: Replace the `$app/stores` import with `$app/state` and remove the `$` prefixes from the usage sites.
```svelte
<script>
---import { page } from '$app/stores';---
+++import { page } from '$app/state';+++
</script>
---{$page.data}---
+++{page.data}+++
```
Use `npx sv migrate app-state` to auto-migrate most of your `$app/stores` usages inside `.svelte` components.
# Migrating from Sapper
SvelteKit is the successor to Sapper and shares many elements of its design.
If you have an existing Sapper app that you plan to migrate to SvelteKit, there are a number of changes you will need to make. You may find it helpful to view [some examples](additional-resources#Examples) while migrating.
## package.json
### type: "module"
Add `"type": "module"` to your `package.json`. You can do this step separately from the rest as part of an incremental migration if you are using Sapper 0.29.3
or newer.
### dependencies
Remove `polka` or `express`, if you're using one of those, and any middleware such as `sirv` or `compression`.
### devDependencies
Remove `sapper` from your `devDependencies` and replace it with `@sveltejs/kit` and whichever [adapter](adapters) you plan to use (see [next section](migrating#Project-files-Configuration)).
### scripts
Any scripts that reference `sapper` should be updated:
- `sapper build` should become `vite build` using the Node [adapter](adapters)
- `sapper export` should become `vite build` using the static [adapter](adapters)
- `sapper dev` should become `vite dev`
- `node __sapper__/build` should become `node build`
## Project files
The bulk of your app, in `src/routes`, can be left where it is, but several project files will need to be moved or updated.
### Configuration
Your `webpack.config.js` or `rollup.config.js` should be replaced with a `svelte.config.js`, as documented [here](configuration). Svelte preprocessor options should be moved to `config.preprocess`.
You will need to add an [adapter](adapters). `sapper build` is roughly equivalent to [adapter-node](adapter-node) while `sapper export` is roughly equivalent to [adapter-static](adapter-static), though you might prefer to use an adapter designed for the platform you're deploying to.
If you were using plugins for filetypes that are not automatically handled by [Vite](https://vitejs.dev), you will need to find Vite equivalents and add them to the [Vite config](project-structure#Project-files-vite.config.js).
### src/client.js
This file has no equivalent in SvelteKit. Any custom logic (beyond `sapper.start(...)`) should be expressed in your `+layout.svelte` file, inside an `onMount` callback.
### src/server.js
When using `adapter-node` the equivalent is a [custom server](adapter-node#Custom-server). Otherwise, this file has no direct equivalent, since SvelteKit apps can run in serverless environments.
### src/service-worker.js
Most imports from `@sapper/service-worker` have equivalents in [`$service-worker`]($service-worker):
- `files` is unchanged
- `routes` has been removed
- `shell` is now `build`
- `timestamp` is now `version`
### src/template.html
The `src/template.html` file should be renamed `src/app.html`.
Remove `%sapper.base%`, `%sapper.scripts%` and `%sapper.styles%`. Replace `%sapper.head%` with `%sveltekit.head%` and `%sapper.html%` with `%sveltekit.body%`. The `<div id="sapper">` is no longer necessary.
### src/node_modules
A common pattern in Sapper apps is to put your internal library in a directory inside `src/node_modules`. This doesn't work with Vite, so we use [`src/lib`]($lib) instead.
## Pages and layouts
### Renamed files
Routes now are made up of the folder name exclusively to remove ambiguity, the folder names leading up to a `+page.svelte` correspond to the route. See [the routing docs](routing) for an overview. The following shows a old/new comparison:
| Old | New |
| ------------------------- | ------------------------- |
| routes/about/index.svelte | routes/about/+page.svelte |
| routes/about.svelte | routes/about/+page.svelte |
Your custom error page component should be renamed from `_error.svelte` to `+error.svelte`. Any `_layout.svelte` files should likewise be renamed `+layout.svelte`. [Any other files are ignored](routing#Other-files).
### Imports
The `goto`, `prefetch` and `prefetchRoutes` imports from `@sapper/app` should be replaced with `goto`, `preloadData` and `preloadCode` imports respectively from [`$app/navigation`]($app-navigation).
The `stores` import from `@sapper/app` should be replaced — see the [Stores](migrating#Pages-and-layouts-Stores) section below.
Any files you previously imported from directories in `src/node_modules` will need to be replaced with [`$lib`]($lib) imports.
### Preload
As before, pages and layouts can export a function that allows data to be loaded before rendering takes place.
This function has been renamed from `preload` to [`load`](load), it now lives in a `+page.js` (or `+layout.js`) next to its `+page.svelte` (or `+layout.svelte`), and its API has changed. Instead of two arguments — `page` and `session` — there is a single `event` argument.
There is no more `this` object, and consequently no `this.fetch`, `this.error` or `this.redirect`. Instead, you can get [`fetch`](load#Making-fetch-requests) from the input methods, and both [`error`](load#Errors) and [`redirect`](load#Redirects) are now thrown.
### Stores
In Sapper, you would get references to provided stores like so:
```js
// @filename: ambient.d.ts
declare module '@sapper/app';
// @filename: index.js
// ---cut---
import { stores } from '@sapper/app';
const { preloading, page, session } = stores();
```
The `page` store still exists; `preloading` has been replaced with a `navigating` store that contains `from` and `to` properties. `page` now has `url` and `params` properties, but no `path` or `query`.
You access them differently in SvelteKit. `stores` is now `getStores`, but in most cases it is unnecessary since you can import `navigating`, and `page` directly from [`$app/stores`]($app-stores). If you're on Svelte 5 and SvelteKit 2.12 or higher, consider using [`$app/state`]($app-state) instead.
### Routing
Regex routes are no longer supported. Instead, use [advanced route matching](advanced-routing#Matching).
### Segments
Previously, layout components received a `segment` prop indicating the child segment. This has been removed; you should use the more flexible `$page.url.pathname` (or `page.url.pathname`) value to derive the segment you're interested in.
### URLs
In Sapper, all relative URLs were resolved against the base URL — usually `/`, unless the `basepath` option was used — rather than against the current page.
This caused problems and is no longer the case in SvelteKit. Instead, relative URLs are resolved against the current page (or the destination page, for `fetch` URLs in `load` functions) instead. In most cases, it's easier to use root-relative (i.e. starts with `/`) URLs, since their meaning is not context-dependent.
### <a> attributes
- `sapper:prefetch` is now `data-sveltekit-preload-data`
- `sapper:noscroll` is now `data-sveltekit-noscroll`
## Endpoints
In Sapper, [server routes](routing#server) received the `req` and `res` objects exposed by Node's `http` module (or the augmented versions provided by frameworks like Polka and Express).
SvelteKit is designed to be agnostic as to where the app is running — it could be running on a Node server, but could equally be running on a serverless platform or in a Cloudflare Worker. For that reason, you no longer interact directly with `req` and `res`. Your endpoints will need to be updated to match the new signature.
To support this environment-agnostic behavior, `fetch` is now available in the global context, so you don't need to import `node-fetch`, `cross-fetch`, or similar server-side fetch implementations in order to use it.
## Integrations
See [integrations](./integrations) for detailed information about integrations.
### HTML minifier
Sapper includes `html-minifier` by default. SvelteKit does not include this, but you can add it as a prod dependency and then use it through a [hook](hooks#Server-hooks-handle):
```js
// @filename: ambient.d.ts
/// <reference types="@sveltejs/kit" />
declare module 'html-minifier';
// @filename: index.js
// ---cut---
import { minify } from 'html-minifier';
import { building } from '$app/environment';
const minification_options = {
collapseBooleanAttributes: true,
collapseWhitespace: true,
conservativeCollapse: true,
decodeEntities: true,
html5: true,
ignoreCustomComments: [/^#/],
minifyCSS: true,
minifyJS: false,
removeAttributeQuotes: true,
removeComments: false, // some hydration code needs comments, so leave them in
removeOptionalTags: true,
removeRedundantAttributes: true,
removeScriptTypeAttributes: true,
removeStyleLinkTypeAttributes: true,
sortAttributes: true,
sortClassName: true
};
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
let page = '';
return resolve(event, {
transformPageChunk: ({ html, done }) => {
page += html;
if (done) {
return building ? minify(page, minification_options) : page;
}
}
});
}
```
Note that `prerendering` is `false` when using `vite preview` to test the production build of the site, so to verify the results of minifying, you'll need to inspect the built HTML files directly.
# Additional resources
## FAQs
Please see the [SvelteKit FAQ](faq) for solutions to common issues and helpful tips and tricks.
The [Svelte FAQ](../svelte/faq) and [`vite-plugin-svelte` FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md) may also be helpful for questions deriving from those libraries.
## Examples
We've written and published a few different SvelteKit sites as examples:
- [`sveltejs/realworld`](https://github.com/sveltejs/realworld) contains an example blog site
- [A HackerNews clone](https://github.com/sveltejs/sites/tree/master/sites/hn.svelte.dev)
- [`svelte.dev`](https://github.com/sveltejs/svelte.dev)
SvelteKit users have also published plenty of examples on GitHub, under the [#sveltekit](https://github.com/topics/sveltekit) and [#sveltekit-template](https://github.com/topics/sveltekit-template) topics, as well as on [the Svelte Society site](https://sveltesociety.dev/recipe/sveltekit-templates-and-examples-e789ed397e7f38fc). Note that these have not been vetted by the maintainers and may not be up to date.
## Support
You can ask for help on [Discord](/chat) and [StackOverflow](https://stackoverflow.com/questions/tagged/sveltekit). Please first search for information related to your issue in the FAQ, Google or another search engine, issue tracker, and Discord chat history in order to be respectful of others' time. There are many more people asking questions than answering them, so this will help in allowing the community to grow in a scalable fashion.
# Glossary
The core of SvelteKit provides a highly configurable rendering engine. This section describes some of the terms used when discussing rendering. A reference for setting these options is provided in the documentation above.
## CSR
Client-side rendering (CSR) is the generation of the page contents in the web browser using JavaScript.
In SvelteKit, client-side rendering will be used by default, but you can turn off JavaScript with [the `csr = false` page option](page-options#csr).
## Edge
Rendering on the edge refers to rendering an application in a content delivery network (CDN) near the user. Edge rendering allows the request and response for a page to travel a shorter distance thus improving latency.
## Hybrid app
SvelteKit uses a hybrid rendering mode by default where it loads the initial HTML from the server (SSR), and then updates the page contents on subsequent navigations via client-side rendering (CSR).
## Hydration
Svelte components store some state and update the DOM when the state is updated. When fetching data during SSR, by default SvelteKit will store this data and transmit it to the client along with the server-rendered HTML. The components can then be initialized on the client with that data without having to call the same API endpoints again. Svelte will then check that the DOM is in the expected state and attach event listeners in a process called hydration. Once the components are fully hydrated, they can react to changes to their properties just like any newly created Svelte component.
In SvelteKit, pages will be hydrated by default, but you can turn off JavaScript with [the `csr = false` page option](page-options#csr).
## ISR
Incremental static regeneration (ISR) allows you to generate static pages on your site as visitors request those pages without redeploying. This may reduces build times compared to [SSG](#SSG) sites with a large number of pages. You can do [ISR with `adapter-vercel`](adapter-vercel#Incremental-Static-Regeneration).
## MPA
Traditional applications that render each page view on the server — such as those written in languages other than JavaScript — are often referred to as multi-page apps (MPA).
## Prerendering
Prerendering means computing the contents of a page at build time and saving the HTML for display. This approach has the same benefits as traditional server-rendered pages, but avoids recomputing the page for each visitor and so scales nearly for free as the number of visitors increases. The tradeoff is that the build process is more expensive and prerendered content can only be updated by building and deploying a new version of the application.
Not all pages can be prerendered. The basic rule is this: for content to be prerenderable, any two users hitting it directly must get the same content from the server, and the page must not contain [actions](form-actions). Note that you can still prerender content that is loaded based on the page's parameters as long as all users will be seeing the same prerendered content.
Pre-rendered pages are not limited to static content. You can build personalized pages if user-specific data is fetched and rendered client-side. This is subject to the caveat that you will experience the downsides of not doing SSR for that content as discussed above.
In SvelteKit, you can control prerendering with [the `prerender` page option](page-options#prerender) and [`prerender` config](configuration#prerender) in `svelte.config.js`.
## PWA
A progressive web app (PWA) is an app that's built using web APIs and technologies, but functions like a mobile or desktop app. Sites served as [PWAs can be installed](https://web.dev/learn/pwa/installation), allowing you to add a shortcut to the application on your launcher, home screen, or start menu. Many PWAs will utilize [service workers](service-workers) to build offline capabilities.
## Routing
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 for the destination page. SvelteKit will then update the displayed contents on the client by rendering the component for the new page, which in turn can make calls to the necessary API endpoints. This process of updating the page on the client in response to attempted navigation is called client-side routing.
In SvelteKit, client-side routing will be used by default, but you can skip it with [`data-sveltekit-reload`](link-options#data-sveltekit-reload).
## SPA
A single-page app (SPA) is an application in which all requests to the server load a single HTML file which then does client-side rendering based on the requested URL. All navigation is handled on the client-side in a process called client-side routing with per-page contents being updated and common layout elements remaining largely unchanged. Throughout this site, when we refer to a SPA, we use this definition where a SPA simply serves an empty shell on the initial request. It should not be confused with a [hybrid app](#Hybrid-app), which serves HTML on the initial request. It has a large performance impact by forcing two network round trips before rendering can begin. Because SPA mode has large negative performance and SEO impacts, it is recommended only in very limited circumstances such as when being wrapped in a mobile app.
In SvelteKit, you can [build SPAs with `adapter-static`](single-page-apps).
## SSG
Static Site Generation (SSG) is a term that refers to a site where every page is prerendered. One benefit of fully prerendering a site is that you do not need to maintain or pay for servers to perform SSR. Once generated, the site can be served from CDNs, leading to great “time to first byte” performance. This delivery model is often referred to as JAMstack.
In SvelteKit, you can do static site generation by using [`adapter-static`](adapter-static) or by configuring every page to be prerendered using [the `prerender` page option](page-options#prerender) or [`prerender` config](configuration#prerender) in `svelte.config.js`.
## SSR
Server-side rendering (SSR) is the generation of the page contents on the server. Returning the page contents from the server via SSR or prerendering is highly preferred for performance and SEO. It significantly improves performance by avoiding the introduction of extra round trips necessary in a SPA, and makes your app accessible to users if JavaScript fails or is disabled (which happens [more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)). While some search engines can index content that is dynamically generated on the client-side, it is likely to take longer even in these cases.
In SvelteKit, pages are server-side rendered by default. You can disable SSR with [the `ssr` page option](page-options#ssr).
# @sveltejs/kit
```js
// @noErrors
import {
Server,
VERSION,
error,
fail,
invalid,
isActionFailure,
isHttpError,
isRedirect,
isValidationError,
json,
normalizeUrl,
redirect,
text
} from '@sveltejs/kit';
```
## Server
<div class="ts-block">
```dts
class Server {/*…*/}
```
<div class="ts-block-property">
```dts
constructor(manifest: SSRManifest);
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
init(options: ServerInitOptions): Promise<void>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
respond(request: Request, options: RequestOptions): Promise<Response>;
```
<div class="ts-block-property-details"></div>
</div></div>
## VERSION
<div class="ts-block">
```dts
const VERSION: string;
```
</div>
## error
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.
<div class="ts-block">
```dts
function error(status: number, body: App.Error): never;
```
</div>
<div class="ts-block">
```dts
function error(
status: number,
body?: {
message: string;
} extends App.Error
? App.Error | string | undefined
: never
): never;
```
</div>
## fail
Create an `ActionFailure` object. Call when form submission fails.
<div class="ts-block">
```dts
function fail(status: number): ActionFailure<undefined>;
```
</div>
<div class="ts-block">
```dts
function fail<T = undefined>(
status: number,
data: T
): ActionFailure<T>;
```
</div>
## invalid
<blockquote class="since note">
Available since 2.47.3
</blockquote>
Use this to throw a validation error to imperatively fail form validation.
Can be used in combination with `issue` passed to form actions to create field-specific issues.
```ts
import { invalid } from '@sveltejs/kit';
import { form } from '$app/server';
import { tryLogin } from '$lib/server/auth';
import * as v from 'valibot';
export const login = form(
v.object({ name: v.string(), _password: v.string() }),
async ({ name, _password }) => {
const success = tryLogin(name, _password);
if (!success) {
invalid('Incorrect username or password');
}
// ...
}
);
```
<div class="ts-block">
```dts
function invalid(
...issues: (StandardSchemaV1.Issue | string)[]
): never;
```
</div>
## isActionFailure
Checks whether this is an action failure thrown by `fail`.
<div class="ts-block">
```dts
function isActionFailure(e: unknown): e is ActionFailure;
```
</div>
## isHttpError
Checks whether this is an error thrown by `error`.
<div class="ts-block">
```dts
function isHttpError<T extends number>(
e: unknown,
status?: T
): e is HttpError_1 & {
status: T extends undefined ? never : T;
};
```
</div>
## isRedirect
Checks whether this is a redirect thrown by `redirect`.
<div class="ts-block">
```dts
function isRedirect(e: unknown): e is Redirect_1;
```
</div>
## isValidationError
<blockquote class="since note">
Available since 2.47.3
</blockquote>
Checks whether this is an validation error thrown by `invalid`.
<div class="ts-block">
```dts
function isValidationError(e: unknown): e is ActionFailure;
```
</div>
## json
Create a JSON `Response` object from the supplied data.
<div class="ts-block">
```dts
function json(data: any, init?: ResponseInit): Response;
```
</div>
## normalizeUrl
<blockquote class="since note">
Available since 2.18.0
</blockquote>
Strips possible SvelteKit-internal suffixes and trailing slashes from the URL pathname.
Returns the normalized URL as well as a method for adding the potential suffix back
based on a new pathname (possibly including search) or URL.
```js
// @errors: 7031
import { normalizeUrl } from '@sveltejs/kit';
const { url, denormalize } = normalizeUrl('/blog/post/__data.json');
console.log(url.pathname); // /blog/post
console.log(denormalize('/blog/post/a')); // /blog/post/a/__data.json
```
<div class="ts-block">
```dts
function normalizeUrl(url: URL | string): {
url: URL;
wasNormalized: boolean;
denormalize: (url?: string | URL) => URL;
};
```
</div>
## redirect
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.
Most common status codes:
* `303 See Other`: redirect as a GET request (often used after a form POST request)
* `307 Temporary Redirect`: redirect will keep the request method
* `308 Permanent Redirect`: redirect will keep the request method, SEO will be transferred to the new page
[See all redirect status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages)
<div class="ts-block">
```dts
function redirect(
status:
| 300
| 301
| 302
| 303
| 304
| 305
| 306
| 307
| 308
| ({} & number),
location: string | URL
): never;
```
</div>
## text
Create a `Response` object from the supplied body.
<div class="ts-block">
```dts
function text(body: string, init?: ResponseInit): Response;
```
</div>
## Action
Shape of a form action method that is part of `export const actions = {...}` in `+page.server.js`.
See [form actions](/docs/kit/form-actions) for more information.
<div class="ts-block">
```dts
type Action<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
OutputData extends Record<string, any> | void = Record<
string,
any
> | void,
RouteId extends AppRouteId | null = AppRouteId | null
> = (
event: RequestEvent<Params, RouteId>
) => MaybePromise<OutputData>;
```
</div>
## ActionFailure
<div class="ts-block">
```dts
interface ActionFailure<T = undefined> {/*…*/}
```
<div class="ts-block-property">
```dts
status: number;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
data: T;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
[uniqueSymbol]: true;
```
<div class="ts-block-property-details"></div>
</div></div>
## ActionResult
When calling a form action via fetch, the response will be one of these shapes.
```svelte
<form method="post" use:enhance={() => {
return ({ result }) => {
// result is of type ActionResult
};
}}
```
<div class="ts-block">
```dts
type ActionResult<
Success extends
| Record<string, unknown>
| undefined = Record<string, any>,
Failure extends
| Record<string, unknown>
| undefined = Record<string, any>
> =
| { type: 'success'; status: number; data?: Success }
| { type: 'failure'; status: number; data?: Failure }
| { type: 'redirect'; status: number; location: string }
| { type: 'error'; status?: number; error: any };
```
</div>
## Actions
Shape of the `export const actions = {...}` object in `+page.server.js`.
See [form actions](/docs/kit/form-actions) for more information.
<div class="ts-block">
```dts
type Actions<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
OutputData extends Record<string, any> | void = Record<
string,
any
> | void,
RouteId extends AppRouteId | null = AppRouteId | null
> = Record<string, Action<Params, OutputData, RouteId>>;
```
</div>
## Adapter
[Adapters](/docs/kit/adapters) are responsible for taking the production build and turning it into something that can be deployed to a platform of your choosing.
<div class="ts-block">
```dts
interface Adapter {/*…*/}
```
<div class="ts-block-property">
```dts
name: string;
```
<div class="ts-block-property-details">
The name of the adapter, using for logging. Will typically correspond to the package name.
</div>
</div>
<div class="ts-block-property">
```dts
adapt: (builder: Builder) => MaybePromise<void>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `builder` An object provided by SvelteKit that contains methods for adapting the app
</div>
This function is called after SvelteKit has built your app.
</div>
</div>
<div class="ts-block-property">
```dts
supports?: {/*…*/}
```
<div class="ts-block-property-details">
Checks called during dev and build to determine whether specific features will work in production with this adapter.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
read?: (details: { config: any; route: { id: string } }) => boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `details.config` The merged route config
</div>
Test support for `read` from `$app/server`.
</div>
</div>
<div class="ts-block-property">
```dts
instrumentation?: () => boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag since">available since</span> v2.31.0
</div>
Test support for `instrumentation.server.js`. To pass, the adapter must support running `instrumentation.server.js` prior to the application code.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
emulate?: () => MaybePromise<Emulator>;
```
<div class="ts-block-property-details">
Creates an `Emulator`, which allows the adapter to influence the environment
during dev, build and prerendering.
</div>
</div></div>
## AfterNavigate
The argument passed to [`afterNavigate`](/docs/kit/$app-navigation#afterNavigate) callbacks.
<div class="ts-block">
```dts
type AfterNavigate = (Navigation | NavigationEnter) & {
/**
* The type of navigation:
* - `enter`: The app has hydrated/started
* - `form`: The user submitted a `<form method="GET">`
* - `link`: Navigation was triggered by a link click
* - `goto`: Navigation was triggered by a `goto(...)` call or a redirect
* - `popstate`: Navigation was triggered by back/forward navigation
*/
type: Exclude<NavigationType, 'leave'>;
/**
* Since `afterNavigate` callbacks are called after a navigation completes, they will never be called with a navigation that unloads the page.
*/
willUnload: false;
};
```
</div>
## AwaitedActions
<div class="ts-block">
```dts
type AwaitedActions<
T extends Record<string, (...args: any) => any>
> = OptionalUnion<
{
[Key in keyof T]: UnpackValidationError<
Awaited<ReturnType<T[Key]>>
>;
}[keyof T]
>;
```
</div>
## BeforeNavigate
The argument passed to [`beforeNavigate`](/docs/kit/$app-navigation#beforeNavigate) callbacks.
<div class="ts-block">
```dts
type BeforeNavigate = Navigation & {
/**
* Call this to prevent the navigation from starting.
*/
cancel: () => void;
};
```
</div>
## Builder
This object is passed to the `adapt` function of adapters.
It contains various methods and properties that are useful for adapting the app.
<div class="ts-block">
```dts
interface Builder {/*…*/}
```
<div class="ts-block-property">
```dts
log: Logger;
```
<div class="ts-block-property-details">
Print messages to the console. `log.info` and `log.minor` are silent unless Vite's `logLevel` is `info`.
</div>
</div>
<div class="ts-block-property">
```dts
rimraf: (dir: string) => void;
```
<div class="ts-block-property-details">
Remove `dir` and all its contents.
</div>
</div>
<div class="ts-block-property">
```dts
mkdirp: (dir: string) => void;
```
<div class="ts-block-property-details">
Create `dir` and any required parent directories.
</div>
</div>
<div class="ts-block-property">
```dts
config: ValidatedConfig;
```
<div class="ts-block-property-details">
The fully resolved Svelte config.
</div>
</div>
<div class="ts-block-property">
```dts
prerendered: Prerendered;
```
<div class="ts-block-property-details">
Information about prerendered pages and assets, if any.
</div>
</div>
<div class="ts-block-property">
```dts
routes: RouteDefinition[];
```
<div class="ts-block-property-details">
An array of all routes (including prerendered)
</div>
</div>
<div class="ts-block-property">
```dts
createEntries: (fn: (route: RouteDefinition) => AdapterEntry) => Promise<void>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `fn` A function that groups a set of routes into an entry point
- <span class="tag deprecated">deprecated</span> Use `builder.routes` instead
</div>
Create separate functions that map to one or more routes of your app.
</div>
</div>
<div class="ts-block-property">
```dts
findServerAssets: (routes: RouteDefinition[]) => string[];
```
<div class="ts-block-property-details">
Find all the assets imported by server files belonging to `routes`
</div>
</div>
<div class="ts-block-property">
```dts
generateFallback: (dest: string) => Promise<void>;
```
<div class="ts-block-property-details">
Generate a fallback page for a static webserver to use when no route is matched. Useful for single-page apps.
</div>
</div>
<div class="ts-block-property">
```dts
generateEnvModule: () => void;
```
<div class="ts-block-property-details">
Generate a module exposing build-time environment variables as `$env/dynamic/public`.
</div>
</div>
<div class="ts-block-property">
```dts
generateManifest: (opts: { relativePath: string; routes?: RouteDefinition[] }) => string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `opts` a relative path to the base directory of the app and optionally in which format (esm or cjs) the manifest should be generated
</div>
Generate a server-side manifest to initialise the SvelteKit [server](/docs/kit/@sveltejs-kit#Server) with.
</div>
</div>
<div class="ts-block-property">
```dts
getBuildDirectory: (name: string) => string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` path to the file, relative to the build directory
</div>
Resolve a path to the `name` directory inside `outDir`, e.g. `/path/to/.svelte-kit/my-adapter`.
</div>
</div>
<div class="ts-block-property">
```dts
getClientDirectory: () => string;
```
<div class="ts-block-property-details">
Get the fully resolved path to the directory containing client-side assets, including the contents of your `static` directory.
</div>
</div>
<div class="ts-block-property">
```dts
getServerDirectory: () => string;
```
<div class="ts-block-property-details">
Get the fully resolved path to the directory containing server-side code.
</div>
</div>
<div class="ts-block-property">
```dts
getAppPath: () => string;
```
<div class="ts-block-property-details">
Get the application path including any configured `base` path, e.g. `my-base-path/_app`.
</div>
</div>
<div class="ts-block-property">
```dts
writeClient: (dest: string) => string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `dest` the destination folder
- <span class="tag">returns</span> an array of files written to `dest`
</div>
Write client assets to `dest`.
</div>
</div>
<div class="ts-block-property">
```dts
writePrerendered: (dest: string) => string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `dest` the destination folder
- <span class="tag">returns</span> an array of files written to `dest`
</div>
Write prerendered files to `dest`.
</div>
</div>
<div class="ts-block-property">
```dts
writeServer: (dest: string) => string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `dest` the destination folder
- <span class="tag">returns</span> an array of files written to `dest`
</div>
Write server-side code to `dest`.
</div>
</div>
<div class="ts-block-property">
```dts
copy: (
from: string,
to: string,
opts?: {
filter?(basename: string): boolean;
replace?: Record<string, string>;
}
) => string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `from` the source file or directory
- `to` the destination file or directory
- `opts.filter` a function to determine whether a file or directory should be copied
- `opts.replace` a map of strings to replace
- <span class="tag">returns</span> an array of files that were copied
</div>
Copy a file or directory.
</div>
</div>
<div class="ts-block-property">
```dts
hasServerInstrumentationFile: () => boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">returns</span> true if the server instrumentation file exists, false otherwise
- <span class="tag since">available since</span> v2.31.0
</div>
Check if the server instrumentation file exists.
</div>
</div>
<div class="ts-block-property">
```dts
instrument: (args: {
entrypoint: string;
instrumentation: string;
start?: string;
module?:
| {
exports: string[];
}
| {
generateText: (args: { instrumentation: string; start: string }) => string;
};
}) => void;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `options` an object containing the following properties:
- `options.entrypoint` the path to the entrypoint to trace.
- `options.instrumentation` the path to the instrumentation file.
- `options.start` the name of the start file. This is what `entrypoint` will be renamed to.
- `options.module` configuration for the resulting entrypoint module.
- `options.module.generateText` a function that receives the relative paths to the instrumentation and start files, and generates the text of the module to be traced. If not provided, the default implementation will be used, which uses top-level await.
- <span class="tag since">available since</span> v2.31.0
</div>
Instrument `entrypoint` with `instrumentation`.
Renames `entrypoint` to `start` and creates a new module at
`entrypoint` which imports `instrumentation` and then dynamically imports `start`. This allows
the module hooks necessary for instrumentation libraries to be loaded prior to any application code.
Caveats:
- "Live exports" will not work. If your adapter uses live exports, your users will need to manually import the server instrumentation on startup.
- If `tla` is `false`, OTEL auto-instrumentation may not work properly. Use it if your environment supports it.
- Use `hasServerInstrumentationFile` to check if the user has a server instrumentation file; if they don't, you shouldn't do this.
</div>
</div>
<div class="ts-block-property">
```dts
compress: (directory: string) => Promise<void>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `directory` The directory containing the files to be compressed
</div>
Compress files in `directory` with gzip and brotli, where appropriate. Generates `.gz` and `.br` files alongside the originals.
</div>
</div></div>
## ClientInit
<blockquote class="since note">
Available since 2.10.0
</blockquote>
The [`init`](/docs/kit/hooks#Shared-hooks-init) will be invoked once the app starts in the browser
<div class="ts-block">
```dts
type ClientInit = () => MaybePromise<void>;
```
</div>
## Config
See the [configuration reference](/docs/kit/configuration) for details.
## Cookies
<div class="ts-block">
```dts
interface Cookies {/*…*/}
```
<div class="ts-block-property">
```dts
get: (name: string, opts?: import('cookie').CookieParseOptions) => string | undefined;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` the name of the cookie
- `opts` the options, passed directly to `cookie.parse`. See documentation [here](https://github.com/jshttp/cookie#cookieparsestr-options)
</div>
Gets a cookie that was previously set with `cookies.set`, or from the request headers.
</div>
</div>
<div class="ts-block-property">
```dts
getAll: (opts?: import('cookie').CookieParseOptions) => Array<{ name: string; value: string }>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `opts` the options, passed directly to `cookie.parse`. See documentation [here](https://github.com/jshttp/cookie#cookieparsestr-options)
</div>
Gets all cookies that were previously set with `cookies.set`, or from the request headers.
</div>
</div>
<div class="ts-block-property">
```dts
set: (
name: string,
value: string,
opts: import('cookie').CookieSerializeOptions & { path: string }
) => void;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` the name of the cookie
- `value` the cookie value
- `opts` the options, passed directly to `cookie.serialize`. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options)
</div>
Sets a cookie. This will add a `set-cookie` header to the response, but also make the cookie available via `cookies.get` or `cookies.getAll` during the current request.
The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The `sameSite` option defaults to `lax`.
You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children
</div>
</div>
<div class="ts-block-property">
```dts
delete: (name: string, opts: import('cookie').CookieSerializeOptions & { path: string }) => void;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` the name of the cookie
- `opts` the options, passed directly to `cookie.serialize`. The `path` must match the path of the cookie you want to delete. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options)
</div>
Deletes a cookie by setting its value to an empty string and setting the expiry date in the past.
You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children
</div>
</div>
<div class="ts-block-property">
```dts
serialize: (
name: string,
value: string,
opts: import('cookie').CookieSerializeOptions & { path: string }
) => string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` the name of the cookie
- `value` the cookie value
- `opts` the options, passed directly to `cookie.serialize`. See documentation [here](https://github.com/jshttp/cookie#cookieserializename-value-options)
</div>
Serialize a cookie name-value pair into a `Set-Cookie` header string, but don't apply it to the response.
The `httpOnly` and `secure` options are `true` by default (except on http://localhost, where `secure` is `false`), and must be explicitly disabled if you want cookies to be readable by client-side JavaScript and/or transmitted over HTTP. The `sameSite` option defaults to `lax`.
You must specify a `path` for the cookie. In most cases you should explicitly set `path: '/'` to make the cookie available throughout your app. You can use relative paths, or set `path: ''` to make the cookie only available on the current path and its children
</div>
</div></div>
## Emulator
A collection of functions that influence the environment during dev, build and prerendering
<div class="ts-block">
```dts
interface Emulator {/*…*/}
```
<div class="ts-block-property">
```dts
platform?(details: { config: any; prerender: PrerenderOption }): MaybePromise<App.Platform>;
```
<div class="ts-block-property-details">
A function that is called with the current route `config` and `prerender` option
and returns an `App.Platform` object
</div>
</div></div>
## Handle
The [`handle`](/docs/kit/hooks#Server-hooks-handle) hook runs every time the SvelteKit server receives a [request](/docs/kit/web-standards#Fetch-APIs-Request) and
determines the [response](/docs/kit/web-standards#Fetch-APIs-Response).
It receives an `event` object representing the request and a function called `resolve`, which renders the route and generates a `Response`.
This allows you to modify response headers or bodies, or bypass SvelteKit entirely (for implementing routes programmatically, for example).
<div class="ts-block">
```dts
type Handle = (input: {
event: RequestEvent;
resolve: (
event: RequestEvent,
opts?: ResolveOptions
) => MaybePromise<Response>;
}) => MaybePromise<Response>;
```
</div>
## HandleClientError
The client-side [`handleError`](/docs/kit/hooks#Shared-hooks-handleError) hook runs when an unexpected error is thrown while navigating.
If an unexpected error is thrown during loading or the following render, this function will be called with the error and the event.
Make sure that this function _never_ throws an error.
<div class="ts-block">
```dts
type HandleClientError = (input: {
error: unknown;
event: NavigationEvent;
status: number;
message: string;
}) => MaybePromise<void | App.Error>;
```
</div>
## HandleFetch
The [`handleFetch`](/docs/kit/hooks#Server-hooks-handleFetch) hook allows you to modify (or replace) the result of an [`event.fetch`](/docs/kit/load#Making-fetch-requests) call that runs on the server (or during prerendering) inside an endpoint, `load`, `action`, `handle`, `handleError` or `reroute`.
<div class="ts-block">
```dts
type HandleFetch = (input: {
event: RequestEvent;
request: Request;
fetch: typeof fetch;
}) => MaybePromise<Response>;
```
</div>
## HandleServerError
The server-side [`handleError`](/docs/kit/hooks#Shared-hooks-handleError) hook runs when an unexpected error is thrown while responding to a request.
If an unexpected error is thrown during loading or rendering, this function will be called with the error and the event.
Make sure that this function _never_ throws an error.
<div class="ts-block">
```dts
type HandleServerError = (input: {
error: unknown;
event: RequestEvent;
status: number;
message: string;
}) => MaybePromise<void | App.Error>;
```
</div>
## HandleValidationError
The [`handleValidationError`](/docs/kit/hooks#Server-hooks-handleValidationError) hook runs when the argument to a remote function fails validation.
It will be called with the validation issues and the event, and must return an object shape that matches `App.Error`.
<div class="ts-block">
```dts
type HandleValidationError<
Issue extends
StandardSchemaV1.Issue = StandardSchemaV1.Issue
> = (input: {
issues: Issue[];
event: RequestEvent;
}) => MaybePromise<App.Error>;
```
</div>
## HttpError
The object returned by the [`error`](/docs/kit/@sveltejs-kit#error) function.
<div class="ts-block">
```dts
interface HttpError {/*…*/}
```
<div class="ts-block-property">
```dts
status: number;
```
<div class="ts-block-property-details">
The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses), in the range 400-599.
</div>
</div>
<div class="ts-block-property">
```dts
body: App.Error;
```
<div class="ts-block-property-details">
The content of the error.
</div>
</div></div>
## InvalidField
A function and proxy object used to imperatively create validation errors in form handlers.
Access properties to create field-specific issues: `issue.fieldName('message')`.
The type structure mirrors the input data structure for type-safe field access.
Call `invalid(issue.foo(...), issue.nested.bar(...))` to throw a validation error.
<div class="ts-block">
```dts
type InvalidField<T> =
WillRecurseIndefinitely<T> extends true
? Record<string | number, any>
: NonNullable<T> extends
| string
| number
| boolean
| File
? (message: string) => StandardSchemaV1.Issue
: NonNullable<T> extends Array<infer U>
? {
[K in number]: InvalidField<U>;
} & ((message: string) => StandardSchemaV1.Issue)
: NonNullable<T> extends RemoteFormInput
? {
[K in keyof T]-?: InvalidField<T[K]>;
} & ((
message: string
) => StandardSchemaV1.Issue)
: Record<string, never>;
```
</div>
## KitConfig
See the [configuration reference](/docs/kit/configuration) for details.
## LessThan
<div class="ts-block">
```dts
type LessThan<
TNumber extends number,
TArray extends any[] = []
> = TNumber extends TArray['length']
? TArray[number]
: LessThan<TNumber, [...TArray, TArray['length']]>;
```
</div>
## Load
The generic form of `PageLoad` and `LayoutLoad`. You should import those from `./$types` (see [generated types](/docs/kit/types#Generated-types))
rather than using `Load` directly.
<div class="ts-block">
```dts
type Load<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
InputData extends Record<string, unknown> | null = Record<
string,
any
> | null,
ParentData extends Record<string, unknown> = Record<
string,
any
>,
OutputData extends Record<
string,
unknown
> | void = Record<string, any> | void,
RouteId extends AppRouteId | null = AppRouteId | null
> = (
event: LoadEvent<Params, InputData, ParentData, RouteId>
) => MaybePromise<OutputData>;
```
</div>
## LoadEvent
The generic form of `PageLoadEvent` and `LayoutLoadEvent`. You should import those from `./$types` (see [generated types](/docs/kit/types#Generated-types))
rather than using `LoadEvent` directly.
<div class="ts-block">
```dts
interface LoadEvent<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
Data extends Record<string, unknown> | null = Record<
string,
any
> | null,
ParentData extends Record<string, unknown> = Record<
string,
any
>,
RouteId extends AppRouteId | null = AppRouteId | null
> extends NavigationEvent<Params, RouteId> {/*…*/}
```
<div class="ts-block-property">
```dts
fetch: typeof fetch;
```
<div class="ts-block-property-details">
`fetch` is equivalent to the [native `fetch` web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch), with a few additional features:
- It can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request.
- It can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context).
- Internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call.
- During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](/docs/kit/hooks#Server-hooks-handle)
- During hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request.
You can learn more about making credentialed requests with cookies [here](/docs/kit/load#Cookies)
</div>
</div>
<div class="ts-block-property">
```dts
data: Data;
```
<div class="ts-block-property-details">
Contains the data returned by the route's server `load` function (in `+layout.server.js` or `+page.server.js`), if any.
</div>
</div>
<div class="ts-block-property">
```dts
setHeaders: (headers: Record<string, string>) => void;
```
<div class="ts-block-property-details">
If you need to set headers for the response, you can do so using the this method. This is useful if you want the page to be cached, for example:
```js
// @errors: 7031
/// file: src/routes/blog/+page.js
export async function load({ fetch, setHeaders }) {
const url = `https://cms.example.com/articles.json`;
const response = await fetch(url);
setHeaders({
age: response.headers.get('age'),
'cache-control': response.headers.get('cache-control')
});
return response.json();
}
```
Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once.
You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](/docs/kit/@sveltejs-kit#Cookies) API in a server-only `load` function instead.
`setHeaders` has no effect when a `load` function runs in the browser.
</div>
</div>
<div class="ts-block-property">
```dts
parent: () => Promise<ParentData>;
```
<div class="ts-block-property-details">
`await parent()` returns data from parent `+layout.js` `load` functions.
Implicitly, a missing `+layout.js` is treated as a `({ data }) => data` function, meaning that it will return and forward data from parent `+layout.server.js` files.
Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data.
</div>
</div>
<div class="ts-block-property">
```dts
depends: (...deps: Array<`${string}:${string}`>) => void;
```
<div class="ts-block-property-details">
This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](/docs/kit/$app-navigation#invalidate) to cause `load` to rerun.
Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
```js
// @errors: 7031
/// file: src/routes/+page.js
let count = 0;
export async function load({ depends }) {
depends('increase:count');
return { count: count++ };
}
```
```html
/// file: src/routes/+page.svelte
<script>
import { invalidate } from '$app/navigation';
let { data } = $props();
const increase = async () => {
await invalidate('increase:count');
}
</script>
<p>{data.count}<p>
<button on:click={increase}>Increase Count</button>
```
</div>
</div>
<div class="ts-block-property">
```dts
untrack: <T>(fn: () => T) => T;
```
<div class="ts-block-property-details">
Use this function to opt out of dependency tracking for everything that is synchronously called within the callback. Example:
```js
// @errors: 7031
/// file: src/routes/+page.server.js
export async function load({ untrack, url }) {
// Untrack url.pathname so that path changes don't trigger a rerun
if (untrack(() => url.pathname === '/')) {
return { message: 'Welcome!' };
}
}
```
</div>
</div>
<div class="ts-block-property">
```dts
tracing: {/*…*/}
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag since">available since</span> v2.31.0
</div>
Access to spans for tracing. If tracing is not enabled or the function is being run in the browser, these spans will do nothing.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
enabled: boolean;
```
<div class="ts-block-property-details">
Whether tracing is enabled.
</div>
</div>
<div class="ts-block-property">
```dts
root: Span;
```
<div class="ts-block-property-details">
The root span for the request. This span is named `sveltekit.handle.root`.
</div>
</div>
<div class="ts-block-property">
```dts
current: Span;
```
<div class="ts-block-property-details">
The span associated with the current `load` function.
</div>
</div></div>
</div>
</div></div>
## LoadProperties
<div class="ts-block">
```dts
type LoadProperties<
input extends Record<string, any> | void
> = input extends void
? undefined // needs to be undefined, because void will break intellisense
: input extends Record<string, any>
? input
: unknown;
```
</div>
## Navigation
<div class="ts-block">
```dts
type Navigation =
| NavigationExternal
| NavigationFormSubmit
| NavigationPopState
| NavigationLink;
```
</div>
## NavigationBase
<div class="ts-block">
```dts
interface NavigationBase {/*…*/}
```
<div class="ts-block-property">
```dts
from: NavigationTarget | null;
```
<div class="ts-block-property-details">
Where navigation was triggered from
</div>
</div>
<div class="ts-block-property">
```dts
to: NavigationTarget | null;
```
<div class="ts-block-property-details">
Where navigation is going to/has gone to
</div>
</div>
<div class="ts-block-property">
```dts
willUnload: boolean;
```
<div class="ts-block-property-details">
Whether or not the navigation will result in the page being unloaded (i.e. not a client-side navigation)
</div>
</div>
<div class="ts-block-property">
```dts
complete: Promise<void>;
```
<div class="ts-block-property-details">
A promise that resolves once the navigation is complete, and rejects if the navigation
fails or is aborted. In the case of a `willUnload` navigation, the promise will never resolve
</div>
</div></div>
## NavigationEnter
<div class="ts-block">
```dts
interface NavigationEnter extends NavigationBase {/*…*/}
```
<div class="ts-block-property">
```dts
type: 'enter';
```
<div class="ts-block-property-details">
The type of navigation:
- `form`: The user submitted a `<form method="GET">`
- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
</div>
</div>
<div class="ts-block-property">
```dts
delta?: undefined;
```
<div class="ts-block-property-details">
In case of a history back/forward navigation, the number of steps to go back/forward
</div>
</div>
<div class="ts-block-property">
```dts
event?: undefined;
```
<div class="ts-block-property-details">
Dispatched `Event` object when navigation occured by `popstate` or `link`.
</div>
</div></div>
## NavigationEvent
<div class="ts-block">
```dts
interface NavigationEvent<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
RouteId extends AppRouteId | null = AppRouteId | null
> {/*…*/}
```
<div class="ts-block-property">
```dts
params: Params;
```
<div class="ts-block-property-details">
The parameters of the current page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object
</div>
</div>
<div class="ts-block-property">
```dts
route: {/*…*/}
```
<div class="ts-block-property-details">
Info about the current route
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
id: RouteId;
```
<div class="ts-block-property-details">
The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
url: URL;
```
<div class="ts-block-property-details">
The URL of the current page
</div>
</div></div>
## NavigationExternal
<div class="ts-block">
```dts
interface NavigationExternal extends NavigationBase {/*…*/}
```
<div class="ts-block-property">
```dts
type: Exclude<NavigationType, 'enter' | 'popstate' | 'link' | 'form'>;
```
<div class="ts-block-property-details">
The type of navigation:
- `form`: The user submitted a `<form method="GET">`
- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
</div>
</div>
<div class="ts-block-property">
```dts
delta?: undefined;
```
<div class="ts-block-property-details">
In case of a history back/forward navigation, the number of steps to go back/forward
</div>
</div></div>
## NavigationFormSubmit
<div class="ts-block">
```dts
interface NavigationFormSubmit extends NavigationBase {/*…*/}
```
<div class="ts-block-property">
```dts
type: 'form';
```
<div class="ts-block-property-details">
The type of navigation:
- `form`: The user submitted a `<form method="GET">`
- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
</div>
</div>
<div class="ts-block-property">
```dts
event: SubmitEvent;
```
<div class="ts-block-property-details">
The `SubmitEvent` that caused the navigation
</div>
</div>
<div class="ts-block-property">
```dts
delta?: undefined;
```
<div class="ts-block-property-details">
In case of a history back/forward navigation, the number of steps to go back/forward
</div>
</div></div>
## NavigationLink
<div class="ts-block">
```dts
interface NavigationLink extends NavigationBase {/*…*/}
```
<div class="ts-block-property">
```dts
type: 'link';
```
<div class="ts-block-property-details">
The type of navigation:
- `form`: The user submitted a `<form method="GET">`
- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
</div>
</div>
<div class="ts-block-property">
```dts
event: PointerEvent;
```
<div class="ts-block-property-details">
The `PointerEvent` that caused the navigation
</div>
</div>
<div class="ts-block-property">
```dts
delta?: undefined;
```
<div class="ts-block-property-details">
In case of a history back/forward navigation, the number of steps to go back/forward
</div>
</div></div>
## NavigationPopState
<div class="ts-block">
```dts
interface NavigationPopState extends NavigationBase {/*…*/}
```
<div class="ts-block-property">
```dts
type: 'popstate';
```
<div class="ts-block-property-details">
The type of navigation:
- `form`: The user submitted a `<form method="GET">`
- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
</div>
</div>
<div class="ts-block-property">
```dts
delta: number;
```
<div class="ts-block-property-details">
In case of a history back/forward navigation, the number of steps to go back/forward
</div>
</div>
<div class="ts-block-property">
```dts
event: PopStateEvent;
```
<div class="ts-block-property-details">
The `PopStateEvent` that caused the navigation
</div>
</div></div>
## NavigationTarget
Information about the target of a specific navigation.
<div class="ts-block">
```dts
interface NavigationTarget<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
RouteId extends AppRouteId | null = AppRouteId | null
> {/*…*/}
```
<div class="ts-block-property">
```dts
params: Params | null;
```
<div class="ts-block-property-details">
Parameters of the target page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
Is `null` if the target is not part of the SvelteKit app (could not be resolved to a route).
</div>
</div>
<div class="ts-block-property">
```dts
route: {/*…*/}
```
<div class="ts-block-property-details">
Info about the target route
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
id: RouteId | null;
```
<div class="ts-block-property-details">
The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
url: URL;
```
<div class="ts-block-property-details">
The URL that is navigated to
</div>
</div></div>
## NavigationType
- `enter`: The app has hydrated/started
- `form`: The user submitted a `<form method="GET">`
- `leave`: The app is being left either because the tab is being closed or a navigation to a different document is occurring
- `link`: Navigation was triggered by a link click
- `goto`: Navigation was triggered by a `goto(...)` call or a redirect
- `popstate`: Navigation was triggered by back/forward navigation
<div class="ts-block">
```dts
type NavigationType =
| 'enter'
| 'form'
| 'leave'
| 'link'
| 'goto'
| 'popstate';
```
</div>
## NumericRange
<div class="ts-block">
```dts
type NumericRange<
TStart extends number,
TEnd extends number
> = Exclude<TEnd | LessThan<TEnd>, LessThan<TStart>>;
```
</div>
## OnNavigate
The argument passed to [`onNavigate`](/docs/kit/$app-navigation#onNavigate) callbacks.
<div class="ts-block">
```dts
type OnNavigate = Navigation & {
/**
* The type of navigation:
* - `form`: The user submitted a `<form method="GET">`
* - `link`: Navigation was triggered by a link click
* - `goto`: Navigation was triggered by a `goto(...)` call or a redirect
* - `popstate`: Navigation was triggered by back/forward navigation
*/
type: Exclude<NavigationType, 'enter' | 'leave'>;
/**
* Since `onNavigate` callbacks are called immediately before a client-side navigation, they will never be called with a navigation that unloads the page.
*/
willUnload: false;
};
```
</div>
## Page
The shape of the [`page`](/docs/kit/$app-state#page) reactive object and the [`$page`](/docs/kit/$app-stores) store.
<div class="ts-block">
```dts
interface Page<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
RouteId extends AppRouteId | null = AppRouteId | null
> {/*…*/}
```
<div class="ts-block-property">
```dts
url: URL & { pathname: ResolvedPathname };
```
<div class="ts-block-property-details">
The URL of the current page.
</div>
</div>
<div class="ts-block-property">
```dts
params: Params;
```
<div class="ts-block-property-details">
The parameters of the current page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
</div>
</div>
<div class="ts-block-property">
```dts
route: {/*…*/}
```
<div class="ts-block-property-details">
Info about the current route.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
id: RouteId;
```
<div class="ts-block-property-details">
The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
status: number;
```
<div class="ts-block-property-details">
HTTP status code of the current page.
</div>
</div>
<div class="ts-block-property">
```dts
error: App.Error | null;
```
<div class="ts-block-property-details">
The error object of the current page, if any. Filled from the `handleError` hooks.
</div>
</div>
<div class="ts-block-property">
```dts
data: App.PageData & Record<string, any>;
```
<div class="ts-block-property-details">
The merged result of all data from all `load` functions on the current page. You can type a common denominator through `App.PageData`.
</div>
</div>
<div class="ts-block-property">
```dts
state: App.PageState;
```
<div class="ts-block-property-details">
The page state, which can be manipulated using the [`pushState`](/docs/kit/$app-navigation#pushState) and [`replaceState`](/docs/kit/$app-navigation#replaceState) functions from `$app/navigation`.
</div>
</div>
<div class="ts-block-property">
```dts
form: any;
```
<div class="ts-block-property-details">
Filled only after a form submission. See [form actions](/docs/kit/form-actions) for more info.
</div>
</div></div>
## ParamMatcher
The shape of a param matcher. See [matching](/docs/kit/advanced-routing#Matching) for more info.
<div class="ts-block">
```dts
type ParamMatcher = (param: string) => boolean;
```
</div>
## PrerenderOption
<div class="ts-block">
```dts
type PrerenderOption = boolean | 'auto';
```
</div>
## Redirect
The object returned by the [`redirect`](/docs/kit/@sveltejs-kit#redirect) function.
<div class="ts-block">
```dts
interface Redirect {/*…*/}
```
<div class="ts-block-property">
```dts
status: 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308;
```
<div class="ts-block-property-details">
The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages), in the range 300-308.
</div>
</div>
<div class="ts-block-property">
```dts
location: string;
```
<div class="ts-block-property-details">
The location to redirect to.
</div>
</div></div>
## RemoteCommand
The return value of a remote `command` function. See [Remote functions](/docs/kit/remote-functions#command) for full documentation.
<div class="ts-block">
```dts
type RemoteCommand<Input, Output> = {
(arg: Input): Promise<Awaited<Output>> & {
updates(
...queries: Array<
RemoteQuery<any> | RemoteQueryOverride
>
): Promise<Awaited<Output>>;
};
/** The number of pending command executions */
get pending(): number;
};
```
</div>
## RemoteForm
The return value of a remote `form` function. See [Remote functions](/docs/kit/remote-functions#form) for full documentation.
<div class="ts-block">
```dts
type RemoteForm<
Input extends RemoteFormInput | void,
Output
> = {
/** Attachment that sets up an event handler that intercepts the form submission on the client to prevent a full page reload */
[attachment: symbol]: (node: HTMLFormElement) => void;
method: 'POST';
/** The URL to send the form to. */
action: string;
/** Use the `enhance` method to influence what happens when the form is submitted. */
enhance(
callback: (opts: {
form: HTMLFormElement;
data: Input;
submit: () => Promise<void> & {
updates: (
...queries: Array<
RemoteQuery<any> | RemoteQueryOverride
>
) => Promise<void>;
};
}) => void | Promise<void>
): {
method: 'POST';
action: string;
[attachment: symbol]: (node: HTMLFormElement) => void;
};
/**
* Create an instance of the form for the given `id`.
* The `id` is stringified and used for deduplication to potentially reuse existing instances.
* Useful when you have multiple forms that use the same remote form action, for example in a loop.
* ```svelte
* {#each todos as todo}
* {@const todoForm = updateTodo.for(todo.id)}
* <form {...todoForm}>
* {#if todoForm.result?.invalid}<p>Invalid data</p>{/if}
* ...
* </form>
* {/each}
* ```
*/
for(
id: ExtractId<Input>
): Omit<RemoteForm<Input, Output>, 'for'>;
/** Preflight checks */
preflight(
schema: StandardSchemaV1<Input, any>
): RemoteForm<Input, Output>;
/** Validate the form contents programmatically */
validate(options?: {
/** Set this to `true` to also show validation issues of fields that haven't been touched yet. */
includeUntouched?: boolean;
/** Set this to `true` to only run the `preflight` validation. */
preflightOnly?: boolean;
}): Promise<void>;
/** The result of the form submission */
get result(): Output | undefined;
/** The number of pending submissions */
get pending(): number;
/** Access form fields using object notation */
fields: RemoteFormFields<Input>;
};
```
</div>
## RemoteFormField
Form field accessor type that provides name(), value(), and issues() methods
<div class="ts-block">
```dts
type RemoteFormField<Value extends RemoteFormFieldValue> =
RemoteFormFieldMethods<Value> & {
/**
* Returns an object that can be spread onto an input element with the correct type attribute,
* aria-invalid attribute if the field is invalid, and appropriate value/checked property getters/setters.
* @example
* ```svelte
* <input {...myForm.fields.myString.as('text')} />
* <input {...myForm.fields.myNumber.as('number')} />
* <input {...myForm.fields.myBoolean.as('checkbox')} />
* ```
*/
as<T extends RemoteFormFieldType<Value>>(
...args: AsArgs<T, Value>
): InputElementProps<T>;
};
```
</div>
## RemoteFormFieldType
<div class="ts-block">
```dts
type RemoteFormFieldType<T> = {
[K in keyof InputTypeMap]: T extends InputTypeMap[K]
? K
: never;
}[keyof InputTypeMap];
```
</div>
## RemoteFormFieldValue
<div class="ts-block">
```dts
type RemoteFormFieldValue =
| string
| string[]
| number
| boolean
| File
| File[];
```
</div>
## RemoteFormFields
Recursive type to build form fields structure with proxy access
<div class="ts-block">
```dts
type RemoteFormFields<T> =
WillRecurseIndefinitely<T> extends true
? RecursiveFormFields
: NonNullable<T> extends
| string
| number
| boolean
| File
? RemoteFormField<NonNullable<T>>
: T extends string[] | File[]
? RemoteFormField<T> & {
[K in number]: RemoteFormField<T[number]>;
}
: T extends Array<infer U>
? RemoteFormFieldContainer<T> & {
[K in number]: RemoteFormFields<U>;
}
: RemoteFormFieldContainer<T> & {
[K in keyof T]-?: RemoteFormFields<T[K]>;
};
```
</div>
## RemoteFormInput
<div class="ts-block">
```dts
interface RemoteFormInput {/*…*/}
```
<div class="ts-block-property">
```dts
[key: string]: MaybeArray<string | number | boolean | File | RemoteFormInput>;
```
<div class="ts-block-property-details"></div>
</div></div>
## RemoteFormIssue
<div class="ts-block">
```dts
interface RemoteFormIssue {/*…*/}
```
<div class="ts-block-property">
```dts
message: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
path: Array<string | number>;
```
<div class="ts-block-property-details"></div>
</div></div>
## RemotePrerenderFunction
The return value of a remote `prerender` function. See [Remote functions](/docs/kit/remote-functions#prerender) for full documentation.
<div class="ts-block">
```dts
type RemotePrerenderFunction<Input, Output> = (
arg: Input
) => RemoteResource<Output>;
```
</div>
## RemoteQuery
<div class="ts-block">
```dts
type RemoteQuery<T> = RemoteResource<T> & {
/**
* On the client, this function will update the value of the query without re-fetching it.
*
* On the server, this can be called in the context of a `command` or `form` and the specified data will accompany the action response back to the client.
* This prevents SvelteKit needing to refresh all queries on the page in a second server round-trip.
*/
set(value: T): void;
/**
* On the client, this function will re-fetch the query from the server.
*
* On the server, this can be called in the context of a `command` or `form` and the refreshed data will accompany the action response back to the client.
* This prevents SvelteKit needing to refresh all queries on the page in a second server round-trip.
*/
refresh(): Promise<void>;
/**
* Temporarily override the value of a query. This is used with the `updates` method of a [command](https://svelte.dev/docs/kit/remote-functions#command-Updating-queries) or [enhanced form submission](https://svelte.dev/docs/kit/remote-functions#form-enhance) to provide optimistic updates.
*
* ```svelte
* <script>
* import { getTodos, addTodo } from './todos.remote.js';
* const todos = getTodos();
* </script>
*
* <form {...addTodo.enhance(async ({ data, submit }) => {
* await submit().updates(
* todos.withOverride((todos) => [...todos, { text: data.get('text') }])
* );
* })}>
* <input type="text" name="text" />
* <button type="submit">Add Todo</button>
* </form>
* ```
*/
withOverride(
update: (current: Awaited<T>) => Awaited<T>
): RemoteQueryOverride;
};
```
</div>
## RemoteQueryFunction
The return value of a remote `query` function. See [Remote functions](/docs/kit/remote-functions#query) for full documentation.
<div class="ts-block">
```dts
type RemoteQueryFunction<Input, Output> = (
arg: Input
) => RemoteQuery<Output>;
```
</div>
## RemoteQueryOverride
<div class="ts-block">
```dts
interface RemoteQueryOverride {/*…*/}
```
<div class="ts-block-property">
```dts
_key: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
release(): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## RemoteResource
<div class="ts-block">
```dts
type RemoteResource<T> = Promise<Awaited<T>> & {
/** The error in case the query fails. Most often this is a [`HttpError`](https://svelte.dev/docs/kit/@sveltejs-kit#HttpError) but it isn't guaranteed to be. */
get error(): any;
/** `true` before the first result is available and during refreshes */
get loading(): boolean;
} & (
| {
/** The current value of the query. Undefined until `ready` is `true` */
get current(): undefined;
ready: false;
}
| {
/** The current value of the query. Undefined until `ready` is `true` */
get current(): Awaited<T>;
ready: true;
}
);
```
</div>
## RequestEvent
<div class="ts-block">
```dts
interface RequestEvent<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
RouteId extends AppRouteId | null = AppRouteId | null
> {/*…*/}
```
<div class="ts-block-property">
```dts
cookies: Cookies;
```
<div class="ts-block-property-details">
Get or set cookies related to the current request
</div>
</div>
<div class="ts-block-property">
```dts
fetch: typeof fetch;
```
<div class="ts-block-property-details">
`fetch` is equivalent to the [native `fetch` web API](https://developer.mozilla.org/en-US/docs/Web/API/fetch), with a few additional features:
- It can be used to make credentialed requests on the server, as it inherits the `cookie` and `authorization` headers for the page request.
- It can make relative requests on the server (ordinarily, `fetch` requires a URL with an origin when used in a server context).
- Internal requests (e.g. for `+server.js` routes) go directly to the handler function when running on the server, without the overhead of an HTTP call.
- During server-side rendering, the response will be captured and inlined into the rendered HTML by hooking into the `text` and `json` methods of the `Response` object. Note that headers will _not_ be serialized, unless explicitly included via [`filterSerializedResponseHeaders`](/docs/kit/hooks#Server-hooks-handle)
- During hydration, the response will be read from the HTML, guaranteeing consistency and preventing an additional network request.
You can learn more about making credentialed requests with cookies [here](/docs/kit/load#Cookies).
</div>
</div>
<div class="ts-block-property">
```dts
getClientAddress: () => string;
```
<div class="ts-block-property-details">
The client's IP address, set by the adapter.
</div>
</div>
<div class="ts-block-property">
```dts
locals: App.Locals;
```
<div class="ts-block-property-details">
Contains custom data that was added to the request within the [`server handle hook`](/docs/kit/hooks#Server-hooks-handle).
</div>
</div>
<div class="ts-block-property">
```dts
params: Params;
```
<div class="ts-block-property-details">
The parameters of the current route - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
</div>
</div>
<div class="ts-block-property">
```dts
platform: Readonly<App.Platform> | undefined;
```
<div class="ts-block-property-details">
Additional data made available through the adapter.
</div>
</div>
<div class="ts-block-property">
```dts
request: Request;
```
<div class="ts-block-property-details">
The original request object.
</div>
</div>
<div class="ts-block-property">
```dts
route: {/*…*/}
```
<div class="ts-block-property-details">
Info about the current route.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
id: RouteId;
```
<div class="ts-block-property-details">
The ID of the current route - e.g. for `src/routes/blog/[slug]`, it would be `/blog/[slug]`. It is `null` when no route is matched.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
setHeaders: (headers: Record<string, string>) => void;
```
<div class="ts-block-property-details">
If you need to set headers for the response, you can do so using the this method. This is useful if you want the page to be cached, for example:
```js
// @errors: 7031
/// file: src/routes/blog/+page.js
export async function load({ fetch, setHeaders }) {
const url = `https://cms.example.com/articles.json`;
const response = await fetch(url);
setHeaders({
age: response.headers.get('age'),
'cache-control': response.headers.get('cache-control')
});
return response.json();
}
```
Setting the same header multiple times (even in separate `load` functions) is an error — you can only set a given header once.
You cannot add a `set-cookie` header with `setHeaders` — use the [`cookies`](/docs/kit/@sveltejs-kit#Cookies) API instead.
</div>
</div>
<div class="ts-block-property">
```dts
url: URL;
```
<div class="ts-block-property-details">
The requested URL.
</div>
</div>
<div class="ts-block-property">
```dts
isDataRequest: boolean;
```
<div class="ts-block-property-details">
`true` if the request comes from the client asking for `+page/layout.server.js` data. The `url` property will be stripped of the internal information
related to the data request in this case. Use this property instead if the distinction is important to you.
</div>
</div>
<div class="ts-block-property">
```dts
isSubRequest: boolean;
```
<div class="ts-block-property-details">
`true` for `+server.js` calls coming from SvelteKit without the overhead of actually making an HTTP request. This happens when you make same-origin `fetch` requests on the server.
</div>
</div>
<div class="ts-block-property">
```dts
tracing: {/*…*/}
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag since">available since</span> v2.31.0
</div>
Access to spans for tracing. If tracing is not enabled, these spans will do nothing.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
enabled: boolean;
```
<div class="ts-block-property-details">
Whether tracing is enabled.
</div>
</div>
<div class="ts-block-property">
```dts
root: Span;
```
<div class="ts-block-property-details">
The root span for the request. This span is named `sveltekit.handle.root`.
</div>
</div>
<div class="ts-block-property">
```dts
current: Span;
```
<div class="ts-block-property-details">
The span associated with the current `handle` hook, `load` function, or form action.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```dts
isRemoteRequest: boolean;
```
<div class="ts-block-property-details">
`true` if the request comes from the client via a remote function. The `url` property will be stripped of the internal information
related to the data request in this case. Use this property instead if the distinction is important to you.
</div>
</div></div>
## RequestHandler
A `(event: RequestEvent) => Response` function exported from a `+server.js` file that corresponds to an HTTP verb (`GET`, `PUT`, `PATCH`, etc) and handles requests with that method.
It receives `Params` as the first generic argument, which you can skip by using [generated types](/docs/kit/types#Generated-types) instead.
<div class="ts-block">
```dts
type RequestHandler<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
RouteId extends AppRouteId | null = AppRouteId | null
> = (
event: RequestEvent<Params, RouteId>
) => MaybePromise<Response>;
```
</div>
## Reroute
<blockquote class="since note">
Available since 2.3.0
</blockquote>
The [`reroute`](/docs/kit/hooks#Universal-hooks-reroute) hook allows you to modify the URL before it is used to determine which route to render.
<div class="ts-block">
```dts
type Reroute = (event: {
url: URL;
fetch: typeof fetch;
}) => MaybePromise<void | string>;
```
</div>
## ResolveOptions
<div class="ts-block">
```dts
interface ResolveOptions {/*…*/}
```
<div class="ts-block-property">
```dts
transformPageChunk?: (input: { html: string; done: boolean }) => MaybePromise<string | undefined>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `input` the html chunk and the info if this is the last chunk
</div>
Applies custom transforms to HTML. If `done` is true, it's the final chunk. Chunks are not guaranteed to be well-formed HTML
(they could include an element's opening tag but not its closing tag, for example)
but they will always be split at sensible boundaries such as `%sveltekit.head%` or layout/page components.
</div>
</div>
<div class="ts-block-property">
```dts
filterSerializedResponseHeaders?: (name: string, value: string) => boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `name` header name
- `value` header value
</div>
Determines which headers should be included in serialized responses when a `load` function loads a resource with `fetch`.
By default, none will be included.
</div>
</div>
<div class="ts-block-property">
```dts
preload?: (input: { type: 'font' | 'css' | 'js' | 'asset'; path: string }) => boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- `input` the type of the file and its path
</div>
Determines what should be added to the `<head>` tag to preload it.
By default, `js` and `css` files will be preloaded.
</div>
</div></div>
## RouteDefinition
<div class="ts-block">
```dts
interface RouteDefinition<Config = any> {/*…*/}
```
<div class="ts-block-property">
```dts
id: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
api: {
methods: Array<HttpMethod | '*'>;
};
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
page: {
methods: Array<Extract<HttpMethod, 'GET' | 'POST'>>;
};
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
pattern: RegExp;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
prerender: PrerenderOption;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
segments: RouteSegment[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
methods: Array<HttpMethod | '*'>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
config: Config;
```
<div class="ts-block-property-details"></div>
</div></div>
## SSRManifest
<div class="ts-block">
```dts
interface SSRManifest {/*…*/}
```
<div class="ts-block-property">
```dts
appDir: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
appPath: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
assets: Set<string>;
```
<div class="ts-block-property-details">
Static files from `kit.config.files.assets` and the service worker (if any).
</div>
</div>
<div class="ts-block-property">
```dts
mimeTypes: Record<string, string>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
_: {/*…*/}
```
<div class="ts-block-property-details">
private fields
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
client: NonNullable<BuildData['client']>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
nodes: SSRNodeLoader[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
remotes: Record<string, () => Promise<any>>;
```
<div class="ts-block-property-details">
hashed filename -> import to that file
</div>
</div>
<div class="ts-block-property">
```dts
routes: SSRRoute[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
prerendered_routes: Set<string>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
matchers: () => Promise<Record<string, ParamMatcher>>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
server_assets: Record<string, number>;
```
<div class="ts-block-property-details">
A `[file]: size` map of all assets imported by server code.
</div>
</div></div>
</div>
</div></div>
## ServerInit
<blockquote class="since note">
Available since 2.10.0
</blockquote>
The [`init`](/docs/kit/hooks#Shared-hooks-init) will be invoked before the server responds to its first request
<div class="ts-block">
```dts
type ServerInit = () => MaybePromise<void>;
```
</div>
## ServerInitOptions
<div class="ts-block">
```dts
interface ServerInitOptions {/*…*/}
```
<div class="ts-block-property">
```dts
env: Record<string, string>;
```
<div class="ts-block-property-details">
A map of environment variables.
</div>
</div>
<div class="ts-block-property">
```dts
read?: (file: string) => MaybePromise<ReadableStream | null>;
```
<div class="ts-block-property-details">
A function that turns an asset filename into a `ReadableStream`. Required for the `read` export from `$app/server` to work.
</div>
</div></div>
## ServerLoad
The generic form of `PageServerLoad` and `LayoutServerLoad`. You should import those from `./$types` (see [generated types](/docs/kit/types#Generated-types))
rather than using `ServerLoad` directly.
<div class="ts-block">
```dts
type ServerLoad<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
ParentData extends Record<string, any> = Record<
string,
any
>,
OutputData extends Record<string, any> | void = Record<
string,
any
> | void,
RouteId extends AppRouteId | null = AppRouteId | null
> = (
event: ServerLoadEvent<Params, ParentData, RouteId>
) => MaybePromise<OutputData>;
```
</div>
## ServerLoadEvent
<div class="ts-block">
```dts
interface ServerLoadEvent<
Params extends
AppLayoutParams<'/'> = AppLayoutParams<'/'>,
ParentData extends Record<string, any> = Record<
string,
any
>,
RouteId extends AppRouteId | null = AppRouteId | null
> extends RequestEvent<Params, RouteId> {/*…*/}
```
<div class="ts-block-property">
```dts
parent: () => Promise<ParentData>;
```
<div class="ts-block-property-details">
`await parent()` returns data from parent `+layout.server.js` `load` functions.
Be careful not to introduce accidental waterfalls when using `await parent()`. If for example you only want to merge parent data into the returned output, call it _after_ fetching your other data.
</div>
</div>
<div class="ts-block-property">
```dts
depends: (...deps: string[]) => void;
```
<div class="ts-block-property-details">
This function declares that the `load` function has a _dependency_ on one or more URLs or custom identifiers, which can subsequently be used with [`invalidate()`](/docs/kit/$app-navigation#invalidate) to cause `load` to rerun.
Most of the time you won't need this, as `fetch` calls `depends` on your behalf — it's only necessary if you're using a custom API client that bypasses `fetch`.
URLs can be absolute or relative to the page being loaded, and must be [encoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding).
Custom identifiers have to be prefixed with one or more lowercase letters followed by a colon to conform to the [URI specification](https://www.rfc-editor.org/rfc/rfc3986.html).
The following example shows how to use `depends` to register a dependency on a custom identifier, which is `invalidate`d after a button click, making the `load` function rerun.
```js
// @errors: 7031
/// file: src/routes/+page.js
let count = 0;
export async function load({ depends }) {
depends('increase:count');
return { count: count++ };
}
```
```html
/// file: src/routes/+page.svelte
<script>
import { invalidate } from '$app/navigation';
let { data } = $props();
const increase = async () => {
await invalidate('increase:count');
}
</script>
<p>{data.count}<p>
<button on:click={increase}>Increase Count</button>
```
</div>
</div>
<div class="ts-block-property">
```dts
untrack: <T>(fn: () => T) => T;
```
<div class="ts-block-property-details">
Use this function to opt out of dependency tracking for everything that is synchronously called within the callback. Example:
```js
// @errors: 7031
/// file: src/routes/+page.js
export async function load({ untrack, url }) {
// Untrack url.pathname so that path changes don't trigger a rerun
if (untrack(() => url.pathname === '/')) {
return { message: 'Welcome!' };
}
}
```
</div>
</div>
<div class="ts-block-property">
```dts
tracing: {/*…*/}
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag since">available since</span> v2.31.0
</div>
Access to spans for tracing. If tracing is not enabled, these spans will do nothing.
<div class="ts-block-property-children"><div class="ts-block-property">
```dts
enabled: boolean;
```
<div class="ts-block-property-details">
Whether tracing is enabled.
</div>
</div>
<div class="ts-block-property">
```dts
root: Span;
```
<div class="ts-block-property-details">
The root span for the request. This span is named `sveltekit.handle.root`.
</div>
</div>
<div class="ts-block-property">
```dts
current: Span;
```
<div class="ts-block-property-details">
The span associated with the current server `load` function.
</div>
</div></div>
</div>
</div></div>
## Snapshot
The type of `export const snapshot` exported from a page or layout component.
<div class="ts-block">
```dts
interface Snapshot<T = any> {/*…*/}
```
<div class="ts-block-property">
```dts
capture: () => T;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
restore: (snapshot: T) => void;
```
<div class="ts-block-property-details"></div>
</div></div>
## SubmitFunction
<div class="ts-block">
```dts
type SubmitFunction<
Success extends
| Record<string, unknown>
| undefined = Record<string, any>,
Failure extends
| Record<string, unknown>
| undefined = Record<string, any>
> = (input: {
action: URL;
formData: FormData;
formElement: HTMLFormElement;
controller: AbortController;
submitter: HTMLElement | null;
cancel: () => void;
}) => MaybePromise<
| void
| ((opts: {
formData: FormData;
formElement: HTMLFormElement;
action: URL;
result: ActionResult<Success, Failure>;
/**
* Call this to get the default behavior of a form submission response.
* @param options Set `reset: false` if you don't want the `<form>` values to be reset after a successful submission.
* @param invalidateAll Set `invalidateAll: false` if you don't want the action to call `invalidateAll` after submission.
*/
update: (options?: {
reset?: boolean;
invalidateAll?: boolean;
}) => Promise<void>;
}) => MaybePromise<void>)
>;
```
</div>
## Transport
<blockquote class="since note">
Available since 2.11.0
</blockquote>
The [`transport`](/docs/kit/hooks#Universal-hooks-transport) hook allows you to transport custom types across the server/client boundary.
Each transporter has a pair of `encode` and `decode` functions. On the server, `encode` determines whether a value is an instance of the custom type and, if so, returns a non-falsy encoding of the value which can be an object or an array (or `false` otherwise).
In the browser, `decode` turns the encoding back into an instance of the custom type.
```ts
import type { Transport } from '@sveltejs/kit';
declare class MyCustomType {
data: any
}
// hooks.js
export const transport: Transport = {
MyCustomType: {
encode: (value) => value instanceof MyCustomType && [value.data],
decode: ([data]) => new MyCustomType(data)
}
};
```
<div class="ts-block">
```dts
type Transport = Record<string, Transporter>;
```
</div>
## Transporter
A member of the [`transport`](/docs/kit/hooks#Universal-hooks-transport) hook.
<div class="ts-block">
```dts
interface Transporter<
T = any,
U = Exclude<
any,
false | 0 | '' | null | undefined | typeof NaN
>
> {/*…*/}
```
<div class="ts-block-property">
```dts
encode: (value: T) => false | U;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
decode: (data: U) => T;
```
<div class="ts-block-property-details"></div>
</div></div>
## ValidationError
A validation error thrown by `invalid`.
<div class="ts-block">
```dts
interface ValidationError {/*…*/}
```
<div class="ts-block-property">
```dts
issues: StandardSchemaV1.Issue[];
```
<div class="ts-block-property-details">
The validation issues
</div>
</div></div>
## Private types
The following are referenced by the public types documented above, but cannot be imported directly:
## AdapterEntry
<div class="ts-block">
```dts
interface AdapterEntry {/*…*/}
```
<div class="ts-block-property">
```dts
id: string;
```
<div class="ts-block-property-details">
A string that uniquely identifies an HTTP service (e.g. serverless function) and is used for deduplication.
For example, `/foo/a-[b]` and `/foo/[c]` are different routes, but would both
be represented in a Netlify _redirects file as `/foo/:param`, so they share an ID
</div>
</div>
<div class="ts-block-property">
```dts
filter(route: RouteDefinition): boolean;
```
<div class="ts-block-property-details">
A function that compares the candidate route with the current route to determine
if it should be grouped with the current route.
Use cases:
- Fallback pages: `/foo/[c]` is a fallback for `/foo/a-[b]`, and `/[...catchall]` is a fallback for all routes
- Grouping routes that share a common `config`: `/foo` should be deployed to the edge, `/bar` and `/baz` should be deployed to a serverless function
</div>
</div>
<div class="ts-block-property">
```dts
complete(entry: { generateManifest(opts: { relativePath: string }): string }): MaybePromise<void>;
```
<div class="ts-block-property-details">
A function that is invoked once the entry has been created. This is where you
should write the function to the filesystem and generate redirect manifests.
</div>
</div></div>
## Csp
<div class="ts-block">
```dts
namespace Csp {
type ActionSource = 'strict-dynamic' | 'report-sample';
type BaseSource =
| 'self'
| 'unsafe-eval'
| 'unsafe-hashes'
| 'unsafe-inline'
| 'wasm-unsafe-eval'
| 'none';
type CryptoSource =
`${'nonce' | 'sha256' | 'sha384' | 'sha512'}-${string}`;
type FrameSource =
| HostSource
| SchemeSource
| 'self'
| 'none';
type HostNameScheme = `${string}.${string}` | 'localhost';
type HostSource =
`${HostProtocolSchemes}${HostNameScheme}${PortScheme}`;
type HostProtocolSchemes = `${string}://` | '';
type HttpDelineator = '/' | '?' | '#' | '\\';
type PortScheme = `:${number}` | '' | ':*';
type SchemeSource =
| 'http:'
| 'https:'
| 'data:'
| 'mediastream:'
| 'blob:'
| 'filesystem:';
type Source =
| HostSource
| SchemeSource
| CryptoSource
| BaseSource;
type Sources = Source[];
}
```
</div>
## CspDirectives
<div class="ts-block">
```dts
interface CspDirectives {/*…*/}
```
<div class="ts-block-property">
```dts
'child-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'default-src'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'frame-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'worker-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'connect-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'font-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'img-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'manifest-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'media-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'object-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'prefetch-src'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'script-src'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'script-src-elem'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'script-src-attr'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'style-src'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'style-src-elem'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'style-src-attr'?: Csp.Sources;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'base-uri'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
sandbox?: Array<
| 'allow-downloads-without-user-activation'
| 'allow-forms'
| 'allow-modals'
| 'allow-orientation-lock'
| 'allow-pointer-lock'
| 'allow-popups'
| 'allow-popups-to-escape-sandbox'
| 'allow-presentation'
| 'allow-same-origin'
| 'allow-scripts'
| 'allow-storage-access-by-user-activation'
| 'allow-top-navigation'
| 'allow-top-navigation-by-user-activation'
>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'form-action'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'frame-ancestors'?: Array<Csp.HostSource | Csp.SchemeSource | Csp.FrameSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'navigate-to'?: Array<Csp.Source | Csp.ActionSource>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'report-uri'?: string[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'report-to'?: string[];
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'require-trusted-types-for'?: Array<'script'>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'trusted-types'?: Array<'none' | 'allow-duplicates' | '*' | string>;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'upgrade-insecure-requests'?: boolean;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
'require-sri-for'?: Array<'script' | 'style' | 'script style'>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
</div>
</div>
<div class="ts-block-property">
```dts
'block-all-mixed-content'?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
</div>
</div>
<div class="ts-block-property">
```dts
'plugin-types'?: Array<`${string}/${string}` | 'none'>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
</div>
</div>
<div class="ts-block-property">
```dts
referrer?: Array<
| 'no-referrer'
| 'no-referrer-when-downgrade'
| 'origin'
| 'origin-when-cross-origin'
| 'same-origin'
| 'strict-origin'
| 'strict-origin-when-cross-origin'
| 'unsafe-url'
| 'none'
>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
</div>
</div></div>
## HttpMethod
<div class="ts-block">
```dts
type HttpMethod =
| 'GET'
| 'HEAD'
| 'POST'
| 'PUT'
| 'DELETE'
| 'PATCH'
| 'OPTIONS';
```
</div>
## Logger
<div class="ts-block">
```dts
interface Logger {/*…*/}
```
<div class="ts-block-property">
```dts
(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
success(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
error(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
warn(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
minor(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
info(msg: string): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## MaybePromise
<div class="ts-block">
```dts
type MaybePromise<T> = T | Promise<T>;
```
</div>
## PrerenderEntryGeneratorMismatchHandler
<div class="ts-block">
```dts
interface PrerenderEntryGeneratorMismatchHandler {/*…*/}
```
<div class="ts-block-property">
```dts
(details: { generatedFromId: string; entry: string; matchedId: string; message: string }): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## PrerenderEntryGeneratorMismatchHandlerValue
<div class="ts-block">
```dts
type PrerenderEntryGeneratorMismatchHandlerValue =
| 'fail'
| 'warn'
| 'ignore'
| PrerenderEntryGeneratorMismatchHandler;
```
</div>
## PrerenderHttpErrorHandler
<div class="ts-block">
```dts
interface PrerenderHttpErrorHandler {/*…*/}
```
<div class="ts-block-property">
```dts
(details: {
status: number;
path: string;
referrer: string | null;
referenceType: 'linked' | 'fetched';
message: string;
}): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## PrerenderHttpErrorHandlerValue
<div class="ts-block">
```dts
type PrerenderHttpErrorHandlerValue =
| 'fail'
| 'warn'
| 'ignore'
| PrerenderHttpErrorHandler;
```
</div>
## PrerenderMap
<div class="ts-block">
```dts
type PrerenderMap = Map<string, PrerenderOption>;
```
</div>
## PrerenderMissingIdHandler
<div class="ts-block">
```dts
interface PrerenderMissingIdHandler {/*…*/}
```
<div class="ts-block-property">
```dts
(details: { path: string; id: string; referrers: string[]; message: string }): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## PrerenderMissingIdHandlerValue
<div class="ts-block">
```dts
type PrerenderMissingIdHandlerValue =
| 'fail'
| 'warn'
| 'ignore'
| PrerenderMissingIdHandler;
```
</div>
## PrerenderOption
<div class="ts-block">
```dts
type PrerenderOption = boolean | 'auto';
```
</div>
## PrerenderUnseenRoutesHandler
<div class="ts-block">
```dts
interface PrerenderUnseenRoutesHandler {/*…*/}
```
<div class="ts-block-property">
```dts
(details: { routes: string[]; message: string }): void;
```
<div class="ts-block-property-details"></div>
</div></div>
## PrerenderUnseenRoutesHandlerValue
<div class="ts-block">
```dts
type PrerenderUnseenRoutesHandlerValue =
| 'fail'
| 'warn'
| 'ignore'
| PrerenderUnseenRoutesHandler;
```
</div>
## Prerendered
<div class="ts-block">
```dts
interface Prerendered {/*…*/}
```
<div class="ts-block-property">
```dts
pages: Map<
string,
{
/** The location of the .html file relative to the output directory */
file: string;
}
>;
```
<div class="ts-block-property-details">
A map of `path` to `{ file }` objects, where a path like `/foo` corresponds to `foo.html` and a path like `/bar/` corresponds to `bar/index.html`.
</div>
</div>
<div class="ts-block-property">
```dts
assets: Map<
string,
{
/** The MIME type of the asset */
type: string;
}
>;
```
<div class="ts-block-property-details">
A map of `path` to `{ type }` objects.
</div>
</div>
<div class="ts-block-property">
```dts
redirects: Map<
string,
{
status: number;
location: string;
}
>;
```
<div class="ts-block-property-details">
A map of redirects encountered during prerendering.
</div>
</div>
<div class="ts-block-property">
```dts
paths: string[];
```
<div class="ts-block-property-details">
An array of prerendered paths (without trailing slashes, regardless of the trailingSlash config)
</div>
</div></div>
## RequestOptions
<div class="ts-block">
```dts
interface RequestOptions {/*…*/}
```
<div class="ts-block-property">
```dts
getClientAddress(): string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
platform?: App.Platform;
```
<div class="ts-block-property-details"></div>
</div></div>
## RouteSegment
<div class="ts-block">
```dts
interface RouteSegment {/*…*/}
```
<div class="ts-block-property">
```dts
content: string;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
dynamic: boolean;
```
<div class="ts-block-property-details"></div>
</div>
<div class="ts-block-property">
```dts
rest: boolean;
```
<div class="ts-block-property-details"></div>
</div></div>
## TrailingSlash
<div class="ts-block">
```dts
type TrailingSlash = 'never' | 'always' | 'ignore';
```
</div>
# @sveltejs/kit/hooks
```js
// @noErrors
import { sequence } from '@sveltejs/kit/hooks';
```
## sequence
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 merged
- `preload` is applied in forward order, the first option "wins" and no `preload` options after it are called
- `filterSerializedResponseHeaders` behaves the same as `preload`
```js
// @errors: 7031
/// file: src/hooks.server.js
import { sequence } from '@sveltejs/kit/hooks';
/** @type {import('@sveltejs/kit').Handle} */
async function first({ event, resolve }) {
console.log('first pre-processing');
const result = await resolve(event, {
transformPageChunk: ({ html }) => {
// transforms are applied in reverse order
console.log('first transform');
return html;
},
preload: () => {
// this one wins as it's the first defined in the chain
console.log('first preload');
return true;
}
});
console.log('first post-processing');
return result;
}
/** @type {import('@sveltejs/kit').Handle} */
async function second({ event, resolve }) {
console.log('second pre-processing');
const result = await resolve(event, {
transformPageChunk: ({ html }) => {
console.log('second transform');
return html;
},
preload: () => {
console.log('second preload');
return true;
},
filterSerializedResponseHeaders: () => {
// this one wins as it's the first defined in the chain
console.log('second filterSerializedResponseHeaders');
return true;
}
});
console.log('second post-processing');
return result;
}
export const handle = 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
```
<div class="ts-block">
```dts
function sequence(...handlers: Handle[]): Handle;
```
</div>
# @sveltejs/kit/node/polyfills
```js
// @noErrors
import { installPolyfills } from '@sveltejs/kit/node/polyfills';
```
## installPolyfills
Make various web APIs available as globals:
- `crypto`
- `File`
<div class="ts-block">
```dts
function installPolyfills(): void;
```
</div>
# @sveltejs/kit/node
```js
// @noErrors
import {
createReadableStream,
getRequest,
setResponse
} from '@sveltejs/kit/node';
```
## createReadableStream
<blockquote class="since note">
Available since 2.4.0
</blockquote>
Converts a file on disk to a readable stream
<div class="ts-block">
```dts
function createReadableStream(file: string): ReadableStream;
```
</div>
## getRequest
<div class="ts-block">
```dts
function getRequest({
request,
base,
bodySizeLimit
}: {
request: import('http').IncomingMessage;
base: string;
bodySizeLimit?: number;
}): Promise<Request>;
```
</div>
## setResponse
<div class="ts-block">
```dts
function setResponse(
res: import('http').ServerResponse,
response: Response
): Promise<void>;
```
</div>
# @sveltejs/kit/vite
```js
// @noErrors
import { sveltekit } from '@sveltejs/kit/vite';
```
## sveltekit
Returns the SvelteKit Vite plugins.
<div class="ts-block">
```dts
function sveltekit(): Promise<import('vite').Plugin[]>;
```
</div>
# $app/environment
```js
// @noErrors
import { browser, building, dev, version } from '$app/environment';
```
## browser
`true` if the app is running in the browser.
<div class="ts-block">
```dts
const browser: boolean;
```
</div>
## building
SvelteKit analyses your app during the `build` step by running it. During this process, `building` is `true`. This also applies during prerendering.
<div class="ts-block">
```dts
const building: boolean;
```
</div>
## dev
Whether the dev server is running. This is not guaranteed to correspond to `NODE_ENV` or `MODE`.
<div class="ts-block">
```dts
const dev: boolean;
```
</div>
## version
The value of `config.kit.version.name`.
<div class="ts-block">
```dts
const version: string;
```
</div>
# $app/forms
```js
// @noErrors
import { applyAction, deserialize, enhance } from '$app/forms';
```
## applyAction
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.
<div class="ts-block">
```dts
function applyAction<
Success extends Record<string, unknown> | undefined,
Failure extends Record<string, unknown> | undefined
>(
result: import('@sveltejs/kit').ActionResult<
Success,
Failure
>
): Promise<void>;
```
</div>
## deserialize
Use this function to deserialize the response from a form submission.
Usage:
```js
// @errors: 7031
import { deserialize } from '$app/forms';
async function handleSubmit(event) {
const response = await fetch('/form?/action', {
method: 'POST',
body: new FormData(event.target)
});
const result = deserialize(await response.text());
// ...
}
```
<div class="ts-block">
```dts
function deserialize<
Success extends Record<string, unknown> | undefined,
Failure extends Record<string, unknown> | undefined
>(
result: string
): import('@sveltejs/kit').ActionResult<Success, Failure>;
```
</div>
## enhance
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 on the 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.
It accepts an options object
- `reset: false` if you don't want the `<form>` values to be reset after a successful submission
- `invalidateAll: false` if you don't want the action to call `invalidateAll` after submission
<div class="ts-block">
```dts
function enhance<
Success extends Record<string, unknown> | undefined,
Failure extends Record<string, unknown> | undefined
>(
form_element: HTMLFormElement,
submit?: import('@sveltejs/kit').SubmitFunction<
Success,
Failure
>
): {
destroy(): void;
};
```
</div>
# $app/navigation
```js
// @noErrors
import {
afterNavigate,
beforeNavigate,
disableScrollHandling,
goto,
invalidate,
invalidateAll,
onNavigate,
preloadCode,
preloadData,
pushState,
refreshAll,
replaceState
} from '$app/navigation';
```
## afterNavigate
A lifecycle function that runs the supplied `callback` when the current component mounts, and also whenever we navigate to a URL.
`afterNavigate` must be called during a component initialization. It remains active as long as the component is mounted.
<div class="ts-block">
```dts
function afterNavigate(
callback: (
navigation: import('@sveltejs/kit').AfterNavigate
) => void
): void;
```
</div>
## beforeNavigate
A navigation interceptor that triggers before we navigate to a 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.
<div class="ts-block">
```dts
function beforeNavigate(
callback: (
navigation: import('@sveltejs/kit').BeforeNavigate
) => void
): void;
```
</div>
## disableScrollHandling
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.
<div class="ts-block">
```dts
function disableScrollHandling(): void;
```
</div>
## goto
Allows you to navigate programmatically to a given route, with options such as keeping the current element focused.
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)`.
<div class="ts-block">
```dts
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>;
```
</div>
## invalidate
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 parameters
import { invalidate } from '$app/navigation';
invalidate((url) => url.pathname === '/path');
```
<div class="ts-block">
```dts
function invalidate(
resource: string | URL | ((url: URL) => boolean)
): Promise<void>;
```
</div>
## invalidateAll
Causes all `load` and `query` functions belonging to the currently active page to re-run. Returns a `Promise` that resolves when the page is subsequently updated.
<div class="ts-block">
```dts
function invalidateAll(): Promise<void>;
```
</div>
## onNavigate
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.
<div class="ts-block">
```dts
function onNavigate(
callback: (
navigation: import('@sveltejs/kit').OnNavigate
) => MaybePromise<(() => void) | void>
): void;
```
</div>
## preloadCode
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.
<div class="ts-block">
```dts
function preloadCode(pathname: string): Promise<void>;
```
</div>
## preloadData
Programmatically preloads the given page, which means
1. ensuring that the code for the page is loaded, and
2. 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.
<div class="ts-block">
```dts
function preloadData(href: string): Promise<
| {
type: 'loaded';
status: number;
data: Record<string, any>;
}
| {
type: 'redirect';
location: string;
}
>;
```
</div>
## pushState
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](/docs/kit/shallow-routing).
<div class="ts-block">
```dts
function pushState(
url: string | URL,
state: App.PageState
): void;
```
</div>
## 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 option argument).
Returns a `Promise` that resolves when the page is subsequently updated.
<div class="ts-block">
```dts
function refreshAll({
includeLoadFunctions
}?: {
includeLoadFunctions?: boolean;
}): Promise<void>;
```
</div>
## replaceState
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](/docs/kit/shallow-routing).
<div class="ts-block">
```dts
function replaceState(
url: string | URL,
state: App.PageState
): void;
```
</div>
# $app/paths
```js
// @noErrors
import { asset, assets, base, resolve, resolveRoute } from '$app/paths';
```
## asset
<blockquote class="since note">
Available since 2.26
</blockquote>
Resolve the URL of an asset in your `static` directory, by prefixing it with [`config.kit.paths.assets`](/docs/kit/configuration#paths) if configured, or otherwise by prefixing it with the base path.
During server rendering, the base path is relative and depends on the page currently being rendered.
```svelte
<script>
import { asset } from '$app/paths';
</script>
<img alt="a potato" src={asset('/potato.jpg')} />
```
<div class="ts-block">
```dts
function asset(file: Asset): string;
```
</div>
## assets
<blockquote class="tag deprecated note">
Use [`asset(...)`](/docs/kit/$app-paths#asset) instead
</blockquote>
An absolute path that matches [`config.kit.paths.assets`](/docs/kit/configuration#paths).
> [!NOTE] If a value for `config.kit.paths.assets` is specified, it will be replaced with `'/_svelte_kit_assets'` during `vite dev` or `vite preview`, since the assets don't yet live at their eventual URL.
<div class="ts-block">
```dts
let assets:
| ''
| `https://${string}`
| `http://${string}`
| '/_svelte_kit_assets';
```
</div>
## base
<blockquote class="tag deprecated note">
Use [`resolve(...)`](/docs/kit/$app-paths#resolve) instead
</blockquote>
A string that matches [`config.kit.paths.base`](/docs/kit/configuration#paths).
Example usage: `<a href="{base}/your-page">Link</a>`
<div class="ts-block">
```dts
let base: '' | `/${string}`;
```
</div>
## resolve
<blockquote class="since note">
Available since 2.26
</blockquote>
Resolve a pathname by prefixing it with the base path, if any, or resolve a route ID by populating dynamic segments with parameters.
During server rendering, the base path is relative and depends on the page currently being rendered.
```js
// @errors: 7031
import { resolve } from '$app/paths';
// using a pathname
const resolved = resolve(`/blog/hello-world`);
// using a route ID plus parameters
const resolved = resolve('/blog/[slug]', {
slug: 'hello-world'
});
```
<div class="ts-block">
```dts
function resolve<T extends RouteId | Pathname>(
...args: ResolveArgs<T>
): ResolvedPathname;
```
</div>
## resolveRoute
<blockquote class="tag deprecated note">
Use [`resolve(...)`](/docs/kit/$app-paths#resolve) instead
</blockquote>
<div class="ts-block">
```dts
function resolveRoute<T extends RouteId | Pathname>(
...args: ResolveArgs<T>
): ResolvedPathname;
```
</div>
# $app/server
```js
// @noErrors
import {
command,
form,
getRequestEvent,
prerender,
query,
read
} from '$app/server';
```
## command
<blockquote class="since note">
Available since 2.27
</blockquote>
Creates a remote command. When called from the browser, the function will be invoked on the server via a `fetch` call.
See [Remote functions](/docs/kit/remote-functions#command) for full documentation.
<div class="ts-block">
```dts
function command<Output>(
fn: () => Output
): RemoteCommand<void, Output>;
```
</div>
<div class="ts-block">
```dts
function command<Input, Output>(
validate: 'unchecked',
fn: (arg: Input) => Output
): RemoteCommand<Input, Output>;
```
</div>
<div class="ts-block">
```dts
function command<Schema extends StandardSchemaV1, Output>(
validate: Schema,
fn: (arg: StandardSchemaV1.InferOutput<Schema>) => Output
): RemoteCommand<
StandardSchemaV1.InferInput<Schema>,
Output
>;
```
</div>
## form
<blockquote class="since note">
Available since 2.27
</blockquote>
Creates a form object that can be spread onto a `<form>` element.
See [Remote functions](/docs/kit/remote-functions#form) for full documentation.
<div class="ts-block">
```dts
function form<Output>(
fn: () => MaybePromise<Output>
): RemoteForm<void, Output>;
```
</div>
<div class="ts-block">
```dts
function form<Input extends RemoteFormInput, Output>(
validate: 'unchecked',
fn: (
data: Input,
issue: InvalidField<Input>
) => MaybePromise<Output>
): RemoteForm<Input, Output>;
```
</div>
<div class="ts-block">
```dts
function form<
Schema extends StandardSchemaV1<
RemoteFormInput,
Record<string, any>
>,
Output
>(
validate: Schema,
fn: (
data: StandardSchemaV1.InferOutput<Schema>,
issue: InvalidField<StandardSchemaV1.InferInput<Schema>>
) => MaybePromise<Output>
): RemoteForm<StandardSchemaV1.InferInput<Schema>, Output>;
```
</div>
## getRequestEvent
<blockquote class="since note">
Available since 2.20.0
</blockquote>
Returns the current `RequestEvent`. Can be used inside server hooks, server `load` functions, actions, and endpoints (and functions called by them).
In environments without [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage), this must be called synchronously (i.e. not after an `await`).
<div class="ts-block">
```dts
function getRequestEvent(): RequestEvent;
```
</div>
## prerender
<blockquote class="since note">
Available since 2.27
</blockquote>
Creates a remote prerender function. When called from the browser, the function will be invoked on the server via a `fetch` call.
See [Remote functions](/docs/kit/remote-functions#prerender) for full documentation.
<div class="ts-block">
```dts
function prerender<Output>(
fn: () => MaybePromise<Output>,
options?:
| {
inputs?: RemotePrerenderInputsGenerator<void>;
dynamic?: boolean;
}
| undefined
): RemotePrerenderFunction<void, Output>;
```
</div>
<div class="ts-block">
```dts
function prerender<Input, Output>(
validate: 'unchecked',
fn: (arg: Input) => MaybePromise<Output>,
options?:
| {
inputs?: RemotePrerenderInputsGenerator<Input>;
dynamic?: boolean;
}
| undefined
): RemotePrerenderFunction<Input, Output>;
```
</div>
<div class="ts-block">
```dts
function prerender<Schema extends StandardSchemaV1, Output>(
schema: Schema,
fn: (
arg: StandardSchemaV1.InferOutput<Schema>
) => MaybePromise<Output>,
options?:
| {
inputs?: RemotePrerenderInputsGenerator<
StandardSchemaV1.InferInput<Schema>
>;
dynamic?: boolean;
}
| undefined
): RemotePrerenderFunction<
StandardSchemaV1.InferInput<Schema>,
Output
>;
```
</div>
## query
<blockquote class="since note">
Available since 2.27
</blockquote>
Creates a remote query. When called from the browser, the function will be invoked on the server via a `fetch` call.
See [Remote functions](/docs/kit/remote-functions#query) for full documentation.
<div class="ts-block">
```dts
function query<Output>(
fn: () => MaybePromise<Output>
): RemoteQueryFunction<void, Output>;
```
</div>
<div class="ts-block">
```dts
function query<Input, Output>(
validate: 'unchecked',
fn: (arg: Input) => MaybePromise<Output>
): RemoteQueryFunction<Input, Output>;
```
</div>
<div class="ts-block">
```dts
function query<Schema extends StandardSchemaV1, Output>(
schema: Schema,
fn: (
arg: StandardSchemaV1.InferOutput<Schema>
) => MaybePromise<Output>
): RemoteQueryFunction<
StandardSchemaV1.InferInput<Schema>,
Output
>;
```
</div>
## read
<blockquote class="since note">
Available since 2.4.0
</blockquote>
Read the contents of an imported asset from the filesystem
```js
// @errors: 7031
import { read } from '$app/server';
import somefile from './somefile.txt';
const asset = read(somefile);
const text = await asset.text();
```
<div class="ts-block">
```dts
function read(asset: string): Response;
```
</div>
## query
<div class="ts-block">
```dts
namespace query {
/**
* Creates a batch query function that collects multiple calls and executes them in a single request
*
* See [Remote functions](https://svelte.dev/docs/kit/remote-functions#query.batch) for full documentation.
*
* @since 2.35
*/
function batch<Input, Output>(
validate: 'unchecked',
fn: (
args: Input[]
) => MaybePromise<(arg: Input, idx: number) => Output>
): RemoteQueryFunction<Input, Output>;
/**
* Creates a batch query function that collects multiple calls and executes them in a single request
*
* See [Remote functions](https://svelte.dev/docs/kit/remote-functions#query.batch) for full documentation.
*
* @since 2.35
*/
function batch<Schema extends StandardSchemaV1, Output>(
schema: Schema,
fn: (
args: StandardSchemaV1.InferOutput<Schema>[]
) => MaybePromise<
(
arg: StandardSchemaV1.InferOutput<Schema>,
idx: number
) => Output
>
): RemoteQueryFunction<
StandardSchemaV1.InferInput<Schema>,
Output
>;
}
```
</div>
# $app/state
SvelteKit makes three read-only state objects available via the `$app/state` module — `page`, `navigating` and `updated`.
> [!NOTE]
> This module was added in 2.12. If you're using an earlier version of SvelteKit, use [`$app/stores`]($app-stores) instead.
```js
// @noErrors
import { navigating, page, updated } from '$app/state';
```
## navigating
A read-only object representing an in-progress navigation, with `from`, `to`, `type` and (if `type === 'popstate'`) `delta` properties.
Values are `null` when no navigation is occurring, or during server rendering.
<div class="ts-block">
```dts
const navigating:
| import('@sveltejs/kit').Navigation
| {
from: null;
to: null;
type: null;
willUnload: null;
delta: null;
complete: null;
};
```
</div>
## page
A read-only reactive object with information about the current page, serving several use cases:
- retrieving the combined `data` of all pages/layouts anywhere in your component tree (also see [loading data](/docs/kit/load))
- retrieving the current value of the `form` prop anywhere in your component tree (also see [form actions](/docs/kit/form-actions))
- retrieving the page state that was set through `goto`, `pushState` or `replaceState` (also see [goto](/docs/kit/$app-navigation#goto) and [shallow routing](/docs/kit/shallow-routing))
- retrieving metadata such as the URL you're on, the current route and its parameters, and whether or not there was an error
```svelte
<!--- file: +layout.svelte --->
<script>
import { page } from '$app/state';
</script>
<p>Currently at {page.url.pathname}</p>
{#if page.error}
<span class="red">Problem detected</span>
{:else}
<span class="small">All systems operational</span>
{/if}
```
Changes to `page` are available exclusively with runes. (The legacy reactivity syntax will not reflect any changes)
```svelte
<!--- file: +page.svelte --->
<script>
import { page } from '$app/state';
const id = $derived(page.params.id); // This will correctly update id for usage on this page
$: badId = page.params.id; // Do not use; will never update after initial load
</script>
```
On the server, values can only be read during rendering (in other words _not_ in e.g. `load` functions). In the browser, the values can be read at any time.
<div class="ts-block">
```dts
const page: import('@sveltejs/kit').Page;
```
</div>
## updated
A read-only reactive value that's initially `false`. If [`version.pollInterval`](/docs/kit/configuration#version) is a non-zero value, SvelteKit will poll for new versions of the app and update `current` to `true` when it detects one. `updated.check()` will force an immediate check, regardless of polling.
<div class="ts-block">
```dts
const updated: {
get current(): boolean;
check(): Promise<boolean>;
};
```
</div>
# $app/stores
This module contains store-based equivalents of the exports from [`$app/state`]($app-state). If you're using SvelteKit 2.12 or later, use that module instead.
```js
// @noErrors
import { getStores, navigating, page, updated } from '$app/stores';
```
## getStores
<div class="ts-block">
```dts
function getStores(): {
page: typeof page;
navigating: typeof navigating;
updated: typeof updated;
};
```
</div>
## navigating
<blockquote class="tag deprecated note">
Use `navigating` from `$app/state` instead (requires Svelte 5, [see docs for more info](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated))
</blockquote>
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.
<div class="ts-block">
```dts
const navigating: import('svelte/store').Readable<
import('@sveltejs/kit').Navigation | null
>;
```
</div>
## page
<blockquote class="tag deprecated note">
Use `page` from `$app/state` instead (requires Svelte 5, [see docs for more info](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated))
</blockquote>
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.
<div class="ts-block">
```dts
const page: import('svelte/store').Readable<
import('@sveltejs/kit').Page
>;
```
</div>
## updated
<blockquote class="tag deprecated note">
Use `updated` from `$app/state` instead (requires Svelte 5, [see docs for more info](/docs/kit/migrating-to-sveltekit-2#SvelteKit-2.12:-$app-stores-deprecated))
</blockquote>
A readable store whose initial value is `false`. If [`version.pollInterval`](/docs/kit/configuration#version) 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.
<div class="ts-block">
```dts
const updated: import('svelte/store').Readable<boolean> & {
check(): Promise<boolean>;
};
```
</div>
# $app/types
This module contains generated types for the routes in your app.
<blockquote class="since note">
<p>Available since 2.26</p>
</blockquote>
```js
// @noErrors
import type { RouteId, RouteParams, LayoutParams } from '$app/types';
```
## Asset
A union of all the filenames of assets contained in your `static` directory, plus a `string` wildcard for asset paths generated from `import` declarations.
<div class="ts-block">
```dts
type Asset = '/favicon.png' | '/robots.txt' | (string & {});
```
</div>
## RouteId
A union of all the route IDs in your app. Used for `page.route.id` and `event.route.id`.
<div class="ts-block">
```dts
type RouteId = '/' | '/my-route' | '/my-other-route/[param]';
```
</div>
## Pathname
A union of all valid pathnames in your app.
<div class="ts-block">
```dts
type Pathname = '/' | '/my-route' | `/my-other-route/${string}` & {};
```
</div>
## ResolvedPathname
Similar to `Pathname`, but possibly prefixed with a [base path](configuration#paths). Used for `page.url.pathname`.
<div class="ts-block">
```dts
type ResolvedPathname = `${'' | `/${string}`}/` | `${'' | `/${string}`}/my-route` | `${'' | `/${string}`}/my-other-route/${string}` | {};
```
</div>
## RouteParams
A utility for getting the parameters associated with a given route.
```ts
// @errors: 2552
type BlogParams = RouteParams<'/blog/[slug]'>; // { slug: string }
```
<div class="ts-block">
```dts
type RouteParams<T extends RouteId> = { /* generated */ } | Record<string, never>;
```
</div>
## LayoutParams
A utility for getting the parameters associated with a given layout, which is similar to `RouteParams` but also includes optional parameters for any child route.
<div class="ts-block">
```dts
type RouteParams<T extends RouteId> = { /* generated */ } | Record<string, never>;
```
</div>
# $env/dynamic/private
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`](https://github.com/sveltejs/kit/tree/main/packages/adapter-node) (or running [`vite preview`](/docs/kit/cli)), this is equivalent to `process.env`. This module only includes variables that _do not_ begin with [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](/docs/kit/configuration#env) (if configured).
This module cannot be imported into client-side code.
```ts
import { env } from '$env/dynamic/private';
console.log(env.DEPLOYMENT_SPECIFIC_VARIABLE);
```
> [!NOTE] In `dev`, `$env/dynamic` always includes environment variables from `.env`. In `prod`, this behavior will depend on your adapter.
# $env/dynamic/public
Similar to [`$env/dynamic/private`](/docs/kit/$env-dynamic-private), but only includes variables that begin with [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) (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.
```ts
import { env } from '$env/dynamic/public';
console.log(env.PUBLIC_DEPLOYMENT_SPECIFIC_VARIABLE);
```
# $env/static/private
Environment variables [loaded by Vite](https://vitejs.dev/guide/env-and-mode.html#env-files) from `.env` files and `process.env`. Like [`$env/dynamic/private`](/docs/kit/$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`](/docs/kit/configuration#env) _and do_ start with [`config.kit.env.privatePrefix`](/docs/kit/configuration#env) (if configured).
_Unlike_ [`$env/dynamic/private`](/docs/kit/$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:
```sh
MY_FEATURE_FLAG="enabled" npm run dev
```
# $env/static/public
Similar to [`$env/static/private`](/docs/kit/$env-static-private), except that it only includes environment variables that begin with [`config.kit.env.publicPrefix`](/docs/kit/configuration#env) (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';
```
# $lib
SvelteKit automatically makes files under `src/lib` available using the `$lib` import alias.
```svelte
<!--- file: src/lib/Component.svelte --->
A reusable component
```
```svelte
<!--- file: src/routes/+page.svelte --->
<script>
import Component from '$lib/Component.svelte';
</script>
<Component />
```
# $service-worker
```js
// @noErrors
import { base, build, files, prerendered, version } from '$service-worker';
```
This module is only available to [service workers](/docs/kit/service-workers).
## base
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.
<div class="ts-block">
```dts
const base: string;
```
</div>
## build
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.
<div class="ts-block">
```dts
const build: string[];
```
</div>
## files
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`](/docs/kit/configuration#serviceWorker)
<div class="ts-block">
```dts
const files: string[];
```
</div>
## prerendered
An array of pathnames corresponding to prerendered pages and endpoints.
During development, this is an empty array.
<div class="ts-block">
```dts
const prerendered: string[];
```
</div>
## version
See [`config.kit.version`](/docs/kit/configuration#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.
<div class="ts-block">
```dts
const version: string;
```
</div>
# Configuration
Your project's configuration lives in a `svelte.config.js` file at the root of your project. As well as SvelteKit, this config object is used by other tooling that integrates with Svelte such as editor extensions.
```js
/// file: svelte.config.js
// @filename: ambient.d.ts
declare module '@sveltejs/adapter-auto' {
const plugin: () => import('@sveltejs/kit').Adapter;
export default plugin;
}
// @filename: index.js
// ---cut---
import adapter from '@sveltejs/adapter-auto';
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
adapter: adapter()
}
};
export default config;
```
## Config
An extension of [`vite-plugin-svelte`'s options](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#svelte-options).
<div class="ts-block">
```dts
interface Config extends SvelteConfig {/*…*/}
```
<div class="ts-block-property">
```dts
kit?: KitConfig;
```
<div class="ts-block-property-details">
SvelteKit options.
</div>
</div>
<div class="ts-block-property">
```dts
[key: string]: any;
```
<div class="ts-block-property-details">
Any additional options required by tooling that integrates with Svelte.
</div>
</div></div>
## KitConfig
The `kit` property configures SvelteKit, and can have the following properties:
## adapter
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `undefined`
</div>
Your [adapter](/docs/kit/adapters) is run when executing `vite build`. It determines how the output is converted for different platforms.
<div class="ts-block-property-children">
</div>
## alias
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `{}`
</div>
An object containing zero or more aliases used to replace values in `import` statements. These aliases are automatically passed to Vite and TypeScript.
```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
alias: {
// this will match a file
'my-file': 'path/to/my-file.js',
// this will match a directory and its contents
// (`my-directory/x` resolves to `path/to/my-directory/x`)
'my-directory': 'path/to/my-directory',
// an alias ending /* will only match
// the contents of a directory, not the directory itself
'my-directory/*': 'path/to/my-directory/*'
}
}
};
```
> [!NOTE] You will need to run `npm run dev` to have SvelteKit automatically generate the required alias configuration in `jsconfig.json` or `tsconfig.json`.
<div class="ts-block-property-children">
</div>
## appDir
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"_app"`
</div>
The directory where SvelteKit keeps its stuff, including static assets (such as JS and CSS) and internally-used routes.
If `paths.assets` is specified, there will be two app directories — `${paths.assets}/${appDir}` and `${paths.base}/${appDir}`.
<div class="ts-block-property-children">
</div>
## csp
<div class="ts-block-property-bullets">
</div>
[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) configuration. CSP helps to protect your users against cross-site scripting (XSS) attacks, by limiting the places resources can be loaded from. For example, a configuration like this...
```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
csp: {
directives: {
'script-src': ['self']
},
// must be specified with either the `report-uri` or `report-to` directives, or both
reportOnly: {
'script-src': ['self'],
'report-uri': ['/']
}
}
}
};
export default config;
```
...would prevent scripts loading from external sites. SvelteKit will augment the specified directives with nonces or hashes (depending on `mode`) for any inline styles and scripts it generates.
To add a nonce for scripts and links manually included in `src/app.html`, you may use the placeholder `%sveltekit.nonce%` (for example `<script nonce="%sveltekit.nonce%">`).
When pages are prerendered, the CSP header is added via a `<meta http-equiv>` tag (note that in this case, `frame-ancestors`, `report-uri` and `sandbox` directives will be ignored).
> [!NOTE] When `mode` is `'auto'`, SvelteKit will use nonces for dynamically rendered pages and hashes for prerendered pages. Using nonces with prerendered pages is insecure and therefore forbidden.
> [!NOTE] Note that most [Svelte transitions](/tutorial/svelte/transition) work by creating an inline `<style>` element. If you use these in your app, you must either leave the `style-src` directive unspecified or add `unsafe-inline`.
If this level of configuration is insufficient and you have more dynamic requirements, you can use the [`handle` hook](/docs/kit/hooks#Server-hooks-handle) to roll your own CSP.
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
mode?: 'hash' | 'nonce' | 'auto';
```
<div class="ts-block-property-details">
Whether to use hashes or nonces to restrict `<script>` and `<style>` elements. `'auto'` will use hashes for prerendered pages, and nonces for dynamically rendered pages.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
directives?: CspDirectives;
```
<div class="ts-block-property-details">
Directives that will be added to `Content-Security-Policy` headers.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
reportOnly?: CspDirectives;
```
<div class="ts-block-property-details">
Directives that will be added to `Content-Security-Policy-Report-Only` headers.
</div>
</div>
</div>
## csrf
<div class="ts-block-property-bullets">
</div>
Protection against [cross-site request forgery (CSRF)](https://owasp.org/www-community/attacks/csrf) attacks.
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
checkOrigin?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `true`
- <span class="tag deprecated">deprecated</span> Use `trustedOrigins: ['*']` instead
</div>
Whether to check the incoming `origin` header for `POST`, `PUT`, `PATCH`, or `DELETE` form submissions and verify that it matches the server's origin.
To allow people to make `POST`, `PUT`, `PATCH`, or `DELETE` requests with a `Content-Type` of `application/x-www-form-urlencoded`, `multipart/form-data`, or `text/plain` to your app from other origins, you will need to disable this option. Be careful!
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
trustedOrigins?: string[];
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `[]`
</div>
An array of origins that are allowed to make cross-origin form submissions to your app.
Each origin should be a complete origin including protocol (e.g., `https://payment-gateway.com`).
This is useful for allowing trusted third-party services like payment gateways or authentication providers to submit forms to your app.
If the array contains `'*'`, all origins will be trusted. This is generally not recommended!
> [!NOTE] Only add origins you completely trust, as this bypasses CSRF protection for those origins.
CSRF checks only apply in production, not in local development.
</div>
</div>
</div>
## embedded
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `false`
</div>
Whether or not the app is embedded inside a larger app. If `true`, SvelteKit will add its event listeners related to navigation etc on the parent of `%sveltekit.body%` instead of `window`, and will pass `params` from the server rather than inferring them from `location.pathname`.
Note that it is generally not supported to embed multiple SvelteKit apps on the same page and use client-side SvelteKit features within them (things such as pushing to the history state assume a single instance).
<div class="ts-block-property-children">
</div>
## env
<div class="ts-block-property-bullets">
</div>
Environment variable configuration
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
dir?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"."`
</div>
The directory to search for `.env` files.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
publicPrefix?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"PUBLIC_"`
</div>
A prefix that signals that an environment variable is safe to expose to client-side code. See [`$env/static/public`](/docs/kit/$env-static-public) and [`$env/dynamic/public`](/docs/kit/$env-dynamic-public). Note that Vite's [`envPrefix`](https://vitejs.dev/config/shared-options.html#envprefix) must be set separately if you are using Vite's environment variable handling - though use of that feature should generally be unnecessary.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
privatePrefix?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `""`
- <span class="tag since">available since</span> v1.21.0
</div>
A prefix that signals that an environment variable is unsafe to expose to client-side code. Environment variables matching neither the public nor the private prefix will be discarded completely. See [`$env/static/private`](/docs/kit/$env-static-private) and [`$env/dynamic/private`](/docs/kit/$env-dynamic-private).
</div>
</div>
</div>
## experimental
<div class="ts-block-property-bullets">
</div>
Experimental features. Here be dragons. These are not subject to semantic versioning, so breaking changes or removal can happen in any release.
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
tracing?: {/*…*/}
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `{ server: false, serverFile: false }`
- <span class="tag since">available since</span> v2.31.0
</div>
Options for enabling server-side [OpenTelemetry](https://opentelemetry.io/) tracing for SvelteKit operations including the [`handle` hook](/docs/kit/hooks#Server-hooks-handle), [`load` functions](/docs/kit/load), [form actions](/docs/kit/form-actions), and [remote functions](/docs/kit/remote-functions).
<div class="ts-block-property-children"><div class="ts-block-property">
```ts
// @noErrors
server?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `false`
- <span class="tag since">available since</span> v2.31.0
</div>
Enables server-side [OpenTelemetry](https://opentelemetry.io/) span emission for SvelteKit operations including the [`handle` hook](/docs/kit/hooks#Server-hooks-handle), [`load` functions](/docs/kit/load), [form actions](/docs/kit/form-actions), and [remote functions](/docs/kit/remote-functions).
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
instrumentation?: {/*…*/}
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag since">available since</span> v2.31.0
</div>
<div class="ts-block-property-children"><div class="ts-block-property">
```ts
// @noErrors
server?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `false`
- <span class="tag since">available since</span> v2.31.0
</div>
Enables `instrumentation.server.js` for tracing and observability instrumentation.
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
remoteFunctions?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `false`
</div>
Whether to enable the experimental remote functions feature. This feature is not yet stable and may be changed or removed at any time.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
forkPreloads?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `false`
</div>
Whether to enable the experimental forked preloading feature using Svelte's fork API.
</div>
</div>
</div>
## files
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
</div>
Where to find various files within your project.
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
src?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src"`
- <span class="tag since">available since</span> v2.28
</div>
the location of your source code
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
assets?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"static"`
</div>
a place to put static files that should have stable URLs and undergo no processing, such as `favicon.ico` or `manifest.json`
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
hooks?: {/*…*/}
```
<div class="ts-block-property-details">
<div class="ts-block-property-children"><div class="ts-block-property">
```ts
// @noErrors
client?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/hooks.client"`
</div>
The location of your client [hooks](/docs/kit/hooks).
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
server?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/hooks.server"`
</div>
The location of your server [hooks](/docs/kit/hooks).
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
universal?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/hooks"`
- <span class="tag since">available since</span> v2.3.0
</div>
The location of your universal [hooks](/docs/kit/hooks).
</div>
</div></div>
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
lib?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/lib"`
</div>
your app's internal library, accessible throughout the codebase as `$lib`
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
params?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/params"`
</div>
a directory containing [parameter matchers](/docs/kit/advanced-routing#Matching)
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
routes?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/routes"`
</div>
the files that define the structure of your app (see [Routing](/docs/kit/routing))
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
serviceWorker?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/service-worker"`
</div>
the location of your service worker's entry point (see [Service workers](/docs/kit/service-workers))
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
appTemplate?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/app.html"`
</div>
the location of the template for HTML responses
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
errorTemplate?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag deprecated">deprecated</span>
- <span class="tag">default</span> `"src/error.html"`
</div>
the location of the template for fallback error responses
</div>
</div>
</div>
## inlineStyleThreshold
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `0`
</div>
Inline CSS inside a `<style>` block at the head of the HTML. This option is a number that specifies the maximum length of a CSS file in UTF-16 code units, as specified by the [String.length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) property, to be inlined. All CSS files needed for the page that are smaller than this value are merged and inlined in a `<style>` block.
> [!NOTE] This results in fewer initial requests and can improve your [First Contentful Paint](https://web.dev/first-contentful-paint) score. However, it generates larger HTML output and reduces the effectiveness of browser caches. Use it advisedly.
<div class="ts-block-property-children">
</div>
## moduleExtensions
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `[".js", ".ts"]`
</div>
An array of file extensions that SvelteKit will treat as modules. Files with extensions that match neither `config.extensions` nor `config.kit.moduleExtensions` will be ignored by the router.
<div class="ts-block-property-children">
</div>
## outDir
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `".svelte-kit"`
</div>
The directory that SvelteKit writes files to during `dev` and `build`. You should exclude this directory from version control.
<div class="ts-block-property-children">
</div>
## output
<div class="ts-block-property-bullets">
</div>
Options related to the build output format
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
preloadStrategy?: 'modulepreload' | 'preload-js' | 'preload-mjs';
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"modulepreload"`
- <span class="tag since">available since</span> v1.8.4
</div>
SvelteKit will preload the JavaScript modules needed for the initial page to avoid import 'waterfalls', resulting in faster application startup. There
are three strategies with different trade-offs:
- `modulepreload` - uses `<link rel="modulepreload">`. This delivers the best results in Chromium-based browsers, in Firefox 115+, and Safari 17+. It is ignored in older browsers.
- `preload-js` - uses `<link rel="preload">`. Prevents waterfalls in Chromium and Safari, but Chromium will parse each module twice (once as a script, once as a module). Causes modules to be requested twice in Firefox. This is a good setting if you want to maximise performance for users on iOS devices at the cost of a very slight degradation for Chromium users.
- `preload-mjs` - uses `<link rel="preload">` but with the `.mjs` extension which prevents double-parsing in Chromium. Some static webservers will fail to serve .mjs files with a `Content-Type: application/javascript` header, which will cause your application to break. If that doesn't apply to you, this is the option that will deliver the best performance for the largest number of users, until `modulepreload` is more widely supported.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
bundleStrategy?: 'split' | 'single' | 'inline';
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `'split'`
- <span class="tag since">available since</span> v2.13.0
</div>
The bundle strategy option affects how your app's JavaScript and CSS files are loaded.
- If `'split'`, splits the app up into multiple .js/.css files so that they are loaded lazily as the user navigates around the app. This is the default, and is recommended for most scenarios.
- If `'single'`, creates just one .js bundle and one .css file containing code for the entire app.
- If `'inline'`, inlines all JavaScript and CSS of the entire app into the HTML. The result is usable without a server (i.e. you can just open the file in your browser).
When using `'split'`, you can also adjust the bundling behaviour by setting [`output.experimentalMinChunkSize`](https://rollupjs.org/configuration-options/#output-experimentalminchunksize) and [`output.manualChunks`](https://rollupjs.org/configuration-options/#output-manualchunks) inside your Vite config's [`build.rollupOptions`](https://vite.dev/config/build-options.html#build-rollupoptions).
If you want to inline your assets, you'll need to set Vite's [`build.assetsInlineLimit`](https://vite.dev/config/build-options.html#build-assetsinlinelimit) option to an appropriate size then import your assets through Vite.
```js
// @errors: 7031
/// file: vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [sveltekit()],
build: {
// inline all imported assets
assetsInlineLimit: Infinity
}
});
```
```svelte
/// file: src/routes/+layout.svelte
<script>
// import the asset through Vite
import favicon from './favicon.png';
</script>
<svelte:head>
<!-- this asset will be inlined as a base64 URL -->
<link rel="icon" href={favicon} />
</svelte:head>
```
</div>
</div>
</div>
## paths
<div class="ts-block-property-bullets">
</div>
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
assets?: '' | `http://${string}` | `https://${string}`;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `""`
</div>
An absolute path that your app's files are served from. This is useful if your files are served from a storage bucket of some kind.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
base?: '' | `/${string}`;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `""`
</div>
A root-relative path that must start, but not end with `/` (e.g. `/base-path`), unless it is the empty string. This specifies where your app is served from and allows the app to live on a non-root path. Note that you need to prepend all your root-relative links with the base value or they will point to the root of your domain, not your `base` (this is how the browser works). You can use [`base` from `$app/paths`](/docs/kit/$app-paths#base) for that: `<a href="{base}/your-page">Link</a>`. If you find yourself writing this often, it may make sense to extract this into a reusable component.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
relative?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `true`
- <span class="tag since">available since</span> v1.9.0
</div>
Whether to use relative asset paths.
If `true`, `base` and `assets` imported from `$app/paths` will be replaced with relative asset paths during server-side rendering, resulting in more portable HTML.
If `false`, `%sveltekit.assets%` and references to build artifacts will always be root-relative paths, unless `paths.assets` is an external URL
[Single-page app](/docs/kit/single-page-apps) fallback pages will always use absolute paths, regardless of this setting.
If your app uses a `<base>` element, you should set this to `false`, otherwise asset URLs will incorrectly be resolved against the `<base>` URL rather than the current page.
In 1.0, `undefined` was a valid value, which was set by default. In that case, if `paths.assets` was not external, SvelteKit would replace `%sveltekit.assets%` with a relative path and use relative paths to reference build artifacts, but `base` and `assets` imported from `$app/paths` would be as specified in your config.
</div>
</div>
</div>
## prerender
<div class="ts-block-property-bullets">
</div>
See [Prerendering](/docs/kit/page-options#prerender).
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
concurrency?: number;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `1`
</div>
How many pages can be prerendered simultaneously. JS is single-threaded, but in cases where prerendering performance is network-bound (for example loading content from a remote CMS) this can speed things up by processing other tasks while waiting on the network response.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
crawl?: boolean;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `true`
</div>
Whether SvelteKit should find pages to prerender by following links from `entries`.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
entries?: Array<'*' | `/${string}`>;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `["*"]`
</div>
An array of pages to prerender, or start crawling from (if `crawl: true`). The `*` string includes all routes containing no required `[parameters]` with optional parameters included as being empty (since SvelteKit doesn't know what value any parameters should have).
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
handleHttpError?: PrerenderHttpErrorHandlerValue;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"fail"`
- <span class="tag since">available since</span> v1.15.7
</div>
How to respond to HTTP errors encountered while prerendering the app.
- `'fail'` — fail the build
- `'ignore'` - silently ignore the failure and continue
- `'warn'` — continue, but print a warning
- `(details) => void` — a custom error handler that takes a `details` object with `status`, `path`, `referrer`, `referenceType` and `message` properties. If you `throw` from this function, the build will fail
```js
// @errors: 7031
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
prerender: {
handleHttpError: ({ path, referrer, message }) => {
// ignore deliberate link to shiny 404 page
if (path === '/not-found' && referrer === '/blog/how-we-built-our-404-page') {
return;
}
// otherwise fail the build
throw new Error(message);
}
}
}
};
```
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
handleMissingId?: PrerenderMissingIdHandlerValue;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"fail"`
- <span class="tag since">available since</span> v1.15.7
</div>
How to respond when hash links from one prerendered page to another don't correspond to an `id` on the destination page.
- `'fail'` — fail the build
- `'ignore'` - silently ignore the failure and continue
- `'warn'` — continue, but print a warning
- `(details) => void` — a custom error handler that takes a `details` object with `path`, `id`, `referrers` and `message` properties. If you `throw` from this function, the build will fail
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
handleEntryGeneratorMismatch?: PrerenderEntryGeneratorMismatchHandlerValue;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"fail"`
- <span class="tag since">available since</span> v1.16.0
</div>
How to respond when an entry generated by the `entries` export doesn't match the route it was generated from.
- `'fail'` — fail the build
- `'ignore'` - silently ignore the failure and continue
- `'warn'` — continue, but print a warning
- `(details) => void` — a custom error handler that takes a `details` object with `generatedFromId`, `entry`, `matchedId` and `message` properties. If you `throw` from this function, the build will fail
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
handleUnseenRoutes?: PrerenderUnseenRoutesHandlerValue;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"fail"`
- <span class="tag since">available since</span> v2.16.0
</div>
How to respond when a route is marked as prerenderable but has not been prerendered.
- `'fail'` — fail the build
- `'ignore'` - silently ignore the failure and continue
- `'warn'` — continue, but print a warning
- `(details) => void` — a custom error handler that takes a `details` object with a `routes` property which contains all routes that haven't been prerendered. If you `throw` from this function, the build will fail
The default behavior is to fail the build. This may be undesirable when you know that some of your routes may never be reached under certain
circumstances such as a CMS not returning data for a specific area, resulting in certain routes never being reached.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
origin?: string;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"http://sveltekit-prerender"`
</div>
The value of `url.origin` during prerendering; useful if it is included in rendered content.
</div>
</div>
</div>
## router
<div class="ts-block-property-bullets">
</div>
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
type?: 'pathname' | 'hash';
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"pathname"`
- <span class="tag since">available since</span> v2.14.0
</div>
What type of client-side router to use.
- `'pathname'` is the default and means the current URL pathname determines the route
- `'hash'` means the route is determined by `location.hash`. In this case, SSR and prerendering are disabled. This is only recommended if `pathname` is not an option, for example because you don't control the webserver where your app is deployed.
It comes with some caveats: you can't use server-side rendering (or indeed any server logic), and you have to make sure that the links in your app all start with #/, or they won't work. Beyond that, everything works exactly like a normal SvelteKit app.
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
resolution?: 'client' | 'server';
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `"client"`
- <span class="tag since">available since</span> v2.17.0
</div>
How to determine which route to load when navigating to a new page.
By default, SvelteKit will serve a route manifest to the browser.
When navigating, this manifest is used (along with the `reroute` hook, if it exists) to determine which components to load and which `load` functions to run.
Because everything happens on the client, this decision can be made immediately. The drawback is that the manifest needs to be
loaded and parsed before the first navigation can happen, which may have an impact if your app contains many routes.
Alternatively, SvelteKit can determine the route on the server. This means that for every navigation to a path that has not yet been visited, the server will be asked to determine the route.
This has several advantages:
- The client does not need to load the routing manifest upfront, which can lead to faster initial page loads
- The list of routes is hidden from public view
- The server has an opportunity to intercept each navigation (for example through a middleware), enabling (for example) A/B testing opaque to SvelteKit
The drawback is that for unvisited paths, resolution will take slightly longer (though this is mitigated by [preloading](/docs/kit/link-options#data-sveltekit-preload-data)).
> [!NOTE] When using server-side route resolution and prerendering, the resolution is prerendered along with the route itself.
</div>
</div>
</div>
## serviceWorker
<div class="ts-block-property-bullets">
</div>
<div class="ts-block-property-children">
</div>
## typescript
<div class="ts-block-property-bullets">
</div>
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
config?: (config: Record<string, any>) => Record<string, any> | void;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `(config) => config`
- <span class="tag since">available since</span> v1.3.0
</div>
A function that allows you to edit the generated `tsconfig.json`. You can mutate the config (recommended) or return a new one.
This is useful for extending a shared `tsconfig.json` in a monorepo root, for example.
Note that any paths configured here should be relative to the generated config file, which is written to `.svelte-kit/tsconfig.json`.
</div>
</div>
</div>
## version
<div class="ts-block-property-bullets">
</div>
Client-side navigation can be buggy if you deploy a new version of your app while people are using it. If the code for the new page is already loaded, it may have stale content; if it isn't, the app's route manifest may point to a JavaScript file that no longer exists.
SvelteKit helps you solve this problem through version management.
If SvelteKit encounters an error while loading the page and detects that a new version has been deployed (using the `name` specified here, which defaults to a timestamp of the build) it will fall back to traditional full-page navigation.
Not all navigations will result in an error though, for example if the JavaScript for the next page is already loaded. If you still want to force a full-page navigation in these cases, use techniques such as setting the `pollInterval` and then using `beforeNavigate`:
```html
/// file: +layout.svelte
<script>
import { beforeNavigate } from '$app/navigation';
import { updated } from '$app/state';
beforeNavigate(({ willUnload, to }) => {
if (updated.current && !willUnload && to?.url) {
location.href = to.url.href;
}
});
</script>
```
If you set `pollInterval` to a non-zero value, SvelteKit will poll for new versions in the background and set the value of [`updated.current`](/docs/kit/$app-state#updated) `true` when it detects one.
<div class="ts-block-property-children">
<div class="ts-block-property">
```ts
// @noErrors
name?: string;
```
<div class="ts-block-property-details">
The current app version string. If specified, this must be deterministic (e.g. a commit ref rather than `Math.random()` or `Date.now().toString()`), otherwise defaults to a timestamp of the build.
For example, to use the current commit hash, you could do use `git rev-parse HEAD`:
```js
// @errors: 7031
/// file: svelte.config.js
import * as child_process from 'node:child_process';
export default {
kit: {
version: {
name: child_process.execSync('git rev-parse HEAD').toString().trim()
}
}
};
```
</div>
</div>
<div class="ts-block-property">
```ts
// @noErrors
pollInterval?: number;
```
<div class="ts-block-property-details">
<div class="ts-block-property-bullets">
- <span class="tag">default</span> `0`
</div>
The interval in milliseconds to poll for version changes. If this is `0`, no polling occurs.
</div>
</div>
</div>
# Command Line Interface
SvelteKit projects use [Vite](https://vitejs.dev), meaning you'll mostly use its CLI (albeit via `npm run dev/build/preview` scripts):
- `vite dev` — start a development server
- `vite build` — build a production version of your app
- `vite preview` — run the production version locally
However SvelteKit includes its own CLI for initialising your project:
## svelte-kit sync
`svelte-kit sync` creates the `tsconfig.json` and all generated types (which you can import as `./$types` inside routing files) for your project. When you create a new project, it is listed as the `prepare` script and will be run automatically as part of the npm lifecycle, so you should not ordinarily have to run this command.
# Types
## Generated types
The `RequestHandler` and `Load` types both accept a `Params` argument allowing you to type the `params` object. For example this endpoint expects `foo`, `bar` and `baz` params:
```js
/// file: src/routes/[foo]/[bar]/[baz]/+server.js
// @errors: 2355 2322 1360
/** @type {import('@sveltejs/kit').RequestHandler<{
foo: string;
bar: string;
baz: string
}>} */
export async function GET({ params }) {
// ...
}
```
Needless to say, this is cumbersome to write out, and less portable (if you were to rename the `[foo]` directory to `[qux]`, the type would no longer reflect reality).
To solve this problem, SvelteKit generates `.d.ts` files for each of your endpoints and pages:
```ts
/// file: .svelte-kit/types/src/routes/[foo]/[bar]/[baz]/$types.d.ts
/// link: true
import type * as Kit from '@sveltejs/kit';
type RouteParams = {
foo: string;
bar: string;
baz: string;
};
export type RequestHandler = Kit.RequestHandler<RouteParams>;
export type PageLoad = Kit.Load<RouteParams>;
```
These files can be imported into your endpoints and pages as siblings, thanks to the [`rootDirs`](https://www.typescriptlang.org/tsconfig#rootDirs) option in your TypeScript configuration:
```js
/// file: src/routes/[foo]/[bar]/[baz]/+server.js
// @filename: $types.d.ts
import type * as Kit from '@sveltejs/kit';
type RouteParams = {
foo: string;
bar: string;
baz: string;
}
export type RequestHandler = Kit.RequestHandler<RouteParams>;
// @filename: index.js
// @errors: 2355 2322
// ---cut---
/** @type {import('./$types').RequestHandler} */
export async function GET({ params }) {
// ...
}
```
```js
/// file: src/routes/[foo]/[bar]/[baz]/+page.js
// @filename: $types.d.ts
import type * as Kit from '@sveltejs/kit';
type RouteParams = {
foo: string;
bar: string;
baz: string;
}
export type PageLoad = Kit.Load<RouteParams>;
// @filename: index.js
// @errors: 2355
// ---cut---
/** @type {import('./$types').PageLoad} */
export async function load({ params, fetch }) {
// ...
}
```
The return types of the load functions are then available through the `$types` module as `PageData` and `LayoutData` respectively, while the union of the return values of all `Actions` is available as `ActionData`.
Starting with version 2.16.0, two additional helper types are provided: `PageProps` defines `data: PageData`, as well as `form: ActionData`, when there are actions defined, while `LayoutProps` defines `data: LayoutData`, as well as `children: Snippet`.
```svelte
<!--- file: src/routes/+page.svelte --->
<script>
/** @type {import('./$types').PageProps} */
let { data, form } = $props();
</script>
```
> [!LEGACY]
> Before 2.16.0:
> ```svelte
> <!--- file: src/routes/+page.svelte --->
> <script>
> /** @type {{ data: import('./$types').PageData, form: import('./$types').ActionData }} */
> let { data, form } = $props();
> </script>
> ```
>
> Using Svelte 4:
> ```svelte
> <!--- file: src/routes/+page.svelte --->
> <script>
> /** @type {import('./$types').PageData} */
> export let data;
> /** @type {import('./$types').ActionData} */
> export let form;
> </script>
> ```
> [!NOTE] For this to work, your own `tsconfig.json` or `jsconfig.json` should extend from the generated `.svelte-kit/tsconfig.json` (where `.svelte-kit` is your [`outDir`](configuration#outDir)):
>
> `{ "extends": "./.svelte-kit/tsconfig.json" }`
### Default tsconfig.json
The generated `.svelte-kit/tsconfig.json` file contains a mixture of options. Some are generated programmatically based on your project configuration, and should generally not be overridden without good reason:
```json
/// file: .svelte-kit/tsconfig.json
{
"compilerOptions": {
"paths": {
"$lib": ["../src/lib"],
"$lib/*": ["../src/lib/*"]
},
"rootDirs": ["..", "./types"]
},
"include": [
"ambient.d.ts",
"non-ambient.d.ts",
"./types/**/$types.d.ts",
"../vite.config.js",
"../vite.config.ts",
"../src/**/*.js",
"../src/**/*.ts",
"../src/**/*.svelte",
"../tests/**/*.js",
"../tests/**/*.ts",
"../tests/**/*.svelte"
],
"exclude": [
"../node_modules/**",
"../src/service-worker.js",
"../src/service-worker/**/*.js",
"../src/service-worker.ts",
"../src/service-worker/**/*.ts",
"../src/service-worker.d.ts",
"../src/service-worker/**/*.d.ts"
]
}
```
Others are required for SvelteKit to work properly, and should also be left untouched unless you know what you're doing:
```json
/// file: .svelte-kit/tsconfig.json
{
"compilerOptions": {
// this ensures that types are explicitly
// imported with `import type`, which is
// necessary as Svelte/Vite cannot
// otherwise compile components correctly
"verbatimModuleSyntax": true,
// Vite compiles one TypeScript module
// at a time, rather than compiling
// the entire module graph
"isolatedModules": true,
// Tell TS it's used only for type-checking
"noEmit": true,
// This ensures both `vite build`
// and `svelte-package` work correctly
"lib": ["esnext", "DOM", "DOM.Iterable"],
"moduleResolution": "bundler",
"module": "esnext",
"target": "esnext"
}
}
```
Use the [`typescript.config` setting](configuration#typescript) in `svelte.config.js` to extend or modify the generated `tsconfig.json`.
## $lib
This is a simple alias to `src/lib`, or whatever directory is specified as [`config.kit.files.lib`](configuration#files). It allows you to access common components and utility modules without `../../../../` nonsense.
### $lib/server
A subdirectory of `$lib`. SvelteKit will prevent you from importing any modules in `$lib/server` into client-side code. See [server-only modules](server-only-modules).
## app.d.ts
The `app.d.ts` file is home to the ambient types of your apps, i.e. types that are available without explicitly importing them.
Always part of this file is the `App` namespace. This namespace contains several types that influence the shape of certain SvelteKit features you interact with.
## Error
Defines the common shape of expected and unexpected errors. Expected errors are thrown using the `error` function. Unexpected errors are handled by the `handleError` hooks which should return this shape.
<div class="ts-block">
```dts
interface Error {/*…*/}
```
<div class="ts-block-property">
```dts
message: string;
```
<div class="ts-block-property-details"></div>
</div></div>
## Locals
The interface that defines `event.locals`, which can be accessed in server [hooks](/docs/kit/hooks) (`handle`, and `handleError`), server-only `load` functions, and `+server.js` files.
<div class="ts-block">
```dts
interface Locals {}
```
</div>
## PageData
Defines the common shape of the [page.data state](/docs/kit/$app-state#page) and [$page.data store](/docs/kit/$app-stores#page) - that is, the data that is shared between all pages.
The `Load` and `ServerLoad` functions in `./$types` will be narrowed accordingly.
Use optional properties for data that is only present on specific pages. Do not add an index signature (`[key: string]: any`).
<div class="ts-block">
```dts
interface PageData {}
```
</div>
## PageState
The shape of the `page.state` object, which can be manipulated using the [`pushState`](/docs/kit/$app-navigation#pushState) and [`replaceState`](/docs/kit/$app-navigation#replaceState) functions from `$app/navigation`.
<div class="ts-block">
```dts
interface PageState {}
```
</div>
## Platform
If your adapter provides [platform-specific context](/docs/kit/adapters#Platform-specific-context) via `event.platform`, you can specify it here.
<div class="ts-block">
```dts
interface Platform {}
```
</div>