Svelte 5 Runes Reactivity, Snippets, and Props Invariants

--- description: Svelte 5 Runes Reactivity, Snippets, and Props Invariants - Enforces fine-grained reactivity and component composition standards using Svelte 5 runes ($state, $derived, $props, $effect) and snippets. Prevents reactivity loss caused by props destructuring, eliminates circular re-renders from effect-based state synchronization, and deprecates legacy Svelte 3/4 stores and slot idioms. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactivity-and-snippets" --- # Svelte 5 Runes Reactivity, Snippets, and Props Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Destructuring $props(), Mutating $derived, Synchronizing State via $effect, and Using Legacy Slots ## System Constraints You are a Principal Frontend Architect enforcing modern Svelte 5 idioms. Mandate the strict use of Svelte 5 runes ($state, $derived, $props, $effect) and snippets. Reject legacy Svelte 3/4 paradigms including `export let`, `<slot />`, manual store subscriptions (`$store`), and `$effect` triggers used for derived computations. ## Strict Guidelines - Engineers MUST ALWAYS use `$props()` for component inputs and avoid destructuring primitive values if reactive updates are consumed downstream without getters. - Engineers MUST NEVER use `$effect` to compute or synchronize values that can be expressed with `$derived` or `$derived.by`. - Engineers MUST use `{#snippet name(params)}...{/snippet}` and `{@render name(args)}` instead of `<slot>` and `let:` bindings for slot-based composition. - Engineers MUST use `$state.raw` for large immutable collections or external instances (e.g., third-party clients, WebGL contexts) to avoid unnecessary deep proxy wrapping overhead. - Code MUST isolate shared global state into `.svelte.ts` files using encapsulated `$state` classes or closure objects rather than legacy Svelte `writable()`/`readable()` stores. - Components NEVER use `export let` or legacy lifecycle hooks (`onMount`, `beforeUpdate`, `afterUpdate`) when equivalent runes (`$effect`, `$effect.pre`) or synchronous `$state` initializations apply. ## Bad vs Good Implementations ### Derived State Computation & Props Contract #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Destructuring primitive props breaks downstream reactivity if mutated or reassigned. Using $effect to calculate 'total' causes an unnecessary microtask cycle and risks cyclic dependencies. Relying on mutable state when values are deterministic derivations violates unidirectional data flow. ```typescript // Bad: Using $effect to synchronize state, legacy slots, and destructuring props import { onMount } from 'svelte'; interface Props { initialCount: number; multiplier: number; } // Destructuring loses reactivity if primitive is reassigned const { initialCount, multiplier } = $props<Props>(); let count = $state(initialCount); let total = $state(0); // Anti-pattern: Synchronizing derived state using an effect causes extra frame render & race conditions $effect(() => { total = count * multiplier; }); export function increment() { count += 1; } ``` #### Production Standard (Correct) > **Standard**: Accessing props via the 'props' proxy retains reactivity across renders. Using $derived creates a dependency graph node that evaluates cleanly without cascading re-renders, race conditions, or explicit synchronization effects. ```typescript // Good: Canonical Svelte 5 props access, $derived rune, and encapsulated logic interface Props { initialCount?: number; multiplier: number; onUpdate?: (total: number) => void; } const props = $props<Props>(); let count = $state(props.initialCount ?? 0); // Pure derived reactivity: evaluated synchronously on read, invalidating dependents precisely const total = $derived(count * props.multiplier); export function increment(): void { count += 1; props.onUpdate?.(total); } ``` ### Universal Shared State in .svelte.ts #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy Svelte stores introduce subscription overhead, require store contract adherence ($ prefix), and bypass the fine-grained proxy signals introduced in Svelte 5. ```typescript // Bad: Legacy writable store pattern used in Svelte 5 codebase import { writable, derived } from 'svelte/store'; export const cartItems = writable<Array<{ id: string; price: number }>>([]); export const cartTotal = derived(cartItems, ($items) => $items.reduce((sum, item) => sum + item.price, 0) ); ``` #### Production Standard (Correct) > **Standard**: Encapsulating state in a class inside a .svelte.ts file leverages native $state and $derived runes. It permits direct property mutations (e.g. array push) tracked by fine-grained proxies without wrapper store boilerplate. ```typescript // Good: Svelte 5 universal reactivity module in a .svelte.ts file class CartState { items = $state<Array<{ id: string; price: number }>>([]); total = $derived.by(() => this.items.reduce((sum, item) => sum + item.price, 0)); addItem(item: { id: string; price: number }): void { this.items.push(item); } clear(): void { this.items = []; } } export const cart = new CartState(); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactivity, Snippets, and Props Invariants

Svelte 5 Runes Reactivity, Snippets, and Props Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces fine-grained reactivity and component composition standards using Svelte 5 runes ($state, $derived, $props, $effect) and snippets. Prevents reactivity loss caused by props destructuring, eliminates circular re-renders from effect-based state synchronization, and deprecates legacy Svelte 3/4 stores and slot idioms. 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: Destructuring $props(), Mutating $derived, Synchronizing State via $effect, and Using Legacy Slots 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	Destructuring $props(), Mutating $derived, Synchronizing State via $effect, and Using Legacy Slots	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 `$props()` for component inputs and avoid destructuring primitive values if reactive updates are consumed downstream without getters.

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.