/web-framework-svelte

name: web-framework-svelte
description: Svelte 5 Runes reactivity - $state, $derived, $effect, $props, $bindable, components, snippets, event handling, context API

Svelte 5 Patterns

> **Quick Guide:** Svelte 5 uses Runes for explicit reactivity. Use `$state` for reactive variables, `$derived` for computed values, `$effect` only as an escape hatch. Use snippets instead of slots. Use callback props instead of event dispatchers. Keep components small and composable.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use Svelte 5 Runes syntax — NOT Svelte 4 patterns like `export let`, `$:`, or stores for component state)**

**(You MUST use `$derived` for computed values — NEVER use `$effect` to synchronize state)**

**(You MUST use snippets (`{#snippet}` / `{@render}`) instead of slots (`<slot>`))**

**(You MUST use callback props (`onclick`, `onsomething`) instead of `createEventDispatcher`)**

**(You MUST use `$state.raw()` for large objects/arrays that are replaced, not mutated)**

**(You MUST use `createContext` for type-safe context instead of raw `setContext`/`getContext` with string keys)**

</critical_requirements>

---

**Auto-detection:** Svelte 5, Runes, $state, $derived, $effect, $props, $bindable, $inspect, .svelte, snippet, @render, createContext, getContext, setContext, $state.raw, $state.eager, $derived.by, $effect.pre, ClassValue

**When to use:**

• Building Svelte 5 components with Runes reactivity
• Managing component state with `$state` and computed values with `$derived`
• Creating reusable markup with snippets (replacing slots)
• Handling events with native event attributes and callback props
• Sharing state across components with context API
• Two-way binding with `$bindable` props

**Key patterns covered:**

• Runes: `$state`, `$derived`, `$effect`, `$props`, `$bindable`, `$inspect`
• Component composition with snippets and `{@render}`
• Event handling with native attributes and callback props
• Context API with `createContext` for type-safe cross-component state
• Class-based reactive state with `$state` fields
• Deep vs shallow reactivity (`$state` vs `$state.raw`)

**When NOT to use:**

• Meta-framework-specific patterns (routing, load functions, form actions) — use the corresponding meta-framework skill
• Svelte 4 patterns (`export let`, `$:` reactive statements, `<slot>`, `createEventDispatcher`)
• Server-side logic (use your meta-framework's server hooks and routes)

**Detailed Resources:**

• For decision frameworks and anti-patterns, see [reference.md](reference.md)

**Runes & Reactivity:**

• [examples/core.md](examples/core.md) - `$state`, `$derived`, `$effect`, `$props`, `$bindable`, component patterns

**Component Patterns:**

• [examples/snippets.md](examples/snippets.md) - Snippet blocks, `{@render}`, passing snippets as props, replacing slots
• [examples/events.md](examples/events.md) - Event handling, component events via callback props, event modifiers

**Advanced:**

• [examples/advanced.md](examples/advanced.md) - `$inspect`, context API, `$state.raw`, `$state.eager`, class-based state, shared state modules

---

<philosophy>

Philosophy

Svelte 5 introduces **Runes** — a set of primitives that bring explicit, fine-grained reactivity to Svelte. Unlike Svelte 4's compiler magic (`$:`, `export let`), Runes make reactivity visible and portable across `.svelte` files, `.ts` files, and class definitions.

**Core principles:**

1. **Explicit reactivity** — Runes (`$state`, `$derived`, `$effect`) make reactive declarations visible. No hidden compiler transformations. 2. **Derived over effects** — Compute values with `$derived`, not `$effect`. Effects are escape hatches, not primary tools. 3. **Deep reactivity by default** — `$state` creates deeply reactive proxies for objects/arrays. Mutations are tracked automatically. 4. **Snippets replace slots** — `{#snippet}` blocks are more powerful, typed, and composable than `<slot>` elements. 5. **Callback props replace event dispatchers** — Pass `onsomething` callback props instead of using `createEventDispatcher`. 6. **Compile-time optimization** — Svelte compiles components to efficient imperative code. No virtual DOM diffing at runtime.

**When to use Svelte 5 Runes:**

• All new Svelte components (Runes are the default in Svelte 5)
• Reactive state in `.svelte.ts` or `.svelte.js` files
• Class-based state with reactive fields
• Any computed value that depends on reactive state

**When NOT to use:**

• Non-reactive constants (use plain `const` or `let`)
• Server-side code that doesn't need reactivity
• Meta-framework concerns (routing, load functions, server hooks) — use the corresponding meta-framework skill
• Svelte 4 patterns — `export let`, `$:`, stores for component state, `<slot>`, `createEventDispatcher`

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Reactive State with $state

Use `$state` to declare reactive variables. Updates to `$state` variables automatically trigger UI re-renders.

<!-- counter.svelte -->
<script lang="ts">
  let count = $state(0);
  const STEP = 5;

  function increment() {
    count += 1;
  }

  function incrementByStep() {
    count += STEP;
  }
</script>

<button onclick={increment}>
  Count: {count}
</button>
<button onclick={incrementByStep}>
  +{STEP}
</button>

**Why good:** Explicit reactive declaration, named constants for magic numbers, plain function event handlers

<!-- BAD: Svelte 4 style -->
<script>
  let count = 0; // Not explicitly reactive in Svelte 5 mode
  $: doubled = count * 2; // Svelte 4 reactive statement
</script>

**Why bad:** `$:` is Svelte 4 syntax deprecated in Svelte 5, implicit reactivity is confusing and non-portable

Deep Reactivity

`$state` creates deep proxies for objects and arrays — mutations are tracked autom