Hooks
Edit this page on GitHub'Hooks' are app-wide functions you declare that SvelteKit will call in response to specific events, giving you fine-grained control over the framework's behaviour.
There are two hooks files, both optional:
src/hooks.server.js
— your app's server hookssrc/hooks.client.js
— your app's client hooks
Code in these modules will run when the application starts up, making them useful for initializing database clients and so on.
You can configure the location of these files with
config.kit.files.hooks
.
Server hookspermalink
The following hooks can be added to src/hooks.server.js
:
handlepermalink
This function runs every time the SvelteKit server receives a request — whether that happens while the app is running, or during prerendering — and determines the 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).
src/hooks.server.js
ts
export async functionhandle ({event ,resolve }) {if (event .url .pathname .startsWith ('/custom')) {return newResponse ('custom response');}constresponse = awaitresolve (event );returnresponse ;}
src/hooks.server.ts
ts
Requests for static assets — which includes pages that were already prerendered — are not handled by SvelteKit.
If unimplemented, defaults to ({ event, resolve }) => resolve(event)
. To add custom data to the request, which is passed to handlers in +server.js
and server-only load
functions, populate the event.locals
object, as shown below.
src/hooks.server.js
ts
export async functionhandle ({event ,resolve }) {event .locals .user = awaitgetUserInformation (event .cookies .get ('sessionid'));constresponse = awaitresolve (event );response .headers .set ('x-custom-header', 'potato');returnresponse ;}
src/hooks.server.ts
ts
You can add call multiple handle
functions with the sequence
helper function.
resolve
also supports a second, optional parameter that gives you more control over how the response will be rendered. That parameter is an object that can have the following fields:
transformPageChunk(opts: { html: string, done: boolean }): MaybePromise<string | undefined>
— applies custom transforms to HTML. Ifdone
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.filterSerializedResponseHeaders(name: string, value: string): boolean
— determines which headers should be included in serialized responses when aload
function loads a resource withfetch
. By default, none will be included.
src/hooks.server.js
ts
export async functionhandle ({event ,resolve }) {constresponse = awaitresolve (event , {transformPageChunk : ({html }) =>html .replace ('old', 'new'),filterSerializedResponseHeaders : (name ) =>name .startsWith ('x-')});returnresponse ;}
src/hooks.server.ts
ts
handleFetchpermalink
This function allows you to modify (or replace) a fetch
request that happens inside a load
function that runs on the server (or during pre-rendering).
Or your load
function might make a request to a public URL like https://api.yourapp.com
when the user performs a client-side navigation to the respective page, but during SSR it might make sense to hit the API directly (bypassing whatever proxies and load balancers sit between it and the public internet).
ts
export async functionhandleFetch ({request ,fetch }) {if (request .url .startsWith ('https://api.yourapp.com/')) {// clone the original request, but change the URLrequest = newRequest (request .url .replace ('https://api.yourapp.com/', 'http://localhost:9999/'),request );}returnfetch (request );}
Credentials
For same-origin requests, SvelteKit's fetch
implementation will forward cookie
and authorization
headers unless the credentials
option is set to "omit"
.
For cross-origin requests, cookie
will be included if the request URL belongs to a subdomain of the app — for example if your app is on my-domain.com
, and your API is on api.my-domain.com
, cookies will be included in the request.
If your app and your API are on sibling subdomains — www.my-domain.com
and api.my-domain.com
for example — then a cookie belonging to a common parent domain like my-domain.com
will not be included, because SvelteKit has no way to know which domain the cookie belongs to. In these cases you will need to manually include the cookie using handleFetch
:
ts
export async functionhandleFetch ({event ,request ,fetch }) {if (request .url .startsWith ('https://api.my-domain.com/')) {request .headers .set ('cookie',event .request .headers .get ('cookie'));}returnfetch (request );}
Shared hookspermalink
The following can be added to src/hooks.server.js
and src/hooks.client.js
:
handleErrorpermalink
If an unexpected error is thrown during loading or rendering, this function will be called with the error
and the event
. This allows for two things:
- you can log the error
- you can generate a custom representation of the error that is safe to show to users, omitting sensitive details like messages and stack traces. The returned value becomes the value of
$page.error
. It defaults to{ message: 'Not Found' }
in case of a 404 (you can detect them throughevent.route.id
beingnull
) and to{ message: 'Internal Error' }
for everything else. To make this type-safe, you can customize the expected shape by declaring anApp.Error
interface (which must includemessage: string
, to guarantee sensible fallback behavior).
The following code shows an example of typing the error shape as { message: string; code: string }
and returning it accordingly from the handleError
functions:
src/app.d.ts
ts
declare namespaceApp {message : string;code : string;}}
src/hooks.server.js
ts
export functionhandleError ({error ,event }) {// example integration with https://sentry.io/Type '{ message: string; code: any; }' is not assignable to type 'void | Error'. Object literal may only specify known properties, and 'code' does not exist in type 'Error'.Object is of type 'unknown'.2322Sentry .captureException ( error , {event });
2571Type '{ message: string; code: any; }' is not assignable to type 'void | Error'. Object literal may only specify known properties, and 'code' does not exist in type 'Error'.Object is of type 'unknown'.return {message : 'Whoops!',code :error .code ?? 'UNKNOWN'};}
src/hooks.server.ts
ts
// example integration with https://sentry.io/Object is of type 'unknown'.2571Object is of type 'unknown'.Sentry .captureException ( error , {event });return {message : 'Whoops!',code :error .code ?? 'UNKNOWN'};}
src/hooks.client.js
ts
export functionhandleError ({error ,event }) {// example integration with https://sentry.io/Type '{ message: string; code: any; }' is not assignable to type 'void | Error'. Object literal may only specify known properties, and 'code' does not exist in type 'Error'.Object is of type 'unknown'.2322Sentry .captureException ( error , {event });
2571Type '{ message: string; code: any; }' is not assignable to type 'void | Error'. Object literal may only specify known properties, and 'code' does not exist in type 'Error'.Object is of type 'unknown'.return {message : 'Whoops!',code :error .code ?? 'UNKNOWN'};}
src/hooks.client.ts
ts
// example integration with https://sentry.io/Object is of type 'unknown'.2571Object is of type 'unknown'.Sentry .captureException ( error , {event });return {message : 'Whoops!',code :error .code ?? 'UNKNOWN'};}
In
src/hooks.client.js
, the type ofhandleError
isHandleClientError
instead ofHandleServerError
, andevent
is aNavigationEvent
rather than aRequestEvent
.
This function is not called for expected errors (those thrown with the error
function imported from @sveltejs/kit
).
During development, if an error occurs because of a syntax error in your Svelte code, the passed in error has a frame
property appended highlighting the location of the error.