Svelte 5 Patterns

Svelte 5 runes and patterns used across the Fuz ecosystem.

Contents

• State Runes
• Derived Values
• Reactive Collections
• Schema-Driven Reactive Classes
• Context Patterns
• Snippet Patterns
• Effect Patterns
• Attachment Patterns
• Props Patterns
• Event Handling
• Component Composition
• Runes in .svelte.ts Files
• Debugging
• Each Blocks
• CSS in Components
• Legacy Features to Avoid
• Quick Reference

State Runes

Only use $state for variables that should be reactive — variables that cause an $effect, $derived, or template expression to update. Everything else can be a normal variable.

$state.raw() vs $state() — opt into mutation reactivity, raw otherwise

Principle: be explicit about when you're opting into mutation reactivity. For primitives the two are equivalent (one extra typeof check on set). For objects and arrays, $state() proxies the value so in-place mutations trigger updates; $state.raw() stores the value directly and only tracks reassignment.

Use $state() for in-place mutation reactivity:

• Arrays you push, splice, pop, sort, or index-assign
• Objects with individual property mutations
• bind:value={obj.field} — binding writes to a property on the object, which needs deep proxy reactivity (binding to a primitive let works either way, since the binding reassigns the variable)

Use $state.raw() for everything else — primitives, values replaced wholesale (filter/spread/reassignment), API responses, data passed to APIs that compare object identity, anything where property-level reactivity isn't wanted.

This is a fuz-stack stylistic preference, not a technical requirement, and diverges from Svelte's official guidance — which defaults to $state() and treats $state.raw as a perf opt-out for large values that are only ever reassigned (API responses and similar). The benefit is explicit intent — reading a state class tells you which fields are designed to mutate in place. The cost is friction with idiomatic-Svelte reviewers and AI assistants that default to $state().

structuredClone, JSON.stringify, and postMessage all walk through $state() proxies cleanly — proxy traps return the target's own keys. JSON.stringify also calls toJSON() through the proxy.

Watch for const objects: A const object declared with $state.raw() can't trigger reactivity at all — it can't be reassigned and property mutations aren't tracked. If its properties are mutated (directly or via bind:), use $state().

Check consumer files, not just the declaring file. A class field may be mutated in place by external code — e.g., a component importing a state class and calling thing.items.splice(i, 1). Grep all of src/ for mutation patterns on the field name before deciding.

The $state.raw()! Non-null Assertion Pattern

Class properties initialized by a constructor or init() use $state.raw()!:

Used across fuz_ui state classes and zzz Cell subclasses. Use $state()! only for arrays/objects that are mutated in place (see above).

$state.snapshot()

Deep-cloned plain copy of a reactive value. Per Svelte's source: recurses into plain objects and arrays; for class instances with toJSON(), calls it and clones the result; otherwise falls through to structuredClone (which strips class prototypes).

Use it when handing a $state() proxy structure to code that does reference-identity checks on members and would otherwise see proxy identities. $state.raw() values holding plain data don't need it at all; for serialization, JSON.stringify and structuredClone walk proxies on their own.

Observed quirk (Svelte 5.56 + vite-plugin-svelte): const r = $state.snapshot(x) is silently elided to const r = x somewhere downstream of Svelte's compileModule (whose output is correct). return $state.snapshot(x) and inline expression use work correctly. zzz Cell's encode_property is the direct-return form, so to_json() is unaffected. If `const r = $state.snapshot(x)` seems to lose snapshot semantics, this is the cause.

Derived Values

Use $derived to compute from state — never $effect with assignment. Deriveds are writable (assign to override, but the expression re-evaluates on dependency change). Derived objects/arrays are not deeply reactive.

$derived vs $derived.by()

$derived takes an expression (not a function); $derived.by() takes a function for loops, conditionals, or multi-step logic.

$derived in Classes

Always mark $derived class properties readonly unless you explicitly need reassignment (which Svelte 5 does allow):

Field-initializer order gotcha (plain classes). Class field initializers run before the constructor body, so a $derived whose expression reads a field the constructor assigns (common in plain .svelte.ts classes — app, name, …) trips TS2729 "used before initialization":

Wrap the read in $derived.by(() => …): TS's init-order check doesn't descend into the closure, and the read is lazy at runtime regardless.

Cells don't hit this — app comes from the base Cell constructor (runs before subclass fields), and schema fields use $state.raw()! (counts as initialized in declaration order). It bites only plain classes that read constructor-assigned fields in a $derived.

Derived from Props

Treat props as though they will change — use $derived for values depending on props:

Reactive Collections

SvelteMap and SvelteSet

From svelte/reactivity — reactive Map/Set that trigger updates on mutations:

Standard Map/Set are not tracked by Svelte's reactivity.

For entity collections consumed by different lookups, maintain multiple SvelteMap indexes over the data (by id, plus one or more secondary keys), rebuilding or updating them as the source changes. Deriveds then do .get() lookups instead of array scans.

