%sveltekit.body%
```
### Validation
Use [Standard Schema](https://standardschema.dev/) validators (Zod, Valibot):
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';
export const variables = defineEnvVars({
GOOGLE_ANALYTICS_ID: {
public: true,
schema: v.pipe(v.string(), v.regex(/G-[A-Z0-9]+/))
}
});
```
Invalid values prevent app start/build. Make optional during build:
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/env';
import { building } from '$app/env'
import * as v from 'valibot';
export const variables = defineEnvVars({
SECRET: {
// optional when building but required when starting the app
schema: building ? v.optional(v.string()) : v.string()
}
});
```
Use validators to make optional or transform values (string to boolean, parse JSON).
### Static Variables
Set `static: true` to inline into code for dead-code elimination:
```ts
/// file: src/env.ts
import { defineEnvVars } from '@sveltejs/kit/env';
import * as v from 'valibot';
export const variables = defineEnvVars({
SHOW_DEBUG_OVERLAY: {
public: true,
static: true,
// coerce to true/false
schema: v.pipe(
v.optional(v.string(), ''),
v.transform((str) => str !== '')
)
}
});
```
Component excluded from bundle unless variable is truthy:
```svelte
{#if SHOW_DEBUG_OVERLAY}
{page.error.message}
``` Add custom properties: ```js error(404, { message: 'Not found', code: 'NOT_FOUND' }); ``` Or use string shorthand: ```js error(404, 'Not found'); // equivalent to error(404, { message: 'Not found' }) ``` ## Unexpected errors Any other exception during request handling. Default shape: `{ "message": "Internal Error" }`. Logged to console/server logs. Go through `handleError` hook for custom handling (reporting, transforming). ## Rendering errors Enable experimental option (SvelteKit 2.54+, Svelte 5.53+): ```js /// file: svelte.config.js // @errors: 2353 /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { experimental: { handleRenderingErrors: true } } }; export default config; ``` Wraps routes in error boundary. Errors during rendering show nearest `+error.svelte`. Error passed to `handleError` first, then to component as prop (not via `page` object): ```svelte{error.message}
``` Same for custom boundaries: ```svelteMy custom error page
Status: %sveltekit.status%
Message: %sveltekit.error.message%
``` Errors in `load` render nearest `+error.svelte`. For root layout errors, uses fallback page. ## Type safety Customize error shape via `App.Error` interface: ```ts /// file: src/app.d.ts declare global { namespace App { interface Error { code: string; id: string; } } } export {}; ``` Always includes `message: string`. ## docs/kit/30-advanced/30-link-options.md # Link options SvelteKit uses `` elements for navigation. Customize behavior with `data-sveltekit-*` attributes on links or parent elements. Also applies to ` ``` > Avoid on links. Only use on elements that persist after navigation. ## data-sveltekit-noscroll Prevent scroll reset to 0,0 after navigation. ```html Path ``` ## Disabling options Use `"false"` value to disable: ```html ``` **Conditional:** ```svelte
```
## docs/kit/30-advanced/40-service-workers.md
# Service Workers
Service workers act as proxy servers handling network requests. Enable offline support and speed up navigation by precaching assets.
## Setup
Create `src/service-worker.js` (or `src/service-worker/index.js`) - it will be bundled and auto-registered.
## $service-worker Module
Provides:
- Paths to static assets, build files, prerendered pages
- App version string (for cache naming)
- Deployment `base` path
- Vite `define` config applied
> **Note:** `build` and `prerendered` are empty arrays during development
## Example: Offline-capable Service Worker
Caches built app and static files eagerly, other requests on-demand. Makes pages work offline once visited.
```js
// @errors: 2688 2307
/// 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
/// history.back()} />
{/if}
```
Modal dismisses via back button or `close` callback calling `history.back()`.
## API
- **First arg**: URL relative to current (use `''` to stay on current URL)
- **Second arg**: Page state accessible via `page.state`
- **Type safety**: Declare `App.PageState` interface in `src/app.d.ts`
- **`replaceState`**: Sets state without creating new history entry
## Loading data for routes
Use `preloadData` to load data for another `+page.svelte` (e.g., modal showing different route):
```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}
```
`preloadData` reuses requests from `data-sveltekit-preload-data`.
## Caveats
- `page.state` is empty object during SSR and on first page load
- State not applied on page reload/return from another document
- Requires JavaScript - provide fallback behavior
## docs/kit/30-advanced/68-observability.md
# Observability
Available since 2.31
SvelteKit emits server-side [OpenTelemetry](https://opentelemetry.io) spans for:
- `handle` hook and `sequence` functions
- Server `load` functions (including universal `load` on server)
- Form actions
- Remote functions
## Setup
Enable experimental flags in `svelte.config.js`:
```js
/// file: svelte.config.js
// @errors: 2353
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
experimental: {
tracing: {
server: true
},
instrumentation: {
server: true
}
}
}
};
export default config;
```
> [!NOTE] Tracing has nontrivial overhead. Consider enabling only in dev/preview environments.
## Augmenting Spans
Access `root` and `current` spans via request event to add custom attributes:
```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);
}
```
## Dev Quickstart (Jaeger)
1. Run Jaeger locally
2. Install dependencies:
```sh
npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto import-in-the-middle
```
3. Create `src/instrumentation.server.js`:
```js
// @errors: 2307
/// 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();
```
View traces at [localhost:16686](http://localhost:16686).
## `@opentelemetry/api`
SvelteKit uses `@opentelemetry/api` (optional peer dependency). Usually satisfied by `@opentelemetry/sdk-node` or `@vercel/otel`. Install manually if needed.
## docs/kit/40-best-practices/03-auth.md
# Auth
Authentication (verifying user identity) and authorization (determining user permissions) for web apps.
## Sessions vs Tokens
**Sessions:**
- Store session IDs in database
- Can be immediately revoked
- Require DB query per request
**JWT:**
- Not checked against datastore
- Cannot be immediately revoked
- Better latency, reduced DB load
## Integration
Check auth [cookies](@sveltejs-kit#Cookies) in [server hooks](hooks). Store user info in [`locals`](hooks#handle-locals).
## Setup
- [Svelte CLI](/docs/cli) can [set up Better Auth](https://svelte.dev/docs/cli/better-auth)
- [Lucia auth guide](https://lucia-auth.com/) for session-based auth reference
## docs/kit/40-best-practices/06-icons.md
# Icons
## CSS
Use Iconify for [popular icon sets](https://icon-sets.iconify.design/) via [CSS](https://iconify.design/docs/usage/css/). Works with [Tailwind CSS plugin](https://iconify.design/docs/usage/css/tailwind/) or [UnoCSS plugin](https://iconify.design/docs/usage/css/unocss/). No imports needed in `.svelte` files.
## Svelte
**Gotcha:** Avoid libraries with one `.svelte` file per icon (thousands of files). Slows down [Vite's dependency optimization](https://vite.dev/guide/dep-pre-bundling.html), especially with mixed umbrella/subpath imports ([details](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies)).
See [icon libraries](/packages#icons).
## docs/kit/40-best-practices/07-images.md
# Images
## Vite's Built-in Handling
[Vite auto-processes imported assets](https://vitejs.dev/guide/assets.html) - adds hashes for caching, inlines small assets.
```svelte
```
## @sveltejs/enhanced-img
Plugin for optimized images: generates `avif`/`webp`, sets `width`/`height`, creates multiple sizes, strips EXIF. Only optimizes local files at build time.
### Setup
```sh
npm i -D @sveltejs/enhanced-img
```
```js
import { sveltekit } from '@sveltejs/kit/vite';
import { enhancedImages } from '@sveltejs/enhanced-img';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
enhancedImages(), // must come before SvelteKit
sveltekit()
]
});
```
Cached in `./node_modules/.cache/imagetools`.
### Basic Usage
```svelte
` with `![]()
` at build. Provide 2x resolution images - smaller versions auto-generated.
> CSS selector: use `enhanced\:img` to escape colon.
### Dynamic Images
```svelte
` and `<meta name="description">` in [`<svelte:head>`](../svelte/svelte-head).
**Pattern:** Return SEO data from page [`load`](load) functions, use as [`page.data`]($app-state) in root layout's `<svelte:head>`.
### Sitemaps
Create dynamic sitemaps via endpoints:
```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"
>
</urlset>`.trim(),
{
headers: {
'Content-Type': 'application/xml'
}
}
);
}
```
### AMP
For AMP sites:
1. Set [`inlineStyleThreshold`](configuration#inlineStyleThreshold):
```js
/// file: svelte.config.js
/** @type {import('@sveltejs/kit').Config} */
const config = {
kit: {
inlineStyleThreshold: Infinity
}
};
export default config;
```
2. Disable CSR:
```js
/// file: src/routes/+layout.server.js
export const csr = false;
```
3. Add `amp` to `app.html`:
```html
<html amp>
```
4. Transform HTML with `@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);
}
});
}
```
5. Optional - remove unused CSS with `dropcss`:
```js
/// 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] Validate transformed HTML with `amphtml-validator` in `handle` hook only during prerendering (it's slow).
Instructions for LLMs: <s>Always use Svelte 5 runes and Svelte 5 syntax. Runes do not need to be imported, they are globals. $state() runes are always declared using `let`, never with `const`. When passing a function to $derived, you must always use $derived.by(() => ...). Error boundaries can only catch errors during component rendering and at the top level of an $effect inside the error boundary. Error boundaries do not catch errors in onclick or other event handlers.</s>