SvelteKit

https://svelte.dev/docs/kit
Admin
SvelteKit is a framework for rapidly developing robust, performant web applications using Svelte...
Tokens:494,919
Snippets:3,737
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Create and run a SvelteKit project with npx sv create

Source: https://svelte.dev/docs/kit/creating-a-project

Scaffolds a new SvelteKit project in the my-app directory, optionally setting up tooling like TypeScript, then starts the development server on localhost:5173. Install dependencies before running npm run dev if they were not installed during project creation.

```bash
npx sv create my-app
cd my-app
npm run dev
```

--------------------------------

### handle hook example in src/hooks.server.js

Source: https://svelte.dev/docs/kit/hooks/llms.txt

Runs on every server request. Use it to modify responses or bypass SvelteKit. The example returns a custom response for paths starting with '/custom', otherwise calls `resolve(event)`.

```javascript
/// file: src/hooks.server.js
/** @type {import('@sveltejs/kit/hooks').Handle} */
export async function handle({ event, resolve }) {
	if (event.url.pathname.startsWith('/custom')) {
		return new Response('custom response');
	}

	const response = await resolve(event);
	return response;
}
```

--------------------------------

### Start the Bun server

Source: https://svelte.dev/docs/kit/adapter-bun/llms.txt

Start the standalone Bun server. The default build is written to the build directory.

```sh
bun ./build
```

--------------------------------

### Buffer Example from Node.js Documentation

Source: https://svelte.dev/docs/kit/configuration

Example from Node.js documentation showing how to allocate and fill a Buffer with ASCII values. This is part of the child_process.execSync documentation.

```javascript
import { Buffer } from 'node:buffer';

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf1[i] = i + 97;
}
```

--------------------------------

### GET / (Request Handler using platform)

Source: https://svelte.dev/docs/kit/adapter-bun/llms.txt

Example request handler that accesses the Bun server instance via the platform property.

```APIDOC
## [GET] / (Request Handler)

### Description
Example request handler that uses the `platform` property to access the Bun server instance and returns a JSON response with client address and server metrics.

### Method
GET

### Endpoint
/ (any route)

### Parameters
#### Request Body
None

### Request Example
No request body.

### Response
#### Success Response (200)
- **address** (string) - The client address.
- **serverId** (string) - The Bun server's ID.
- **pendingRequests** (number) - Number of pending requests.
- **pendingWebSockets** (number) - Number of pending WebSockets.

#### Response Example
{
  "address": "127.0.0.1",
  "serverId": "server-123",
  "pendingRequests": 0,
  "pendingWebSockets": 0
}
```

--------------------------------

### Install @sveltejs/adapter-bun

Source: https://svelte.dev/docs/kit/adapter-bun/llms.txt

Install the adapter as a development dependency. Requires Bun 1.4 or newer.

```sh
bun add -D @sveltejs/adapter-bun
```

--------------------------------

### Example process.env object

Source: https://svelte.dev/docs/kit/adapter-node

An example of the process.env object containing user environment variables.

```json
{
  "TERM": "xterm-256color",
  "SHELL": "/usr/local/bin/bash",
  "USER": "maciej",
  "PATH": "~/.bin/:/usr/bin:/usr/bin:/usr/sbin:/usr/local/bin",
  "PWD": "/Users/maciej",
  "EDITOR": "vim",
  "SHLVL": "1",
  "HOME": "/Users/maciej",
  "LOGNAME": "maciej",
  "_": "/usr/local/bin/node"
}
```

--------------------------------

### Install adapter-node with npm

Source: https://svelte.dev/docs/kit/adapter-node

Install the adapter-node package as a dev dependency.

```bash
npm i -D @sveltejs/adapter-node
```

--------------------------------

### Bun.build compile examples

Source: https://svelte.dev/docs/kit/adapter-bun

Examples of using Bun.build with compile options: create executable for current platform, cross-compile for Linux x64, and produce self-contained HTML.

```javascript
// Create executable for current platform
await Bun.build({
  entrypoints: ['./app.js'],
  compile: {
    target: 'linux-x64',
  },
  outfile: './my-app'
});

// Cross-compile for Linux x64
await Bun.build({
  entrypoints: ['./app.js'],
  compile: 'linux-x64',
  outfile: './my-app'
});

// Produce self-contained HTML
await Bun.build({
  entrypoints: ['./index.html'],
  target: 'browser',
  compile: true,
});

```