Schema-Driven Reactive Classes

Zod schemas paired with Svelte 5 runes classes — the schema defines the JSON shape, the class adds reactivity and behavior. See ./zod-schemas.

Simple Pattern (fuz_ui)

Cell Pattern (zzz)

Advanced version with a Cell base class that automates JSON hydration from Zod schemas. Same rune conventions ($state.raw()! by default, $state()! for in-place mutations, readonly $derived for computed values). See ./zod-schemas for the full pattern.

Context Patterns

Creating Context

create_context<T>() from @fuzdev/fuz_ui/context_helpers.ts. Two overloads: without a fallback, get() throws if unset and get_maybe() returns undefined; with a fallback, get() uses it and the set() value is optional:

Using Context

Getter Function Context Pattern

Some contexts wrap values in () => T so the context reference stays stable while the value can change:

The getter must be read lazily — calling it once at init (const theme_state = get_theme_state(); without $derived) captures a snapshot and loses reactivity, defeating the pattern's purpose. Besides the script-level $derived above, two other lazy forms appear in real consumers:

Used when the context value might be reassigned (e.g., theme_state is a prop). library_context is a getter context (() => Library) for the same reason — components with a library prop (LibraryDetail, ApiIndex, ApiModule) project the prop into it for their subtree via library_context.set(() => library). Direct value contexts like frontend_context and site_context are for values stable for the context's lifetime.

For an inventory of contexts in fuz_ui and zzz, grep for create_context<.

Snippet Patterns

