## docs/svelte/01-introduction/01-overview.md

# Overview

Svelte compiles declarative components (HTML, CSS, JS) into optimized JavaScript.

**Basic component:**

```svelte
<!file: App.svelte>
<script>
	function greet() {
		alert('Welcome to Svelte!');
	}
</script>

<button onclick={greet}>click me</button>

<style>
	button {
		font-size: 2em;
	}
</style>
```

Use for standalone components or full apps with SvelteKit.

## docs/svelte/01-introduction/02-getting-started.md

# Getting started

## Create project

```sh
npx sv create myapp
cd myapp
npm install
npm run dev
```

Uses [SvelteKit](../kit) (official framework) + [Vite](https://vite.dev/).

## Alternatives

**Vite standalone:** `npm create vite@latest` → select `svelte`. Generates HTML/JS/CSS in `dist`. Need to add [routing library](/packages#routing).

**Other bundlers:** [Plugins available](/packages#bundler-plugins), but Vite recommended.

## Editor tooling

- [VS Code extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)
- [Other editors](https://sveltesociety.dev/collection/editor-support-c85c080efc292a34)
- CLI check: `npx sv check`

## Help

- [Discord](/chat)
- [Stack Overflow](https://stackoverflow.com/questions/tagged/svelte)

## docs/svelte/01-introduction/03-svelte-files.md

# .svelte files

Components are written in `.svelte` files. All three sections are optional.

```svelte
/// file: MyComponent.svelte
<script module>
	// module-level logic (rarely used)
</script>

<script>
	// instance-level logic
</script>

<!-- markup -->

<style>
	/* styles */
</style>
```

## `<script>`

Runs when component instance is created. Top-level variables can be referenced in markup. Use runes for props and reactivity.

## `<script module>`

Runs once when module first evaluates (not per instance). Variables declared here accessible in component, but not vice versa.

```svelte
<script module>
	let total = 0;
</script>

<script>
	total += 1;
	console.log(`instantiated ${total} times`);
</script>
```

Can `export` bindings (becomes module exports). Cannot `export default` (component is default export).

> **Note:** Svelte 4 used `<script context="module">`

## `<style>`

CSS scoped to component only.

```svelte
<style>
	p {
		/* only affects <p> in this component */
		color: burlywood;
	}
</style>
```

## docs/svelte/01-introduction/04-svelte-js-files.md

# .svelte.js and .svelte.ts files

`.svelte.js` and `.svelte.ts` files behave like regular `.js`/`.ts` modules but support runes.

**Use cases:**
- Reusable reactive logic
- Sharing reactive state across app

**Gotcha:** Cannot export reassigned state (see `$state` docs)

## docs/svelte/02-runes/01-what-are-runes.md

# Runes

Runes are compiler keywords with `$` prefix that control Svelte behavior in `.svelte` and `.svelte.js`/`.svelte.ts` files.

```js
let message = $state('hello');
```

**Key characteristics:**
- No import needed (globals)
- Not values (can't assign to variables or pass as arguments)
- Position-specific like JS keywords
- Svelte 5+ only

## docs/svelte/02-runes/02-$state.md

# $state

Creates reactive state that updates the UI when changed.

```svelte
<script>
	let count = $state(0);
</script>

<button onclick={() => count++}>
	clicks: {count}
</button>
```

`count` is just a number, update it like any variable.

## Deep state

Arrays and plain objects become deeply reactive proxies. Updates trigger granular UI changes.

```js
let todos = $state([
	{
		done: false,
		text: 'add more todos'
	}
]);

// triggers updates for this specific property
todos[0].done = !todos[0].done;

// new objects are also proxified
todos.push({
	done: false,
	text: 'eat lunch'
});
```

**Gotcha:** Destructuring breaks reactivity (evaluated at destructure time):

```js
let { done, text } = todos[0];
// this will NOT affect the value of `done`
todos[0].done = !todos[0].done;
```

## Classes

Use `$state` in class fields or as first assignment in constructor:

```js
class Todo {
	done = $state(false);

	constructor(text) {
		this.text = $state(text);
	}

	reset() {
		this.text = '';
		this.done = false;
	}
}
```

**Gotcha:** `this` binding in methods. Use inline function or arrow function:

```svelte
<!-- Won't work - wrong `this` -->
<button onclick={todo.reset}>reset</button>

<!-- Works -->
<button onclick={() => todo.reset()}>reset</button>
```

Or use arrow function in class:

```js
class Todo {
	done = $state(false);

	constructor(text) {
		this.text = $state(text);
	}

	reset = () => {
		this.text = '';
		this.done = false;
	}
}
```

## Built-in classes

Import reactive `Set`, `Map`, `Date`, `URL` from `svelte/reactivity`.

## `$state.raw`

Non-deep reactive state. Cannot mutate, only reassign.

```js
let person = $state.raw({
	name: 'Heraclitus',
	age: 49
});

// no effect
person.age += 1;

// works - reassignment
person = {
	name: 'Heraclitus',
	age: 50
};
```

Better performance for large arrays/objects you won't mutate. Can contain reactive state.

## `$state.snapshot`

Takes static snapshot of reactive proxy:

```svelte
<script>
	let counter = $state({ count: 0 });

	function onclick() {
		// Logs `{ count: ... }` not `Proxy { ... }`
		console.log($state.snapshot(counter));
	}
</script>
```

Useful for external libraries expecting plain objects (e.g., `structuredClone`).

## `$state.eager`

Updates UI immediately instead of waiting for `await` synchronization:

```svelte
<nav>
	<a href="/" aria-current={$state.eager(pathname) === '/' ? 'page' : null}>home</a>
	<a href="/about" aria-current={$state.eager(pathname) === '/about' ? 'page' : null}>about</a>
</nav>
```

Use sparingly, only for user feedback during actions.

## Passing state into functions

JavaScript is pass-by-value. To pass current values, use functions:

```js
function add(getA, getB) {
	return() => getA() + getB();
}

let a = 1;
let b = 2;
let total = add(() => a, () => b);
console.log(total()); // 3

a = 3;
b = 4;
console.log(total()); // 7
```

Or use getters:

```js
function add(input) {
	return {
		get value() {
			return input.a + input.b;
		}
	};
}

let input = $state({ a: 1, b: 2 });
let total = add(input);
console.log(total.value); // 3

input.a = 3;
input.b = 4;
console.log(total.value); // 7
```

## Passing state across modules

Can't directly export reassignable state from `.svelte.js`/`.svelte.ts`:

```js
// ❌ Won't work
export let count = $state(0);
```

**Options:**

1. Export object, update properties:

```js
// ✅ Works
export const counter = $state({
	count: 0
});

export function increment() {
	counter.count += 1;
}
```

2. Don't directly export:

```js
// ✅ Works
let count = $state(0);

export function getCount() {
	return count;
}

export function increment() {
	count += 1;
}
```

## docs/svelte/02-runes/03-$derived.md

# $derived

Derived state recomputes when dependencies change:

```svelte
<script>
	let count = $state(0);
	let doubled = $derived(count * 2);
</script>

<button onclick={() => count++}>
	{doubled}
</button>

<p>{count} doubled is {doubled}</p>
```

**Key rules:**
- Expression must be side-effect free (no `count++`)
- Can mark class fields as `$derived`
- Without `$derived`, values don't update when dependencies change

## `$derived.by`

For complex derivations, use `$derived.by` with a function:

```svelte
<script>
	let numbers = $state([1, 2, 3]);
	let total = $derived.by(() => {
		let total = 0;
		for (const n of numbers) {
			total += n;
		}
		return total;
	});
</script>

<button onclick={() => numbers.push(numbers.length + 1)}>
	{numbers.join(' + ')} = {total}
</button>
```

`$derived(expression)` = `$derived.by(() => expression)`

## Dependencies

Anything read synchronously inside `$derived` is a dependency. Use [`untrack`](svelte#untrack) to exempt state from being a dependency.

## Overriding Values

Can temporarily reassign derived values (unless `const`). Useful for optimistic UI:

```svelte
<script>
	let { post, like } = $props();

	let likes = $derived(post.likes);

	async function onclick() {
		// increment the `likes` count immediately...
		likes += 1;

		// and tell the server, which will eventually update `post`
		try {
			await like();
		} catch {
			// failed! roll back the change
			likes -= 1;
		}
	}
</script>

<button {onclick}>🧡 {likes}</button>
```

## Reactivity

`$derived` values are NOT deeply reactive (unlike `$state`):

```js
// @errors: 7005
let items = $state([ /*...*/ ]);

let index = $state(0);
let selected = $derived(items[index]);
```

Mutating `selected` affects the underlying `items` array.

## Destructuring

Destructured variables are all reactive:

```js
function stuff() { return { a: 1, b: 2, c: 3 } }
//cut
let { a, b, c } = $derived(stuff());
```

Equivalent to:

```js
function stuff() { return { a: 1, b: 2, c: 3 } }
//cut
let _stuff = $derived(stuff());
let a = $derived(_stuff.a);
let b = $derived(_stuff.b);
let c = $derived(_stuff.c);
```

## Update Propagation

**Push-pull reactivity:** Dependencies notified immediately (push), but derived values only re-evaluated when read (pull).

If new value is referentially identical to previous, downstream updates skip:

```svelte
<script>
	let count = $state(0);
	let large = $derived(count > 10);
</script>

<button onclick={() => count++}>
	{large}
</button>
```

Button only updates when `large` changes, not `count`.

## docs/svelte/02-runes/04-$effect.md

# $effect

Effects run when state updates. Run in browser only, not during SSR.

**Don't update state inside effects** - leads to complexity and infinite loops. See alternatives below.

## Basic Usage

```svelte
<script>
	let size = $state(50);
	let color = $state('#ff3e00');

	let canvas;

	$effect(() => {
		const context = canvas.getContext('2d');
		context.clearRect(0, 0, canvas.width, canvas.height);

		// re-runs whenever `color` or `size` change
		context.fillStyle = color;
		context.fillRect(0, 0, size, size);
	});
</script>

<canvas bind:this={canvas} width="100" height="100"></canvas>
```

Tracks accessed state/derived and re-runs when they change.

## Lifecycle

- Runs after component mounts
- Re-runs in microtask after state changes (batched)
- Can be used anywhere while parent effect is running

### Teardown Functions

```svelte
<script>
	let count = $state(0);
	let milliseconds = $state(1000);

	$effect(() => {
		const interval = setInterval(() => {
			count += 1;
		}, milliseconds);

		return () => {
			// runs before re-run and on destroy
			clearInterval(interval);
		};
	});
</script>

<h1>{count}</h1>

<button onclick={() => (milliseconds *= 2)}>slower</button>
<button onclick={() => (milliseconds /= 2)}>faster</button>
```

## Dependencies

Auto-tracks **synchronously** read reactive values. Async reads (after `await`, inside `setTimeout`) not tracked:

```ts
$effect(() => {
	const context = canvas.getContext('2d');
	context.clearRect(0, 0, canvas.width, canvas.height);

	// re-runs when `color` changes
	context.fillStyle = color;

	setTimeout(() => {
		// does NOT track `size`
		context.fillRect(0, 0, size, size);
	}, 0);
});
```

### Object vs Property Tracking

```svelte
<script>
	let state = $state({ value: 0 });
	let derived = $derived({ value: state.value * 2 });

	// runs once - `state` object never reassigned
	$effect(() => {
		state;
	});

	// runs when `state.value` changes
	$effect(() => {
		state.value;
	});

	// runs when `state.value` changes - `derived` is new object each time
	$effect(() => {
		derived;
	});
</script>

<button onclick={() => (state.value += 1)}>
	{state.value}
</button>

<p>{state.value} doubled is {derived.value}</p>
```

### Conditional Dependencies

Effect only depends on values read in last run:

```ts
import confetti from 'canvas-confetti';

let condition = $state(true);
let color = $state('#ff3e00');

$effect(() => {
	if (condition) {
		confetti({ colors: [color] }); // tracks `condition` and `color`
	} else {
		confetti(); // only tracks `condition`
	}
});
```

## `$effect.pre`

Runs **before** DOM updates:

```svelte
<script>
	import { tick } from 'svelte';

	let div = $state();
	let messages = $state([]);

	$effect.pre(() => {
		if (!div) return;

		messages.length; // track array length

		// autoscroll when new messages added
		if (div.offsetHeight + div.scrollTop > div.scrollHeight - 20) {
			tick().then(() => {
				div.scrollTo(0, div.scrollHeight);
			});
		}
	});
</script>

<div bind:this={div}>
	{#each messages as message}
		<p>{message}</p>
	{/each}
</div>
```

## `$effect.tracking`

Returns `true` if code runs inside tracking context (effect or template):

```svelte
<script>
	console.log('in component setup:', $effect.tracking()); // false

	$effect(() => {
		console.log('in effect:', $effect.tracking()); // true
	});
</script>

<p>in template: {$effect.tracking()}</p>
```

## `$effect.pending`

Returns count of pending promises in current boundary (excludes child boundaries):

```svelte
<button onclick={() => a++}>a++</button>
<button onclick={() => b++}>b++</button>

<p>{a} + {b} = {await add(a, b)}</p>

{#if $effect.pending()}
	<p>pending promises: {$effect.pending()}</p>
{/if}
```

## `$effect.root`

Creates non-tracked scope with manual cleanup. Can create effects outside component init:

```js
const destroy = $effect.root(() => {
	$effect(() => {
		// setup
	});

	return () => {
		// cleanup
	};
});

// later...
destroy();
```

## When NOT to Use

### ❌ Don't synchronize state

```svelte
<script>
	let count = $state(0);
	let doubled = $state();

	// don't do this!
	$effect(() => {
		doubled = count * 2;
	});
</script>
```

### ✅ Use $derived instead

```svelte
<script>
	let count = $state(0);
	let doubled = $derived(count * 2);
</script>
```

### ❌ Don't link values with effects

```svelte
<script>
	const total = 100;
	let spent = $state(0);
	let left = $state(total);

	$effect(() => {
		left = total - spent;
	});

	$effect(() => {
		spent = total - left;
	});
</script>

<label>
	<input type="range" bind:value={spent} max={total} />
	{spent}/{total} spent
</label>

<label>
	<input type="range" bind:value={left} max={total} />
	{left}/{total} left
</label>
```

### ✅ Use callbacks or function bindings

```svelte
<script>
	const total = 100;
	let spent = $state(0);
	let left = $derived(total - spent);

	function updateLeft(left) {
		spent = total - left;
	}
</script>

<label>
	<input type="range" bind:value={spent} max={total} />
	{spent}/{total} spent
</label>

<label>
	<input type="range" bind:value={() => left, updateLeft} max={total} />
	{left}/{total} left
</label>
```

**Note:** If you must update `$state` in effect and hit infinite loop, use `untrack()`.

## docs/svelte/02-runes/05-$props.md

# $props

Pass props to components like attributes:

```svelte
<!file: App.svelte>
<script>
	import MyComponent from './MyComponent.svelte';
</script>

<MyComponent adjective="cool" />
```

Receive with `$props()` rune (destructuring is common):

```svelte
<!file: MyComponent.svelte>
<script>
	let { adjective } = $props();
</script>

<p>this component is {adjective}</p>
```

## Fallback values

Use destructuring defaults for undefined props:

```js
let { adjective = 'happy' } = $props();
```

> **Note:** Fallback values are NOT reactive proxies

## Renaming props

For invalid identifiers or keywords:

```js
let { super: trouper = 'lights are gonna find me' } = $props();
```

## Rest props

```js
let { a, b, c, ...others } = $props();
```

## Updating props

Props update when parent changes. Child can temporarily **reassign** (not mutate):

```svelte
<!file: App.svelte>
<script>
	import Child from './Child.svelte';

	let count = $state(0);
</script>

<button onclick={() => (count += 1)}>
	clicks (parent): {count}
</button>

<Child {count} />
```

```svelte
<!file: Child.svelte>
<script>
	let { count } = $props();
</script>

<button onclick={() => (count += 1)}>
	clicks (child): {count}
</button>
```

### Don't mutate props

- Regular object mutation: no effect
- Reactive proxy mutation: works but triggers `ownership_invalid_mutation` warning
- Fallback value mutation: no effect

**Solution:** Use callback props or `$bindable` for shared state.

## Type safety

TypeScript:
```svelte
<script lang="ts">
	let { adjective }: { adjective: string } = $props();
</script>
```

JSDoc:
```svelte
<script>
	/** @type {{ adjective: string }} */
	let { adjective } = $props();
</script>
```

With interface:
```svelte
<script lang="ts">
	interface Props {
		adjective: string;
	}

	let { adjective }: Props = $props();
</script>
```

> **Note:** Use `Snippet` interface from `'svelte'` for snippet props. Native DOM element interfaces in `svelte/elements`.

## `$props.id()`

Generates unique ID per component instance (consistent during SSR hydration):

```svelte
<script>
	const uid = $props.id();
</script>

<form>
	<label for="{uid}-firstname">First Name: </label>
	<input id="{uid}-firstname" type="text" />

	<label for="{uid}-lastname">Last Name: </label>
	<input id="{uid}-lastname" type="text" />
</form>
```

## docs/svelte/02-runes/06-$bindable.md

# $bindable

Props normally flow parent → child. `$bindable` allows two-way binding (child ↔ parent).

**Use sparingly** — overuse makes data flow unpredictable.

## Basic Usage

Child component marks prop as bindable:

```svelte
/// file: FancyInput.svelte
<script>
	let { value = $bindable(), ...props } = $props();
</script>

<input bind:value={value} {...props} />

<style>
	input {
		font-family: 'Comic Sans MS';
		color: deeppink;
	}
</style>
```

Parent uses `bind:` directive:

```svelte
/// file: App.svelte
<script>
	import FancyInput from './FancyInput.svelte';

	let message = $state('hello');
</script>

<FancyInput bind:value={message} />
<p>{message}</p>
```

## Fallback Value

Parent can pass normal prop without `bind:`. Provide fallback for when no prop passed:

```js
/// file: FancyInput.svelte
let { value = $bindable('fallback'), ...props } = $props();
```

## Key Points

- Enables state proxy mutation in child
- Mutating normal props triggers warning
- Parent not required to use `bind:`

## docs/svelte/02-runes/07-$inspect.md

# $inspect

> **Note:** Dev-only. Noop in production.

Roughly equivalent to `console.log`, but re-runs when arguments change. Tracks reactive state deeply.

```svelte
<script>
	let count = $state(0);
	let message = $state('hello');

	$inspect(count, message); // logs when count or message change
</script>

<button onclick={() => count++}>Increment</button>
<input bind:value={message} />
```

Prints stack trace on updates (except in playground).

## $inspect(...).with

Custom callback instead of `console.log`. First arg is `"init"` or `"update"`, rest are inspected values.

```svelte
<script>
	let count = $state(0);

	$inspect(count).with((type, count) => {
		if (type === 'update') {
			debugger; // or console.trace, etc
		}
	});
</script>

<button onclick={() => count++}>Increment</button>
```

## $inspect.trace(...)

Added in 5.14. Traces function re-runs in effects/derived. Logs which reactive state caused re-run.

```svelte
<script>
	import { doSomeWork } from './elsewhere';

	$effect(() => {
		// Must be first statement in function body
		$inspect.trace();
		doSomeWork();
	});
</script>
```

Takes optional label as first argument.

## docs/svelte/02-runes/08-$host.md

# $host

Provides access to the host element when compiling a component as a custom element.

## Usage

```svelte
/// file: Stepper.svelte
<svelte:options customElement="my-stepper" />

<script>
	function dispatch(type) {
		$host().dispatchEvent(new CustomEvent(type));
	}
</script>

<button onclick={() => dispatch('decrement')}>decrement</button>
<button onclick={() => dispatch('increment')}>increment</button>
```

```svelte
/// file: App.svelte
<script>
	import './Stepper.svelte';

	let count = $state(0);
</script>

<my-stepper
	ondecrement={() => count -= 1}
	onincrement={() => count += 1}
></my-stepper>

<p>count: {count}</p>
```

**Key use case:** Dispatching custom events from custom elements.

## docs/svelte/03-template-syntax/01-basic-markup.md

# Basic markup

## Tags

Lowercase = HTML element. Capitalized/dot notation = component.

```svelte
<script>
	import Widget from './Widget.svelte';
</script>

<div>
	<Widget />
</div>
```

## Element attributes

Attributes work like HTML. Values can contain or be JavaScript expressions.

```svelte
<input type=checkbox />
<a href="page/{p}">page {p}</a>
<button disabled={!clickable}>...</button>
```

**Boolean attributes**: included if truthy, excluded if falsy.
**Other attributes**: included unless nullish (`null`/`undefined`).

```svelte
<input required={false} placeholder="This input field is not required" />
<div title={null}>This div has no title attribute</div>
```

**Shorthand**: `{name}` when name and value match.

```svelte
<button {disabled}>...</button>
```

## Component props

Same rules as attributes. Use shorthand `{name}` when applicable.

```svelte
<Widget foo={bar} answer={42} text="hello" />
```

## Spread attributes

Multiple spreads allowed. Order matters for precedence.

```svelte
<Widget a="b" {...things} c="d" />
```

## Events

Use `on` prefix (e.g., `onclick`). Case sensitive.

```svelte
<button onclick={() => console.log('clicked')}>click me</button>
```

- Shorthand/spread work: `<button {onclick}>` or `<button {...events}>`
- Fire after bindings (e.g., `oninput` after `bind:value`)
- `ontouchstart`/`ontouchmove` are passive for performance

### Event delegation

Svelte delegates certain events to app root for performance. 

**Gotchas**:
- Manual dispatch needs `{ bubbles: true }`
- Avoid `stopPropagation` with `addEventListener` directly
- Use `on` from `svelte/events` instead of `addEventListener`

**Delegated events**: `beforeinput`, `click`, `change`, `dblclick`, `contextmenu`, `focusin`, `focusout`, `input`, `keydown`, `keyup`, `mousedown`, `mousemove`, `mouseout`, `mouseover`, `mouseup`, `pointerdown`, `pointermove`, `pointerout`, `pointerover`, `pointerup`, `touchend`, `touchmove`, `touchstart`

## Text expressions

Use `{expression}`. `null`/`undefined` omitted, others coerced to strings.

```svelte
<h1>Hello {name}!</h1>
<p>{a} + {b} = {a + b}.</p>

<div>{(/^[A-Za-z ]+$/).test(value) ? x : y}</div>
```

**Render HTML** (escaped by default):

```svelte
{@html potentiallyUnsafeHtmlString}
```

> **Warning**: Escape strings to prevent XSS attacks.

## Comments

HTML comments work. `svelte-ignore` disables warnings for next markup block.

```svelte

<input bind:value={name} autofocus />
```

`@component` JSDoc shows on hover:

````svelte

<script>
	let { name } = $props();
</script>

<main>
	<h1>
		Hello, {name}
	</h1>
</main>
````

## docs/svelte/03-template-syntax/02-if.md

# {#if ...}

Conditionally render content.

## Syntax

```svelte
{#if expression}...{/if}
{#if expression}...{:else if expression}...{/if}
{#if expression}...{:else}...{/if}
```

## Examples

```svelte
{#if answer === 42}
	<p>what was the question?</p>
{/if}
```

```svelte
{#if porridge.temperature > 100}
	<p>too hot!</p>
{:else if 80 > porridge.temperature}
	<p>too cold!</p>
{:else}
	<p>just right!</p>
{/if}
```

**Note:** Blocks can wrap elements or text within elements.

## docs/svelte/03-template-syntax/03-each.md

# {#each ...}

Iterate over arrays, array-likes (with `length`), or iterables (`Map`, `Set`). Internally converted via `Array.from`. `null`/`undefined` treated as empty arrays.

## Basic syntax

```svelte
{#each items as item}
	<li>{item.name} x {item.qty}</li>
{/each}
```

## With index

```svelte
{#each items as item, i}
	<li>{i + 1}: {item.name} x {item.qty}</li>
{/each}
```

## Keyed each blocks

Use `(key)` to intelligently update lists (insert/move/delete) instead of updating in place. Keys should be strings/numbers.

```svelte
{#each items as item (item.id)}
	<li>{item.name} x {item.qty}</li>
{/each}

{#each items as item, i (item.id)}
	<li>{i + 1}: {item.name} x {item.qty}</li>
{/each}
```

## Destructuring

```svelte
{#each items as { id, name, qty }, i (id)}
	<li>{i + 1}: {name} x {qty}</li>
{/each}

{#each objects as { id, ...rest }}
	<li><span>{id}</span><MyComponent {...rest} /></li>
{/each}

{#each items as [id, ...rest]}
	<li><span>{id}</span><MyComponent values={rest} /></li>
{/each}
```

## Without item (render n times)

```svelte
<div class="chess-board">
	{#each { length: 8 }, rank}
		{#each { length: 8 }, file}
			<div class:black={(rank + file) % 2 === 1}></div>
		{/each}
	{/each}
</div>
```

## Else blocks

Renders when list is empty.

```svelte
{#each todos as todo}
	<p>{todo.text}</p>
{:else}
	<p>No tasks today!</p>
{/each}
```

## docs/svelte/03-template-syntax/04-key.md

# {#key ...}

```svelte
{#key expression}...{/key}
```

Destroys and recreates contents when expression changes.

**Reinstantiate components:**
```svelte
{#key value}
	<Component />
{/key}
```

**Replay transitions on value change:**
```svelte
{#key value}
	<div transition:fade>{value}</div>
{/key}
```

## docs/svelte/03-template-syntax/05-await.md

# {#await ...}

Branches on Promise states: pending, fulfilled, rejected.

## Syntax

```svelte
<!copy: false>
{#await expression}...{:then name}...{:catch name}...{/await}
{#await expression}...{:then name}...{/await}
{#await expression then name}...{/await}
{#await expression catch name}...{/await}
```

## Examples

**Full syntax:**
```svelte
{#await promise}
	<p>waiting for the promise to resolve...</p>
{:then value}
	<p>The value is {value}</p>
{:catch error}
	<p>Something went wrong: {error.message}</p>
{/await}
```

**Omit catch:**
```svelte
{#await promise}
	<p>waiting for the promise to resolve...</p>
{:then value}
	<p>The value is {value}</p>
{/await}
```

**Omit pending:**
```svelte
{#await promise then value}
	<p>The value is {value}</p>
{/await}
```

**Only error state:**
```svelte
{#await promise catch error}
	<p>The error is {error}</p>
{/await}
```

## Gotchas

- SSR only renders pending branch
- Non-Promise expressions only render `:then` branch (including SSR)

## Pattern: Lazy component loading

```svelte
{#await import('./Component.svelte') then { default: Component }}
	<Component />
{/await}
```

## docs/svelte/03-template-syntax/06-snippet.md

# {#snippet ...}

## Syntax

```svelte
{#snippet name()}...{/snippet}
{#snippet name(param1, param2, paramN)}...{/snippet}
```

Snippets create reusable markup chunks. Use with `{@render}` tags.

## Basic Example

```svelte
{#snippet figure(image)}
	<figure>
		<img src={image.src} alt={image.caption} width={image.width} height={image.height} />
		<figcaption>{image.caption}</figcaption>
	</figure>
{/snippet}

{#each images as image}
	{#if image.href}
		<a href={image.href}>
			{@render figure(image)}
		</a>
	{:else}
		{@render figure(image)}
	{/if}
{/each}
```

## Parameters

- Arbitrary number of parameters with default values
- Destructuring supported
- No rest parameters

## Scope

Snippets reference values from outer scope:

```svelte
<script>
	let { message = `it's great to see you!` } = $props();
</script>

{#snippet hello(name)}
	<p>hello {name}! {message}!</p>
{/snippet}

{@render hello('alice')}
{@render hello('bob')}
```

Snippets can reference themselves and each other:

```svelte
{#snippet blastoff()}
	<span>🚀</span>
{/snippet}

{#snippet countdown(n)}
	{#if n > 0}
		<span>{n}...</span>
		{@render countdown(n - 1)}
	{:else}
		{@render blastoff()}
	{/if}
{/snippet}

{@render countdown(10)}
```

## Passing to Components

### Explicit props

```svelte
<script>
	import Table from './Table.svelte';

	const fruits = [
		{ name: 'apples', qty: 5, price: 2 },
		{ name: 'bananas', qty: 10, price: 1 },
		{ name: 'cherries', qty: 20, price: 0.5 }
	];
</script>

{#snippet header()}
	<th>fruit</th>
	<th>qty</th>
	<th>price</th>
	<th>total</th>
{/snippet}

{#snippet row(d)}
	<td>{d.name}</td>
	<td>{d.qty}</td>
	<td>{d.price}</td>
	<td>{d.qty * d.price}</td>
{/snippet}

<Table data={fruits} {header} {row} />
```

### Implicit props

Snippets declared inside component tags become props automatically:

```svelte
<Table data={fruits}>
	{#snippet header()}
		<th>fruit</th>
		<th>qty</th>
		<th>price</th>
		<th>total</th>
	{/snippet}

	{#snippet row(d)}
		<td>{d.name}</td>
		<td>{d.qty}</td>
		<td>{d.price}</td>
		<td>{d.qty * d.price}</td>
	{/snippet}
</Table>
```

### Implicit `children` snippet

Content inside component tags (not snippet declarations) becomes `children` snippet:

```svelte
<!file: App.svelte>
<Button>click me</Button>
```

```svelte
<!file: Button.svelte>
<script>
	let { children } = $props();
</script>

<button>{@render children()}</button>
```

**Gotcha:** Cannot have a prop named `children` if component has content inside tags.

## Optional Snippets

Optional chaining:

```svelte
<script>
    let { children } = $props();
</script>

{@render children?.()}
```

With fallback:

```svelte
<script>
    let { children } = $props();
</script>

{#if children}
    {@render children()}
{:else}
    fallback content
{/if}
```

## TypeScript

```svelte
<script lang="ts">
	import type { Snippet } from 'svelte';

	interface Props {
		data: any[];
		children: Snippet;
		row: Snippet<[any]>;
	}

	let { data, children, row }: Props = $props();
</script>
```

With generics:

```svelte
<script lang="ts" generics="T">
	import type { Snippet } from 'svelte';

	let {
		data,
		children,
		row
	}: {
		data: T[];
		children: Snippet;
		row: Snippet<[T]>;
	} = $props();
</script>
```

**Note:** `Snippet` type argument is a tuple for multiple parameters.

## Exporting Snippets

Top-level snippets can be exported from `<script module>` if they don't reference non-module `<script>` declarations:

```svelte
<script module>
	export { add };
</script>

{#snippet add(a, b)}
	{a} + {b} = {a + b}
{/snippet}
```

**Requires:** Svelte 5.5.0+

## Programmatic Snippets

Use [`createRawSnippet`](svelte#createRawSnippet) API for advanced use cases.

## Migration

Snippets replace Svelte 4 slots (now deprecated).

## docs/svelte/03-template-syntax/07-@render.md

# {@render ...}

Renders a [snippet](snippet).

```svelte
{#snippet sum(a, b)}
	<p>{a} + {b} = {a + b}</p>
{/snippet}

{@render sum(1, 2)}
{@render sum(3, 4)}
{@render sum(5, 6)}
```

Expression can be any JavaScript:

```svelte
{@render (cool ? coolSnippet : lameSnippet)()}
```

## Optional snippets

Use optional chaining for potentially undefined snippets (e.g., props):

```svelte
{@render children?.()}
```

Or `{#if}` with fallback:

```svelte
{#if children}
	{@render children()}
{:else}
	<p>fallback content</p>
{/if}
```

## docs/svelte/03-template-syntax/08-@html.md

# {@html ...}

Injects raw HTML into component:

```svelte
<article>
	{@html content}
</article>
```

**Warning:** Escape strings or use trusted values only to prevent XSS attacks. Never render unsanitized content.

## Limitations

- Expression must be valid standalone HTML (can't split tags)
- Won't compile Svelte code

## Styling

`{@html}` content is invisible to scoped styles. Use `:global` modifier:

```svelte
<article>
	{@html content}
</article>

<style>
	article :global {
		a { color: hotpink }
		img { width: 100% }
	}
</style>
```

## docs/svelte/03-template-syntax/09-@attach.md

# {@attach ...}

Attachments are functions that run in an effect when an element mounts or when state updates. Can return cleanup function.

```svelte
<script>
	/** @type {import('svelte/attachments').Attachment} */
	function myAttachment(element) {
		console.log(element.nodeName); // 'DIV'

		return () => {
			console.log('cleaning up');
		};
	}
</script>

<div {@attach myAttachment}>...</div>
```

## Attachment factories

Functions can return attachments. Re-runs when state changes:

```svelte
<script>
	import tippy from 'tippy.js';

	let content = $state('Hello!');

	/**
	 * @param {string} content
	 * @returns {import('svelte/attachments').Attachment}
	 */
	function tooltip(content) {
		return (element) => {
			const tooltip = tippy(element, { content });
			return tooltip.destroy;
		};
	}
</script>

<input bind:value={content} />

<button {@attach tooltip(content)}>
	Hover me
</button>
```

## Inline attachments

```svelte
<canvas
	width={32}
	height={32}
	{@attach (canvas) => {
		const context = canvas.getContext('2d');

		$effect(() => {
			context.fillStyle = color;
			context.fillRect(0, 0, canvas.width, canvas.height);
		});
	}}
></canvas>
```

## Conditional attachments

Falsy values = no attachment:

```svelte
<div {@attach enabled && myAttachment}>...</div>
```

## Passing to components

`{@attach ...}` on components creates a Symbol prop. Spread props to pass attachments to elements:

```svelte
<!file: Button.svelte>
<script>
	/** @type {import('svelte/elements').HTMLButtonAttributes} */
	let { children, ...props } = $props();
</script>

<button {...props}>
	{@render children?.()}
</button>
```

```svelte
<!file: App.svelte>
<script>
	import tippy from 'tippy.js';
	import Button from './Button.svelte';

	let content = $state('Hello!');

	/**
	 * @param {string} content
	 * @returns {import('svelte/attachments').Attachment}
	 */
	function tooltip(content) {
		return (element) => {
			const tooltip = tippy(element, { content });
			return tooltip.destroy;
		};
	}
</script>

<input bind:value={content} />

<Button {@attach tooltip(content)}>
	Hover me
</Button>
```

## Controlling re-runs

Attachments are fully reactive: `{@attach foo(bar)}` re-runs on changes to `foo`, `bar`, or any state read inside.

To prevent expensive re-runs, pass data in a function and read in child effect:

```js
// @errors: 7006 2304 2552
function foo(getBar) {
	return (node) => {
		veryExpensiveSetupWork(node);

		$effect(() => {
			update(node, getBar());
		});
	}
}
```

## Utilities

- [`createAttachmentKey`](svelte-attachments#createAttachmentKey) - add attachments to objects for spreading
- [`fromAction`](svelte-attachments#fromAction) - convert actions to attachments

## docs/svelte/03-template-syntax/10-@const.md

# {@const ...}

Defines a local constant within blocks.

```svelte
{#each boxes as box}
	{@const area = box.width * box.height}
	{box.width} * {box.height} = {area}
{/each}
```

**Restriction:** Only allowed as immediate child of:
- `{#if ...}`, `{#each ...}`, `{#snippet ...}` blocks
- `<Component />`
- `<svelte:boundary>`

## docs/svelte/03-template-syntax/11-@debug.md

# {@debug ...}

Logs variable values when they change and pauses execution in devtools.

```svelte
<script>
	let user = {
		firstname: 'Ada',
		lastname: 'Lovelace'
	};
</script>

{@debug user}

<h1>Hello {user.firstname}!</h1>
```

## Usage

**Accepts:** Comma-separated variable names (not expressions)

```svelte
{@debug user}
{@debug user1, user2, user3}

<!-- ❌ Invalid -->
{@debug user.firstname}
{@debug myArray[0]}
{@debug !isReady}
{@debug typeof user === 'object'}
```

**No arguments:** Triggers on any state change

```svelte
{@debug}
```

## docs/svelte/03-template-syntax/12-bind.md

# bind:

Data flows down (parent → child). `bind:` flows data up (child → parent).

Syntax: `bind:property={expression}` or `bind:property` (shorthand when names match)

```svelte
<input bind:value={value} />
<input bind:value />
```

Svelte creates event listeners to update bound values. Most bindings are two-way; some are readonly.

## Function bindings

Use `bind:property={get, set}` for validation/transformation:

```svelte
<input bind:value={
	() => value,
	(v) => value = v.toLowerCase()}
/>
```

For readonly bindings, set `get` to `null`:

```svelte
<div
	bind:clientWidth={null, redraw}
	bind:clientHeight={null, redraw}
>...</div>
```

## `<input bind:value>`

Binds input's `value` property:

```svelte
<script>
	let message = $state('hello');
</script>

<input bind:value={message} />
<p>{message}</p>
```

Numeric inputs (`type="number"` or `type="range"`) coerce to number:

```svelte
<script>
	let a = $state(1);
	let b = $state(2);
</script>

<label>
	<input type="number" bind:value={a} min="0" max="10" />
	<input type="range" bind:value={a} min="0" max="10" />
</label>

<label>
	<input type="number" bind:value={b} min="0" max="10" />
	<input type="range" bind:value={b} min="0" max="10" />
</label>

<p>{a} + {b} = {a + b}</p>
```

Empty/invalid value is `undefined`.

Since 5.6.0: `defaultValue` reverts on form reset (unless binding is `null`/`undefined`):

```svelte
<script>
	let value = $state('');
</script>

<form>
	<input bind:value defaultValue="not the empty string">
	<input type="reset" value="Reset">
</form>
```

## `<input bind:checked>`

For checkboxes:

```svelte
<label>
	<input type="checkbox" bind:checked={accepted} />
	Accept terms and conditions
</label>
```

Since 5.6.0: `defaultChecked` reverts on form reset:

```svelte
<script>
	let checked = $state(true);
</script>

<form>
	<input type="checkbox" bind:checked defaultChecked={true}>
	<input type="reset" value="Reset">
</form>
```

> Use `bind:group` for radio inputs, not `bind:checked`.

## `<input bind:indeterminate>`

For checkbox indeterminate state:

```svelte
<script>
	let checked = $state(false);
	let indeterminate = $state(true);
</script>

<form>
	<input type="checkbox" bind:checked bind:indeterminate>

	{#if indeterminate}
		waiting...
	{:else if checked}
		checked
	{:else}
		unchecked
	{/if}
</form>
```

## `<input bind:group>`

For radio/checkbox groups:

```svelte
<!file: BurritoChooser.svelte>
<script>
	let tortilla = $state('Plain');

	/** @type {string[]} */
	let fillings = $state([]);
</script>


<label><input type="radio" bind:group={tortilla} value="Plain" /> Plain</label>
<label><input type="radio" bind:group={tortilla} value="Whole wheat" /> Whole wheat</label>
<label><input type="radio" bind:group={tortilla} value="Spinach" /> Spinach</label>


<label><input type="checkbox" bind:group={fillings} value="Rice" /> Rice</label>
<label><input type="checkbox" bind:group={fillings} value="Beans" /> Beans</label>
<label><input type="checkbox" bind:group={fillings} value="Cheese" /> Cheese</label>
<label><input type="checkbox" bind:group={fillings} value="Guac (extra)" /> Guac (extra)</label>
```

> Only works if inputs are in same component.

## `<input bind:files>`

For `type="file"`:

```svelte
<script>
	let files = $state();

	function clear() {
		files = new DataTransfer().files; // null or undefined does not work
	}
</script>

<label for="avatar">Upload a picture:</label>
<input accept="image/png, image/jpeg" bind:files id="avatar" name="avatar" type="file" />
<button onclick={clear}>clear</button>
```

Must use `FileList` object. Create via `DataTransfer` to modify programmatically.

> Leave uninitialized for SSR compatibility.

## `<select bind:value>`

Binds to selected `<option>` value (any type, not just strings):

```svelte
<select bind:value={selected}>
	<option value={a}>a</option>
	<option value={b}>b</option>
	<option value={c}>c</option>
</select>
```

`<select multiple>` binds to array:

```svelte
<select multiple bind:value={fillings}>
	<option value="Rice">Rice</option>
	<option value="Beans">Beans</option>
	<option value="Cheese">Cheese</option>
	<option value="Guac (extra)">Guac (extra)</option>
</select>
```

Omit `value` if it matches text:

```svelte
<select multiple bind:value={fillings}>
	<option>Rice</option>
	<option>Beans</option>
	<option>Cheese</option>
	<option>Guac (extra)</option>
</select>
```

Use `selected` attribute for default/reset value:

```svelte
<select bind:value={selected}>
	<option value={a}>a</option>
	<option value={b} selected>b</option>
	<option value={c}>c</option>
</select>
```

## `<audio>`

**Two-way bindings:**
- `currentTime`, `playbackRate`, `paused`, `volume`, `muted`

**Readonly bindings:**
- `duration`, `buffered`, `seekable`, `seeking`, `ended`, `readyState`, `played`

```svelte
<audio src={clip} bind:duration bind:currentTime bind:paused></audio>
```

## `<video>`

Same as `<audio>` plus readonly `videoWidth` and `videoHeight`.

## `<img>`

Readonly: `naturalWidth`, `naturalHeight`

## `<details bind:open>`

```svelte
<details bind:open={isOpen}>
	<summary>How do you comfort a JavaScript bug?</summary>
	<p>You console it.</p>
</details>
```

## Contenteditable bindings

For `contenteditable` elements: `innerHTML`, `innerText`, `textContent`

```svelte
<div contenteditable="true" bind:innerHTML={html}></div>
```

## Dimensions

Readonly bindings (via `ResizeObserver`):
- `clientWidth`, `clientHeight`, `offsetWidth`, `offsetHeight`
- `contentRect`, `contentBoxSize`, `borderBoxSize`, `devicePixelContentBoxSize`

```svelte
<div bind:offsetWidth={width} bind:offsetHeight={height}>
	<Chart {width} {height} />
</div>
```

> `display: inline` elements (except intrinsic dimensions like `<img>`) need `display: inline-block` or similar. CSS transforms don't trigger `ResizeObserver`.

## bind:this

Get DOM node reference (available after mount):

```svelte
<script>
	/** @type {HTMLCanvasElement} */
	let canvas;

	$effect(() => {
		const ctx = canvas.getContext('2d');
		drawStuff(ctx);
	});
</script>

<canvas bind:this={canvas}></canvas>
```

Works with components:

```svelte
<!file: App.svelte>
<ShoppingCart bind:this={cart} />

<button onclick={() => cart.empty()}> Empty shopping cart </button>
```

```svelte
<!file: ShoppingCart.svelte>
<script>
	// All instance exports are available on the instance object
	export function empty() {
		// ...
	}
</script>
```

> With function bindings, getter is required for proper cleanup.

## bind:_property_ for components

Bind to component props:

```svelte
<Keypad bind:value={pin} />
```

Mark props as bindable with `$bindable()`:

```svelte
<script>
	let { readonlyProperty, bindableProperty = $bindable() } = $props();
</script>
```

Bindable means _can_ use `bind:`, not _must_.

Fallback values:

```svelte
<script>
	let { bindableProperty = $bindable('fallback value') } = $props();
</script>
```

Fallback only applies when not bound. When bound with fallback, parent must provide non-`undefined` value or runtime error occurs.

## docs/svelte/03-template-syntax/13-use.md

# use: (Actions)

> [!NOTE]
> Svelte 5.29+: Consider using [attachments](@attach) instead - more flexible and composable.

Actions are functions called when an element mounts. Use `use:` directive with `$effect` for cleanup:

```svelte
<script>
	/** @type {import('svelte/action').Action} */
	function myaction(node) {
		// node mounted in DOM

		$effect(() => {
			// setup

			return () => {
				// teardown
			};
		});
	}
</script>

<div use:myaction>...</div>
```

## With Arguments

```svelte
<script>
	/** @type {import('svelte/action').Action} */
	function myaction(node, data) {
		// ...
	}
</script>

<div use:myaction={data}>...</div>
```

**Key:** Action called once on mount (not SSR). Does NOT re-run if argument changes.

## Typing

`Action<NodeType, Parameter, CustomEvents>`:

```svelte
<script>
	/**
	 * @type {import('svelte/action').Action<
	 * 	HTMLDivElement,
	 * 	undefined,
	 * 	{
	 * 		onswiperight: (e: CustomEvent) => void;
	 * 		onswipeleft: (e: CustomEvent) => void;
	 * 	}
	 * >}
	 */
	function gestures(node) {
		$effect(() => {
			// ...
			node.dispatchEvent(new CustomEvent('swipeleft'));
			// ...
			node.dispatchEvent(new CustomEvent('swiperight'));
		});
	}
</script>

<div use:gestures onswipeleft={next} onswiperight={prev}>...</div>
```

## docs/svelte/03-template-syntax/14-transition.md

# transition:

Transitions trigger when elements enter/leave DOM due to state changes.

`transition:` = bidirectional (can reverse mid-transition)

```svelte
<script>
	import { fade } from 'svelte/transition';

	let visible = $state(false);
</script>

<button onclick={() => visible = !visible}>toggle</button>

{#if visible}
	<div transition:fade>fades in and out</div>
{/if}
```

## Local vs Global

**Local** (default): plays only when own block created/destroyed
**Global**: plays when any parent block changes

```svelte
{#if x}
	{#if y}
		<p transition:fade>fades in and out only when y changes</p>
		<p transition:fade|global>fades in and out when x or y change</p>
	{/if}
{/if}
```

## Parameters

```svelte
{#if visible}
	<div transition:fade={{ duration: 2000 }}>fades in and out over two seconds</div>
{/if}
```

## Custom Transitions

```js
transition = (node: HTMLElement, params: any, options: { direction: 'in' | 'out' | 'both' }) => {
	delay?: number,
	duration?: number,
	easing?: (t: number) => number,
	css?: (t: number, u: number) => string,
	tick?: (t: number, u: number) => void
}
```

- `t`: 0→1 after easing (in transitions), 1→0 (out transitions)
- `u`: `1 - t`
- `css`: generates web animation keyframes (preferred - runs off main thread)
- `tick`: called during transition (use only if `css` not possible)

```svelte
<script>
	import { elasticOut } from 'svelte/easing';

	/** @type {boolean} */
	export let visible;

	/**
	 * @param {HTMLElement} node
	 * @param {{ delay?: number, duration?: number, easing?: (t: number) => number }} params
	 */
	function whoosh(node, params) {
		const existingTransform = getComputedStyle(node).transform.replace('none', '');

		return {
			delay: params.delay || 0,
			duration: params.duration || 400,
			easing: params.easing || elasticOut,
			css: (t, u) => `transform: ${existingTransform} scale(${t})`
		};
	}
</script>

{#if visible}
	<div in:whoosh>whooshes in</div>
{/if}
```

**With `tick`:**

```svelte
<script>
	export let visible = false;

	/**
	 * @param {HTMLElement} node
	 * @param {{ speed?: number }} params
	 */
	function typewriter(node, { speed = 1 }) {
		const valid = node.childNodes.length === 1 && node.childNodes[0].nodeType === Node.TEXT_NODE;

		if (!valid) {
			throw new Error(`This transition only works on elements with a single text node child`);
		}

		const text = node.textContent;
		const duration = text.length / (speed * 0.01);

		return {
			duration,
			tick: (t) => {
				const i = ~~(text.length * t);
				node.textContent = text.slice(0, i);
			}
		};
	}
</script>

{#if visible}
	<p in:typewriter={{ speed: 1 }}>The quick brown fox jumps over the lazy dog</p>
{/if}
```

**Returning function**: Called in next microtask, enables crossfade effects

## Events

- `introstart`
- `introend`
- `outrostart`
- `outroend`

```svelte
{#if visible}
	<p
		transition:fly={{ y: 200, duration: 2000 }}
		onintrostart={() => (status = 'intro started')}
		onoutrostart={() => (status = 'outro started')}
		onintroend={() => (status = 'intro ended')}
		onoutroend={() => (status = 'outro ended')}
	>
		Flies in and out
	</p>
{/if}
```

## docs/svelte/03-template-syntax/15-in-and-out.md

# in: and out:

`in:` and `out:` directives work like [`transition:`](transition) but are **not bidirectional** — they don't reverse if interrupted. If an out transition is aborted, transitions restart from scratch.

```svelte
<script>
  import { fade, fly } from 'svelte/transition';

  let visible = $state(false);
</script>

<label>
  <input type="checkbox" bind:checked={visible}>
  visible
</label>

{#if visible}
	<div in:fly={{ y: 200 }} out:fade>flies in, fades out</div>
{/if}
```

## docs/svelte/03-template-syntax/16-animate.md

# animate:

Triggers when contents of a keyed each block are re-ordered. Only runs on index changes, not add/remove. Must be on immediate child of keyed each block.

## Basic Usage

```svelte
{#each list as item, index (item)}
	<li animate:flip>{item}</li>
{/each}
```

## Parameters

```svelte
{#each list as item, index (item)}
	<li animate:flip={{ delay: 500 }}>{item}</li>
{/each}
```

## Custom Animation Functions

**Signature:**
```js
animation = (node: HTMLElement, { from: DOMRect, to: DOMRect }, params: any) => {
	delay?: number,
	duration?: number,
	easing?: (t: number) => number,
	css?: (t: number, u: number) => string,
	tick?: (t: number, u: number) => void
}
```

- `from`: DOMRect at start position
- `to`: DOMRect at end position
- `t`: easing-applied value from 0→1
- `u`: equals `1 - t`

**CSS method (preferred - runs off main thread):**

```svelte
<script>
	import { cubicOut } from 'svelte/easing';

	/**
	 * @param {HTMLElement} node
	 * @param {{ from: DOMRect; to: DOMRect }} states
	 * @param {any} params
	 */
	function whizz(node, { from, to }, params) {
		const dx = from.left - to.left;
		const dy = from.top - to.top;

		const d = Math.sqrt(dx * dx + dy * dy);

		return {
			delay: 0,
			duration: Math.sqrt(d) * 120,
			easing: cubicOut,
			css: (t, u) => `transform: translate(${u * dx}px, ${u * dy}px) rotate(${t * 360}deg);`
		};
	}
</script>

{#each list as item, index (item)}
	<div animate:whizz>{item}</div>
{/each}
```

**Tick method (runs during animation):**

```svelte
<script>
	import { cubicOut } from 'svelte/easing';

	/**
	 * @param {HTMLElement} node
	 * @param {{ from: DOMRect; to: DOMRect }} states
	 * @param {any} params
	 */
	function whizz(node, { from, to }, params) {
		const dx = from.left - to.left;
		const dy = from.top - to.top;

		const d = Math.sqrt(dx * dx + dy * dy);

		return {
			delay: 0,
			duration: Math.sqrt(d) * 120,
			easing: cubicOut,
			tick: (t, u) => Object.assign(node.style, { color: t > 0.5 ? 'Pink' : 'Blue' })
		};
	}
</script>

{#each list as item, index (item)}
	<div animate:whizz>{item}</div>
{/each}
```

> Prefer `css` over `tick` - web animations run off main thread, preventing jank.

## docs/svelte/03-template-syntax/17-style.md

# style:

Shorthand for setting styles on elements.

## Basic Usage

```svelte
<div style:color="red">...</div>
<!-- equivalent to -->
<div style="color: red;">...</div>
```

## Dynamic Values

```svelte
<div style:color={myColor}>...</div>
```

## Shorthand

```svelte
<div style:color>...</div>
```

## Multiple Styles

```svelte
<div style:color style:width="12rem" style:background-color={darkMode ? 'black' : 'white'}>...</div>
```

## Important Modifier

```svelte
<div style:color|important="red">...</div>
```

## Precedence

`style:` directives always take precedence over `style` attributes, even over `!important`:

```svelte
<div style:color="red" style="color: blue">This will be red</div>
<div style:color="red" style="color: blue !important">This will still be red</div>
```

## docs/svelte/03-template-syntax/18-class.md

# class

Two ways to set classes: `class` attribute and `class:` directive.

## Attributes

Primitive values:

```svelte
<div class={large ? 'large' : 'small'}>...</div>
```

> **Note:** Falsy values are stringified (`class="false"`), except `undefined`/`null` which omit the attribute. Future versions will omit all falsy values.

### Objects and arrays (Svelte 5.16+)

Uses [clsx](https://github.com/lukeed/clsx) internally.

**Object** - truthy keys are added:

```svelte
<script>
	let { cool } = $props();
</script>


<div class={{ cool, lame: !cool }}>...</div>
```

**Array** - truthy values combined:

```svelte

<div class={[faded && 'saturate-0 opacity-50', large && 'scale-200']}>...</div>
```

**Nested arrays/objects** - automatically flattened. Useful for combining local classes with props:

```svelte
<!file: Button.svelte>
<script>
	let props = $props();
</script>

<button {...props} class={['cool-button', props.class]}>
	{@render props.children?.()}
</button>
```

```svelte
<!file: App.svelte>
<script>
	import Button from './Button.svelte';
	let useTailwind = $state(false);
</script>

<Button
	onclick={() => useTailwind = true}
	class={{ 'bg-blue-700 sm:w-1/2': useTailwind }}
>
	Accept the inevitability of Tailwind
</Button>
```

**TypeScript** (Svelte 5.19+):

```svelte
<script lang="ts">
	import type { ClassValue } from 'svelte/elements';

	const props: { class: ClassValue } = $props();
</script>

<div class={['original', props.class]}>...</div>
```

## `class:` directive

Legacy conditional class syntax (pre-5.16):

```svelte

<div class={{ cool, lame: !cool }}>...</div>
<div class:cool={cool} class:lame={!cool}>...</div>
```

Shorthand when name matches value:

```svelte
<div class:cool class:lame={!cool}>...</div>
```

> **Note:** Prefer `class` attribute over `class:` - more powerful and composable.

## docs/svelte/03-template-syntax/19-await-expressions.md

# await

**Experimental feature (Svelte 5.36+)** — opt in via config:

```js
/// file: svelte.config.js
export default {
	compilerOptions: {
		experimental: {
			async: true
		}
	}
};
```

Flag removed in Svelte 6.

## Usage

Use `await` in three places:
- Top level of `<script>`
- Inside `$derived(...)`
- Inside markup

```svelte
<script>
	let a = $state(1);
	let b = $state(2);

	async function add(a, b) {
		await new Promise((f) => setTimeout(f, 500)); // artificial delay
		return a + b;
	}
</script>

<input type="number" bind:value={a}>
<input type="number" bind:value={b}>

<p>{a} + {b} = {await add(a, b)}</p>
```

## Synchronized updates

UI updates wait for async work to complete — prevents inconsistent states. If you increment `a`, the `<p>` won't show `2 + 2 = 3`, it waits to show `2 + 2 = 4`.

Updates can overlap — fast updates render while slow ones are ongoing.

## Concurrency

Independent `await` expressions run in parallel:

```svelte
<p>{await one()}</p>
<p>{await two()}</p>
```

Both functions run simultaneously.

Sequential `await` in `<script>` or functions run sequentially (normal JS behavior).

Exception: Independent `$derived` update independently after initial sequential run:

```js
// these will run sequentially the first time,
// but will update independently
let a = $derived(await one());
let b = $derived(await two());
```

> [!NOTE] Expect [`await_waterfall`](runtime-warnings#Client-warnings-await_waterfall) warning

## Loading states

**Placeholder UI**: Use `<svelte:boundary>` with `pending` snippet (shown on first load only).

**Subsequent updates**: Use `$effect.pending()` for spinners/indicators.

**Wait for completion**: Use `settled()`:

```js
import { tick, settled } from 'svelte';

async function onclick() {
	updating = true;

	// without this, the change to `updating` will be
	// grouped with the other changes, meaning it
	// won't be reflected in the UI
	await tick();

	color = 'octarine';
	answer = 42;

	await settled();

	// any updates affected by `color` or `answer`
	// have now been applied
	updating = false;
}
```

## Error handling

Errors bubble to nearest [error boundary](svelte-boundary).

## SSR

Await `render(...)` for async SSR:

```js
/// file: server.js
import { render } from 'svelte/server';
import App from './App.svelte';

const { head, body } =awaitrender(App);
```

`<svelte:boundary>` with `pending` snippet renders that snippet during SSR. All other `await` expressions resolve before `render(...)` returns.

## Forking

`fork(...)` (5.42+) runs `await` expressions for expected future actions (e.g., preloading):

```svelte
<script>
	import { fork } from 'svelte';
	import Menu from './Menu.svelte';

	let open = $state(false);

	/** @type {import('svelte').Fork | null} */
	let pending = null;

	function preload() {
		pending ??= fork(() => {
			open = true;
		});
	}

	function discard() {
		pending?.discard();
		pending = null;
	}
</script>

<button
	onfocusin={preload}
	onfocusout={discard}
	onpointerenter={preload}
	onpointerleave={discard}
	onclick={() => {
		pending?.commit();
		pending = null;

		// in case `pending` didn't exist
		// (if it did, this is a no-op)
		open = true;
	}}
>open menu</button>

{#if open}
	
	<Menu onclose={() => open = false} />
{/if}
```

## Caveats

- Experimental: breaking changes possible outside semver major
- Effects run differently: block effects (`{#if}`, `{#each}`) run before `$effect.pre`/`beforeUpdate` in same component

## docs/svelte/04-styling/01-scoped-styles.md

# Scoped Styles

## Basics

CSS in `<style>` is scoped by default via hash-based classes (e.g. `svelte-123xyz`).

```svelte
<style>
	p {
		/* this will only affect <p> elements in this component */
		color: burlywood;
	}
</style>
```

## Specificity

Scoped selectors get +0-1-0 specificity from the scoping class. Component `p` selector beats global `p` selector, even if global loads later.

Multiple scoping classes use `:where(.svelte-xyz123)` after the first to avoid further specificity increases.

## Scoped Keyframes

`@keyframes` names are hashed. `animation` rules auto-adjusted.

```svelte
<style>
	.bouncy {
		animation: bounce 10s;
	}

	/* these keyframes are only accessible inside this component */
	@keyframes bounce {
		/* ... */
	}
</style>
```

## docs/svelte/04-styling/02-global-styles.md

# Global Styles

## :global(...)

Apply styles to a single selector globally:

```svelte
<style>
	:global(body) {
		/* applies to <body> */
		margin: 0;
	}

	div :global(strong) {
		/* applies to all <strong> elements, in any component,
		   that are inside <div> elements belonging
		   to this component */
		color: goldenrod;
	}

	p:global(.big.red) {
		/* applies to all <p> elements belonging to this component
		   with `class="big red"`, even if it is applied
		   programmatically (for example by a library) */
	}
</style>
```

**Global keyframes:** Prepend with `-global-`, which gets removed at compile time:

```svelte
<style>
	@keyframes -global-my-animation-name {
		/* code goes here */
	}
</style>
```

## :global {...}

Apply styles to multiple selectors globally:

```svelte
<style>
	:global {
		/* applies to every <div> in your application */
		div { ... }

		/* applies to every <p> in your application */
		p { ... }
	}

	.a :global {
		/* applies to every `.b .c .d` element, in any component,
		   that is inside an `.a` element in this component */
		.b .c .d {...}
	}
</style>
```

## docs/svelte/04-styling/03-custom-properties.md

# Custom Properties

## Passing CSS Custom Properties

Pass static and dynamic CSS custom properties to components:

```svelte
<Slider
	bind:value
	min={0}
	max={100}
	--track-color="black"
	--thumb-color="rgb({r} {g} {b})"
/>
```

## How It Works

Desugars to a wrapper element with inline styles:

```svelte
<svelte-css-wrapper style="display: contents; --track-color: black; --thumb-color: rgb({r} {g} {b})">
	<Slider
		bind:value
		min={0}
		max={100}
	/>
</svelte-css-wrapper>
```

For SVG elements, uses `<g>` instead:

```svelte
<g style="--track-color: black; --thumb-color: rgb({r} {g} {b})">
	<Slider
		bind:value
		min={0}
		max={100}
	/>
</g>
```

## Using Custom Properties

Read custom properties with `var()` and provide fallbacks:

```svelte
<style>
	.track {
		background: var(--track-color, #aaa);
	}

	.thumb {
		background: var(--thumb-color, blue);
	}
</style>
```

Custom properties inherit from parent elements. Define on `:root` in global stylesheet for app-wide availability.

**Gotcha:** Wrapper element affects CSS selectors using `>` combinator targeting direct children.

## docs/svelte/04-styling/04-nested-style-elements.md

# Nested `<style>` elements

Only one top-level `<style>` per component. Nested `<style>` tags (inside elements/logic blocks) are inserted as-is into DOM with **no scoping or processing**.

```svelte
<div>
	<style>
		/* this style tag will be inserted as-is */
		div {
			/* this will apply to all `<div>` elements in the DOM */
			color: red;
		}
	</style>
</div>
```

## docs/svelte/05-special-elements/01-svelte-boundary.md

# `<svelte:boundary>`

```svelte
<svelte:boundary onerror={handler}>...</svelte:boundary>
```

**Added in 5.3.0**

Boundaries wall off app sections to:
- Show UI while `await` expressions resolve
- Handle rendering/effect errors and show error UI

When handling errors, existing content is removed.

**Errors NOT caught:** Event handlers, `setTimeout`, async work outside rendering.

## Properties

### `pending`

Shows while `await` expressions inside boundary resolve (first render only):

```svelte
<svelte:boundary>
	<p>{await delayed('hello!')}</p>

	{#snippet pending()}
		<p>loading...</p>
	{/snippet}
</svelte:boundary>
```

For subsequent updates, use `$effect.pending()`.

### `failed`

Renders when error thrown. Receives `error` and `reset` function:

```svelte
<svelte:boundary>
	<FlakyComponent />

	{#snippet failed(error, reset)}
		<button onclick={reset}>oops! try again</button>
	{/snippet}
</svelte:boundary>
```

Can pass explicitly: `<svelte:boundary {failed}>` or implicitly as shown.

### `onerror`

Called with `error` and `reset` args. For error tracking:

```svelte
<svelte:boundary onerror={(e) => report(e)}>
	...
</svelte:boundary>
```

Or using error/reset outside boundary:

```svelte
<script>
	let error = $state(null);
	let reset = $state(() => {});

	function onerror(e, r) {
		error = e;
		reset = r;
	}
</script>

<svelte:boundary {onerror}>
	<FlakyComponent />
</svelte:boundary>

{#if error}
	<button onclick={() => {
		error = null;
		reset();
	}}>
		oops! try again
	</button>
{/if}
```

Errors in `onerror` bubble to parent boundary if exists.

## docs/svelte/05-special-elements/02-svelte-window.md

# `<svelte:window>`

```svelte
<svelte:window onevent={handler} />
<svelte:window bind:prop={value} />
```

Adds event listeners to `window` without manual cleanup. Auto-handles SSR. Must be at component top level.

## Event listeners

```svelte
<script>
	function handleKeydown(event) {
		alert(`pressed the ${event.key} key`);
	}
</script>

<svelte:window onkeydown={handleKeydown} />
```

## Bindable properties

- `innerWidth` (readonly)
- `innerHeight` (readonly)
- `outerWidth` (readonly)
- `outerHeight` (readonly)
- `scrollX`
- `scrollY`
- `online` (readonly, alias for `window.navigator.onLine`)
- `devicePixelRatio` (readonly)

```svelte
<svelte:window bind:scrollY={y} />
```

**Gotcha:** Initial binding values don't trigger scroll (accessibility). Only subsequent changes scroll. To scroll on render, use `scrollTo()` in `$effect`.

## docs/svelte/05-special-elements/03-svelte-document.md

# `<svelte:document>`

```svelte
<svelte:document onevent={handler} />
<svelte:document bind:prop={value} />
```

Adds listeners to `document` events (e.g. `visibilitychange`) and allows actions on `document`.

**Rules:**
- Must be at top level of component
- Cannot be inside blocks or elements

**Example:**
```svelte
<svelte:document onvisibilitychange={handleVisibilityChange} use:someAction />
```

**Bindable properties (readonly):**
- `activeElement`
- `fullscreenElement`
- `pointerLockElement`
- `visibilityState`

## docs/svelte/05-special-elements/04-svelte-body.md

# `<svelte:body>`

```svelte
<svelte:body onevent={handler} />
```

Adds event listeners to `document.body` for events that don't fire on `window` (e.g., `mouseenter`, `mouseleave`). Also supports [actions](use).

**Restrictions:**
- Must be at top level of component
- Cannot be inside blocks or elements

```svelte
<svelte:body onmouseenter={handleMouseenter} onmouseleave={handleMouseleave} use:someAction />
```

## docs/svelte/05-special-elements/05-svelte-head.md

# `<svelte:head>`

```svelte
<svelte:head>...</svelte:head>
```

Inserts elements into `document.head`. During SSR, `head` content is exposed separately from `body`.

**Restrictions:**
- Must be at top level of component
- Cannot be inside blocks or elements

**Example:**
```svelte
<svelte:head>
	<title>Hello world!</title>
	<meta name="description" content="This is where the description goes for SEO" />
</svelte:head>
```

## docs/svelte/05-special-elements/06-svelte-element.md

# `<svelte:element>`

```svelte
<svelte:element this={expression} />
```

Renders dynamic elements (e.g., from CMS). Properties and event listeners apply to the element.

**Key points:**
- Only `bind:this` supported (built-in bindings don't work)
- Nullish `this` renders nothing
- Void elements (e.g., `br`) with children throw runtime error in dev
- Must be valid DOM tag (not `#text`, `svelte:head`, etc.)

**Namespace:**
```svelte
<svelte:element this={tag} xmlns="http://www.w3.org/2000/svg" />
```

**Example:**
```svelte
<script>
	let tag = $state('hr');
</script>

<svelte:element this={tag}>
	This text cannot appear inside an hr element
</svelte:element>
```

## docs/svelte/05-special-elements/07-svelte-options.md

# `<svelte:options>`

```svelte
<svelte:options option={value} />
```

Per-component compiler options.

## Options

- `runes={true}` — force runes mode
- `runes={false}` — force legacy mode
- `namespace="..."` — namespace: `"html"` (default), `"svg"`, or `"mathml"`
- `customElement={...}` — custom element [options](custom-elements#Component-options). String value used as `tag`
- `css="injected"` — inject styles inline: `<style>` tag in `head` (SSR) or via JS (client)

## Example

```svelte
<svelte:options customElement="my-custom-element" />
```

## Deprecated (Svelte 4, non-functional in runes mode)

- `immutable={true|false}` — referential equality checks
- `accessors={true|false}` — getters/setters for props

## docs/svelte/06-runtime/01-stores.md

# Stores

A store is an object that allows reactive access to a value via a store contract. Access store values in components by prefixing with `$` - Svelte auto-subscribes/unsubscribes.

Assignments to `$`-prefixed variables call the store's `.set` method. Store must be declared at component top level.

```svelte
<script>
	import { writable } from 'svelte/store';

	const count = writable(0);
	console.log($count); // logs 0

	count.set(1);
	console.log($count); // logs 1

	$count = 2;
	console.log($count); // logs 2
</script>
```

## When to use stores

In Svelte 5, runes replace most store use cases:

**Extracting logic:** Use runes in `.svelte.js`/`.svelte.ts` files:

```ts
/// file: state.svelte.js
export const userState = $state({
	name: 'name',
	/* ... */
});
```

```svelte
<!file: App.svelte>
<script>
	import { userState } from './state.svelte.js';
</script>

<p>User name: {userState.name}</p>
<button onclick={() => {
	userState.name = 'new name';
}}>
	change name
</button>
```

**Use stores for:** complex async data streams, manual control over updates/subscriptions, or RxJs integration.

## svelte/store

### `writable`

Store with `set` and `update` methods for external updates.

```js
/// file: store.js
import { writable } from 'svelte/store';

const count = writable(0);

count.subscribe((value) => {
	console.log(value);
}); // logs '0'

count.set(1); // logs '1'

count.update((n) => n + 1); // logs '2'
```

Optional second argument: function called when subscribers go 0→1, must return cleanup function called when subscribers go 1→0.

```js
/// file: store.js
import { writable } from 'svelte/store';

const count = writable(0, () => {
	console.log('got a subscriber');
	return () => console.log('no more subscribers');
});

count.set(1); // does nothing

const unsubscribe = count.subscribe((value) => {
	console.log(value);
}); // logs 'got a subscriber', then '1'

unsubscribe(); // logs 'no more subscribers'
```

### `readable`

Store whose value cannot be set externally. Same second argument as `writable`.

```ts
import { readable } from 'svelte/store';

const time = readable(new Date(), (set) => {
	set(new Date());

	const interval = setInterval(() => {
		set(new Date());
	}, 1000);

	return () => clearInterval(interval);
});

const ticktock = readable('tick', (set, update) => {
	const interval = setInterval(() => {
		update((sound) => (sound === 'tick' ? 'tock' : 'tick'));
	}, 1000);

	return () => clearInterval(interval);
});
```

### `derived`

Derives store from one or more stores. Callback runs on first subscribe and when dependencies change.

```ts
// @filename: ambient.d.ts
import { type Writable } from 'svelte/store';

declare global {
	const a: Writable<number>;
}

export {};

// @filename: index.ts
//cut
import { derived } from 'svelte/store';

const doubled = derived(a, ($a) => $a * 2);
```

Async with `set`/`update` (third arg is initial value):

```ts
// @filename: ambient.d.ts
import { type Writable } from 'svelte/store';

declare global {
	const a: Writable<number>;
}

export {};

// @filename: index.ts
// @errors: 18046 2769 7006
//cut
import { derived } from 'svelte/store';

const delayed = derived(
	a,
	($a, set) => {
		setTimeout(() => set($a), 1000);
	},
	2000
);

const delayedIncrement = derived(a, ($a, set, update) => {
	set($a);
	setTimeout(() => update((x) => x + 1), 1000);
	// every time $a produces a value, this produces two
	// values, $a immediately and then $a + 1 a second later
});
```

Return function for cleanup:

```ts
// @filename: ambient.d.ts
import { type Writable } from 'svelte/store';

declare global {
	const frequency: Writable<number>;
}

export {};

// @filename: index.ts
//cut
import { derived } from 'svelte/store';

const tick = derived(
	frequency,
	($frequency, set) => {
		const interval = setInterval(() => {
			set(Date.now());
		}, 1000 / $frequency);

		return () => {
			clearInterval(interval);
		};
	},
	2000
);
```

Multiple stores:

```ts
// @filename: ambient.d.ts
import { type Writable } from 'svelte/store';

declare global {
	const a: Writable<number>;
	const b: Writable<number>;
}

export {};

// @filename: index.ts

//cut
import { derived } from 'svelte/store';

const summed = derived([a, b], ([$a, $b]) => $a + $b);

const delayed = derived([a, b], ([$a, $b], set) => {
	setTimeout(() => set($a + $b), 1000);
});
```

### `readonly`

Makes store readonly while allowing subscriptions.

```js
import { readonly, writable } from 'svelte/store';

const writableStore = writable(1);
const readableStore = readonly(writableStore);

readableStore.subscribe(console.log);

writableStore.set(2); // console: 2
// @errors: 2339
readableStore.set(2); // ERROR
```

### `get`

Retrieves store value without subscribing. Not recommended in hot code paths.

```ts
// @filename: ambient.d.ts
import { type Writable } from 'svelte/store';

declare global {
	const store: Writable<string>;
}

export {};

// @filename: index.ts
//cut
import { get } from 'svelte/store';

const value = get(store);
```

## Store contract

```ts
// @noErrors
store = { subscribe: (subscription: (value: any) => void) => (() => void), set?: (value: any) => void }
```

Custom stores must implement:

1. `.subscribe(fn)` - immediately/synchronously calls `fn` with current value, calls all active subscriptions when value changes
2. Returns unsubscribe function that stops subscription
3. Optional `.set(value)` - synchronously calls all active subscriptions (makes it writable)

`.subscribe` may return object with `.unsubscribe` method (RxJS compatibility).

## docs/svelte/06-runtime/02-context.md

# Context

Context allows components to access values from parent components without prop-drilling.

## Basic Usage

Parent sets context with `setContext(key, value)`:

```svelte
<!file: Parent.svelte>
<script>
	import { setContext } from 'svelte';

	setContext('my-context', 'hello from Parent.svelte');
</script>
```

Child retrieves with `getContext`:

```svelte
<!file: Child.svelte>
<script>
	import { getContext } from 'svelte';

	const message = getContext('my-context');
</script>

<h1>{message}, inside Child.svelte</h1>
```

Works through `children` snippets:

```svelte
<Parent>
	<Child />
</Parent>
```

Key and value can be any JavaScript value.

**Available functions:** `setContext`, `getContext`, `hasContext`, `getAllContexts`

## Reactive State in Context

Store reactive state in context:

```svelte
<script>
	import { setContext } from 'svelte';
	import Child from './Child.svelte';

	let counter = $state({
		count: 0
	});

	setContext('counter', counter);
</script>

<button onclick={() => counter.count += 1}>
	increment
</button>

<Child />
<Child />
<Child />
```

**Gotcha:** Mutate state, don't reassign it:

```svelte
<!-- ❌ Breaks the link -->
<button onclick={() => counter = { count: 0 }}>
	reset
</button>

<!-- ✅ Correct -->
<button onclick={() =>counter.count = 0}>
	reset
</button>
```

## Type-Safe Context

Use `createContext` for type safety without keys:

```ts
/// file: context.ts
// @filename: ambient.d.ts
interface User {}

// @filename: index.ts
//cut
import { createContext } from 'svelte';

export const [getUserContext, setUserContext] = createContext<User>();
```

**Testing wrapper (v5.49+):**

```js
import { mount, unmount } from 'svelte';
import { expect, test } from 'vitest';
import { setUserContext } from './context';
import MyComponent from './MyComponent.svelte';

test('MyComponent', () => {
	function Wrapper(...args) {
		setUserContext({ name: 'Bob' });
		return MyComponent(...args);
	}

	const component = mount(Wrapper, {
		target: document.body
	});

	expect(document.body.innerHTML).toBe('<h1>Hello Bob!</h1>');

	unmount(component);
});
```

Works with `hydrate` and `render` too.

## vs Global State

Global state modules work but have SSR risks:

```js
/// file: state.svelte.js
export const myGlobalState = $state({
	user: {
		// ...
	}
	// ...
});
```

If mutated during SSR, data may leak between requests:

```svelte
<!file: App.svelte->
<script>
	import { myGlobalState } from './state.svelte.js';

	let { data } = $props();

	if (data.user) {
		myGlobalState.user = data.user;
	}
</script>
```

**Context is request-scoped and prevents this.**

## docs/svelte/06-runtime/03-lifecycle-hooks.md

# Lifecycle Hooks

Svelte 5 lifecycle = creation + destruction. No "before/after update" hooks — effects react to specific state changes, not component-wide updates.

## `onMount`

Runs when component mounts to DOM. Must be called during component initialization. **Does not run on server.**

```svelte
<script>
	import { onMount } from 'svelte';

	onMount(() => {
		console.log('the component has mounted');
	});
</script>
```

Return a function to run on unmount:

```svelte
<script>
	import { onMount } from 'svelte';

	onMount(() => {
		const interval = setInterval(() => {
			console.log('beep');
		}, 1000);

		return () => clearInterval(interval);
	});
</script>
```

**Note:** Only works with synchronous functions. `async` functions return a `Promise`.

## `onDestroy`

Runs before component unmounts. **Only lifecycle hook that runs server-side.**

```svelte
<script>
	import { onDestroy } from 'svelte';

	onDestroy(() => {
		console.log('the component is being destroyed');
	});
</script>
```

## `tick`

Returns promise that resolves after pending state changes apply (or next microtask if none).

```svelte
<script>
	import { tick } from 'svelte';

	$effect.pre(() => {
		console.log('the component is about to update');
		tick().then(() => {
				console.log('the component just updated');
		});
	});
</script>
```

## Deprecated: `beforeUpdate` / `afterUpdate`

**Shimmed for Svelte 4 compatibility. Not available with runes.**

Use `$effect.pre` instead of `beforeUpdate` and `$effect` instead of `afterUpdate` — more granular, only react to relevant changes.

### Example: Chat autoscroll

`beforeUpdate` fires on every update (flawed). `$effect.pre` only runs when `messages` changes, not `theme`.

```svelte
<script>
	import { tick } from 'svelte';

	let theme = $state('dark');
	let messages = $state([]);

	let viewport;

	$effect.pre(() => {
		messages;
		const autoscroll = viewport && viewport.offsetHeight + viewport.scrollTop > viewport.scrollHeight - 50;

		if (autoscroll) {
			tick().then(() => {
				viewport.scrollTo(0, viewport.scrollHeight);
			});
		}
	});

	function handleKeydown(event) {
		if (event.key === 'Enter') {
			const text = event.target.value;
			if (!text) return;

			messages = [...messages, text];
			event.target.value = '';
		}
	}

	function toggle() {
		theme = theme === 'dark' ? 'light' : 'dark';
	}
</script>

<div class:dark={theme === 'dark'}>
	<div bind:this={viewport}>
		{#each messages as message}
			<p>{message}</p>
		{/each}
	</div>

	<input onkeydown={handleKeydown} />

	<button onclick={toggle}> Toggle dark mode </button>
</div>
```

## docs/svelte/06-runtime/04-imperative-component-api.md

# Imperative Component API

## `mount`

Instantiates and mounts a component to a target element:

```js
// @errors: 2322
import { mount } from 'svelte';
import App from './App.svelte';

const app = mount(App, {
	target: document.querySelector('#app'),
	props: { some: 'property' }
});
```

**Key points:**
- Can mount multiple components per page
- Effects (including `onMount`, actions) don't run during `mount`
- Use `flushSync()` to force pending effects to run

## `unmount`

Unmounts a component created with `mount` or `hydrate`:

```js
import { mount, unmount } from 'svelte';
import App from './App.svelte';

const app = mount(App, { target: document.body });

// later
unmount(app, { outro: true });
```

- `options.outro: true` plays transitions before removal
- Returns `Promise` that resolves after transitions (if `outro: true`) or immediately

## `render`

Server-only. Returns `body` and `head` HTML for SSR:

```js
// @errors: 2724 2305 2307
import { render } from 'svelte/server';
import App from './App.svelte';

const result = render(App, {
	props: { some: 'property' }
});
result.body; // HTML for somewhere in this <body> tag
result.head; // HTML for somewhere in this <head> tag
```

## `hydrate`

Like `mount`, but reuses SSR HTML and makes it interactive:

```js
// @errors: 2322
import { hydrate } from 'svelte';
import App from './App.svelte';

const app = hydrate(App, {
	target: document.querySelector('#app'),
	props: { some: 'property' }
});
```

- Effects don't run during `hydrate` — use `flushSync()` if needed

## docs/svelte/06-runtime/05-hydratable.md

# Hydratable Data

## Problem

Awaiting async data in components causes redundant work during hydration:

```svelte
<script>
  import { getUser } from 'my-database-library';

  // Gets user on server AND again during client hydration (wasteful)
  const user = await getUser();
</script>

<h1>{user.name}</h1>
```

## Solution: `hydratable()`

Serializes server data and reuses it during hydration:

```svelte
<script>
  import { hydratable } from 'svelte';
  import { getUser } from 'my-database-library';

  // Server: runs getUser(), serializes result to <head>
  // Hydration: uses serialized data, skips getUser()
  // Post-hydration: runs getUser() normally
  const user = await hydratable('user', () => getUser());
</script>

<h1>{user.name}</h1>
```

**Usage for stable random/time values:**

```ts
import { hydratable } from 'svelte';
const rand = hydratable('random', () => Math.random());
```

**Library authors:** Prefix keys with library name to avoid conflicts.

## Serialization

Uses [`devalue`](https://npmjs.com/package/devalue) - supports JSON plus `Map`, `Set`, `URL`, `BigInt`, `Promise`, etc:

```svelte
<script>
  import { hydratable } from 'svelte';
  const promises = hydratable('random', () => {
    return {
      one: Promise.resolve(1),
      two: Promise.resolve(2)
    }
  });
</script>

{await promises.one}
{await promises.two}
```

## CSP

`hydratable` adds inline `<script>` to `head`. For CSP compliance:

**Dynamic rendering (use `nonce`):**

```js
const nonce = crypto.randomUUID();

const { head, body } = await render(App, {
	csp: { nonce }
});

response.headers.set(
  'Content-Security-Policy',
  `script-src 'nonce-${nonce}'`
);
```

**Static HTML (use `hash`):**

```js
const { head, body, hashes } = await render(App, {
	csp: { hash: true }
});

response.headers.set(
  'Content-Security-Policy',
  `script-src ${hashes.script.map((hash) => `'${hash}'`).join(' ')}`
);
```

**Prefer `nonce`** - `hash` will interfere with future streaming SSR.

## docs/svelte/07-misc/02-testing.md

# Testing

Svelte is unopinionated about testing frameworks. Use [Vitest](https://vitest.dev/), [Jasmine](https://jasmine.github.io/), [Cypress](https://www.cypress.io/), [Playwright](https://playwright.dev/), etc.

## Unit and Component Tests with Vitest

### Setup

Install Vitest:
```sh
npm install -D vitest
```

Configure `vite.config.js`:
```js
/// file: vite.config.js
import { defineConfig } from'vitest/config';

export default defineConfig({
	// Tell Vitest to use `browser` entry points in package.json
	resolve: process.env.VITEST
		? {
				conditions: ['browser']
			}
		: undefined
});
```

### Unit Tests

```js
/// file: multiplier.svelte.test.js
import { flushSync } from 'svelte';
import { expect, test } from 'vitest';
import { multiplier } from './multiplier.svelte.js';

test('Multiplier', () => {
	let double = multiplier(0, 2);

	expect(double.value).toEqual(0);

	double.set(5);

	expect(double.value).toEqual(10);
});
```

```js
/// file: multiplier.svelte.js
export function multiplier(initial, k) {
	let count = $state(initial);

	return {
		get value() {
			return count * k;
		},
		set: (c) => {
			count = c;
		}
	};
}
```

### Using Runes in Tests

Runes work in test files with `.svelte` extension:

```js
/// file: multiplier.svelte.test.js
import { flushSync } from 'svelte';
import { expect, test } from 'vitest';
import { multiplier } from './multiplier.svelte.js';

test('Multiplier', () => {
	let count = $state(0);
	let double = multiplier(() => count, 2);

	expect(double.value).toEqual(0);

	count = 5;

	expect(double.value).toEqual(10);
});
```

### Testing Effects

Wrap tests using effects in `$effect.root`:

```js
/// file: logger.svelte.test.js
import { flushSync } from 'svelte';
import { expect, test } from 'vitest';
import { logger } from './logger.svelte.js';

test('Effect', () => {
	const cleanup = $effect.root(() => {
		let count = $state(0);

		let log = logger(() => count);

		// flushSync executes pending effects synchronously
		flushSync();
		expect(log).toEqual([0]);

		count = 1;
		flushSync();

		expect(log).toEqual([0, 1]);
	});

	cleanup();
});
```

```js
/// file: logger.svelte.js
export function logger(getValue) {
	let log = [];

	$effect(() => {
		log.push(getValue());
	});

	return log;
}
```

### Component Testing

> [!NOTE] Consider extracting logic from components to test it in isolation without component overhead.

Install jsdom:
```sh
npm install -D jsdom
```

Configure `vite.config.js`:
```js
/// file: vite.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
	plugins: [/* ... */],
	test: {
		environment: 'jsdom' // or use `// @vitest-environment jsdom` in test files
	},
	resolve: process.env.VITEST
		? {
				conditions: ['browser']
			}
		: undefined
});
```

Basic component test:
```js
/// file: component.test.js
import { flushSync, mount, unmount } from 'svelte';
import { expect, test } from 'vitest';
import Component from './Component.svelte';

test('Component', () => {
	const component = mount(Component, {
		target: document.body,
		props: { initial: 0 }
	});

	expect(document.body.innerHTML).toBe('<button>0</button>');

	document.body.querySelector('button').click();
	flushSync();

	expect(document.body.innerHTML).toBe('<button>1</button>');

	unmount(component);
});
```

Using [@testing-library/svelte](https://testing-library.com/docs/svelte-testing-library/intro/):
```js
/// file: component.test.js
import { render, screen } from '@testing-library/svelte';
import userEvent from '@testing-library/user-event';
import { expect, test } from 'vitest';
import Component from './Component.svelte';

test('Component', async () => {
	const user = userEvent.setup();
	render(Component);

	const button = screen.getByRole('button');
	expect(button).toHaveTextContent(0);

	await user.click(button);
	expect(button).toHaveTextContent(1);
});
```

**Gotcha:** For two-way bindings, context, or snippet props, create a wrapper component for your test.

## Component Tests with Storybook

[Storybook](https://storybook.js.org) uses Vitest's browser mode for realistic testing.

Setup: `npx sv add storybook`

Example with [play function](https://storybook.js.org/docs/writing-tests/interaction-testing?renderer=svelte#writing-interaction-tests):

```svelte
/// file: LoginForm.stories.svelte
<script module>
	import { defineMeta } from '@storybook/addon-svelte-csf';
	import { expect, fn } from 'storybook/test';

	import LoginForm from './LoginForm.svelte';

	const { Story } = defineMeta({
		component: LoginForm,
		args: {
			onSubmit: fn(),
		}
	});
</script>
 
<Story name="Empty Form" />
 
<Story
	name="Filled Form"
	play={async ({ args, canvas, userEvent }) => {
		await userEvent.type(canvas.getByTestId('email'), 'email@provider.com');
		await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
		await userEvent.click(canvas.getByRole('button'));

		await expect(args.onSubmit).toHaveBeenCalledTimes(1);
		await expect(canvas.getByText('You're in!')).toBeInTheDocument();
	}}
/>
```

## E2E Tests with Playwright

Setup: `npx sv add playwright` or `npm init playwright`

Configure `playwright.config.js`:
```js
/// file: playwright.config.js
const config = {
	webServer: {
		command: 'npm run build && npm run preview',
		port: 4173
	},
	testDir: 'tests',
	testMatch: /(.+\.)?(test|spec)\.[jt]s/
};

export default config;
```

Write tests (framework-agnostic):
```js
/// file: tests/hello-world.spec.js
import { expect, test } from '@playwright/test';

test('home page has expected h1', async ({ page }) => {
	await page.goto('/');
	await expect(page.locator('h1')).toBeVisible();
});
```

## docs/svelte/07-misc/03-typescript.md

# TypeScript

## `<script lang="ts">`

Add `lang="ts"` to use TypeScript:

```svelte
<script lang="ts">
	let name: string = 'world';

	function greet(name: string) {
		alert(`Hello, ${name}!`);
	}
</script>

<button onclick={(e: Event) => greet(e.target.innerText)}>
	{name as string}
</button>
```

**Limitations:** Only type-only features supported (types, interfaces). Not supported:
- Enums
- `private`/`protected`/`public` with initializers
- Non-stage-4 ECMAScript features

For these, use a preprocessor.

## Preprocessor Setup

### SvelteKit/Vite

Scaffold with `npx sv create` (TypeScript option) or `npm create vite@latest` (`svelte-ts` option).

```ts
/// file: svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

const config = {
	preprocess: vitePreprocess()
};

export default config;
```

For non-type-only features, add `{ script: true }`:

```ts
/// file: svelte.config.js
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

const config = {
	preprocess: vitePreprocess({ script: true })
};

export default config;
```

### Other Tools

Use `rollup-plugin-svelte` or `svelte-loader` with `svelte-preprocess`.

## tsconfig.json

Required settings:
- `target`: `ES2015` minimum
- `verbatimModuleSyntax`: `true`
- `isolatedModules`: `true`

## Typing `$props`

```svelte
<script lang="ts">
	import type { Snippet } from 'svelte';

	interface Props {
		requiredProperty: number;
		optionalProperty?: boolean;
		snippetWithStringArgument: Snippet<[string]>;
		eventHandler: (arg: string) => void;
		[key: string]: unknown;
	}

	let {
		requiredProperty,
		optionalProperty,
		snippetWithStringArgument,
		eventHandler,
		...everythingElse
	}: Props = $props();
</script>

<button onclick={() => eventHandler('clicked button')}>
	{@render snippetWithStringArgument('hello')}
</button>
```

## Generic `$props`

Use `generics` attribute for type relationships:

```svelte
<script lang="ts" generics="Item extends { text: string }">
	interface Props {
		items: Item[];
		select(item: Item): void;
	}

	let { items, select }: Props = $props();
</script>

{#each items as item}
	<button onclick={() => select(item)}>
		{item.text}
	</button>
{/each}
```

## Typing Wrapper Components

Use `svelte/elements` types:

```svelte
<script lang="ts">
	import type { HTMLButtonAttributes } from 'svelte/elements';

	let { children, ...rest }: HTMLButtonAttributes = $props();
</script>

<button {...rest}>
	{@render children?.()}
</button>
```

For elements without dedicated types:

```svelte
<script lang="ts">
	import type { SvelteHTMLElements } from 'svelte/elements';

	let { children, ...rest }: SvelteHTMLElements['div'] = $props();
</script>

<div {...rest}>
	{@render children?.()}
</div>
```

## Typing `$state`

```ts
let count: number = $state(0);
```

Without initial value, type includes `undefined`. Use `as` casting if you know it will be defined:

```ts
class Counter {
	count = $state() as number;
	constructor(initial: number) {
		this.count = initial;
	}
}
```

## The `Component` Type

Constrain dynamic components:

```svelte
<script lang="ts">
	import type { Component } from 'svelte';

	interface Props {
		DynamicComponent: Component<{ prop: string }>;
	}

	let { DynamicComponent }: Props = $props();
</script>

<DynamicComponent prop="foo" />
```

Extract props with `ComponentProps`:

```ts
import type { Component, ComponentProps } from 'svelte';
import MyComponent from './MyComponent.svelte';

function withProps<TComponent extends Component<any>>(
	component: TComponent,
	props: ComponentProps<TComponent>
) {}

withProps(MyComponent, { foo: 'bar' });
```

Constructor/instance types:

```svelte
<script lang="ts">
	import MyComponent from './MyComponent.svelte';

	let componentConstructor: typeof MyComponent = MyComponent;
	let componentInstance: MyComponent;
</script>

<MyComponent bind:this={componentInstance} />
```

## Enhancing Built-in DOM Types

Augment `svelte/elements` for custom/experimental attributes:

```ts
/// file: additional-svelte-typings.d.ts
import { HTMLButtonAttributes } from 'svelte/elements';

declare module 'svelte/elements' {
	export interface SvelteHTMLElements {
		'custom-button': HTMLButtonAttributes;
	}

	export interface HTMLAttributes<T> {
		globalattribute?: string;
	}

	export interface HTMLButtonAttributes {
		veryexperimentalattribute?: string;
	}
}

export {};
```

Reference in `tsconfig.json` (e.g., `"include": ["src/**/*"]`).

## docs/kit/10-getting-started/10-introduction.md

# Introduction

## What is SvelteKit?

Framework for building robust, performant web apps using Svelte. Similar to Next (React) or Nuxt (Vue).

## What is Svelte?

UI component framework. Compiler converts components to JavaScript (renders HTML) and CSS. See [Svelte tutorial](/tutorial) to learn more.

## SvelteKit vs Svelte

**Svelte**: Renders UI components only.

**SvelteKit**: Full-featured framework providing:
- Router
- [Build optimizations](https://vitejs.dev/guide/features.html#build-optimizations)
- [Offline support](service-workers)
- [Preloading](link-options#data-sveltekit-preload-data)
- [Configurable rendering](page-options): [SSR](glossary#SSR), [CSR](glossary#CSR), [prerendering](glossary#Prerendering)
- [Image optimization](images)
- [HMR](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#hot) via [Vite](https://vitejs.dev/)

See [project types](project-types) for application examples.

## docs/kit/10-getting-started/20-creating-a-project.md

# Creating a project

## Quick start

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

First command scaffolds project with optional TypeScript/tooling setup. `npm run dev` starts dev server on localhost:5173.

## Core concepts

- Each page = Svelte component
- Add files to `src/routes` to create pages
- Server-rendered first visit → client-side app takeover

## Editor setup

Use VS Code with Svelte extension (other editors supported).

## docs/kit/10-getting-started/25-project-types.md

# Project Types

SvelteKit offers configurable rendering. Rendering settings are not mutually exclusive - choose optimal rendering per route. Adapter choice and config control build/deploy/render behavior.

## Default Rendering

First page: [SSR](glossary#SSR). Subsequent pages: [CSR](glossary#CSR). SSR improves SEO and initial load. CSR updates pages without rerendering common components (faster, no flash). Also called [transitional apps](https://www.youtube.com/watch?v=860d8usGC0o).

## Static Site Generation

Use [`adapter-static`](adapter-static) for full [prerendering](glossary#Prerendering) ([SSG](glossary#SSG)). Or use [prerender option](page-options#prerender) to prerender some pages and dynamically render others with different adapter.

For very large sites: [`adapter-vercel`](adapter-vercel) supports [ISR](adapter-vercel#Incremental-Static-Regeneration).

## Single-Page App

[SPAs](glossary#SPA) use [CSR](glossary#CSR) exclusively. See [building SPAs](single-page-apps). If no backend or [separate backend](#Separate-backend), ignore `server` file docs.

## Multi-Page App

Not typical for SvelteKit. Options:
- [`csr = false`](page-options#csr) removes JS, renders subsequent links on server
- [`data-sveltekit-reload`](link-options#data-sveltekit-reload) renders specific links on server

## Separate Backend

For backends in Go, Java, PHP, Ruby, Rust, C#, etc:
- **Recommended**: Deploy frontend separately using `adapter-node` or serverless adapter
- Alternative: Deploy as [SPA](single-page-apps) served by backend (worse SEO/performance)

Ignore `server` file docs. See [FAQ on backend API calls](faq#How-do-I-use-a-different-backend-API-server).

## Serverless App

[`adapter-auto`](adapter-auto) auto-detects platforms. Or use [`adapter-vercel`](adapter-vercel), [`adapter-netlify`](adapter-netlify), [`adapter-cloudflare`](adapter-cloudflare). [Community adapters](/packages#sveltekit-adapters) support most serverless environments. Some adapters offer `edge` option for [edge rendering](glossary#Edge).

## Your Own Server

Use [`adapter-node`](adapter-node) for VPS/server deployment.

## Container

Use [`adapter-node`](adapter-node) for Docker/LXC containers.

## Library

Create library for other Svelte apps with [`@sveltejs/package`](packaging) add-on. Choose library option in [`sv create`](/docs/cli/sv-create).

## Offline App

Full [service worker](service-workers) support for offline apps and [PWAs](glossary#PWA).

## Mobile App

Turn [SvelteKit SPA](single-page-apps) into mobile app with [Tauri](https://v2.tauri.app/start/frontend/sveltekit/) or [Capacitor](https://capacitorjs.com/solution/svelte). Camera, geolocation, push notifications via plugins.

Platforms use local web server. Consider [`bundleStrategy: 'single'`](configuration#output) to limit requests (Capacitor uses HTTP/1, limiting concurrent connections).

## Desktop App

Turn [SvelteKit SPA](single-page-apps) into desktop app with [Tauri](https://v2.tauri.app/start/frontend/sveltekit/), [Wails](https://wails.io/docs/guides/sveltekit/), or [Electron](https://www.electronjs.org/).

## Browser Extension

Use [`adapter-static`](adapter-static) or [community adapters](/packages#sveltekit-adapters) for browser extensions.

## Embedded Device

Svelte runs on low-power devices. For microcontrollers/TVs with limited concurrent connections, use [`bundleStrategy: 'single'`](configuration#output).

## docs/kit/10-getting-started/30-project-structure.md

# Project Structure

## Directory Layout

```tree
my-project/
├ src/
│ ├ lib/
│ │ ├ server/         # Server-only code
│ │ └ [lib files]     # Utilities/components, import via $lib
│ ├ params/           # Param matchers
│ ├ routes/           # App routes
│ ├ app.html          # Page template
│ ├ error.html        # Error page
│ ├ hooks.client.js
│ ├ hooks.server.js
│ ├ service-worker.js
│ └ instrumentation.server.js
├ static/             # Static assets (served as-is)
├ tests/
├ package.json
├ svelte.config.js
├ tsconfig.json
└ vite.config.js
```

## Key Files

### src/lib
- Import via `$lib` alias
- `server/` subdirectory: server-only code via `$lib/server` alias (client imports prevented)

### src/app.html
Page template with placeholders:
- `%sveltekit.head%` — `<link>`, `<script>`, `<svelte:head>` content
- `%sveltekit.body%` — rendered markup (must be inside `<div>`, not directly in `<body>`)
- `%sveltekit.assets%` — `paths.assets` or relative to `paths.base`
- `%sveltekit.nonce%` — CSP nonce
- `%sveltekit.env.[NAME]%` — environment variable (must start with `publicPrefix`, usually `PUBLIC_`)
- `%sveltekit.version%` — app version

### src/error.html
Fallback error page with:
- `%sveltekit.status%` — HTTP status
- `%sveltekit.error.message%` — error message

### src/hooks.client.js / hooks.server.js
Client and server hooks

### src/instrumentation.server.js
Observability setup. Runs before app code (requires adapter support)

### static/
Static assets served without name changes. Prefer `import` for cache-friendly hashed filenames

### package.json
Must include `@sveltejs/kit`, `svelte`, `vite` as `devDependencies`
Must have `"type": "module"` (`.cjs` for CommonJS)

### svelte.config.js
Svelte and SvelteKit configuration

### tsconfig.json
TypeScript config. Extends generated `.svelte-kit/tsconfig.json`. Use `typescript.config` setting for top-level changes

### vite.config.js
Vite config with `@sveltejs/kit/vite` plugin

### .svelte-kit
Generated files (configurable via `outDir`). Can be deleted, will regenerate

## docs/kit/10-getting-started/40-web-standards.md

# Web Standards

SvelteKit builds on standard Web APIs available in modern browsers and non-browser environments.

## Fetch APIs

`fetch` available in hooks, server routes, and browser.

**Special server-side `fetch`:**
- In `load` functions, server hooks, and API routes: invokes endpoints directly during SSR without HTTP calls
- Preserves credentials automatically
- Allows relative requests
- Outside `load`: must explicitly pass `cookie`/`authorization` headers

### Request

`event.request` in hooks and server routes. Methods: `request.json()`, `request.formData()`

### Response

Returned from `await fetch(...)` and `+server.js` handlers.

### Headers

Read `request.headers`, set `response.headers`:

```js
// @errors: 2461
/// file: src/routes/what-is-my-user-agent/+server.js
import { json } from '@sveltejs/kit';

/** @type {import('./$types').RequestHandler} */
export function GET({ request }) {
	// log all headers
	console.log(...request.headers);

	// create a JSON Response using a header we received
	return json({
		// retrieve a specific header
		userAgent: request.headers.get('user-agent')
	}, {
		// set a header on the response
		headers: { 'x-custom-header': 'potato' }
	});
}
```

## FormData

For HTML form submissions:

```js
// @errors: 2461
/// file: src/routes/hello/+server.js
import { json } from '@sveltejs/kit';

/** @type {import('./$types').RequestHandler} */
export async function POST(event) {
	const body = await event.request.formData();

	// log all fields
	console.log([...body]);

	return json({
		// get a specific field's value
		name: body.get('name') ?? 'world'
	});
}
```

## Stream APIs

For large/chunked responses: `ReadableStream`, `WritableStream`, `TransformStream`

## URL APIs

`URL` interface with `origin`, `pathname` properties. Available as:
- `event.url` in hooks/server routes
- `page.url` in pages
- `from`/`to` in `beforeNavigate`/`afterNavigate`

### URLSearchParams

Access query params via `url.searchParams`:

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

export {};

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

## Web Crypto

`crypto` global for CSP headers and utilities:

```js
const uuid = crypto.randomUUID();
```

## docs/kit/20-core-concepts/10-routing.md

# Routing

Filesystem-based router. Routes defined by directories in `src/routes`:

- `src/routes` → root route
- `src/routes/about` → `/about`
- `src/routes/blog/[slug]` → route with parameter `slug`

**Key rules:**
- All files run on server
- All files run on client except `+server`
- `+layout` and `+error` apply to subdirectories

## +page

### +page.svelte

Defines a page. Rendered on server (SSR) initially, then client (CSR) for navigation.

```svelte
<!file: src/routes/+page.svelte>
<h1>Hello and welcome to my site!</h1>
<a href="/about">About my site</a>
```

Uses `<a>` elements for navigation, not framework components.

Receives `data` from load functions:

```svelte
<!file: src/routes/blog/[slug]/+page.svelte>
<script>
	/** @type {import('./$types').PageProps} */
	let { data } = $props();
</script>

<h1>{data.title}</h1>
<div>{@html data.content}</div>
```

Also receives `params` prop (2.24+):

```svelte
<!file: src/routes/blog/[slug]/+page.svelte>
<script>
	import { getPost } from '../blog.remote';

	/** @type {import('./$types').PageProps} */
	let { params } = $props();

	const post = $derived(await getPost(params.slug));
</script>

<h1>{post.title}</h1>
<div>{@html post.content}</div>
```

### +page.js

Exports `load` function for data fetching. Runs on server and client.

```js
/// file: src/routes/blog/[slug]/+page.js
import { error } from '@sveltejs/kit';

/** @type {import('./$types').PageLoad} */
export function load({ params }) {
	if (params.slug === 'hello-world') {
		return {
			title: 'Hello world!',
			content: 'Welcome to our blog. Lorem ipsum dolor sit amet...'
		};
	}

	error(404, 'Not found');
}
```

Can export page options: `prerender`, `ssr`, `csr`

### +page.server.js

Server-only load function. Use for database access, private env vars, etc. Change type to `PageServerLoad`.

```js
/// file: src/routes/blog/[slug]/+page.server.js
import { error } from '@sveltejs/kit';

/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
	const post = await getPostFromDatabase(params.slug);

	if (post) {
		return post;
	}

	error(404, 'Not found');
}
```

Return value must be serializable. Can also export actions for form submissions.

## +error

Customizes error page per route:

```svelte
<!file: src/routes/blog/[slug]/+error.svelte>
<script>
	import { page } from '$app/state';
</script>

<h1>{page.status}: {page.error.message}</h1>
```

SvelteKit walks up tree to find closest error boundary. Root fallback is `src/error.html`.

**Note:** Not used for errors in `handle` hook or `+server.js` handlers.

## +layout

### +layout.svelte

Shared UI across pages. Must include `{@render children()}`.

```svelte
<!file: src/routes/+layout.svelte>
<script>
	let { children } = $props();
</script>

<nav>
	<a href="/">Home</a>
	<a href="/about">About</a>
	<a href="/settings">Settings</a>
</nav>

{@render children()}
```

Layouts nest. Child layouts inherit parent layouts.

```svelte
<!file: src/routes/settings/+layout.svelte>
<script>
	/** @type {import('./$types').LayoutProps} */
	let { data, children } = $props();
</script>

<h1>Settings</h1>

<div class="submenu">
	{#each data.sections as section}
		<a href="/settings/{section.slug}">{section.title}</a>
	{/each}
</div>

{@render children()}
```

### +layout.js

Provides data to layout and child pages:

```js
/// file: src/routes/settings/+layout.js
/** @type {import('./$types').LayoutLoad} */
export function load() {
	return {
		sections: [
			{ slug: 'profile', title: 'Profile' },
			{ slug: 'notifications', title: 'Notifications' }
		]
	};
}
```

Can export page options as defaults for children.

### +layout.server.js

Server-only layout load. Change type to `LayoutServerLoad`. Can export page options.

## +server

API routes. Export HTTP verb functions (`GET`, `POST`, etc.) returning `Response`.

```js
/// file: src/routes/api/random-number/+server.js
import { error } from '@sveltejs/kit';

/** @type {import('./$types').RequestHandler} */
export function GET({ url }) {
	const min = Number(url.searchParams.get('min') ?? '0');
	const max = Number(url.searchParams.get('max') ?? '1');

	const d = max - min;

	if (isNaN(d) || d < 0) {
		error(400, 'min and max must be numbers, and min must be less than max');
	}

	const random = min + Math.random() * d;

	return new Response(String(random));
}
```

**Notes:**
- `+layout` files don't affect `+server.js`
- Errors return JSON or fallback HTML, not `+error.svelte`

### Receiving data

```svelte
<!file: src/routes/add/+page.svelte>
<script>
	let a = $state(0);
	let b = $state(0);
	let total = $state(0);

	async function add() {
		const response = await fetch('/api/add', {
			method: 'POST',
			body: JSON.stringify({ a, b }),
			headers: {
				'content-type': 'application/json'
			}
		});

		total = await response.json();
	}
</script>

<input type="number" bind:value={a}> +
<input type="number" bind:value={b}> =
{total}

<button onclick={add}>Calculate</button>
```

```js
/// file: src/routes/api/add/+server.js
import { json } from '@sveltejs/kit';

/** @type {import('./$types').RequestHandler} */
export async function POST({ request }) {
	const { a, b } = await request.json();
	return json(a + b);
}
```

### Fallback method handler

Handles unhandled HTTP methods:

```js
/// file: src/routes/api/add/+server.js
import { json, text } from '@sveltejs/kit';

/** @type {import('./$types').RequestHandler} */
export async function POST({ request }) {
	const { a, b } = await request.json();
	return json(a + b);
}

// This handler will respond to PUT, PATCH, DELETE, etc.
/** @type {import('./$types').RequestHandler} */
export async function fallback({ request }) {
	return text(`I caught your ${request.method} request!`);
}
```

### Content negotiation

`+server.js` can coexist with `+page` files:
- `PUT`/`PATCH`/`DELETE`/`OPTIONS` → always `+server.js`
- `GET`/`POST`/`HEAD` → page if `accept` header prioritizes `text/html`, else `+server.js`
- `GET` responses include `Vary: Accept` header

## $types

SvelteKit generates `$types.d.ts` for type safety.

`PageProps`/`LayoutProps` (2.16.0+) type all props:

```svelte
<!file: src/routes/blog/[slug]/+page.svelte>
<script>
	/** @type {import('./$types').PageProps} */
	let { data } = $props();
</script>
```

Load function types: `PageLoad`, `PageServerLoad`, `LayoutLoad`, `LayoutServerLoad`

IDE tooling can auto-insert types—manual annotation optional.

## Other files

Non-route files in route directories are ignored. Colocate components with routes. Shared modules go in `$lib`.

## docs/kit/20-core-concepts/20-load.md

# Loading data

## Page data

`+page.js` exports a `load` function. Return value available via `data` prop:

```js
/// file: src/routes/blog/[slug]/+page.js
/** @type {import('./$types').PageLoad} */
export function load({ params }) {
	return {
		post: {
			title: `Title for ${params.slug} goes here`,
			content: `Content for ${params.slug} goes here`
		}
	};
}
```

```svelte
<!file: src/routes/blog/[slug]/+page.svelte>
<script>
	/** @type {import('./$types').PageProps} */
	let { data } = $props();
</script>

<h1>{data.post.title}</h1>
<div>{@html data.post.content}</div>
```

`+page.server.js` for server-only `load` (database access, private env vars):

```js
/// file: src/routes/blog/[slug]/+page.server.js
import * as db from '$lib/server/database';

/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
	return {
		post: await db.getPost(params.slug)
	};
}
```

## Layout data

`+layout.js` or `+layout.server.js` loads data for layouts:

```js
/// file: src/routes/blog/[slug]/+layout.server.js
import * as db from '$lib/server/database';

/** @type {import('./$types').LayoutServerLoad} */
export async function load() {
	return {
		posts: await db.getPostSummaries()
	};
}
```

```svelte
<!file: src/routes/blog/[slug]/+layout.svelte>
<script>
	/** @type {import('./$types').LayoutProps} */
	let { data, children } = $props();
</script>

<main>
	{@render children()}
</main>

<aside>
	<h2>More posts</h2>
	<ul>
		{#each data.posts as post}
			<li>
				<a href="/blog/{post.slug}">
					{post.title}
				</a>
			</li>
		{/each}
	</ul>
</aside>
```

Child components access parent layout data. Last key wins if multiple `load` functions return same key.

## page.data

Access page/child data from parent layouts via `page.data`:

```svelte
<!file: src/routes/+layout.svelte>
<script>
	import { page } from '$app/state';
</script>

<svelte:head>
	<title>{page.data.title}</title>
</svelte:head>
```

## Universal vs server

**Server `load`** (`+page.server.js`, `+layout.server.js`):
- Always runs server-side
- Access to `clientAddress`, `cookies`, `locals`, `platform`, `request`
- Must return serializable data (devalue)

**Universal `load`** (`+page.js`, `+layout.js`):
- Runs on server during SSR, then in browser during hydration
- Subsequent runs in browser only
- Can return non-serializable values (classes, components)
- Has `data` property (from server `load` if both exist)

**When to use:**
- Server: database access, private credentials, filesystem
- Universal: external API without credentials, non-serializable returns
- Both: server `load` passes data to universal `load` via `data` property

## Using URL data

### url
`URL` instance with `origin`, `hostname`, `pathname`, `searchParams`. `url.hash` unavailable during `load`.

### route
Current route directory: `route.id` is `/a/[b]/[...c]`

### params
Derived from `url.pathname` and `route.id`:
```json
{
	"b": "x",
	"c": "y/z"
}
```

## Making fetch requests

Provided `fetch` function:
- Inherits `cookie`/`authorization` headers on server
- Allows relative requests on server
- Internal requests go direct to handler (no HTTP overhead)
- Response captured and inlined during SSR
- Response read from HTML during hydration (no extra request)

```js
/// file: src/routes/items/[id]/+page.js
/** @type {import('./$types').PageLoad} */
export async function load({ fetch, params }) {
	const res = await fetch(`/api/items/${params.id}`);
	const item = await res.json();

	return { item };
}
```

## Cookies

Server `load` can get/set cookies:

```js
/// file: src/routes/+layout.server.js
import * as db from '$lib/server/database';

/** @type {import('./$types').LayoutServerLoad} */
export async function load({ cookies }) {
	const sessionid = cookies.get('sessionid');

	return {
		user: await db.getUser(sessionid)
	};
}
```

Cookies passed through `fetch` only if target is same host or more specific subdomain.

## Headers

`setHeaders` sets response headers (server-side only):

```js
/// file: src/routes/products/+page.js
/** @type {import('./$types').PageLoad} */
export async function load({ fetch, setHeaders }) {
	const url = `https://cms.example.com/products.json`;
	const response = await fetch(url);

	setHeaders({
		age: response.headers.get('age'),
		'cache-control': response.headers.get('cache-control')
	});

	return response.json();
}
```

Cannot set same header multiple times. Use `cookies.set()` for `set-cookie`.

## Using parent data

`await parent()` accesses parent `load` data:

```js
/// file: src/routes/+layout.js
/** @type {import('./$types').LayoutLoad} */
export function load() {
	return { a: 1 };
}
```

```js
/// file: src/routes/abc/+layout.js
/** @type {import('./$types').LayoutLoad} */
export async function load({ parent }) {
	const { a } = await parent();
	return { b: a + 1 };
}
```

```js
/// file: src/routes/abc/+page.js
/** @type {import('./$types').PageLoad} */
export async function load({ parent }) {
	const { a, b } = await parent();
	return { c: a + b };
}
```

Avoid waterfalls - call independent operations before `await parent()`.

## Errors

Use `error` helper for expected errors:

```js
/// file: src/routes/admin/+layout.server.js
import { error } from '@sveltejs/kit';

/** @type {import('./$types').LayoutServerLoad} */
export function load({ locals }) {
	if (!locals.user) {
		error(401, 'not logged in');
	}

	if (!locals.user.isAdmin) {
		error(403, 'not an admin');
	}
}
```

Calling `error(...)` throws exception. Unexpected errors treated as 500.

## Redirects

Use `redirect` helper:

```js
/// file: src/routes/user/+layout.server.js
import { redirect } from '@sveltejs/kit';

/** @type {import('./$types').LayoutServerLoad} */
export function load({ locals }) {
	if (!locals.user) {
		redirect(307, '/login');
	}
}
```

Don't use inside `try {...}` blocks. In browser, use `goto` from `$app/navigation`.

## Streaming with promises

Server `load` promises stream to browser as they resolve:

```js
/// file: src/routes/blog/[slug]/+page.server.js
/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
	return {
		comments: loadComments(params.slug), // not awaited
		post: await loadPost(params.slug)
	};
}
```

```svelte
<!file: src/routes/blog/[slug]/+page.svelte>
<script>
	/** @type {import('./$types').PageProps} */
	let { data } = $props();
</script>

<h1>{data.post.title}</h1>
<div>{@html data.post.content}</div>

{#await data.comments}
	Loading comments...
{:then comments}
	{#each comments as comment}
		<p>{comment.content}</p>
	{/each}
{:catch error}
	<p>error loading comments: {error.message}</p>
{/await}
```

Handle rejections to avoid unhandled promise errors. Attach noop-`catch` or use SvelteKit's `fetch`.

**Limitations:**
- No streaming on platforms without support (AWS Lambda, Firebase)
- Can't `setHeaders` or redirect inside streamed promise
- Don't return promises from universal `load` if SSR enabled
- Headers/status can't change after streaming starts

## Parallel loading

All `load` functions run concurrently. Server `load` results grouped into single response.

## Rerunning load functions

`load` reruns when dependencies change:
- Referenced `params` property changes
- Referenced `url` property changes (`pathname`, `search`)
- `url.searchParams.get/getAll/has()` parameter changes
- `await parent()` called and parent reruns
- Dependency marked invalid via `fetch(url)` or `depends(url)` + `invalidate(url)`
- `invalidateAll()` called

### Untracking dependencies

```js
/// file: src/routes/+page.js
/** @type {import('./$types').PageLoad} */
export async function load({ untrack, url }) {
	if (untrack(() => url.pathname === '/')) {
		return { message: 'Welcome!' };
	}
}
```

### Manual invalidation

```js
/// file: src/routes/random-number/+page.js
/** @type {import('./$types').PageLoad} */
export async function load({ fetch, depends }) {
	const response = await fetch('https://api.example.com/random-number');
	depends('app:random');

	return {
		number: await response.json()
	};
}
```

```svelte
<!file: src/routes/random-number/+page.svelte>
<script>
	import { invalidate, invalidateAll } from '$app/navigation';

	/** @type {import('./$types').PageProps} */
	let { data } = $props();

	function rerunLoadFunction() {
		invalidate('app:random');
		invalidate('https://api.example.com/random-number');
		invalidate(url => url.href.includes('random-number'));
		invalidateAll();
	}
</script>

<p>random number: {data.number}</p>
<button onclick={rerunLoadFunction}>Update random number</button>
```

## Auth implications

- Layout `load` doesn't run on every request (e.g., client-side nav)
- Layout and page `load` run concurrently unless `await parent()` called
- If layout `load` throws, page `load` runs but client won't receive data

**Strategies:**
- Use hooks to protect routes before `load` runs
- Put auth guards in `+page.server.js` for route-specific protection
- Avoid auth in `+layout.server.js` unless all children call `await parent()`

## Using getRequestEvent

Access request event in shared logic:

```js
/// file: src/lib/server/auth.js
import { redirect } from '@sveltejs/kit';
import { getRequestEvent } from '$app/server';

export function requireLogin() {
	const { locals, url } = getRequestEvent();

	if (!locals.user) {
		const redirectTo = url.pathname + url.search;
		const params = new URLSearchParams({ redirectTo });

		redirect(307, `/login?${params}`);
	}

	return locals.user;
}
```

```js
/// file: +page.server.js
import { requireLogin } from '$lib/server/auth';

export function load() {
	const user = requireLogin();

	return {
		message: `hello ${user.name}!`
	};
}
```

## docs/kit/20-core-concepts/30-form-actions.md

# Form Actions

A `+page.server.js` file exports _actions_ to `POST` data to the server using `<form>`. Works without JavaScript, can be progressively enhanced.

## Default Actions

```js
/// file: src/routes/login/+page.server.js
export const actions = {
	default: async (event) => {
		// TODO log the user in
	}
};
```

```svelte
<!file: src/routes/login/+page.svelte>
<form method="POST">
	<label>
		Email
		<input name="email" type="email">
	</label>
	<label>
		Password
		<input name="password" type="password">
	</label>
	<button>Log in</button>
</form>
```

**From other pages:** Add `action` attribute pointing to the page:

```html
<form method="POST" action="/login"></form>
```

> Actions always use `POST` requests.

## Named Actions

```js
/// file: src/routes/login/+page.server.js
export const actions = {
	login: async (event) => {
		// TODO log the user in
	},
	register: async (event) => {
		// TODO register the user
	}
};
```

**Invoke with query parameter:**

```svelte
<form method="POST" action="?/register">
```

**Or from other pages:**

```svelte
<form method="POST" action="/login?/register">
```

**Use `formaction` on buttons:**

```svelte
<form method="POST" action="?/login">
	<label>
		Email
		<input name="email" type="email">
	</label>
	<label>
		Password
		<input name="password" type="password">
	</label>
	<button>Log in</button>
	<button formaction="?/register">Register</button>
</form>
```

> Can't have default actions next to named actions - query parameter persists in URL.

## Anatomy of an Action

Actions receive `RequestEvent`, read data with `request.formData()`. Return data available via `form` prop and `page.form`.

```js
/// file: src/routes/login/+page.server.js
import * as db from '$lib/server/db';

export async function load({ cookies }) {
	const user = await db.getUserFromSession(cookies.get('sessionid'));
	return { user };
}

export const actions = {
	login: async ({ cookies, request }) => {
		const data = await request.formData();
		const email = data.get('email');
		const password = data.get('password');

		const user = await db.getUser(email);
		cookies.set('sessionid', await db.createSession(user), { path: '/' });

		return { success: true };
	},
	register: async (event) => {
		// TODO register the user
	}
};
```

```svelte
<!file: src/routes/login/+page.svelte>
<script>
	/** @type {import('./$types').PageProps} */
	let { data, form } = $props();
</script>

{#if form?.success}
	<p>Successfully logged in! Welcome back, {data.user.name}</p>
{/if}
```

### Validation Errors

Use `fail()` to return HTTP status code (400/422) with validation errors:

```js
/// file: src/routes/login/+page.server.js
import { fail } from '@sveltejs/kit';
import * as db from '$lib/server/db';

export const actions = {
	login: async ({ cookies, request }) => {
		const data = await request.formData();
		const email = data.get('email');
		const password = data.get('password');

		if (!email) {
			return fail(400, { email, missing: true });
		}

		const user = await db.getUser(email);

		if (!user || user.password !== db.hash(password)) {
			return fail(400, { email, incorrect: true });
		}

		cookies.set('sessionid', await db.createSession(user), { path: '/' });

		return { success: true };
	},
	register: async (event) => {
		// TODO register the user
	}
};
```

```svelte
/// file: src/routes/login/+page.svelte
<form method="POST" action="?/login">
	{#if form?.missing}<p class="error">The email field is required</p>{/if}
	{#if form?.incorrect}<p class="error">Invalid credentials!</p>{/if}
	<label>
		Email
		<input name="email" type="email" value={form?.email ?? ''}>
	</label>
	<label>
		Password
		<input name="password" type="password">
	</label>
	<button>Log in</button>
	<button formaction="?/register">Register</button>
</form>
```

### Redirects

```js
/// file: src/routes/login/+page.server.js
import { fail, redirect } from '@sveltejs/kit';
import * as db from '$lib/server/db';

export const actions = {
	login: async ({ cookies, request, url }) => {
		const data = await request.formData();
		const email = data.get('email');
		const password = data.get('password');

		const user = await db.getUser(email);
		if (!user) {
			return fail(400, { email, missing: true });
		}

		if (user.password !== db.hash(password)) {
			return fail(400, { email, incorrect: true });
		}

		cookies.set('sessionid', await db.createSession(user), { path: '/' });

		if (url.searchParams.has('redirectTo')) {
			redirect(303, url.searchParams.get('redirectTo'));
		}

		return { success: true };
	},
	register: async (event) => {
		// TODO register the user
	}
};
```

## Loading Data

After action runs, page re-renders with action's return value as `form` prop. Page `load` functions run after action completes.

**Important:** `handle` runs before action and doesn't rerun before `load`. Update `event.locals` in action if needed:

```js
/// file: src/hooks.server.js
export async function handle({ event, resolve }) {
	event.locals.user = await getUser(event.cookies.get('sessionid'));
	return resolve(event);
}
```

```js
/// file: src/routes/account/+page.server.js
export function load(event) {
	return {
		user: event.locals.user
	};
}

export const actions = {
	logout: async (event) => {
		event.cookies.delete('sessionid', { path: '/' });
		event.locals.user = null;
	}
};
```

## Progressive Enhancement

### use:enhance

```svelte
/// file: src/routes/login/+page.svelte
<script>
	import { enhance } from '$app/forms';

	/** @type {import('./$types').PageProps} */
	let { form } = $props();
</script>

<form method="POST" use:enhance>
```

> Only works with `method="POST"` and actions in `+page.server.js`.

**Default behavior:**
- Updates `form`, `page.form`, `page.status` (only if action on same page)
- Resets `<form>` element
- Invalidates all data with `invalidateAll` on success
- Calls `goto` on redirect
- Renders nearest `+error` boundary on error
- Resets focus

### Customising use:enhance

```svelte
<form
	method="POST"
	use:enhance={({ formElement, formData, action, cancel, submitter }) => {
		// `formElement` is this `<form>` element
		// `formData` is its `FormData` object that's about to be submitted
		// `action` is the URL to which the form is posted
		// calling `cancel()` will prevent the submission
		// `submitter` is the `HTMLElement` that caused the form to be submitted

		return async ({ result, update }) => {
			// `result` is an `ActionResult` object
			// `update` is a function which triggers the default logic that would be triggered if this callback wasn't set
		};
	}}
>
```

**Using `applyAction`:**

```svelte
/// file: src/routes/login/+page.svelte
<script>
	import { enhance, applyAction } from '$app/forms';

	/** @type {import('./$types').PageProps} */
	let { form } = $props();
</script>

<form
	method="POST"
	use:enhance={({ formElement, formData, action, cancel }) => {
		return async ({ result }) => {
			if (result.type === 'redirect') {
				goto(result.location);
			} else {
				await applyAction(result);
			}
		};
	}}
>
```

**`applyAction(result)` behavior:**
- `success`, `failure` — sets `page.status`, updates `form` and `page.form`
- `redirect` — calls `goto(result.location, { invalidateAll: true })`
- `error` — renders nearest `+error` boundary

### Custom Event Listener

```svelte
<!file: src/routes/login/+page.svelte>
<script>
	import { invalidateAll, goto } from '$app/navigation';
	import { applyAction, deserialize } from '$app/forms';

	/** @type {import('./$types').PageProps} */
	let { form } = $props();

	/** @param {SubmitEvent & { currentTarget: EventTarget & HTMLFormElement}} event */
	async function handleSubmit(event) {
		event.preventDefault();
		const data = new FormData(event.currentTarget, event.submitter);

		const response = await fetch(event.currentTarget.action, {
			method: 'POST',
			body: data
		});

		/** @type {import('@sveltejs/kit').ActionResult} */
		const result = deserialize(await response.text());

		if (result.type === 'success') {
			// rerun all `load` functions, following the successful update
			await invalidateAll();
		}

		applyAction(result);
	}
</script>

<form method="POST" onsubmit={handleSubmit}>
	
</form>
```

**Must use `deserialize()` not `JSON.parse()`** - supports `Date` and `BigInt`.

**POST to action with `+server.js` present:**

```js
const response = await fetch(this.action, {
	method: 'POST',
	body: data,
	headers: {
		'x-sveltekit-action': 'true'
	}
});
```

## Alternatives

Use `+server.js` for JSON APIs:

```svelte
<!file: src/routes/send-message/+page.svelte>
<script>
	function rerun() {
		fetch('/api/ci', {
			method: 'POST'
		});
	}
</script>

<button onclick={rerun}>Rerun CI</button>
```

```js
/// file: src/routes/api/ci/+server.js
export function POST() {
	// do something
}
```

## GET vs POST

Use `method="GET"` for forms that don't POST data (e.g., search). SvelteKit treats them like `<a>` elements using client-side router:

```html
<form action="/search">
	<label>
		Search
		<input name="q">
	</label>
</form>
```

Navigates to `/search?q=...`, invokes `load` but not action. Supports `data-sveltekit-*` attributes like `<a>` elements.

## docs/kit/20-core-concepts/40-page-options.md

# Page Options

SvelteKit renders components server-side first, sends HTML to client, then hydrates for interactivity. Control this per-page via `+page.js`/`+page.server.js` or per-group via `+layout.js`/`+layout.server.js`. Child layouts/pages override parent values.

## prerender

Generate static HTML at build time.

```js
/// file: +page.js/+page.server.js/+server.js
export const prerender = true;
```

Or set in root layout and opt-out specific pages:

```js
/// file: +page.js/+page.server.js/+server.js
export const prerender = false;
```

Third option excludes from SSR manifest but still prerenders:

```js
/// file: +page.js/+page.server.js/+server.js
export const prerender = 'auto';
```

Prerenderer starts at root, follows `<a>` links to find pages. Configure entry points via `config.kit.prerender.entries` or [`entries`](#entries) function.

### Prerendering server routes

`+server.js` files inherit `prerender` from pages that fetch from them unless explicitly set.

```js
/// file: +page.js
export const prerender = true;

/** @type {import('./$types').PageLoad} */
export async function load({ fetch }) {
	const res = await fetch('/my-server-route.json');
	return await res.json();
}
```

### When not to prerender

**Rule:** Two users hitting a page directly must get identical server content.

- Don't prerender personalized content
- `url.searchParams` forbidden during prerender (use in browser only, e.g. `onMount`)
- Pages with [actions](form-actions) can't be prerendered

### Route conflicts

Avoid directory/file name conflicts. Use file extensions: `foo.json/+server.js` and `foo/bar.json/+server.js` create `foo.json` and `foo/bar.json`. Pages write `foo/index.html`.

### Troubleshooting

Error "routes marked as prerenderable, but were not prerendered" means crawler didn't reach the route.

**Fixes:**
- Add links from `config.kit.prerender.entries` or [`entries`](#entries)
- Ensure links exist on prerendered pages
- Change to `export const prerender = 'auto'`

## entries

Define dynamic route parameters for prerendering:

```js
/// file: src/routes/blog/[slug]/+page.server.js
/** @type {import('./$types').EntryGenerator} */
export function entries() {
	return [
		{ slug: 'hello-world' },
		{ slug: 'another-blog-post' }
	];
}

export const prerender = true;
```

Can be `async` to fetch from CMS/database.

## ssr

Disable server-side rendering:

```js
/// file: +page.js
export const ssr = false;
// If both `ssr` and `csr` are `false`, nothing will be rendered!
```

Renders empty shell instead of full HTML. Not recommended for most cases.

**Note:** If all page options are static values, SvelteKit evaluates them statically. Otherwise, it imports files at build/runtime, so browser-only code must not run on module load.

## csr

Disable client-side rendering (no JavaScript shipped):

```js
/// file: +page.js
export const csr = false;
// If both `csr` and `ssr` are `false`, nothing will be rendered!
```

**Effects:**
- Page must work with HTML/CSS only
- All `<script>` tags removed
- Forms can't be progressively enhanced
- Full-page browser navigation
- HMR disabled

Enable in dev only:

```js
/// file: +page.js
import { dev } from '$app/environment';

export const csr = dev;
```

## trailingSlash

Control URL trailing slashes: `'never'` (default), `'always'`, or `'ignore'`.

```js
/// file: src/routes/+layout.js
export const trailingSlash = 'always';
```

Affects prerendering: `'always'` creates `about/index.html`, otherwise `about.html`.

**Note:** Don't use `'ignore'` — harms SEO and changes relative path semantics.

## config

Adapter-specific deployment configuration:

```js
/// file: src/routes/+page.js
/** @type {import('some-adapter').Config} */
export const config = {
	runtime: 'edge'
};
```

Configs merge at top level only:

```js
/// file: src/routes/+layout.js
export const config = {
	runtime: 'edge',
	regions: 'all',
	foo: { bar: true }
}
```

```js
/// file: src/routes/+page.js
export const config = {
	regions: ['us1', 'us2'],
	foo: { baz: true }
}
```

Result: `{ runtime: 'edge', regions: ['us1', 'us2'], foo: { baz: true } }`

## docs/kit/20-core-concepts/50-state-management.md

# State Management

## Avoid shared state on the server

Servers are shared by multiple users. **Never store data in shared variables.**

```js
// @errors: 7034 7005
/// file: +page.server.js
let user; // ❌ NEVER DO THIS - shared across all users

/** @type {import('./$types').PageServerLoad} */
export function load() {
	return { user };
}

/** @satisfies {import('./$types').Actions} */
export const actions = {
	default: async ({ request }) => {
		const data = await request.formData();

		// NEVER DO THIS!
		user = {
			name: data.get('name'),
			embarrassingSecret: data.get('secret')
		};
	}
}
```

✅ Use [`cookies`](load#Cookies) for authentication and persist to a database.

## No side-effects in load

`load` functions must be **pure** - no side-effects.

```js
/// file: +page.js
// @filename: ambient.d.ts
declare module '$lib/user' {
	export const user: { set: (value: any) => void };
}

// @filename: index.js
//cut
import { user } from '$lib/user';

/** @type {import('./$types').PageLoad} */
export async function load({ fetch }) {
	const response = await fetch('/api/user');

	// NEVER DO THIS!
	user.set(await response.json());
}
```

✅ Return data instead:

```js
/// file: +page.js
/** @type {import('./$types').PageServerLoad} */
export async function load({ fetch }) {
	const response = await fetch('/api/user');

return {
		user: await response.json()
	};
}
```

Pass to components or use [`page.data`](load#page.data).

## Using state with context

Use Svelte's context API for shared state:

```svelte
<!file: src/routes/+layout.svelte>
<script>
	import { setContext } from 'svelte';

	/** @type {import('./$types').LayoutProps} */
	let { data } = $props();

	// Pass a function referencing our state
	// to the context for child components to access
	setContext('user', () => data.user);
</script>
```

```svelte
<!file: src/routes/user/+page.svelte>
<script>
	import { getContext } from 'svelte';

	// Retrieve user store from context
	const user = getContext('user');
</script>

<p>Welcome {user().name}</p>
```

> Pass a function to `setContext` to maintain reactivity. See [$state docs](/docs/svelte/$state#Passing-state-into-functions).

**Gotcha:** Context updates in child components during SSR won't affect already-rendered parents. Prefer passing state down.

Without SSR, you can use shared modules directly.

## Component state is preserved

Components are reused during navigation. State won't reset automatically:

```svelte
<!file: src/routes/blog/[slug]/+page.svelte>
<script>
	/** @type {import('./$types').PageProps} */
	let { data } = $props();

	// THIS CODE IS BUGGY!
	const wordCount = data.content.split(' ').length;
	const estimatedReadingTime = wordCount / 250;
</script>

<header>
	<h1>{data.title}</h1>
	<p>Reading time: {Math.round(estimatedReadingTime)} minutes</p>
</header>

<div>{@html data.content}</div>
```

✅ Use reactive state:

```svelte
/// file: src/routes/blog/[slug]/+page.svelte
<script>
	/** @type {import('./$types').PageProps} */
	let { data } = $props();

let wordCount = $derived(data.content.split(' ').length);
	let estimatedReadingTime = $derived(wordCount / 250);
</script>
```

> Use [afterNavigate]($app-navigation#afterNavigate) / [beforeNavigate]($app-navigation#beforeNavigate) if you need to re-run `onMount`/`onDestroy` logic.

Force remount with `{#key}`:

```svelte
<script>
	import { page } from '$app/state';
</script>

{#key page.url.pathname}
	<BlogPost title={data.title} content={data.title} />
{/key}
```

## Storing state in the URL

For state that should survive reloads/affect SSR (filters, sorting):

- Use URL search params: `?sort=price&order=ascending`
- Access in `load` via `url` parameter
- Access in components via `page.url.searchParams`
- Set via `<a href>`, `<form action>`, or `goto('?key=value')`

## Storing ephemeral state in snapshots

For disposable UI state (accordion open/closed) that should persist across navigation but not reloads, use [snapshots](snapshots) to associate state with history entries.

## docs/kit/20-core-concepts/60-remote-functions.md

# Remote Functions

**Experimental feature** - Enable in `svelte.config.js`:

```js
/// file: svelte.config.js
const config = {
	kit: {
		experimental: {
			remoteFunctions: true
		}
	},
	compilerOptions: {
		experimental: {
			async: true // for await in components
		}
	}
};
```

Remote functions are type-safe client-server communication. They're called anywhere but always run on the server, allowing safe access to server-only modules (env vars, DB clients).

Export from `.remote.js` or `.remote.ts` files. Four types: `query`, `form`, `command`, `prerender`.

## query

Read dynamic data from server:

```js
/// file: src/routes/blog/data.remote.js
import { query } from '$app/server';
import * as db from '$lib/server/database';

export const getPosts = query(async () => {
	const posts = await db.sql`
		SELECT title, slug FROM post ORDER BY published_at DESC
	`;
	return posts;
});
```

Use with `await` in components:

```svelte
<!file: src/routes/blog/+page.svelte>
<script>
	import { getPosts } from './data.remote';
</script>

<ul>
	{#each await getPosts() as { title, slug }}
		<li><a href="/blog/{slug}">{title}</a></li>
	{/each}
</ul>
```

Alternative: use `loading`, `error`, `current` properties:

```svelte
<script>
	const query = getPosts();
</script>

{#if query.error}
	<p>oops!</p>
{:else if query.loading}
	<p>loading...</p>
{:else}
	<ul>
		{#each query.current as { title, slug }}
			<li><a href="/blog/{slug}">{title}</a></li>
		{/each}
	</ul>
{/if}
```

### Query arguments

Validate with Standard Schema (Zod, Valibot):

```js
import * as v from 'valibot';
import { error } from '@sveltejs/kit';
import { query } from '$app/server';

export const getPost = query(v.string(), async (slug) => {
	const [post] = await db.sql`SELECT * FROM post WHERE slug = ${slug}`;
	if (!post) error(404, 'Not found');
	return post;
});
```

```svelte
<script>
	import { getPost } from '../data.remote';
	let { params } = $props();
	const post = $derived(await getPost(params.slug));
</script>

<h1>{post.title}</h1>
```

Arguments and return values serialized with [devalue](https://github.com/sveltejs/devalue).

### Refreshing queries

```svelte
<button onclick={() => getPosts().refresh()}>
	Check for new posts
</button>
```

Queries are cached: `getPosts() === getPosts()`.

## query.batch

Batches requests in same macrotask (solves n+1 problem):

```js
import * as v from 'valibot';
import { query } from '$app/server';

export const getWeather = query.batch(v.string(), async (cityIds) => {
	const weather = await db.sql`
		SELECT * FROM weather WHERE city_id = ANY(${cityIds})
	`;
	const lookup = new Map(weather.map(w => [w.city_id, w]));
	return (cityId) => lookup.get(cityId);
});
```

## form

Write data to server with progressive enhancement:

```js
/// file: src/routes/blog/data.remote.js
import * as v from 'valibot';
import { error, redirect } from '@sveltejs/kit';
import { form } from '$app/server';
import * as auth from '$lib/server/auth';

export const createPost = form(
	v.object({
		title: v.pipe(v.string(), v.nonEmpty()),
		content: v.pipe(v.string(), v.nonEmpty())
	}),
	async ({ title, content }) => {
		const user = await auth.getUser();
		if (!user) error(401, 'Unauthorized');

		const slug = title.toLowerCase().replace(/ /g, '-');
		await db.sql`INSERT INTO post (slug, title, content) VALUES (${slug}, ${title}, ${content})`;
		redirect(303, `/blog/${slug}`);
	}
);
```

```svelte
<!file: src/routes/blog/new/+page.svelte>
<script>
	import { createPost } from '../data.remote';
</script>

<form {...createPost}>
	<label>
		<h2>Title</h2>
		<input {...createPost.fields.title.as('text')} />
	</label>

	<label>
		<h2>Write your post</h2>
		<textarea {...createPost.fields.content.as('text')}></textarea>
	</label>

	<button>Publish!</button>
</form>
```

Works without JS (submits and reloads). With JS, progressively enhanced (no reload).

### Fields

Field types: strings, numbers, booleans, `File` objects. Can be nested in objects/arrays.

```js
const datingProfile = v.object({
	name: v.string(),
	photo: v.file(),
	info: v.object({
		height: v.number(),
		likesDogs: v.optional(v.boolean(), false)
	}),
	attributes: v.array(v.string())
});

export const createProfile = form(datingProfile, (data) => { /* ... */ });
```

```svelte
<form {...createProfile} enctype="multipart/form-data">
	<input {...name.as('text')} /> Name
	<input {...photo.as('file')} /> Photo
	<input {...info.height.as('number')} /> Height (cm)
	<input {...info.likesDogs.as('checkbox')} /> I like dogs
	<input {...attributes[0].as('text')} />
	<button>submit</button>
</form>
```

**Note:** Unchecked checkboxes not in FormData, use `v.optional(v.boolean(), false)`.

**Note:** Generated `name` uses JS object notation. Boolean/number fields prefixed with `b:`/`n:`.

Radio/checkbox groups need value as second arg:

```svelte
{#each operatingSystems as os}
	<label>
		<input {...survey.fields.operatingSystem.as('radio', os)}>
		{os}
	</label>
{/each}
```

Select elements:

```svelte
<select {...survey.fields.operatingSystem.as('select')}>
	{#each operatingSystems as os}
		<option>{os}</option>
	{/each}
</select>

<select {...survey.fields.languages.as('select multiple')}>
	{#each languages as language}
		<option>{language}</option>
	{/each}
</select>
```

### Programmatic validation

Use `invalid` helper for runtime validation:

```js
import { invalid } from '@sveltejs/kit';
import { form } from '$app/server';

export const buyHotcakes = form(
	v.object({
		qty: v.pipe(v.number(), v.minValue(1, 'you must buy at least one hotcake'))
	}),
	async (data, issue) => {
		try {
			await db.buy(data.qty);
		} catch (e) {
			if (e.code === 'OUT_OF_STOCK') {
				invalid(issue.qty(`we don't have enough hotcakes`));
			}
		}
	}
);
```

### Validation

Show issues per field:

```svelte
<form {...createPost}>
	<label>
		<h2>Title</h2>
		{#each createPost.fields.title.issues() as issue}
			<p class="issue">{issue.message}</p>
		{/each}
		<input {...createPost.fields.title.as('text')} />
	</label>
	<button>Publish!</button>
</form>
```

Validate programmatically:

```svelte
<form {...createPost} oninput={() => createPost.validate()}>
```

Validate all inputs: `validate({ includeUntouched: true })`.

Client-side preflight validation:

```svelte
<script>
	import * as v from 'valibot';
	const schema = v.object({
		title: v.pipe(v.string(), v.nonEmpty()),
		content: v.pipe(v.string(), v.nonEmpty())
	});
</script>

<form {...createPost.preflight(schema)}>
```

All issues: `createPost.fields.allIssues()`.

### Getting/setting inputs

Get current value:

```svelte
<div class="preview">
	<h2>{createPost.fields.title.value()}</h2>
</div>
```

Set values:

```svelte
<script>
	createPost.fields.set({
		title: 'My new blog post',
		content: 'Lorem ipsum...'
	});

	// or individually:
	createPost.fields.title.set('My new blog post');
</script>
```

### Handling sensitive data

Prefix with underscore to prevent sending back to user:

```svelte
<input {...register.fields._password.as('password')} />
```

### Single-flight mutations

Refresh specific queries instead of all. Server-side:

```js
export const createPost = form(
	v.object({/* ... */}),
	async (data) => {
		// form logic...
		await getPosts().refresh();
		redirect(303, `/blog/${slug}`);
	}
);

export const updatePost = form(
	v.object({/* ... */}),
	async (data) => {
		const result = externalApi.update(post);
		await getPost(post.id).set(result);
	}
);
```

### Returns and redirects

Return data instead of redirecting:

```js
export const createPost = form(
	v.object({/* ... */}),
	async (data) => {
		// ...
		return { success: true };
	}
);
```

```svelte
{#if createPost.result?.success}
	<p>Successfully published!</p>
{/if}
```

Result is ephemeral (vanishes on resubmit/navigate/reload).

### enhance

Customize submission behavior:

```svelte
<form {...createPost.enhance(async ({ form, data, submit }) => {
	try {
		await submit();
		form.reset();
		showToast('Successfully published!');
	} catch (error) {
		showToast('Oh no! Something went wrong');
	}
})}>
```

Client-driven single-flight mutations:

```ts
await submit().updates(getPosts());
```

Optimistic updates:

```ts
await submit().updates(
	getPosts().withOverride((posts) => [newPost, ...posts])
);
```

### Multiple instances

Isolate repeated forms:

```svelte
{#each await getTodos() as todo}
	{@const modify = modifyTodo.for(todo.id)}
	<form {...modify}>
		<button disabled={!!modify.pending}>save changes</button>
	</form>
{/each}
```

### Multiple submit buttons

```svelte
<form {...loginOrRegister}>
	<input {...loginOrRegister.fields.username.as('text')} />
	<input {...loginOrRegister.fields._password.as('password')} />
	<button {...loginOrRegister.fields.action.as('submit', 'login')}>login</button>
	<button {...loginOrRegister.fields.action.as('submit', 'register')}>register</button>
</form>
```

```js
export const loginOrRegister = form(
	v.object({
		username: v.string(),
		_password: v.string(),
		action: v.picklist(['login', 'register'])
	}),
	async ({ username, _password, action }) => {
		if (action === 'login') {
			// handle login
		} else {
			// handle registration
		}
	}
);
```

## command

Write data from anywhere (not element-specific):

```js
/// file: likes.remote.js
import * as v from 'valibot';
import { query, command } from '$app/server';

export const getLikes = query(v.string(), async (id) => {
	const [row] = await db.sql`SELECT likes FROM item WHERE id = ${id}`;
	return row.likes;
});

export const addLike = command(v.string(), async (id) => {
	await db.sql`UPDATE item SET likes = likes + 1 WHERE id = ${id}`;
});
```

```svelte
<button
	onclick={async () => {
		try {
			await addLike(item.id);
		} catch (error) {
			showToast('Something went wrong!');
		}
	}}
>
	add like
</button>

<p>likes: {await getLikes(item.id)}</p>
```

**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:

```
<IfModule mod_rewrite.c>
	RewriteEngine On
	RewriteBase /
	RewriteRule ^200\.html$ - [L]
	RewriteCond %{REQUEST_FILENAME} !-f
	RewriteCond %{REQUEST_FILENAME} !-d
	RewriteRule . /200.html [L]
</IfModule>
```

## docs/kit/30-advanced/10-advanced-routing.md

# Advanced Routing

## Rest Parameters

Unknown number of segments:

```sh
/[org]/[repo]/tree/[branch]/[...file]
```

Request `/sveltejs/kit/tree/main/documentation/docs/04-advanced-routing.md` gives:

```js
{
	org: 'sveltejs',
	repo: 'kit',
	branch: 'main',
	file: 'documentation/docs/04-advanced-routing.md'
}
```

> `src/routes/a/[...rest]/z/+page.svelte` matches `/a/z`, `/a/b/z`, `/a/b/c/z`, etc. Validate rest parameter values using matchers.

### 404 Pages

Create catch-all route for custom 404s:

```tree
src/routes/
├ marx-brothers/
| ├ [...path]/
│ ├ chico/
│ ├ harpo/
│ ├ groucho/
│ └ +error.svelte
└ +error.svelte
```

```js
/// file: src/routes/marx-brothers/[...path]/+page.js
import { error } from '@sveltejs/kit';

/** @type {import('./$types').PageLoad} */
export function load(event) {
	error(404, 'Not Found');
}
```

> Unhandled 404s appear in `handleError`

## Optional Parameters

`[[lang]]/home` matches both `home` and `en/home`.

> Cannot follow rest parameter: `[...rest]/[[optional]]` is invalid

## Matching

Validate parameters with matchers in `src/params/`:

```js
/// file: src/params/fruit.js
/**
 * @param {string} param
 * @return {param is ('apple' | 'orange')}
 * @satisfies {import('@sveltejs/kit').ParamMatcher}
 */
export function match(param) {
	return param === 'apple' || param === 'orange';
}
```

Use in routes:

```
src/routes/fruits/[page=fruit]
```

> Matchers run on server and browser. `*.test.js` and `*.spec.js` files ignored.

## Sorting

Multiple routes can match same path. Priority (highest to lowest):

1. More specific routes (fewer parameters)
2. Parameters with matchers `[name=type]` over `[name]`
3. `[[optional]]` and `[...rest]` lowest priority (ignored unless final segment)
4. Alphabetical for ties

Example order for `/foo-abc`:

```sh
src/routes/foo-abc/+page.svelte
src/routes/foo-[c]/+page.svelte
src/routes/[[a=x]]/+page.svelte
src/routes/[b]/+page.svelte
src/routes/[...catchall]/+page.svelte
```

## Encoding

Use hex escapes `[x+nn]` for special characters:

- `\` — `[x+5c]`
- `/` — `[x+2f]`
- `:` — `[x+3a]`
- `*` — `[x+2a]`
- `?` — `[x+3f]`
- `"` — `[x+22]`
- `<` — `[x+3c]`
- `>` — `[x+3e]`
- `|` — `[x+7c]`
- `#` — `[x+23]`
- `%` — `[x+25]`
- `[` — `[x+5b]`
- `]` — `[x+5d]`
- `(` — `[x+28]`
- `)` — `[x+29]`

Example: `/smileys/:-)` → `src/routes/smileys/[x+3a]-[x+29]/+page.svelte`

Get hex code: `':'.charCodeAt(0).toString(16); // '3a'`

Unicode escapes `[u+nnnn]` also supported:

```
src/routes/[u+d83e][u+dd2a]/+page.svelte
src/routes/🤪/+page.svelte  // equivalent
```

> Encode `.well-known` as `[x+2e]well-known` for TypeScript compatibility

## Advanced Layouts

### (group)

Parentheses create groups without affecting URLs:

```tree
src/routes/
│ (app)/
│ ├ dashboard/
│ ├ item/
│ └ +layout.svelte
│ (marketing)/
│ ├ about/
│ ├ testimonials/
│ └ +layout.svelte
├ admin/
└ +layout.svelte
```

`+page` can go directly in `(group)`.

### Breaking Out of Layouts

Routes outside groups (like `/admin`) don't inherit group layouts.

### +page@

Break out of layouts per-page with `@segment`:

```tree
src/routes/
├ (app)/
│ ├ item/
│ │ ├ [id]/
│ │ │ ├ embed/
│ │ │ │ └ +page@(app).svelte
│ │ │ └ +layout.svelte
│ │ └ +layout.svelte
│ └ +layout.svelte
└ +layout.svelte
```

Options:
- `+page@[id].svelte` - inherits from `[id]/+layout.svelte`
- `+page@item.svelte` - inherits from `item/+layout.svelte`
- `+page@(app).svelte` - inherits from `(app)/+layout.svelte`
- `+page@.svelte` - inherits from root layout

### +layout@

Layouts can also break out:

```
src/routes/
├ (app)/
│ ├ item/
│ │ ├ [id]/
│ │ │ ├ embed/
│ │ │ │ └ +page.svelte  // uses (app)/item/[id]/+layout.svelte
│ │ │ ├ +layout.svelte  // inherits from (app)/item/+layout@.svelte
│ │ │ └ +page.svelte    // uses (app)/item/+layout@.svelte
│ │ └ +layout@.svelte   // inherits from root layout, skipping (app)/+layout.svelte
│ └ +layout.svelte
└ +layout.svelte
```

### When to Use Layout Groups

Not always necessary. Alternative: reuse components/functions:

```svelte
<!file: src/routes/nested/route/+layout@.svelte>
<script>
	import ReusableLayout from '$lib/ReusableLayout.svelte';
	let { data, children } = $props();
</script>

<ReusableLayout {data}>
	{@render children()}
</ReusableLayout>
```

```js
/// file: src/routes/nested/route/+layout.js
import { reusableLoad } from '$lib/reusable-load-function';

/** @type {import('./$types').PageLoad} */
export function load(event) {
	// Add additional logic here, if needed
	return reusableLoad(event);
}
```

## docs/kit/30-advanced/20-hooks.md

# Hooks

App-wide functions SvelteKit calls in response to specific events.

Three optional files:
- `src/hooks.server.js` — server hooks
- `src/hooks.client.js` — client hooks  
- `src/hooks.js` — universal hooks (both client and server)

Code runs at app startup, useful for initializing database clients.

> Configure location with [`config.kit.files.hooks`](configuration#files)

## Server hooks

### handle

Runs on every server [request](web-standards#Fetch-APIs-Request) (including [prerendering](page-options#prerender)). Receives `event` and `resolve` function. Modify response or bypass SvelteKit.

```js
/// file: src/hooks.server.js
/** @type {import('@sveltejs/kit').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;
}
```

> Static assets and prerendered pages are _not_ handled by SvelteKit.

Default: `({ event, resolve }) => resolve(event)`

Check [`building`]($app-environment#building) to exclude code from prerendering.

#### locals

Add custom data to `event.locals` for handlers and server `load` functions:

```js
/// file: src/hooks.server.js
// @filename: ambient.d.ts
type User = {
	name: string;
}

declare namespace App {
	interface Locals {
		user: User;
	}
}

const getUserInformation: (cookie: string | void) => Promise<User>;

// @filename: index.js
//cut
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
	event.locals.user = await getUserInformation(event.cookies.get('sessionid'));

	const response = await resolve(event);

	// Note that modifying response headers isn't always safe.
	// Response objects can have immutable headers
	// (e.g. Response.redirect() returned from an endpoint).
	// Modifying immutable headers throws a TypeError.
	// In that case, clone the response or avoid creating a
	// response object with immutable headers.
	response.headers.set('x-custom-header', 'potato');

	return response;
}
```

Chain multiple `handle` functions with [`sequence`](@sveltejs-kit-hooks).

#### resolve options

Second parameter to `resolve`:

- `transformPageChunk(opts: { html: string, done: boolean }): MaybePromise<string | undefined>` — transform HTML chunks
- `filterSerializedResponseHeaders(name: string, value: string): boolean` — filter headers in serialized responses (default: none)
- `preload(input: { type: 'js' | 'css' | 'font' | 'asset', path: string }): boolean` — determine preloaded files (default: `js` and `css`). Not called in dev mode.

```js
/// file: src/hooks.server.js
/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
	const response = await resolve(event, {
		transformPageChunk: ({ html }) => html.replace('old', 'new'),
		filterSerializedResponseHeaders: (name) => name.startsWith('x-'),
		preload: ({ type, path }) => type === 'js' || path.includes('/important/')
	});

	return response;
}
```

`resolve(...)` never throws — always returns `Promise<Response>`. Errors elsewhere in `handle` are fatal. Customize error page via `src/error.html`. See [error handling](errors).

### handleFetch

Modify [`event.fetch`](load#Making-fetch-requests) calls on server/during prerendering (in endpoints, `load`, `action`, `handle`, `handleError`, `reroute`).

```js
/// file: src/hooks.server.js
/** @type {import('@sveltejs/kit').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);
}
```

`event.fetch` follows browser credentials model. Same-origin: forwards `cookie`/`authorization` unless `credentials: "omit"`. Cross-origin: includes `cookie` for subdomains.

**Caveat**: Sibling subdomains (`www.my-domain.com` and `api.my-domain.com`) don't share parent domain cookies automatically:

```js
/// file: src/hooks.server.js
// @errors: 2345
/** @type {import('@sveltejs/kit').HandleFetch} */
export async function handleFetch({ event, request, fetch }) {
	if (request.url.startsWith('https://api.my-domain.com/')) {
		request.headers.set('cookie', event.request.headers.get('cookie'));
	}

	return fetch(request);
}
```

### handleValidationError

Called when remote function argument doesn't match [Standard Schema](https://standardschema.dev/). Must return [`App.Error`](types#Error) shape.

```js
/// file: src/hooks.server.js
/** @type {import('@sveltejs/kit').HandleValidationError} */
export function handleValidationError({ issues }) {
	return {
		message: 'No thank you'
	};
}
```

Default: 400 status, 'Bad Request' message. Be careful exposing information — likely malicious requests.

## Shared hooks

Add to both `src/hooks.server.js` _and_ `src/hooks.client.js`:

### handleError

Called on [unexpected errors](errors#Unexpected-errors) during loading/rendering/endpoints. Receives `error`, `event`, `status`, `message`.

Use to:
- Log errors
- Generate safe error representation (becomes `$page.error`)

Default return: `{ message }`. Status is 500, message is "Internal Error" for code errors.

Customize via `App.Error` interface:

```ts
/// file: src/app.d.ts
declare global {
	namespace App {
		interface Error {
			message: string;
			errorId: string;
		}
	}
}

export {};
```

```js
/// file: src/hooks.server.js
// @errors: 2322 2353
// @filename: ambient.d.ts
declare module '@sentry/sveltekit' {
	export const init: (opts: any) => void;
	export const captureException: (error: any, opts: any) => void;
}

// @filename: index.js
//cut
import * as Sentry from '@sentry/sveltekit';

Sentry.init({/*...*/})

/** @type {import('@sveltejs/kit').HandleServerError} */
export async function handleError({ error, event, status, message }) {
	const errorId = crypto.randomUUID();

	// example integration with https://sentry.io/
	Sentry.captureException(error, {
		extra: { event, errorId, status }
	});

	return {
		message: 'Whoops!',
		errorId
	};
}
```

```js
/// file: src/hooks.client.js
// @errors: 2322 2353
// @filename: ambient.d.ts
declare module '@sentry/sveltekit' {
	export const init: (opts: any) => void;
	export const captureException: (error: any, opts: any) => void;
}

// @filename: index.js
//cut
import * as Sentry from '@sentry/sveltekit';

Sentry.init({/*...*/})

/** @type {import('@sveltejs/kit').HandleClientError} */
export async function handleError({ error, event, status, message }) {
	const errorId = crypto.randomUUID();

	// example integration with https://sentry.io/
	Sentry.captureException(error, {
		extra: { event, errorId, status }
	});

	return {
		message: 'Whoops!',
		errorId
	};
}
```

> Client: type is `HandleClientError`, `event` is `NavigationEvent` not `RequestEvent`.

Not called for expected errors ([`error`](@sveltejs-kit#error) function).

Dev: Svelte syntax errors include `frame` property.

> `handleError` must never throw.

### init

Runs once at server creation or browser app start. For async work like database connections.

```js
// @errors: 2307
/// file: src/hooks.server.js
import * as db from '$lib/server/database';

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

> Browser: async work in `init` delays hydration.

## Universal hooks

Add to `src/hooks.js`. Runs on both server and client.

### reroute

Runs before `handle`. Changes URL-to-route translation. Returned pathname selects route and parameters.

```js
// @errors: 2345 2304
/// file: src/hooks.js

/** @type {Record<string, string>} */
const translated = {
	'/en/about': '/en/about',
	'/de/ueber-uns': '/de/about',
	'/fr/a-propos': '/fr/about',
};

/** @type {import('@sveltejs/kit').Reroute} */
export function reroute({ url }) {
	if (url.pathname in translated) {
		return translated[url.pathname];
	}
}
```

Doesn't change browser address bar or `event.url`.

Since 2.18: can be async. Use `fetch` argument (same benefits as `load` fetch, but `params`/`id` unavailable to `handleFetch`).

```js
// @errors: 2345 2304
/// file: src/hooks.js

/** @type {import('@sveltejs/kit').Reroute} */
export async function reroute({ url, fetch }) {
	// Ask a special endpoint within your app about the destination
	if (url.pathname === '/api/reroute') return;

	const api = new URL('/api/reroute', url);
	api.searchParams.set('pathname', url.pathname);

	const result = await fetch(api).then(r => r.json());
	return result.pathname;
}
```

> `reroute` is pure/idempotent. SvelteKit caches results on client (called once per unique URL).

### transport

Transporters for passing custom types across server/client boundary (from `load`/form actions). Each has `encode` (server) and `decode` (client):

```js
// @errors: 2307
/// file: src/hooks.js
import { Vector } from '$lib/math';

/** @type {import('@sveltejs/kit').Transport} */
export const transport = {
	Vector: {
		encode: (value) => value instanceof Vector && [value.x, value.y],
		decode: ([x, y]) => new Vector(x, y)
	}
};
```

## docs/kit/30-advanced/25-errors.md

# Errors

SvelteKit distinguishes between **expected** and **unexpected** errors, both represented as `{ message: string }` objects by default.

## Expected Errors

Created with `error()` helper from `@sveltejs/kit`:

```js
/// file: src/routes/blog/[slug]/+page.server.js
import { error } from '@sveltejs/kit';
import * as db from '$lib/server/database';

/** @type {import('./$types').PageServerLoad} */
export async function load({ params }) {
	const post = await db.getPost(params.slug);

	if (!post) {
		error(404, {
			message: 'Not found'
		});
	}

	return { post };
}
```

Sets response status and renders nearest `+error.svelte` component where `page.error` is the error object:

```svelte
<!file: src/routes/+error.svelte>
<script>
	import { page } from '$app/state';
</script>

<h1>{page.error.message}</h1>
```

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

```html
<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<title>%sveltekit.error.message%</title>
	</head>
	<body>
		<h1>My custom error page</h1>
		<p>Status: %sveltekit.status%</p>
		<p>Message: %sveltekit.error.message%</p>
	</body>
</html>
```

## 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 `<a>` elements for navigation. Customize behavior with `data-sveltekit-*` attributes on links or parent elements.

Also applies to `<form method="GET">`.

## data-sveltekit-preload-data

Preload page data before click by detecting hover/touch events.

**Values:**
- `"hover"` - preload on mouse hover (desktop) or `touchstart` (mobile)
- `"tap"` - preload on `touchstart` or `mousedown` only

**Default template:**
```html
<body data-sveltekit-preload-data="hover">
	<div style="display: contents">%sveltekit.body%</div>
</body>
```

**Example:**
```html
<a data-sveltekit-preload-data="tap" href="/stonks">
	Get current stonk values
</a>
```

> Ignored if `navigator.connection.saveData` is `true`.

## data-sveltekit-preload-code

Preload route code without data.

**Values (decreasing eagerness):**
- `"eager"` - preload immediately
- `"viewport"` - preload when link enters viewport
- `"hover"` - preload on hover (code only)
- `"tap"` - preload on tap (code only)

> `viewport` and `eager` only apply to links present immediately after navigation.
> Only effective if more eager than `data-sveltekit-preload-data`.
> Ignored if user has reduced data usage.

## data-sveltekit-reload

Force full-page navigation (browser handles link).

```html
<a data-sveltekit-reload href="/path">Path</a>
```

> Links with `rel="external"` get same treatment and are ignored during prerendering.

## data-sveltekit-replacestate

Replace history entry instead of creating new one.

```html
<a data-sveltekit-replacestate href="/path">Path</a>
```

## data-sveltekit-keepfocus

Prevent focus reset after navigation.

```html
<form data-sveltekit-keepfocus>
	<input type="text" name="query">
</form>
```

> Avoid on links. Only use on elements that persist after navigation.

## data-sveltekit-noscroll

Prevent scroll to top (0,0) after navigation.

```html
<a href="path" data-sveltekit-noscroll>Path</a>
```

## Disabling options

Use `"false"` to disable inherited attributes:

```html
<div data-sveltekit-preload-data>
	
	<a href="/a">a</a>
	<a href="/b">b</a>
	<a href="/c">c</a>

	<div data-sveltekit-preload-data="false">
		
		<a href="/d">d</a>
		<a href="/e">e</a>
		<a href="/f">f</a>
	</div>
</div>
```

**Conditional:**
```svelte
<div data-sveltekit-preload-data={condition ? 'hover' : false}>
```

## 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
/// <reference no-default-lib="true"/>
/// <reference lib="esnext" />
/// <reference lib="webworker" />
/// <reference types="@sveltejs/kit" />
/// <reference types="../.svelte-kit/ambient.d.ts" />

import { build, files, version } from '$service-worker';

const self = /** @type {ServiceWorkerGlobalScope} */ (/** @type {unknown} */ (globalThis.self));

const CACHE = `cache-${version}`;

const ASSETS = [
	...build, // the app itself
	...files  // everything in `static`
];

self.addEventListener('install', (event) => {
	async function addFilesToCache() {
		const cache = await caches.open(CACHE);
		await cache.addAll(ASSETS);
	}

	event.waitUntil(addFilesToCache());
});

self.addEventListener('activate', (event) => {
	async function deleteOldCaches() {
		for (const key of await caches.keys()) {
			if (key !== CACHE) await caches.delete(key);
		}
	}

	event.waitUntil(deleteOldCaches());
});

self.addEventListener('fetch', (event) => {
	if (event.request.method !== 'GET') return;

	async function respond() {
		const url = new URL(event.request.url);
		const cache = await caches.open(CACHE);

		// `build`/`files` can always be served from the cache
		if (ASSETS.includes(url.pathname)) {
			const response = await cache.match(url.pathname);

			if (response) {
				return response;
			}
		}

		// for everything else, try the network first, but
		// fall back to the cache if we're offline
		try {
			const response = await fetch(event.request);

			if (!(response instanceof Response)) {
				throw new Error('invalid response from fetch');
			}

			if (response.status === 200) {
				cache.put(event.request, response.clone());
			}

			return response;
		} catch (err) {
			const response = await cache.match(event.request);

			if (response) {
				return response;
			}

			throw err;
		}
	}

	event.respondWith(respond());
});
```

**Gotchas:**
- Stale data may be worse than no data
- Browsers empty caches when full - avoid caching large assets (videos)

## Development

Service worker bundled for production only. Dev requires browsers supporting [modules in service workers](https://web.dev/es-modules-in-sw).

Manual registration in dev needs `{ type: 'module' }`:

```js
import { dev } from '$app/environment';

navigator.serviceWorker.register('/service-worker.js', {
	type: dev ? 'module' : 'classic'
});
```

**Note:** `build` and `prerendered` are empty arrays in dev.

## Alternatives

- [Workbox](https://web.dev/learn/pwa/workbox) - industry standard PWA library
- [Vite PWA plugin](https://vite-pwa-org.netlify.app/frameworks/sveltekit.html) - Workbox integration for SvelteKit

## docs/kit/30-advanced/50-server-only-modules.md

# Server-only modules

SvelteKit prevents accidental import of sensitive server code into client-side bundles.

## Private environment variables

`$env/static/private` and `$env/dynamic/private` can only be imported in server modules like `hooks.server.js` or `+page.server.js`.

## Server-only utilities

`$app/server` module (contains `read()` for filesystem access) only works on server.

## Your modules

Make modules server-only by:
- Adding `.server` to filename: `secrets.server.js`
- Placing in `$lib/server`: `$lib/server/secrets.js`

## How it works

Importing server-only code in public-facing code causes build error:

```js
/// file: $lib/server/secrets.js
export const atlantisCoordinates = [/* redacted */];
```

```js
/// file: src/routes/utils.js
export { atlantisCoordinates } from '$lib/server/secrets.js';
export const add = (a, b) => a + b;
```

```html
/// file: src/routes/+page.svelte
<script>
	import { add } from './utils.js';
</script>
```

**Error:**
```
Cannot import $lib/server/secrets.ts into code that runs in the browser

 src/routes/+page.svelte imports
  src/routes/utils.js imports
   $lib/server/secrets.ts

If you're only using the import as a type, change it to `import type`.
```

Even though only `add` is used, the entire import chain is blocked to prevent leaking `atlantisCoordinates`.

Works with dynamic imports including interpolated ones: `` await import(`./${foo}.js`) ``

> **Note:** Detection disabled when `process.env.TEST === 'true'` (for Vitest, etc.)

## docs/kit/30-advanced/65-snapshots.md

# Snapshots

Preserves ephemeral DOM state (scroll positions, input values, etc.) across navigation.

## Usage

Export `snapshot` object with `capture` and `restore` methods from `+page.svelte` or `+layout.svelte`:

```svelte
<!file: +page.svelte>
<script>
	let comment = $state('');

	/** @type {import('./$types').Snapshot<string>} */
	export const snapshot = {
		capture: () => comment,
		restore: (value) => comment = value
	};
</script>

<form method="POST">
	<label for="comment">Comment</label>
	<textarea id="comment" bind:value={comment} />
	<button>Post comment</button>
</form>
```

- `capture`: Called before page updates, returns value stored in browser history
- `restore`: Called when navigating back, receives stored value

## Constraints

- Data must be JSON serializable (persisted to `sessionStorage`)
- Avoid large objects (retained in memory for session duration)

## docs/kit/30-advanced/67-shallow-routing.md

# Shallow routing

Create history entries without navigation. Useful for modals that users can dismiss by navigating back.

## Basic usage

Use `pushState` and `replaceState` to associate state with history entries:

```svelte
<!file: +page.svelte>
<script>
	import { pushState } from '$app/navigation';
	import { page } from '$app/state';
	import Modal from './Modal.svelte';

	function showModal() {
		pushState('', {
			showModal: true
		});
	}
</script>

{#if page.state.showModal}
	<Modal close={() => 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
<!file: src/routes/photos/+page.svelte>
<script>
	import { preloadData, pushState, goto } from '$app/navigation';
	import { page } from '$app/state';
	import Modal from './Modal.svelte';
	import PhotoPage from './[id]/+page.svelte';

	let { data } = $props();
</script>

{#each data.thumbnails as thumbnail}
	<a
		href="/photos/{thumbnail.id}"
		onclick={async (e) => {
			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);
			}
		}}
	>
		<img alt={thumbnail.alt} src={thumbnail.src} />
	</a>
{/each}

{#if page.state.selected}
	<Modal onclose={() => history.back()}>
		
		<PhotoPage data={page.state.selected} />
	</Modal>
{/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
<script>
	import logo from '$lib/assets/logo.png';
</script>

<img alt="The project logo" src={logo} />
```

## @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
<enhanced:img src="./path/to/your/image.jpg" alt="An alt text" />
```

Becomes `<img>` wrapped in `<picture>` with multiple formats/sizes. Provide 2x resolution for HiDPI; smaller versions auto-generated.

> CSS selector: use `enhanced\:img` to escape colon.

### Dynamic Images

```svelte
<script>
	import MyImage from './path/to/your/image.jpg?enhanced';
</script>

<enhanced:img src={MyImage} alt="some alt text" />
```

With `import.meta.glob`:

```svelte
<script>
	const imageModules = import.meta.glob(
		'/path/to/assets/*.{avif,gif,heif,jpeg,jpg,png,tiff,webp}',
		{
			eager: true,
			query: {
				enhanced: true
			}
		}
	)
</script>

{#each Object.entries(imageModules) as [_path, module]}
	<enhanced:img src={module.default} alt="some alt text" />
{/each}
```

> SVG only supported statically.

### Intrinsic Dimensions

`width`/`height` auto-inferred and added. Browser reserves space, prevents layout shift. Override with CSS:

```svelte
<style>
	.hero-image img {
		width: var(--size);
		height: auto;
	}
</style>
```

### `srcset` and `sizes`

For large images, specify `sizes` for responsive loading:

```svelte
<enhanced:img src="./image.png" sizes="min(1280px, 100vw)"/>
```

Auto-generates images ≥540px. Custom widths via `w` param:

```svelte
<enhanced:img
  src="./image.png?w=1280;640;400"
  sizes="(min-width:1920px) 1280px, (min-width:1080px) 640px, (min-width:768px) 400px"
/>
```

Without `sizes`: generates 2x and 1x for HiDPI/standard displays.

### Per-image Transforms

Apply transforms via query string:

```svelte
<enhanced:img src="./path/to/your/image.jpg?blur=15" alt="An alt text" />
```

[Full directive list](https://github.com/JonasKruckenberg/imagetools/blob/main/docs/directives.md).

## Loading from CDN

For images not available at build time (CMS, backend). CDNs optimize dynamically, more flexible, but may have setup costs and caching delays.

Use CDN-agnostic [`@unpic/svelte`](https://unpic.pics/img/svelte/), CDN-specific libs ([Cloudinary](https://svelte.cloudinary.dev/)), or CMS built-ins (Contentful, Storyblok, Contentstack).

## Best Practices

- **Mix solutions**: Vite for `<meta>` tags, `enhanced-img` for homepage, CDN for user content.
- **Use CDN**: Reduces latency via global distribution.
- **2x resolution**: Originals should be 2x display width for HiDPI.
- **`sizes` for large images**: Images >400px (hero images) need `sizes` for mobile optimization.
- **LCP images**: Set `fetchpriority="high"`, avoid `loading="lazy"`.
- **Prevent layout shift**: `width`/`height` reserve space (auto-added by `enhanced-img`).
- **`alt` text**: Always provide (compiler warns if missing).
- **Avoid `em`/`rem` in `sizes`**: Don't change default font-size (e.g., `html { font-size: 62.5%; }`). In `sizes`/`@media`, `em`/`rem` = user's default font-size, causing mismatch with CSS layout.

## docs/kit/40-best-practices/20-seo.md

# SEO

## Out of the box

### SSR
SvelteKit uses SSR by default. Keep it enabled - search engines index SSR content more reliably. Only disable in [`handle`](hooks#Server-hooks-handle) if necessary.

### Performance
[Core Web Vitals](https://web.dev/vitals/#core-web-vitals) impact rankings. Use [hybrid rendering](glossary#Hybrid-app), [optimize images](images), and test with [PageSpeed Insights](https://pagespeed.web.dev/). See [performance page](performance).

### Normalized URLs
SvelteKit auto-redirects trailing slashes based on [`trailingSlash`](page-options#trailingSlash) config to avoid duplicate URLs.

## Manual setup

### &lt;title&gt; and &lt;meta&gt;
Every page needs unique `<title>` 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>