--- name: svelte description: >- Svelte runes-first reactivity and SvelteKit fullstack conventions. Invoke whenever task involves any interaction with Svelte code — writing, reviewing, refactoring, debugging, or understanding .svelte, .svelte.js, .svelte.ts files and SvelteKit projects. --- # Svelte **Reactivity is explicit, compiler-driven, and minimal-runtime.** Every reactive declaration uses a `$` rune. The compiler transforms declarative code into surgical DOM updates -- no virtual DOM, no diffing, no hidden magic. References contain extended examples, rationale, and edge cases for each topic. ## References | Topic | Reference | Contents | |-------|-----------|----------| | Runes | `references/runes.md` | `$state`, `$derived`, `$effect`, `$props`, `$bindable` details | | Components | `references/components.md` | Snippets, events, context, special elements | | SvelteKit | `references/sveltekit.md` | Route files, load functions, form actions, hooks, full key imports table | ## Runes ### `$state` 1. Every mutable reactive value must use `$state` or `$state.raw`. Plain `let` declarations are not reactive. 2. Arrays and plain objects become deeply reactive proxies. Mutations trigger granular updates. 3. Destructuring `$state` objects breaks reactivity -- destructured values are snapshots, not live references. 4. Use `$state` on class fields or as first assignment in constructor. The compiler transforms these into getter/setter pairs. Use arrow functions to preserve `this` in event handlers on classes. 5. `$state.raw` opts out of deep reactivity -- state can only be reassigned, not mutated. Use for large arrays/objects you replace wholesale to avoid proxy overhead. 6. `$state.snapshot(value)` takes a static copy of a reactive proxy for external APIs that don't expect proxies (e.g., `structuredClone`, logging). 7. Import reactive `Set`, `Map`, `Date`, `URL` from `svelte/reactivity` when you need reactive built-in types. ### Sharing State Across Modules Cannot directly export reassignable `$state`. Two patterns: - **Object property (preferred):** export `$state({ count: 0 })` as a const, mutate properties, export modifier functions. - **Getter function:** keep `$state` private, export `getCount()` and `increment()`. Runes only work in `.svelte` and `.svelte.js`/`.svelte.ts` files. ### `$derived` 1. Use `$derived` for all computed values -- never synchronize state with `$effect`. 2. `$derived.by(() => { ... })` for complex derivations needing a function body. 3. Only synchronously read values are tracked. Use `untrack` to exempt specific reads. 4. Derived values can be temporarily overridden (useful for optimistic UI) -- reverts to derived computation on next dependency update. 5. Destructured `$derived` values are individually reactive. 6. Push-pull reactivity: dependents are notified immediately (push) but only recalculated on read (pull). If new value is referentially identical, downstream updates are skipped. ### `$effect` 1. `$effect` is an escape hatch. Use only for side effects: DOM manipulation, analytics, third-party library calls, timers. 2. Return a cleanup function when acquiring resources (intervals, listeners). 3. Only synchronously read values are tracked -- values read after `await` or inside `setTimeout` are NOT tracked. 4. Conditional reads: only values read in the last execution are dependencies. 5. Runs only in the browser, after DOM updates. 6. `$effect.pre` runs before DOM updates -- use for pre-DOM manipulation like autoscrolling. 7. `$effect.tracking()` returns `true` if code is running inside a tracking context. 8. `$effect.root(() => { ... })` creates a non-tracked scope for manual effect lifecycle control. Returns a destroy function. **Never use `$effect` to synchronize state** -- use `$derived` with callback event handlers or function bindings instead. ### `$props` 1. Always destructure props: `let { name, count = 0 } = $props()`. 2. Type with an interface in TypeScript: `let { name }: Props = $props()`. 3. Renaming: `let { class: klass } = $props()`. 4. Rest props: `let { a, b, ...rest } = $props()`. 5. All props: `let props = $props()`. 6. Unique ID: `$props.id()` -- consistent across SSR/hydration. 7. Props can be temporarily overridden by child. Do NOT mutate prop objects unless `$bindable`. Use callback props to communicate changes upward. ### `$bindable` 1. Marks a prop as two-way bindable: `let { value = $bindable() } = $props()`. 2. Parent optionally uses `bind:value={variable}`. 3. Use sparingly -- overuse makes data flow unpredictable. Prefer callback props for most parent-child communication. ### `$inspect` 1. Development-only debugging rune. Re-runs when arguments change. Noop in production. 2. `$inspect(count, message)` logs when tracked values change. 3. `$inspect(value).with((type, ...args) => { ... })` replaces default `console.log` with custom callback. Type is `"init"` or `"update"`. 4. `$inspect.trace()` traces which reactive state caused a re-execution. Must be first statement in a function body. ### `$host` Only available inside custom elements. Provides access to the host element for dispatching custom events. ## Components ### Structure Order 1. Imports 2. Props (`$props()`) 3. State (`$state`) 4. Derived values (`$derived`) 5. Effects (`$effect`, sparingly) 6. Functions 7. Markup (template) 8. Styles (`