Svelte 5 replaces slots with snippets ({#snippet}, {@render}).

The children Snippet

The implicit children replaces the default slot. Typed Snippet (or Snippet<[params]> with parameters):

Content between component tags becomes children:

Children with Parameters

Children can be parameterized — Dialog passes a DialogContext object back to the consumer (DialogContext from @fuzdev/fuz_ui/dialog.ts is {close: (e?: Event) => void; register_surface: (el) => () => void}):

Consumers reach close via dialog.close; register_surface marks click-outside-safe regions. ThemeRoot uses the same parameterized-children pattern with multiple values: Snippet<[theme_state: ThemeState, style: string | null, theme_style_html: string | null]>.

Named Snippets

Snippets with Parameters

A snippet prop can take parameters (Snippet<[T]>). Illustrative generic list renderer — fuz_ui's real generics= user is Contextmenu.svelte:

Default Snippet Content and String/Snippet Unions

For optional snippets, fall back with {#if snippet} {@render snippet()} {:else} ... {/if}. For props accepting a string or a snippet (e.g. icon?: string | Snippet), branch on typeof at render. fuz_ui's Card and Alert use this; Alert further parameterizes with Snippet<[icon: string]> to pass the resolved icon back.

Effect Patterns

Effects are an escape hatch — avoid when possible. Prefer:

• $derived / $derived.by() for computing from state
• {@attach} for syncing with external libraries or DOM
• Event handlers / function bindings for responding to user interaction
• $inspect / $inspect.trace() for debugging (not $effect + console.log)
• createSubscriber from svelte/reactivity for observing external sources

Don't wrap effect contents in if (browser) {...} — effects don't run on the server. Avoid updating $state inside effects.

Effect Cleanup

Return a cleanup function for subscriptions or timers (runs before the next effect and on destroy):

For window/document listeners, prefer <svelte:window onkeydown={...}> and <svelte:document> over $effect + addEventListener. For element-scoped listeners, prefer {@attach} (with on() from svelte/events inside).

$effect.pre()

Runs before DOM updates. Used for dev-mode validation and scroll management:

effect_with_count()

From @fuzdev/fuz_ui/rune_helpers.svelte.ts — passes call count to the effect, useful for skipping the initial run:

untrack()

Read values without creating dependencies — config reads that shouldn't trigger re-runs, stable references, or breaking infinite loops in bidirectional syncing:

Attachment Patterns

Svelte 5 attachments ({@attach}) replace actions (use:). Attachments live in *.svelte.ts files and use Attachment from svelte/attachments.

Attachment API

An attachment is (element) => cleanup | void. fuz_ui uses a factory pattern — export a function that accepts config and returns the Attachment:

Usage: {@attach my_attachment()} or {@attach my_attachment({...options})}

fuz_ui Attachments

autofocus -- Focus on Mount

Solves the HTML autofocus attribute not working when elements mount from reactive conditionals ({#if}) in SPAs.

intersect -- IntersectionObserver

Wraps IntersectionObserver with a lazy function pattern — reactive callbacks update without recreating the observer:

contextmenu_attachment -- Context Menu Data

Caches context menu params on an element via dataset. Direct params (no lazy function). Returns cleanup that removes the cache entry.

Class Method Attachments (zzz)

Attachments as class properties, sharing reactive state with the instance:

Choosing a Pattern

Writing a New Attachment

1. Create src/lib/my_attachment.svelte.ts
2. Export a factory returning Attachment<HTMLElement | SVGElement>
3. Return cleanup if holding resources (observers, listeners)
4. Use $effect inside for reactive behavior, on() for event listeners
5. Add JSDoc with @module and @param tags

Props Patterns

Basic Props

Bindable Props

Use let (not const) for $bindable() props:

Real examples from fuz_ui:

Rest Props with SvelteHTMLElements

Intersect SvelteHTMLElements from svelte/elements with custom props:

Use SvelteHTMLElements['div'] (not HTMLAttributes<HTMLDivElement>).

Event Handling

Svelte 5 uses standard DOM event syntax:

Programmatic Event Listeners

on() from svelte/events for programmatic listeners in attachments, .svelte.ts files, and plain .ts modules. It preserves correct ordering relative to declarative handlers that use event delegation, and returns a cleanup function. Always prefer on() over addEventListener, even in non-component code:

swallow — Claiming Events

swallow() from @fuzdev/fuz_util/dom.ts combines preventDefault() and stopImmediatePropagation() (or stopPropagation() with immediate: false).

Design principle: handling an event = claiming it. Calling preventDefault already says "I own this event's default behavior"; swallow extends that to "and no one else should react to it either." Use it whenever you would call preventDefault. If a parent needs to observe events before children claim them, use the capture phase explicitly — don't rely on implicit bubbling.

For handlers that only need stopPropagation without preventDefault (e.g., preventing game input from seeing keystrokes in a chat input), use e.stopPropagation() directly.

Component Composition

Module Script Block

Use <script lang="ts" module> for component-level exports (contexts, types):

Forwarding Snippets

Generic Components

Dynamic Elements

svelte:element for components rendering different HTML tags:

Runes in .svelte.ts Files

.svelte.ts files use runes ($state, $derived, $effect) outside components. Prefer classes over module-level state — export a class, instantiate once at the appropriate root, share it via context.

Avoid Module-Level Runes for Shared State

Don't declare $state variables at module scope and expose them through getter/setter objects. A module-level rune is a hidden global: it can't be reset per test, per realm, or per session; it ties state lifetime to the module rather than a component; and a second instance is impossible if you later need one.

Use a class + context instead — the class owns its state, and a root component sets it once:

When module-level runes are fine: inside a factory function body (see below) — the state is scoped to the returned object, not the module.

Factory Functions with Getter/Setter Proxies

Reactive State Classes

The most common pattern for shared state:

Plain Classes for Imperative Loops

Canvas2D/WebGPU renderers, requestAnimationFrame loops, and long-lived pointer listeners are the inverse case: use a plain class with no runes, mounted by a thin .svelte wrapper. Private fields (e.g. #hovered_id, #cursor_x) stay non-reactive on purpose — mutating them from an rAF tick must not schedule reruns. The wrapper binds dimensions, forwards reactive sources via getter-backed options, and calls destroy() on unmount. Runes live in the wrapper, never in the loop.

Debugging

$inspect.trace()

Add as the first line of an $effect or $derived.by to trace dependencies and discover which one triggered an update:

Each Blocks

Prefer keyed each blocks — Svelte surgically inserts or removes items rather than updating existing DOM:

The key must uniquely identify the object — do not use the array index. Avoid destructuring if you need to mutate the item (e.g., bind:value={item.count}).

CSS in Components

Goal: minimal <style> blocks. Components delegate styling to fuz_css utility classes and design tokens; many well-designed components have no <style> block at all. See css-patterns.md §Default styling is the baseline and §Component Styling In Practice for the full rationale, anti-patterns, and examples.

When a <style> block is needed, keep it focused on component-specific layout logic (positioning, complex pseudo-states, responsive breakpoints), with all values referencing design tokens, not hardcoded pixels or colors.

Class naming: fuz_css utilities use snake_case (p_md, gap_lg); component-local classes use kebab-case (site-header, nav-links) to distinguish them visually.

JS Variables in CSS

Use style: directive to pass JS values as CSS custom properties:

Styling Child Components

Prefer CSS custom properties. Use :global only when necessary (e.g., third-party components):

Use clsx-style arrays and objects in class attributes instead of class: directive:

Legacy Features to Avoid

Always use runes mode. Deprecated patterns and their replacements:

Quick Reference

The decision-fraught choices, summarized:

• $state.raw() vs $state() — $state.raw() for primitives and values replaced wholesale; $state() when you want in-place mutation (push, property writes, bind: on object properties) to trigger reactivity.
• $derived vs $derived.by() — $derived takes an expression; $derived.by() takes a function for loops/conditionals/multi-step logic. Mark class-level deriveds readonly.
• {@attach} vs $effect — attachments for element behavior (replaces use:action); effects for everything else, but reach for $derived, <svelte:window>, or event handlers first.
• create_context<T>() vs raw setContext/getContext — fuz_ui's create_context provides the throw-on-missing get() plus get_maybe(), with optional fallback factory.