--------------------------------

### Install adapter-vercel with npm

Source: https://svelte.dev/docs/kit/adapter-vercel

Command to install the Vercel adapter as a dev dependency.

```bash
npm i -D @sveltejs/adapter-vercel
```

--------------------------------

### Zero-config adapter-static setup in vite.config.js

Source: https://svelte.dev/docs/kit/adapter-static/llms.txt

Zero-config setup for platforms like Vercel. Omit adapter options so adapter-static provides optimal configuration.

```javascript
// @errors: 2307
/// file: vite.config.js
import adapter from '@sveltejs/adapter-static';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			adapter: adapter(---{...}---)
		})
	]
});
```

--------------------------------

### Install adapter with npx sv add sveltekit-adapter

Source: https://svelte.dev/docs/kit/adapters

Command to install an adapter and add it to your config. Run this before configuring the adapter in vite.config.js.

```bash
npx sv add sveltekit-adapter
```

--------------------------------

### RouteParams usage example

Source: https://svelte.dev/docs/kit/%24app-types/llms.txt

Utility for getting parameters associated with a given route. The example shows a type error because the route '/blog/[slug]' is not in the generated RouteId.

```typescript
// @errors: 2552
type BlogParams = RouteParams<'/blog/[slug]'>; // { slug: string }
```

--------------------------------

### Run server with MY_APP_ prefix

Source: https://svelte.dev/docs/kit/adapter-bun

Alternative example using the MY_APP_ prefix for environment variables.

```bash
MY_APP_HOST=127.0.0.1 MY_APP_PORT=4000 bun ./build

```

--------------------------------

### Example handle hook that intercepts /custom

Source: https://svelte.dev/docs/kit/hooks

An example handle hook that checks if the request pathname starts with '/custom' and returns a custom response. Otherwise, it resolves the event normally.

```typescript
export const handle: Handle = async ({ event, resolve }) => {
	if (event.url.pathname.startsWith('/custom')) {
		return new Response('custom response');
	}

	const response = await resolve(event);
	return response;
};
```

--------------------------------

### Adapter API implementation example

Source: https://svelte.dev/docs/kit/writing-adapters/llms.txt

Shows the structure of an adapter package, including required `name` and `adapt` methods, and optional `emulate`, `supports`, and `vite` methods. The `adapt` method should clear the build directory, write client/server/prerendered output, and bundle the output. The `emulate` method returns an object that becomes `event.platform` during dev, build, and preview.

```javascript
// @errors: 2322
// @filename: ambient.d.ts
type AdapterSpecificOptions = any;

// @filename: index.js
// ---cut---
import { getRequest, setResponse } from '@sveltejs/kit/node';

/** @param {AdapterSpecificOptions} options */
export default function (options) {
	/** @type {import('@sveltejs/kit').Adapter} */
	const adapter = {
		name: 'adapter-package-name',
		async adapt(builder) {
			// adapter implementation
		},
		async emulate() {
			return {
				async platform({ config, prerender }) {
					// the returned object becomes `event.platform` during dev, build and
					// preview. Its shape is that of `App.Platform`
				}
			}
		},
		supports: {
			read: ({ config, route }) => {
				// Return `true` if the route with the given `config` can use `read`
				// from `$app/server` in production, return `false` if it can't.
				// Or throw a descriptive error describing how to configure the deployment
			},
			instrumentation: () => {
				// Return `true` if this adapter supports loading `instrumentation.server.js`.
				// Return `false if it can't, or throw a descriptive error.
			}
		},
		vite: {
			getRequest(options) {
				const request = getRequest(options);
				// modify the Request object here if needed
				return request;
			},
			setResponse(res, response) {
				// handle WebSockets here, for example
				setResponse(res, response);
			},
			plugins: {
				// add plugins here to integrate with Vite
				pre: [],
				post: []
			}
		}
	};

	return adapter;
}
```

--------------------------------

### Set custom envPrefix and run with custom environment variables

Source: https://svelte.dev/docs/kit/adapter-node/llms.txt

Shows how to set a custom envPrefix and then run the built server with the corresponding environment variables. The example uses 'MY_CUSTOM_' as the prefix and sets MY_CUSTOM_HOST and MY_CUSTOM_PORT.

```javascript
envPrefix: 'MY_CUSTOM_';
```

```shell
MY_CUSTOM_HOST=127.0.0.1 \
MY_CUSTOM_PORT=4000 \
node build
```

--------------------------------

### GET /api/items/[id]

Source: https://svelte.dev/docs/kit/load/llms.txt

Example of using the `fetch` function in a SvelteKit load function to retrieve data from an API endpoint.

```APIDOC
## [GET] /api/items/[id]

