Svelte 5 Runes skill for Codex

Done well means: state is declared with $state, everything computable is $derived, $effect is used only to sync with the outside world (DOM APIs, timers, network, logging) and always cleans up, and components compile in runes mode with zero warnings from svelte-check.

Inspect first

1. Read AGENTS.md and package.json: svelte must be 5.x. Note @sveltejs/kit (routing and data loading live in $sveltekit).
2. Check svelte.config.js for compilerOptions.runes (forces runes mode) or experimental.async (enables await in components).
3. A component is in runes mode as soon as it uses any rune. Legacy syntax (export let, $:) in the same file is then a compile error, so convert a file completely.

The runes

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

  interface Props {
    items: { id: string; label: string; price: number }[];
    selected?: string;               // bindable from the parent
    onchoose?: (id: string) => void; // callback prop replaces createEventDispatcher
    empty?: Snippet;                 // replaces a named slot
    row: Snippet<[{ id: string; label: string; price: number }]>;
  }
  let { items, selected = $bindable(), onchoose, empty, row }: Props = $props();

  let query = $state("");
  let filtered = $derived(items.filter((i) => i.label.toLowerCase().includes(query.toLowerCase())));
  let total = $derived.by(() => {
    let sum = 0;
    for (const i of filtered) sum += i.price;
    return sum;
  });

  $effect(() => {
    const id = setTimeout(() => console.debug("filtered", filtered.length), 300);
    return () => clearTimeout(id); // runs before the next run and on destroy
  });
</script>

<input bind:value={query} placeholder="Filter" />
{#each filtered as item (item.id)}
  <button class:active={item.id === selected} onclick={() => { selected = item.id; onchoose?.(item.id); }}>
    {@render row(item)}
  </button>
{:else}
  {@render empty?.()}
{/each}
<p>Total: {total}</p>

Parent usage:

<List {items} bind:selected onchoose={track}>
  {#snippet row(item)}<span>{item.label}</span>{/snippet}
  {#snippet empty()}<p>No matches</p>{/snippet}
</List>

Content placed directly between component tags becomes the children snippet prop.

Choosing the rune

Need	Use	Not
Mutable local value, object or array (deeply reactive)	$state
Large data you only replace, never mutate (API payloads)	$state.raw	$state (proxies every node)
Value computed from other state	$derived(expr) / $derived.by(fn)	$effect that assigns state
Plain copy of state to pass to a library or structuredClone	$state.snapshot(x)	passing the proxy
React to state by touching the DOM, a timer, a socket	$effect
Measure layout before paint	$effect.pre
Debug what changed	$inspect(x) (dev only)	$effect + console.log
Two-way bound prop	$bindable()	mutating a non-bindable prop
Unique id for label/input pairs	$props.id()	counters

Derived values can be reassigned locally since Svelte 5.25 (for optimistic UI); the next change in dependencies recomputes them.

Effects: rules

• Dependencies are whatever the effect reads synchronously. Values read after an await or inside setTimeout are not tracked. Read them first, then await.
• An effect that writes state it also reads loops (effect_update_depth_exceeded). If you must read without tracking, use untrack(() => value).
• Effects do not run during SSR. Code that must run on the server cannot live in one.
• Prefer event handlers for user-driven work: “when the user clicks save, POST” belongs in onclick, not in an effect watching a saving flag.
• Return a cleanup function for anything you start.

Shared state across components

Runes work in .svelte.ts / .svelte.js files. Export an object or class, never a reassigned primitive:

// lib/cart.svelte.ts
export class Cart {
  lines = $state<{ sku: string; qty: number }[]>([]);
  count = $derived(this.lines.reduce((n, l) => n + l.qty, 0));
  add(sku: string) {
    const l = this.lines.find((x) => x.sku === sku);
    if (l) l.qty++; else this.lines.push({ sku, qty: 1 });
  }
}
export const cart = new Cart(); // client-only apps; see SSR note below

• export let count = $state(0) cannot be reassigned by importers; export an object (export const counter = $state({ value: 0 })) or getter functions.
• In SvelteKit, module-level state is shared by every request on the server. For per-user state, create it in a component and pass it with setContext/getContext.
• Use SvelteMap, SvelteSet, SvelteURL, SvelteDate from svelte/reactivity; plain Map/Set inside $state are not made reactive.
• Destructuring a $state object (let { a } = obj) copies values; reference obj.a.

Migrating from Svelte 4

- [ ] Commit; run the test suite and svelte-check for a baseline
- [ ] npx sv migrate svelte-5            (needs network; rewrites syntax, adds TODOs)
- [ ] Search for "@migration" comments and run_in_legacy_mode markers; fix each by hand
- [ ] Replace createEventDispatcher with callback props; update parents (on:x -> onx)
- [ ] Replace $: side effects with $effect only where truly side effects; others -> $derived
- [ ] Convert slots to snippets where the migrator left <slot>
- [ ] Decide store usage: stores still work; move to .svelte.ts classes when touching them
- [ ] svelte-check, tests, manual pass on interactive pages

The migration script handles one component at a time well but cannot know whether a $: block is a derivation or a side effect; it often emits run(...) from svelte/legacy. Treat every svelte/legacy import as a TODO. For the full Svelte 4 to 5 mapping (events, modifiers, slots, lifecycle, component API), read references/migration-map.md when converting by hand.

Gotchas

• Event modifiers are gone: on:click|preventDefault becomes onclick={(e) => { e.preventDefault(); ... }}.
• bind:this on a component gives its exports, not $$props; components are functions, not classes. new Component(...) becomes mount(Component, { target, props }).
• $state objects are proxies: === against the original object fails, and console.log shows a Proxy. Use $state.snapshot or $inspect.
• {#each} without a key reuses DOM by index; add (item.id) for lists that reorder.
• Props are read-only unless $bindable; mutating a prop object warns (ownership_invalid_mutation). Emit a callback or make it bindable.
• onMount still works; beforeUpdate/afterUpdate do not in runes mode. Use $effect.pre and $effect.

Verification

npx svelte-check --threshold warning   # zero runes or a11y warnings
npx vitest run                         # @testing-library/svelte supports Svelte 5

• In tests, wrap state changes made outside components in flushSync() before asserting.
• Open the page with the browser console visible: no effect_update_depth_exceeded, state_unsafe_mutation or ownership warnings.

Output

Report components converted or added, any prop or event API change parents must adopt (on:x to onx, slot to snippet), remaining svelte/legacy usages, and test results.