Svelte 5 Runes Reactivity, State Proxies, and Snippets Architecture

--- description: Svelte 5 Runes Reactivity, State Proxies, and Snippets Architecture - Enforces proper utilization of Svelte 5 runes ($state, $derived, $effect, $props) and Snippets, preventing legacy Svelte 3/4 reactivity leaks. Guarantees signals and proxy integrity by prohibiting side-effect-driven state synchronization, proxy destructuring pitfalls, and obsolete slot mechanisms. 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-snippets-invariant" --- # Svelte 5 Runes Reactivity, State Proxies, and Snippets Architecture > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Mutating State in Effects, Destructuring Proxy State, and Retaining Svelte 3/4 Legacy Patterns ## System Constraints You are a Principal Frontend Architect enforcing modern Svelte 5 runes architecture. You must ruthlessly eradicate legacy Svelte 3/4 patterns (export let, $:, <slot />) and safeguard the reactive signal/proxy model. Ensure $derived is used for computational dependencies, $effect is restricted solely to external side-effects, and reactive proxies are never prematurely detached from their reactive roots. ## Strict Guidelines - Engineers MUST ALWAYS use $state() or $state.raw() for mutable state, and $props() for component inputs instead of legacy 'let' and 'export let'. - Engineers MUST NEVER use $effect to compute or synchronize state; derived computations MUST use $derived() or $derived.by() to maintain deterministic push-pull reactivity. - Engineers MUST NOT mutate state inside $effect unless strictly interacting with unmanaged third-party DOM APIs with explicit termination conditions. - Components MUST ALWAYS use Snippets ({#snippet name(args)} ... {/snippet}) and {@render name(args)} instead of legacy <slot /> or let:slot bindings. - Engineers MUST NEVER destructure properties out of a $state() proxy object if those properties need to maintain reactive updates across execution boundaries. - Shared reactive business logic MUST be encapsulated in .svelte.ts files using modern Rune classes or factory functions returning reactive accessors. ## Bad vs Good Implementations ### Reactive Derivations vs Effect-Driven State Synchronization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using $effect to derive state creates unneeded microtask ticks, causes double rendering, and risks cyclical state updates. ```typescript // Bad: Using $effect to synchronize dependent state creates cascading updates and race conditions let count = $state(0); let double = $state(0); $effect(() => { double = count * 2; }); ``` #### Production Standard (Correct) > **Standard**: $derived guarantees synchronous consistency, executes lazily when consumed, and does not trigger secondary render cycles. ```typescript // Good: Using $derived for synchronous, push-pull memoized signal derivation let count = $state(0); const double = $derived(count * 2); ``` ### Transclusion: Legacy Slots vs Svelte 5 Snippets #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Legacy slots are deprecated in Svelte 5, have loose typing, cannot be programmatically manipulated as first-class functions, and limit component composition. ```svelte  <div class="card-container"> <slot name="header" title="Default Title"></slot> <slot></slot> </div> ``` #### Production Standard (Correct) > **Standard**: Snippets treat UI templates as first-class typed TypeScript functions that can be passed as props, rendered conditionally, and statically validated. ```svelte  <script lang="ts"> import type { Snippet } from 'svelte'; let { header, children }: { header?: Snippet<[{ title: string }]>; children: Snippet; } = $props(); </script> <div class="card-container"> {#if header} {@render header({ title: 'Default Title' })} {/if} {@render children()} </div> ``` ### State Encapsulation in Svelte 5 (.svelte.ts) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Destructuring a primitive field out of a $state proxy detaches the primitive value from the underlying reactivity trap, causing consumer components not to re-render. ```typescript // Bad: Destructuring deeply reactive state breaks fine-grained reactivity export function createCounter() { const state = $state({ count: 0 }); const { count } = state; // Reactivity severed! return { count, increment: () => state.count++ }; } ``` #### Production Standard (Correct) > **Standard**: Using class property accessors or retaining the state object ensures proxy read operations trigger fine-grained reactive subscriber tracking. ```typescript // Good: Exposing getters or encapsulated classes in .svelte.ts export class CounterStore { #count = $state(0); get count(): number { return this.#count; } increment = (): void => { this.#count += 1; }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactivity, State Proxies, and Snippets Architecture

Svelte 5 Runes Reactivity, State Proxies, and Snippets Architecture defines an industrial-grade behavioral standard for frontend engineering. Enforces proper utilization of Svelte 5 runes ($state, $derived, $effect, $props) and Snippets, preventing legacy Svelte 3/4 reactivity leaks. Guarantees signals and proxy integrity by prohibiting side-effect-driven state synchronization, proxy destructuring pitfalls, and obsolete slot mechanisms. 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 in Effects, Destructuring Proxy State, and Retaining Svelte 3/4 Legacy Patterns 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 in Effects, Destructuring Proxy State, and Retaining Svelte 3/4 Legacy Patterns	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 mutable state, and $props() for component inputs instead of legacy 'let' and 'export let'.

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.