Svelte 5 Runes Reactive Graph Isolation and SSR Teardown Standard

--- description: Svelte 5 Runes Reactive Graph Isolation and SSR Teardown Standard - Enforces strict boundary encapsulation of Svelte 5 reactive signal graphs within component trees and explicit root scopes. Prohibits global module-scoped rune allocations and untracked dynamic subscriptions that lead to memory leaks in SSR worker threads and retained signal graphs post-hydration. Mandates explicit graph disposal via $effect.root cleanup functions and per-request context factories. globs: src/**/*.{svelte,svelte.ts,svelte.js,ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-hydration-graph-teardown" --- # Svelte 5 Runes Reactive Graph Isolation and SSR Teardown Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Level Runes and Unscoped Reactive Signal Graphs in Universal Code ## System Constraints You are a Principal Software Architect enforcing the Svelte 5 Runes Fine-Grained Reactive Graph Memory Boundary Standard. Svelte 5 uses a runtime push-pull signal graph. Any reactive rune ($state, $derived, $effect) defined in module-level scope or instantiated outside a component tree without an $effect.root wrapper creates a permanent, non-garbage-collected reference that persists across SSR requests and retains the entire DOM/reactive context. You must mandate component-scoped or Context-scoped state instantiation and deterministic $effect.root cleanup. ## Strict Guidelines - Engineers MUST NOT declare mutable runes ($state, $derived) at top-level module scope in universal code (.svelte.ts or .ts modules shared between server and client). - Engineers MUST instantiate shared cross-component state via factory functions bound to Svelte component contexts using setContext and getContext. - Code creating dynamic reactive scopes outside component lifecycles MUST wrap execution in $effect.root() and invoke the returned cleanup function on destruction. - Services managing long-lived signal graphs MUST implement an explicit destroy() or dispose() method that cleans up all signal subscriptions and active listeners. - Components NEVER attach $effect hooks to external global event emitters or subjects without returning an explicit cleanup callback inside the effect. ## Bad vs Good Implementations ### Module-Scoped Signal Leak vs. Context-Scoped State Factory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Exporting a singleton instance containing runes at the module level attaches the reactive signals to the global process runtime. In SSR environments, this singleton leaks user data across requests, prevents V8 garbage collection of subscriber graphs, and causes hydration mismatches and unbounded memory growth on client route changes. ```typescript // src/lib/stores/session.svelte.ts // FATAL: Top-level module-scoped rune retains memory across all incoming SSR requests // and causes state pollution between different authenticated users in Node.js/SSR runtimes. class GlobalSessionStore { user = $state<{ id: string; name: string } | null>(null); isAuthenticated = $derived(this.user !== null); } export const sessionStore = new GlobalSessionStore(); ``` #### Production Standard (Correct) > **Standard**: Encapsulating rune state within an instantiable class accessed through Svelte's Context API ensures that every SSR render pass and client component tree has a discrete, isolated signal graph. When the component unmounts, the entire context branch is automatically reclaimed by the garbage collector. ```typescript // src/lib/stores/session.svelte.ts import { getContext, setContext } from 'svelte'; export class SessionStore { user = $state<{ id: string; name: string } | null>(null); isAuthenticated = $derived(this.user !== null); constructor(initialUser: { id: string; name: string } | null = null) { this.user = initialUser; } } const SESSION_KEY = Symbol('SESSION_KEY'); export function setSessionStore(initialUser: { id: string; name: string } | null = null): SessionStore { const store = new SessionStore(initialUser); return setContext(SESSION_KEY, store); } export function getSessionStore(): SessionStore { const store = getContext<SessionStore>(SESSION_KEY); if (!store) { throw new Error('SessionStore accessed outside component context hierarchy'); } return store; } ``` ### Standalone Reactive Graph with Explicit $effect.root Teardown #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling $effect outside an active component initialization context fails silently or throws depending on environment, and if called inside an unscoped utility, it creates an unmanaged reactive node that can never be garbage collected, leaking listeners whenever createExternalTracker is called. ```typescript // src/lib/services/tracker.svelte.ts // FATAL: Instantiating reactive roots outside component tree without capture or teardown export function createExternalTracker(sourceSignal: () => number) { let lastVal = $state(0); // Memory leak: This effect persists indefinitely without component lifecycle coupling $effect(() => { lastVal = sourceSignal(); console.log('Value changed:', lastVal); }); return { get value() { return lastVal; } }; } ``` #### Production Standard (Correct) > **Standard**: Wrapping external or dynamic signal operations in $effect.root provides a reference to the graph cleanup routine. Calling cleanup() explicitly cuts all bidirectional edges in the reactive graph, detaching dependencies and permitting immediate V8 garbage collection. ```typescript // src/lib/services/tracker.svelte.ts export interface ExternalTracker { readonly value: number; dispose: () => void; } export function createExternalTracker(sourceSignal: () => number): ExternalTracker { let lastVal = $state(0); // Deterministic isolation: $effect.root creates an explicit ownership boundary const cleanup = $effect.root(() => { $effect(() => { lastVal = sourceSignal(); }); }); return { get value() { return lastVal; }, dispose() { cleanup(); } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Reactive Graph Isolation and SSR Teardown Standard

Svelte 5 Runes Reactive Graph Isolation and SSR Teardown Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces strict boundary encapsulation of Svelte 5 reactive signal graphs within component trees and explicit root scopes. Prohibits global module-scoped rune allocations and untracked dynamic subscriptions that lead to memory leaks in SSR worker threads and retained signal graphs post-hydration. Mandates explicit graph disposal via $effect.root cleanup functions and per-request context factories. 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: Global Module-Level Runes and Unscoped Reactive Signal Graphs in Universal Code 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	Global Module-Level Runes and Unscoped Reactive Signal Graphs in Universal Code	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 NOT declare mutable runes ($state, $derived) at top-level module scope in universal code (.svelte.ts or .ts modules shared between server and client).

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.