Canonical rules for writing Svelte 5 components using runes. Every execution-agent MUST use runes (`$state`, `$derived`, `$effect`, `$props`, `$bindable`, `$inspect`, `$effect.root`) as compiler keywords, not runtime function calls. Legacy Svelte 4 patterns (`export let`, `$:` reactive statements, `on:event` directives, ``, `createEventDispatcher`) are forbidden in new code.
**Base axiom:** runes are compile-time signals — the `$` prefix tells the Svelte compiler how to wire reactivity. They are not imports, not callable values, not React hooks. The component file is the only place a reading agent can recover this reactivity contract — so the file MUST stay self-describing: explicit runes, intent-named handlers, machine-friendly comments.
Scope: `.svelte`, `.svelte.js`, `.svelte.ts` files (compiler-aware). Out of scope: plain `.ts` modules (runes do not work there).
- ai/directives/coding/typescript-rules.xml
Runes are compiler directives prefixed with `$`, not runtime functions. They are never imported from any module, never assigned to variables, never passed as values. Reading `$state` / `$derived` / `$effect` as «function call» mental model leads to React-hook habits (dependency arrays, memoization wrappers) — none of which apply here.
Agent treating a rune as a value (`const s = $state; s(0)`) produces code that compiles to nothing useful and silently breaks reactivity.
Runes appear ONLY inside Svelte compiler context: `.svelte` files, or `.svelte.js` / `.svelte.ts` modules. Using a rune in a plain `.ts` file produces a compile error; the rune does NOT silently degrade to a function call.
Cross-file shared reactive state belongs in a `.svelte.ts` module exporting runes-backed values, or in classic stores. Mixing the two for the same value is forbidden.
Local component state uses `$state` / `$derived` / `$effect`. Classic stores (`writable`, `readable`, `derived` from `svelte/store`) remain available for cross-component shared state but MUST NOT be used as a substitute for local state when a rune suffices. A store introduces a subscription lifecycle that local runes do not need.
The `$store` auto-subscription syntax in templates is unchanged from Svelte 4 and remains supported.
`$derived(expression)` and `$derived.by(() => ...)` MUST be pure: no side effects, no I/O, no logging, no mutation of other reactive state. Side effects belong in `$effect`. A `$derived` that mutates is a hidden cycle waiting to fire on every dependency change.
`$effect(() => { ... })` runs after DOM updates; return a teardown function from the body when the effect allocates a resource (timer, subscription, listener, observer) — Svelte runs the teardown before the next run and on component destroy.
For effects outside a component context, use `$effect.root(() => { ... })` and dispose of its returned cleanup function explicitly. Forgetting the teardown function inside an effect that allocates is the classic source of leaked listeners and timers.
Component props come from a SINGLE `$props()` destructuring call at the top of the script: `let { foo, bar = defaultValue, onSomething } = $props()`. Defaults inline in the destructuring. Optional callbacks declared as props, not via `createEventDispatcher`.
Multiple `$props()` calls in one component are forbidden — there is one props surface per component.
Two-way bindable props are declared via `$bindable(initialValue)` inside the `$props()` destructuring (`let { value = $bindable('') } = $props()`). The parent then writes `bind:value={...}`. Without `$bindable` a prop is one-way and the parent cannot `bind:`.
Reusable template fragments use `{#snippet name(params)}...{/snippet}` and are invoked via `{@render name(params)}`. The Svelte 4 `` mechanism, `$$slots`, and slot props are forbidden in new components — they are removed concepts in the Svelte 5 mental model.
DOM event handlers are written as attributes (`onclick={handler}`, `oninput={handler}`), NOT as `on:event` directives. Custom component events are passed as callback props (`onConfirm={...}`), NOT through `createEventDispatcher`.
`on:event` directives, `dispatch(...)`, and `createEventDispatcher` are forbidden — they belonged to the Svelte 4 event model.
A Svelte 5 component file has a fixed structure: an optional `
```
One `$props()` destructure with defaults; `$state` for the mutable value; `$derived` pure; `$effect` mediates the outgoing side-channel; attribute `onclick`, not `on:click`.Two-way bindable prop for a form input.
```svelte
```
`$bindable` only inside `$props()` destructure; parent can now use ``.Reusable template fragment via `{#snippet}` and `{@render}` — the Svelte 5 replacement for slots.
```svelte
{#snippet card(title, body)}
{title}
{body}
{/snippet}
{@render card('Hello', 'World')}
```
Snippets are reactive and re-render when arguments change. No ``, no `$$slots`.`$effect` allocating a resource MUST return a teardown.
```svelte
```
Return value is the teardown — runs before next effect invocation and on destroy. Forgetting it leaks the interval.`export let userId: string; export let onConfirm: () => void;` at the top of a `