### Description
Fetches an item from an external API or a `+server.js` handler using the provided `fetch` function. The `fetch` function behaves like the native `fetch` web API but supports credentialed requests, relative URLs, and direct handler calls on the server.

### Method
GET

### Endpoint
`/api/items/[id]`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item to fetch.

### Request Example
```js
const res = await fetch(`/api/items/${params.id}`);
const item = await res.json();
```

### Response
#### Success Response (200)
- **item** (object) - The fetched item data.

#### Response Example
```json
{
  "item": {}
}
```
```

--------------------------------

### Reading `page.params.id` with `$derived` in a `+page` component

Source: https://svelte.dev/docs/kit/%24app-state

Example showing how to reactively read `page.params.id` in a `+page` component. Use `$derived` to get a value that updates; the legacy `$:` reactive statement will not update after initial load. The two blocks are the JavaScript and TypeScript variants of the same example.

```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>
```

```svelte
<script lang="ts">
	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>
```

--------------------------------

### ServerInitOptions

Source: https://svelte.dev/docs/kit/%40sveltejs-kit

Documentation for the ServerInitOptions interface in SvelteKit.

```APIDOC
## ServerInitOptions

### Description
An interface for options passed to the `Server.init` method, including environment variables and an optional read function.

### Interface
```ts
interface ServerInitOptions {
	env: Record<string, string | undefined>;
	read?: (file: string) => MaybePromise<ReadableStream | null>;
}
```

### Properties
- `env` (Record<string, string | undefined>) - Required - A map of environment variables.
- `read` ((file: string) => MaybePromise<ReadableStream | null>) - Optional - A function that turns an asset filename into a `ReadableStream`. Required for the `read` export from `$app/server` to work.
```

--------------------------------

### SvelteKit Vite plugin configuration in vite.config.js

Source: https://svelte.dev/docs/kit/%40sveltejs-kit-vite

Example of a vite.config.js file that imports and uses the SvelteKit Vite plugin. This is the required setup for any SvelteKit project.

```javascript
/// file: vite.config.js
import adapter from '@sveltejs/adapter-auto';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

```

--------------------------------

### goto(url, opts?)

Source: https://svelte.dev/docs/kit/shallow-routing

Documentation for the `goto` function from SvelteKit, including its signature, parameters, and usage notes.

```APIDOC
## goto(url, opts?)

### Description
Allows you to navigate programmatically to a given route, with control over details such as whether scroll and focus are reset (as they would be with a regular navigation) or preserved. Returns a Promise that resolves when SvelteKit navigates (or fails to navigate, in which case the promise rejects) or the state change has been applied.

### Method
Function call

### Signature
`goto(url: string | URL, opts?: GotoOptions): Promise<void>`

### Parameters
- **url** (string | URL) - Required - Where to navigate to. Note that if you've set config.paths.base and the URL is root-relative, you need to prepend the base path if you want to navigate within the app.
- **opts** (GotoOptions) - Optional - Options related to the navigation.

