## 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; the error will be passed to `handleError` as an _expected_ error.
Make sure you're not catching the thrown error, which would prevent SvelteKit from handling it.
## fail
Create an `ActionFailure` object. Call when form submission fails.
```dts
function fail(status: number): ActionFailure;
```
```dts
function fail(
status: number,
data: T
): ActionFailure;
```
## invalid
Available since 2.47.3
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');
}
// ...
}
);
```
```dts
function invalid(
...issues: (StandardSchemaV1.Issue | string)[]
): never;
```
## isActionFailure
Checks whether this is an action failure thrown by `fail`.
```dts
function isActionFailure(e: unknown): e is ActionFailure;
```
## isHttpError
Checks whether this is an error thrown by `error`.
```dts
function isHttpError(
e: unknown,
status?: T
): e is HttpError & {
status: T extends undefined ? never : T;
};
```
## isRedirect
Checks whether this is a redirect thrown by `redirect`.
```dts
function isRedirect(e: unknown): e is Redirect;
```
## json
use `Response.json`
Create a JSON `Response` object from the supplied data.
```dts
function json(data: any, init?: ResponseInit): Response;
```
## normalizeUrl
Available since 2.18.0
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
```
## 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)
Create a `Response` object from the supplied body.
```dts
function text(body: string, init?: ResponseInit): Response;
```
## 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.
## 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.
```dts
interface Adapter {/*…*/}
```
```dts
name: string;
```
The name of the adapter, using for logging. Will typically correspond to the package name.
- `details.config` The merged adapter-specific route config exported from the route with `export const config`
Test support for `read` from `$app/server`.
```dts
instrumentation?: () => boolean;
```
- available since v2.31.0
Test support for `instrumentation.server.js`. To pass, the adapter must support running `instrumentation.server.js` prior to the application code.
```dts
emulate?: () => MaybePromise;
```
Creates an `Emulator`, which allows the adapter to influence the environment
during dev, build and prerendering.
```dts
vite?: {
plugins?: {
/**
* Vite plugins placed before any of SvelteKit's own plugins.
* @since 3.0.0
*/
pre?: Plugin[];
/**
* Vite plugins placed after any of SvelteKit's own plugins.
* @since 3.0.0
*/
post?: Plugin[];
};
};
```
## AwaitedActions
```dts
type AwaitedActions<
T extends Record any>
> = OptionalUnion<
{
[Key in keyof T]: UnpackValidationError<
Awaited>
>;
}[keyof T]
>;
```
## Builder
This object is passed to the `adapt` function of adapters.
It contains various methods and properties that are useful for adapting the app.
```dts
interface Builder {/*…*/}
```
```dts
log: Logger;
```
Print messages to the console. `log.info` and `log.minor` are silent unless Vite's `logLevel` is `info`.
- `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
- returns an array of files that were copied
- `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.
- available since v2.31.0
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.
A function that is called with the current route `config` and `prerender` option
and returns an `App.Platform` object
## HttpError
The object returned by the [`error`](/docs/kit/@sveltejs-kit#error) function.
```dts
interface HttpError {/*…*/}
```
```dts
status: number;
```
The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#client_error_responses), in the range 400-599.
```dts
body: App.Error;
```
The content of the error.
## 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.
```dts
type Load<
Params extends AppLayoutParams<'/'> =
AppLayoutParams<'/'>,
InputData extends Record | null = Record<
string,
any
> | null,
ParentData extends Record = Record<
string,
any
>,
OutputData extends Record | void =
Record | void,
RouteId extends AppRouteId | null = AppRouteId | null
> = (
event: LoadEvent
) => MaybePromise;
```
## 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.
```dts
interface LoadEvent<
Params extends AppLayoutParams<'/'> =
AppLayoutParams<'/'>,
Data extends Record | null = Record<
string,
any
> | null,
ParentData extends Record = Record<
string,
any
>,
RouteId extends AppRouteId | null = AppRouteId | null
> extends NavigationEvent {/*…*/}
```
```dts
fetch: typeof fetch;
```
`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#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)
```dts
data: Data;
```
Contains the data returned by the route's server `load` function (in `+layout.server.js` or `+page.server.js`), if any.
```dts
setHeaders: (headers: Record) => void;
```
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/$app-server#Cookies) API in a server-only `load` function instead.
`setHeaders` has no effect when a `load` function runs in the browser.
```dts
parent: () => Promise;
```
`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.
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
{data.count}
```
```dts
untrack: (fn: () => T) => T;
```
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!' };
}
}
```
```dts
tracing: {/*…*/}
```
- available since v2.31.0
Access to spans for tracing. If tracing is not enabled or the function is being run in the browser, these spans will do nothing.
```dts
enabled: boolean;
```
Whether tracing is enabled.
```dts
root: Span;
```
The root span for the request. This span is named `sveltekit.handle.root`.
```dts
current: Span;
```
The span associated with the current `load` function.
## LoadProperties
```dts
type LoadProperties<
input extends Record | void
> = input extends void
? undefined // needs to be undefined, because void will break intellisense
: input extends Record
? input
: unknown;
```
The [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#redirection_messages), in the range 300-308.
```dts
location: string;
```
The location to redirect to.
## 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.
## SSRManifest
Information required to instantiate a new `Server` instance.
```dts
interface SSRManifest {/*…*/}
```
```dts
appDir: string;
```
The directory where SvelteKit keeps its stuff, including static assets (such as JS and CSS) and internally-used routes.
```dts
appPath: string;
```
The `base` and `appDir` settings combined without a leading slash.
```dts
assets: Set;
```
Static files from `config.files.assets` and the service worker (if any).
```dts
mimeTypes: Record;
```
## ServerInitOptions
```dts
interface ServerInitOptions {/*…*/}
```
```dts
env: Record;
```
A map of environment variables.
```dts
read?: (file: string) => MaybePromise;
```
A function that turns an asset filename into a `ReadableStream`. Required for the `read` export from `$app/server` to work.
## 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.
```dts
type ServerLoad<
Params extends AppLayoutParams<'/'> =
AppLayoutParams<'/'>,
ParentData extends Record = Record<
string,
any
>,
OutputData extends Record | void = Record<
string,
any
> | void,
RouteId extends AppRouteId | null = AppRouteId | null
> = (
event: ServerLoadEvent
) => MaybePromise;
```
`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.
```dts
depends: (...deps: string[]) => void;
```
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
{data.count}
```
```dts
untrack: (fn: () => T) => T;
```
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!' };
}
}
```
```dts
tracing: {/*…*/}
```
- available since v2.31.0
Access to spans for tracing. If tracing is not enabled, these spans will do nothing.
```dts
enabled: boolean;
```
Whether tracing is enabled.
```dts
root: Span;
```
The root span for the request. This span is named `sveltekit.handle.root`.
```dts
current: Span;
```
The span associated with the current server `load` function.
## Snapshot
Use the [`snapshot`](/docs/kit/$app-navigation#snapshot) helper from `$app/navigation` instead.
The type of `export const snapshot` exported from a page or layout component.
```dts
interface Snapshot {/*…*/}
```
```dts
capture: () => T;
```
```dts
restore: (snapshot: T) => void;
```
## Private types
The following are referenced by the public types documented above, but cannot be imported directly:
## AdapterEntry
```dts
interface AdapterEntry {/*…*/}
```
```dts
id: string;
```
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
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
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.