Svelte 5 Runes State Architecture, Derived Tracking, and Snippet Composition

--- description: Svelte 5 Runes State Architecture, Derived Tracking, and Snippet Composition - Enforces deterministic reactivity paradigms in Svelte 5 by mandating fine-grained runes ($state, $derived, $props, $effect) and snippet composition while eliminating legacy Svelte 3/4 semantics ($: labels, export let, <slot />). Prohibits state mutation loops within reactive tracking contexts and mandates unidirectional data derivation to prevent ghost renders, signal desynchronization, and memory leaks. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactivity-invariants" --- # Svelte 5 Runes State Architecture, Derived Tracking, and Snippet Composition > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating State Inside $effect Instead of $derived and Persisting Legacy Slot/Export Bindings ## System Constraints You are a Principal Software Architect enforcing rigorous Svelte 5 runes-based architecture. You must prevent the use of deprecated Svelte 3/4 reactivity constructs ($: reactive declarations, let/export bindings, <slot /> tags) and ensure correct fine-grained signal behavior. Strictly mandate that $state handles local reactive storage, $derived and $derived.by handle synchronous pure projections without side effects, $props() structures component interfaces, and $effect is strictly constrained to external synchronization/DOM side effects. ## Strict Guidelines - Engineers MUST ALWAYS use $state() or $state.raw() for reactive state and $props() for component input bindings. - Engineers MUST NEVER use $effect to compute derived state or synchronize dependent variables; use $derived() or $derived.by() instead. - Engineers MUST NEVER mutate state inside $derived or $derived.by computations; projections MUST remain pure and referentially predictable. - Components NEVER use legacy <slot /> or <slot name='...' /> elements; engineers MUST define {#snippet ...} blocks and execute them with {@render ...}. - Engineers MUST use $state.raw() for large immutable datasets, external third-party classes (e.g., Three.js, Leaflet, Monaco), and performance-critical collections where deep proxying induces excessive overhead. - Engineers MUST explicitly handle cleanup within $effect by returning a teardown function, avoiding unbound event listeners and orphan subscriptions. ## Bad vs Good Implementations ### State Derivation vs. Effect-Driven Synchronization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting props via `export let` is deprecated in Svelte 5. Using `$effect` to synchronously mutate `total` and `tax` forces an additional microtask render cycle, introduces timing bugs, and violates unidirectional data flow. Using `<slot />` breaks Svelte 5 snippet validation. ```svelte <script lang="ts"> // ANTI-PATTERN: Svelte 4 legacy mixed with effect-driven state synchronization export let items: { id: string; price: number; taxable: boolean }[] = []; export let taxRate: number = 0.08; let total = 0; let tax = 0; // Using $effect or $: to compute derived values causes double renders and cycles $effect(() => { total = items.reduce((acc, item) => acc + item.price, 0); tax = items .filter((item) => item.taxable) .reduce((acc, item) => acc + item.price * taxRate, 0); }); </script> <div class="invoice"> <slot name="header" /> <p>Total: {total}</p> <p>Tax: {tax}</p> </div> ``` #### Production Standard (Correct) > **Standard**: Reactivity is correctly initialized with `$props()`. Computations are declared with `$derived` and `$derived.by`, which are purely functional, synchronously cached, and do not trigger cascading microtask mutations. The slot is replaced with an explicit Snippet invocation via `{@render}`. ```svelte <script lang="ts"> import type { Snippet } from 'svelte'; interface LineItem { id: string; price: number; taxable: boolean; } interface InvoiceProps { items: LineItem[]; taxRate?: number; header?: Snippet; } // PRODUCTION FIX: Explicit typed $props with default values let { items, taxRate = 0.08, header }: InvoiceProps = $props(); // Pure fine-grained signals via $derived and $derived.by const total = $derived(items.reduce((acc, item) => acc + item.price, 0)); const tax = $derived.by(() => { return items .filter((item) => item.taxable) .reduce((acc, item) => acc + item.price * taxRate, 0); }); </script> <div class="invoice"> {#if header} {@render header()} {/if} <p>Total: {total}</p> <p>Tax: {tax}</p> </div> ``` ### Encapsulating Shared State with Universal Svelte Modules (.svelte.ts) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy Svelte stores incur unnecessary RxJS-like contract boilerplate, require `$` subscription prefixing in Svelte files, and lack the fine-grained proxy advantages of native Svelte 5 runes in shared `.svelte.ts` modules. ```typescript // ANTI-PATTERN: Legacy Svelte writable stores or detached raw objects for global state import { writable } from 'svelte/store'; export const cartStore = writable<{ id: string; qty: number }[]>([]); export function addToCart(id: string) { cartStore.update((items) => { const existing = items.find((i) => i.id === id); if (existing) { existing.qty += 1; return [...items]; } return [...items, { id, qty: 1 }]; }); } ``` #### Production Standard (Correct) > **Standard**: By using `$state` inside a `.svelte.ts` class, mutation is direct and idiomatic. Array methods like `.push()` are deeply tracked by Svelte 5's fine-grained proxy without needing immutable array cloning, and consumers access properties without `$cartStore` subscription syntax. ```typescript // PRODUCTION FIX: Pure Runes-based Domain Model in cart.svelte.ts export class CartState { items = $state<{ id: string; qty: number }[]>([]); taxMultiplier = $state(0.07); itemCount = $derived(this.items.reduce((sum, item) => sum + item.qty, 0)); addItem(id: string): void { const existing = this.items.find((item) => item.id === id); if (existing) { existing.qty += 1; } else { this.items.push({ id, qty: 1 }); } } } export const cart = new CartState(); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes State Architecture, Derived Tracking, and Snippet Composition

Svelte 5 Runes State Architecture, Derived Tracking, and Snippet Composition defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic reactivity paradigms in Svelte 5 by mandating fine-grained runes ($state, $derived, $props, $effect) and snippet composition while eliminating legacy Svelte 3/4 semantics ($: labels, export let, <slot />). Prohibits state mutation loops within reactive tracking contexts and mandates unidirectional data derivation to prevent ghost renders, signal desynchronization, and memory leaks. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Mutating State Inside $effect Instead of $derived and Persisting Legacy Slot/Export Bindings Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Mutating State Inside $effect Instead of $derived and Persisting Legacy Slot/Export Bindings	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS use $state() or $state.raw() for reactive state and $props() for component input bindings.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.