### GotoOptions Properties
- **state** (App.PageState) - Optional - An optional object that will be available as `page.state`.
- **replace** (boolean) - Optional - If true, replaces the current history entry rather than creating a new one. Default: `false`.
- **persistState** (boolean) - Optional - If true, `page.state` will be restored after a full page reload. Default: `false`.
- **shallow** (boolean) - Optional - If true, updates the URL and `page.state` without navigating. Default: `false`.
- **reset** (boolean) - Optional - If true, resets the scroll position (to the top of the page, or to the element matching the URL's `#hash` if there is one) and resets focus (to the `<body>`, or the autofocus element if there is one) once the navigation completes. If false, the current scroll position and focused element are left alone. Default: `true`, or `false` when `shallow` is `true`.

### Usage Notes
- `goto` is intended for navigations to routes that belong to the app, and will reject if a route cannot be resolved.
- For external URLs, use `window.location = url` to perform a full-page navigation instead of calling `goto(url)`.
- A regular `goto` call without `shallow: true`, or a standard link click, exits shallow routing.
- Navigating back or forward to a shallow entry restores its `page.state` and `page.shallow`. The rendered page, and therefore `page.url`, is still the one the user was on when `goto` was called. To navigate to the visible URL, call `goto(page.shallow.url)` without `shallow: true`.
- In SvelteKit 2, this functionality was achieved using `pushState` and `replaceState`, which are now deprecated. Use `goto` with `shallow: true` instead, and use the `replace` option when replacing the current history entry.
- By default, state set with `goto` is not restored after a reload. To change that, use `persistState`.
- Shallow navigations preserve the current scroll position and focused element by default. You can opt out of this behavior with `reset: true`.
- `page.state` is only populated after JavaScript loads, which can cause flickering UI. Use it carefully.
```

--------------------------------

### Import sveltekit and defineConfig in vite.config.js

Source: https://svelte.dev/docs/kit/%40sveltejs-kit-vite

Minimal example of importing the sveltekit plugin and defineConfig in vite.config.js. This is the starting point for configuring SvelteKit in the Vite config file.

```javascript
/// file: vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

```

--------------------------------

### Set up integrations with npx sv add

Source: https://svelte.dev/docs/kit/integrations

Run this command to set up many different complex integrations with a single command, including prettier, eslint, vitest, playwright, better-auth, tailwind, drizzle, paraglide, mdsvex, storybook, adapters, and mcp.

```bash
npx sv add
```

--------------------------------

### Set up SvelteKit with Yarn 3

Source: https://svelte.dev/docs/kit/faq

Steps to set up a SvelteKit app with Yarn 3 (Berry). First create the app, then enable Yarn Berry. Add nodeLinker: node-modules to .yarnrc.yml to avoid build failures caused by enableGlobalCache.

```bash
yarn create svelte myapp
cd myapp
```

```bash
yarn set version berry
yarn install
```

```yaml
nodeLinker: node-modules
```

--------------------------------

### Enable Yarn Berry (Yarn 3)

Source: https://svelte.dev/docs/kit/faq/llms.txt

Commands to enable Yarn Berry (version 3) and install dependencies. This is part of the Yarn 3 setup workflow.

```sh
yarn set version berry
yarn install
```

--------------------------------

### Get query parameter with URLSearchParams

Source: https://svelte.dev/docs/kit/web-standards/llms.txt

Shows how to access a query parameter from a URL using the URLSearchParams interface. The example declares a global URL variable and then retrieves the 'foo' parameter.

```javascript
// @filename: ambient.d.ts
declare global {
	const url: URL;
}

export {};

// @filename: index.js
// ---cut---
const foo = url.searchParams.get('foo');
```

--------------------------------

### init

Source: https://svelte.dev/docs/kit/hooks

Documentation for the init hook in SvelteKit, which runs once on server creation or app start in the browser.

```APIDOC
## init

### Description
Runs once when the server is created or the app starts in the browser. Useful for asynchronous initialization such as database connections.

### Method
N/A (lifecycle hook)

### Endpoint
N/A

### Parameters
None

### Request Example
N/A

### Response
N/A

### Notes
- Can be added to `src/hooks.server.js` and `src/hooks.client.js`.
- In the browser, asynchronous work in `init` will delay hydration.
- If the environment supports top-level await, `init` is equivalent to top-level initialization logic.

### Type Signature
`ServerInit = () => MaybePromise<void>`

### Example (Server)
```js
import db from '#lib/server/database.js';

/** @type {import('@sveltejs/kit/hooks').ServerInit} */
export async function init() {
	await db.connect();
}
```

### Example (Server with type import)
```js
import db from '#lib/server/database.js';
import type { ServerInit } from '@sveltejs/kit/hooks';

export const init: ServerInit = async () => {
	await db.connect();
};
```
```

--------------------------------

### Access request.cf in SvelteKit 3

Source: https://svelte.dev/docs/kit/migrating-to-sveltekit-3/llms.txt

Shows that the 'cf' property is now on the Request object in SvelteKit 3 with adapter-cloudflare. The example includes a type declaration for Request.cf and a GET handler that accesses request.cf.

```javascript
/// file: src/routes/cf/+server.js
// @filename: ambient.d.ts
interface Request {
  cf: import('@cloudflare/workers-types').IncomingRequestCfProperties;
}
// @filename: index.js
// @errors: 7031
// ---cut---
export async function GET({ request }) {
	const { country } = request.cf;
}
```

--------------------------------

### Set Version Name from Git Commit Hash in vite.config.js

Source: https://svelte.dev/docs/kit/configuration

Example vite.config.js that sets the version.name using child_process.execSync to get the current git commit hash, ensuring deterministic versioning.

```javascript
import * as child_process from 'node:child_process';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
 		version: {
				name: child_process.execSync('git rev-parse HEAD').toString().trim()
			}
		})
	]
});
```

--------------------------------

### Using cookies.parse to apply external Set-Cookie headers

Source: https://svelte.dev/docs/kit/%40sveltejs-kit/llms.txt

Example showing how to use cookies.parse to apply cookies received from an external source. It uses getRequestEvent to access cookies, iterates over response.headers.getSetCookie() (not get('set-cookie')), and sets each parsed cookie.

```js
// @errors: 7031
import { getRequestEvent } from '$app/server';

