--- 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 | [`${CLAUDE_SKILL_DIR}/references/runes.md`] | `$state`, `$derived`, `$effect`, `$props`, `$bindable` details | | Components | [`${CLAUDE_SKILL_DIR}/references/components.md`] | Snippets, events, context, special elements | | SvelteKit | [`${CLAUDE_SKILL_DIR}/references/sveltekit.md`] | Routing, load functions, form actions, hooks, imports | ## Runes ### `$state` - Every mutable reactive value must use `$state` or `$state.raw`. Plain `let` declarations are not reactive. - Arrays and plain objects become deeply reactive proxies. Mutations trigger granular updates. - Destructuring `$state` objects breaks reactivity -- destructured values are snapshots, not live references. - 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. - `$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. - `$state.snapshot(value)` takes a static copy of a reactive proxy for external APIs that don't expect proxies (e.g., `structuredClone`, logging). - 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` - Use `$derived` for all computed values -- never synchronize state with `$effect`. - `$derived.by(() => { ... })` for complex derivations needing a function body. - Only synchronously read values are tracked. Use `untrack` to exempt specific reads. - Derived values can be temporarily overridden (useful for optimistic UI) -- reverts to derived computation on next dependency update. - Destructured `$derived` values are individually reactive. - 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` - `$effect` is an escape hatch. Use only for side effects: DOM manipulation, analytics, third-party library calls, timers. - Return a cleanup function when acquiring resources (intervals, listeners). - Only synchronously read values are tracked -- values read after `await` or inside `setTimeout` are NOT tracked. - Conditional reads: only values read in the last execution are dependencies. - Runs only in the browser, after DOM updates. - `$effect.pre` runs before DOM updates -- use for pre-DOM manipulation like autoscrolling. - `$effect.tracking()` returns `true` if code is running inside a tracking context. - `$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` - Always destructure props: `let { name, count = 0 } = $props()`. - Type with an interface in TypeScript: `let { name }: Props = $props()`. - Renaming: `let { class: klass } = $props()`. - Rest props: `let { a, b, ...rest } = $props()`. - All props: `let props = $props()`. - Unique ID: `$props.id()` -- consistent across SSR/hydration. - Props can be temporarily overridden by child. Do NOT mutate prop objects unless `$bindable`. Use callback props to communicate changes upward. ### `$bindable` - Marks a prop as two-way bindable: `let { value = $bindable() } = $props()`. - Parent optionally uses `bind:value={variable}`. - Use sparingly -- overuse makes data flow unpredictable. Prefer callback props for most parent-child communication. ### `$inspect` - Development-only debugging rune. Re-runs when arguments change. Noop in production. - `$inspect(count, message)` logs when tracked values change. - `$inspect(value).with((type, ...args) => { ... })` replaces default `console.log` with custom callback. Type is `"init"` or `"update"`. - `$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 (`