likes: {await getLikes(item.id)}
``` **Note:** Commands cannot be called during render. Prefer `form` where possible. ### Updating queries Inside command: ```js export const addLike = command(v.string(), async (id) => { await db.sql`UPDATE item SET likes = likes + 1 WHERE id = ${id}`; getLikes(id).refresh(); // or: getLikes(id).set(...) }); ``` When calling: ```ts await addLike(item.id).updates(getLikes(item.id)); ``` Optimistic updates: ```ts await addLike(item.id).updates( getLikes(item.id).withOverride((n) => n + 1) ); ``` ## prerender Invoked at build time for static data: ```js import { prerender } from '$app/server'; export const getPosts = prerender(async () => { const posts = await db.sql`SELECT title, slug FROM post ORDER BY published_at DESC`; return posts; }); ``` Data cached using Cache API, survives reloads, cleared on new deployment. ### Prerender arguments ```js export const getPost = prerender(v.string(), async (slug) => { const [post] = await db.sql`SELECT * FROM post WHERE slug = ${slug}`; if (!post) error(404, 'Not found'); return post; }); ``` Specify inputs: ```js export const getPost = prerender( v.string(), async (slug) => { /* ... */ }, { inputs: () => ['first-post', 'second-post', 'third-post'] } ); ``` Allow dynamic calls: ```js export const getPost = prerender( v.string(), async (slug) => { /* ... */ }, { dynamic: true, inputs: () => ['first-post', 'second-post', 'third-post'] } ); ``` ## Handling validation errors Implement `handleValidationError` hook: ```js /// file: src/hooks.server.ts export function handleValidationError({ event, issues }) { return { message: 'Nice try, hacker!' }; } ``` Opt out of validation: ```ts export const getStuff = query('unchecked', async ({ id }: { id: string }) => { // shape might not match TypeScript }); ``` ## Using `getRequestEvent` Access `RequestEvent` inside `query`, `form`, `command`: ```ts import { getRequestEvent, query } from '$app/server'; export const getProfile = query(async () => { const user = await getUser(); return { name: user.name, avatar: user.avatar }; }); const getUser = query(async () => { const { cookies } = getRequestEvent(); return await findUser(cookies.get('session_id')); }); ``` **Note:** Some properties differ in remote functions: - Cannot set headers (except cookies in `form`/`command`) - `route`, `params`, `url` relate to calling page, not endpoint - Don't use for authorization checks ## Redirects Use `redirect(...)` in `query`, `form`, `prerender`. **Not** in `command` (return `{ redirect: location }` if needed). ## docs/kit/25-build-and-deploy/10-building-your-app.md # Building your app Building happens in two stages when running `vite build`: 1. Vite creates optimized production builds (server code, browser code, service worker). Prerendering executes here. 2. An adapter tunes the build for your target environment. ## During the build Files are loaded for analysis during build. Code that shouldn't execute at build time must check `building`: ```js import { building } from '$app/environment'; import { initialiseDatabase } from '$lib/server/database'; if (!building) { initialiseDatabase(); } export function load() { // ... } ``` ## Preview your app View production build locally with `vite preview`. Runs in Node, so adapter-specific features like `platform` object don't apply. ## docs/kit/25-build-and-deploy/20-adapters.md # Adapters Adapters are plugins that prepare your SvelteKit app for deployment to specific platforms. ## Official Adapters - `@sveltejs/adapter-cloudflare` - Cloudflare Workers/Pages - `@sveltejs/adapter-netlify` - Netlify - `@sveltejs/adapter-node` - Node servers - `@sveltejs/adapter-static` - Static site generation (SSG) - `@sveltejs/adapter-vercel` - Vercel Community adapters available at `/packages#sveltekit-adapters`. ## Usage Configure in `svelte.config.js`: ```js /// file: svelte.config.js // @filename: ambient.d.ts declare module 'svelte-adapter-foo' { const adapter: (opts: any) => import('@sveltejs/kit').Adapter; export default adapter; } // @filename: index.js //cut import adapter from 'svelte-adapter-foo'; /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { adapter: adapter({ // adapter options go here }) } }; export default config; ``` ## Platform-Specific Context Adapters may provide platform-specific data (e.g., Cloudflare KV namespaces) via `platform` property in `RequestEvent` (available in hooks and server routes). See adapter docs for details. ## docs/kit/25-build-and-deploy/55-single-page-apps.md # Single-page apps Turn SvelteKit into a client-rendered SPA by specifying a fallback page that serves URLs not handled by prerendered pages. > [!NOTE] SPA mode forces multiple network round trips (HTML → JS → data) before showing content, harming performance and SEO. Prerender as many pages as possible, especially your homepage. If all pages can be prerendered, use [static site generation](adapter-static) instead. ## Usage Disable SSR for non-prerendered pages: ```js /// file: src/routes/+layout.js export const ssr = false; ``` If no server-side logic (`+page.server.js`, `+layout.server.js`, `+server.js`), use `adapter-static`: ```js /// file: svelte.config.js import adapter from '@sveltejs/adapter-static'; /** @type {import('@sveltejs/kit').Config} */ const config = { kit: { adapter: adapter({ fallback: '200.html' // may differ from host to host }) } }; export default config; ``` The `fallback` page is an HTML page that loads your app and navigates to the correct route. Consult your platform's docs for the correct filename (e.g. `200.html` for Surge). Avoid `index.html` as it may conflict with prerendering. > [!NOTE] Fallback page always contains absolute asset paths (starting with `/`) regardless of `paths.relative`. ## Prerendering individual pages Re-enable `ssr` + `prerender` for specific pages: ```js /// file: src/routes/my-prerendered-page/+page.js export const prerender = true; export const ssr = true; ``` No Node server needed—pages are server-rendered at build time to static `.html` files. ## Apache Add `static/.htaccess` to route requests to fallback: ```{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" }`. Sensitive info not exposed to users. Use [`handleError`](hooks#Shared-hooks-handleError) hook for custom handling (logging, reporting, etc.). ## Responses **In `handle` or `+server.js`:** Returns fallback error page or JSON based on `Accept` headers. **In `load` functions:** Renders nearest `+error.svelte` component. If error in root `+layout(.server).js`, uses fallback error page. ### Custom Fallback Error Page ```htmlMy custom error page
Status: %sveltekit.status%
Message: %sveltekit.error.message%
``` ## 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` property. ## 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 to top (0,0) after navigation. ```html Path ``` ## Disabling options Use `"false"` to disable inherited attributes: ```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 built JS/CSS.
## Setup
Place service worker at `src/service-worker.js` (or `src/service-worker/index.js`) - auto-bundled and registered.
Can [disable auto-registration](configuration#serviceWorker) and register manually:
```js
if ('serviceWorker' in navigator) {
addEventListener('load', function () {
navigator.serviceWorker.register('./path/to/service-worker.js');
});
}
```
## `$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
## Example: Offline-Capable Caching
Eagerly caches built app + `static` files. Caches other requests on-demand. Makes pages work offline once visited.
```js
/// file: src/service-worker.js
/// 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-safe via `App.PageState` interface in `src/app.d.ts`
- `replaceState`: Same as `pushState` but doesn't create new history entry
> SvelteKit 2.12+: use `page.state` from `$app/state`. Earlier/Svelte 4: use `$page.state` from `$app/stores`
## Loading data for routes
Render another `+page.svelte` inside current page using `preloadData`:
```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
- SSR: `page.state` always empty object
- First page load: state not applied until navigation (even on reload)
- Requires JavaScript - provide fallback behavior
## docs/kit/30-advanced/68-observability.md
# Observability
Available since 2.31. Experimental features - subject to change.
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 in `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 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
/// 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`
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 verifies user identity via credentials. Authorization determines allowed actions.
## Sessions vs Tokens
**Sessions:**
- Stored in database
- Require DB query per request
- Can be immediately revoked
**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#Server-hooks). Store user info in [`locals`](hooks#Server-hooks-locals).
## Guides
[Lucia](https://lucia-auth.com/) provides session-based auth examples for SvelteKit.
Add to project:
- New project: `npx sv create`
- Existing: `npx sv add lucia`
Auth is tightly coupled to web frameworks. SvelteKit-specific guides like Lucia are preferable to generic JS auth libraries that bundle multiple frameworks.
## docs/kit/40-best-practices/06-icons.md
# Icons
## CSS
Use Iconify for [many icon sets](https://icon-sets.iconify.design/) via [CSS](https://iconify.design/docs/usage/css/). Works with [Tailwind](https://iconify.design/docs/usage/css/tailwind/) and [UnoCSS](https://iconify.design/docs/usage/css/unocss/) plugins. No imports needed in `.svelte` files.
## Svelte
Many [icon libraries](/packages#icons) available. **Avoid libraries with one `.svelte` file per icon** - thousands of files slow down [Vite's dependency optimization](https://vite.dev/guide/dep-pre-bundling.html). Especially problematic with mixed umbrella and subpath imports ([see FAQ](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md#what-is-going-on-with-vite-and-pre-bundling-dependencies)).
## docs/kit/40-best-practices/07-images.md
# Images
Images impact performance. Optimize by generating optimal formats (`.avif`, `.webp`), creating multiple sizes, and ensuring caching.
## Vite's Built-in Handling
[Vite auto-processes imported assets](https://vitejs.dev/guide/assets.html). Adds hashes for caching, inlines small assets. Works for images, video, audio, CSS `url()`.
```svelte
```
## @sveltejs/enhanced-img
Plugin for Vite that serves `avif`/`webp`, sets `width`/`height` to avoid layout shift, 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(), // before sveltekit()
sveltekit()
]
});
```
Output cached in `./node_modules/.cache/imagetools`.
### Basic Usage
```svelte
![]()
` wrapped in `` with multiple formats/sizes. Provide 2x resolution for HiDPI; 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). Common pattern: return SEO data from [`load`](load), use as [`page.data`]($app-state) in root [layout](routing#layout).
### 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](https://amp.dev/) 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`](https://www.npmjs.com/package/dropcss):
```js
/// file: src/hooks.server.js
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>`);
}
}
});
}
```
> Validate with `amphtml-validator` in `handle` hook, but only when 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>