Svelte 5 Runes Invariant: Fine-Grained Reactivity and Snippet Composition

--- description: Svelte 5 Runes Invariant: Fine-Grained Reactivity and Snippet Composition - Enforces architectural invariants for Svelte 5 runes ($state, $derived, $props, $effect) and snippet composition. Prevents reactivity severing caused by destructuring reactive proxies, completely eliminates legacy Svelte 3/4 reactivity paradigms (export let, $:, <slot />), and bans side-effect synchronization antipatterns in $effect. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js, src/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-reactivity-and-snippets-standard" --- # Svelte 5 Runes Invariant: Fine-Grained Reactivity and Snippet Composition > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Reactivity severing through proxy destructuring and derived-state synchronization inside $effect ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes standards. Svelte 5 completely deprecates the compiler-driven let/export/$: reactivity model in favor of fine-grained signal proxies ($state, $derived, $props, $effect) and programmatic snippets. You MUST mandate strict adherence to rune semantics, prevent reactivity stripping via premature destructuring, and eradicate legacy slot or reactive assignment patterns. ## Strict Guidelines - Engineers MUST ALWAYS use $props() for component interface definitions and MUST NOT use legacy 'export let' syntax. - Engineers MUST NEVER destructure properties directly from a mutable $state object if reactivity across property updates is required; access properties directly via the proxy reference. - Engineers MUST NEVER use $effect() to synchronize state that can be computed synchronously; use $derived() or $derived.by() instead. - Engineers MUST encapsulate shared reactive logic in '.svelte.ts' or '.svelte.js' module files using runes, never in plain '.ts' files relying on store subscriptions. - Components NEVER use legacy <slot /> or <svelte:fragment> syntax; snippet composition using '{#snippet name(args)}' and '{@render name(args)}' MUST be used exclusively. - Code MUST use $state.raw() for large immutable collections, third-party class instances, or complex objects that do not require deep fine-grained proxy wrapping. - Engineers MUST ensure cleanup functions returned from $effect() are idempotent and free of secondary reactive mutations that cause infinite loops. ## Bad vs Good Implementations ### State Derivation and Proxy Preservation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Destructuring `profile` disconnects `name` and `loginCount` from the underlying Svelte proxy, freezing their values. Using `$effect` to write to another `$state` variable causes dual-cycle updates, breaks synchronous consistency, and causes unnecessary renders. ```typescript import { untrack } from 'svelte'; // Anti-pattern: Destructuring reactive proxy breaks mutation tracking, // and using $effect to mirror state leads to redundant render cascades. interface UserProfile { name: string; loginCount: number; } let profile = $state<UserProfile>({ name: 'Ada', loginCount: 1 }); // Destructuring breaks reactivity; 'name' is now an immutable primitive copy: let { name, loginCount } = profile; let isReturningUser = $state(false); // Slower, prone to infinite loops and flash of uncomputed state: $effect(() => { isReturningUser = loginCount > 0; }); ``` #### Production Standard (Correct) > **Standard**: Preserving the `profile` proxy ensures fine-grained subscriptions track mutations accurately. Replacing the `$effect` with `$derived` guarantees synchronous purity, optimal dependency tracking, and avoids cascade cycles. ```typescript interface UserProfile { name: string; loginCount: number; } // Production standard: Keep proxy intact and compute synchronously via $derived const profile = $state<UserProfile>({ name: 'Ada', loginCount: 1 }); // Explicit derived state computed synchronously without effect scheduling const isReturningUser = $derived(profile.loginCount > 0); // Direct property access preserves fine-grained dependency tracking export function updateName(newName: string): void { profile.name = newName; } ``` ### Component Props Contract with Snippet Composition #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `export let` and `$:` is legacy Svelte 3/4 syntax that breaks interoperability in Svelte 5 runes mode and impedes static type inference with TypeScript. ```typescript // Bad: Mixing legacy props with $state or attempting to mutate immutable incoming props directly interface Props { userId: string; initialFilter?: string; } // Incorrect legacy syntax combined with anti-pattern mutation export let userId: string; export let initialFilter: string = 'all'; $: normalizedFilter = initialFilter.toLowerCase(); ``` #### Production Standard (Correct) > **Standard**: The `$props()` rune correctly types and declares incoming component inputs. Snippets replace legacy slots for explicit, typed template rendering with parameter passing. ```typescript import type { Snippet } from 'svelte'; interface Props { userId: string; initialFilter?: string; header?: Snippet<[{ title: string }]>; children?: Snippet; } // Production standard: $props() rune with type checking, destructuring, and snippets const { userId, initialFilter = 'all', header, children }: Props = $props(); const normalizedFilter = $derived(initialFilter.toLowerCase()); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Invariant: Fine-Grained Reactivity and Snippet Composition

Svelte 5 Runes Invariant: Fine-Grained Reactivity and Snippet Composition defines an industrial-grade behavioral standard for frontend engineering. Enforces architectural invariants for Svelte 5 runes ($state, $derived, $props, $effect) and snippet composition. Prevents reactivity severing caused by destructuring reactive proxies, completely eliminates legacy Svelte 3/4 reactivity paradigms (export let, $:, <slot />), and bans side-effect synchronization antipatterns in $effect. 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: Reactivity severing through proxy destructuring and derived-state synchronization inside $effect 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	Reactivity severing through proxy destructuring and derived-state synchronization inside $effect	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 interface definitions and MUST NOT use legacy 'export let' syntax.

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.