export async function GET() {
	const { cookies } = getRequestEvent();

	const response = await fetch('...');

	for (const str of response.headers.getSetCookie()) {
		const { name, value, ...options } = cookies.parse(str);
		cookies.set(name, value, options);
	}

	// ...
}
```

--------------------------------

### Run server with prefixed environment variables

Source: https://svelte.dev/docs/kit/adapter-bun

Run the built server with environment variables using the configured prefix. The example uses MY_CUSTOM_ prefix.

```bash
MY_CUSTOM_HOST=127.0.0.1 \
MY_CUSTOM_PORT=4000 \
bun ./build

```

--------------------------------

### handleFetch: Rewrite request URL in src/hooks.server.js

Source: https://svelte.dev/docs/kit/hooks

Modify the URL of an incoming fetch request during server-side rendering or prerendering. The example checks if the request URL starts with a public API endpoint and rewrites it to a local URL before passing it to the original fetch. This is useful for bypassing proxies or load balancers during SSR.

```javascript
/** @type {import('@sveltejs/kit/hooks').HandleFetch} */
export async function handleFetch({ request, fetch }) {
	if (request.url.startsWith('https://api.yourapp.com/')) {
		// clone the original request, but change the URL
		request = new Request(
			request.url.replace('https://api.yourapp.com/', 'http://localhost:9999/'),
			request
		);
	}

	return fetch(request);
}
```

--------------------------------

### Node.js process.argv example output

Source: https://svelte.dev/docs/kit/adapter-static

Example output from running the process-args.js script. Shows the array indices and values of process.argv. The first element is the Node.js executable, the second is the script path, and the rest are the provided arguments.

```text
0: /usr/local/bin/node
1: /Users/mjr/work/node/process-args.js
2: one
3: two=three
4: four
```

--------------------------------

### Install @sveltejs/enhanced-img

Source: https://svelte.dev/docs/kit/images

Install the @sveltejs/enhanced-img package as a dev dependency.

```bash
npm i -D @sveltejs/enhanced-img
```

--------------------------------

### Build and run compiled executable

Source: https://svelte.dev/docs/kit/adapter-bun

Build the server with Bun and run the generated executable without a separately installed Bun runtime.

```bash
bun run --bun build
./build/server

```

--------------------------------

### handleFetch hook: forward cookies to API requests

Source: https://svelte.dev/docs/kit/hooks

Use this hook to modify or replace the result of an event.fetch call that runs on the server (or during prerendering) inside an endpoint, load, action, handle, handleError, or reroute. The example forwards the original request's cookie header when the request URL starts with 'https://api.my-domain.com/'. The hook receives the event, the request, and the fetch function, and must return a Response.

```typescript
import type { HandleFetch } from '@sveltejs/kit/hooks';

export const handleFetch: HandleFetch = async ({ event, request, fetch }) => {
	if (request.url.startsWith('https://api.my-domain.com/')) {
		request.headers.set('cookie', event.request.headers.get('cookie'));
	}

	return fetch(request);
};
```
Tokens:
Raw