Svelte 5 Universal Runes SSR Isolation and Reactive Root Lifecycle Invariant

--- description: Svelte 5 Universal Runes SSR Isolation and Reactive Root Lifecycle Invariant - Enforces strict isolation of Svelte 5 universal runes ($state, $derived) and explicit lifecycle disposal of $effect.root instances during SSR. Prohibits module-level reactive state singletons in server runtimes to prevent cross-request memory retention, data contamination across tenants, and unbounded heap exhaustion. 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-ssr-lifecycle-isolation" --- # Svelte 5 Universal Runes SSR Isolation and Reactive Root Lifecycle Invariant > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Global Module-Scoped Runes and Orphaned Effect Roots Inducing Cross-Request SSR State Leakage ## System Constraints You are a Principal Software Architect enforcing zero-leak Svelte 5 runes architecture in server-rendered environments. You must detect and eliminate any global module-level reactive state ($state, $state.raw) in files reachable by SSR, mandate Svelte Context-based dependency injection for stateful runes, and enforce deterministic cleanup functions for all manual $effect.root invocations. ## Strict Guidelines - Engineers MUST NEVER declare module-level universal reactive state (`export const state = $state(...)` or top-level `$state` in `.svelte.ts`/`.ts` files) when executing in SSR environments; state MUST be scoped to Svelte component contexts via `setContext`/`getContext` or instantiated within request-scoped lifecycle boundaries. - Engineers MUST ALWAYS invoke and store the cleanup closure returned by `$effect.root(() => ...)` and guarantee execution of `cleanup()` in teardown paths when managing non-component reactive computations. - Components and server-side utilities MUST NOT invoke `$effect` or `$effect.pre` expecting execution during SSR; all imperative server setup logic MUST reside in SvelteKit `load` functions or standard async functions. - Classes utilizing Svelte 5 runes (`$state`, `$derived`) MUST be instantiated inside component initialization trees or request contexts (such as `event.locals`), NEVER as global module-scoped singletons. - Engineers MUST wrap SSR-shared store factories in dedicated context keys using `Symbol()` to guarantee type safety and prevent shared runtime reference mutation across concurrent incoming HTTP requests. - Code creating detached reactive scopes MUST explicitly enforce boundary termination using `try...finally` blocks to guarantee `$effect.root` cleanup execution even in the event of unhandled exceptions. ## Bad vs Good Implementations ### Module-Scoped Runes vs. Context-Isolated Request Stores #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In SSR runtimes (Node.js, Bun, Cloudflare Workers), module-level exports are singletons evaluated once per worker lifecycle. Exporting a single instance with runes leaks the authenticated user's state to subsequent incoming requests from other users and leaks memory across the lifetime of the process. ```typescript // src/lib/stores/user-session.svelte.ts // CRITICAL FLAW: Module-level $state persists across concurrent SSR requests in Node/Bun runtimes class SessionStore { user = $state<{ id: string; name: string } | null>(null); isAuthenticated = $derived(this.user !== null); } // Leaks tenant data across requests and causes unbounded memory retention export const sessionStore = new SessionStore(); ``` #### Production Standard (Correct) > **Standard**: The store is decoupled from global scope. By encapsulating state initialization inside Svelte's context boundary (`setContext`/`getContext`), the reactive instance is tied exclusively to the component tree of the current SSR render request and is safely garbage-collected when the request finishes. ```typescript // src/lib/stores/user-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('USER_SESSION_STORE'); export function setSessionStore(initialUser: { id: string; name: string } | null): SessionStore { const store = new SessionStore(initialUser); return setContext(SESSION_KEY, store); } export function getSessionStore(): SessionStore { const store = getContext<SessionStore | undefined>(SESSION_KEY); if (!store) { throw new Error('SessionStore accessed outside of component context boundary.'); } return store; } ``` ### Unmanaged $effect.root vs. Deterministic Disposed Effect Tree #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling $effect.root creates an independent reactive root. Failing to return or execute the cleanup function traps all referenced variables in the active reactive graph, preventing garbage collection and generating memory leaks in long-running Node.js processes. ```typescript // src/lib/utils/reactive-worker.ts // CRITICAL FLAW: $effect.root created without cleanup capture leaks memory across SSR / async tasks export function createExternalWatcher(source: () => number, callback: (val: number) => void) { $effect.root(() => { $effect(() => { callback(source()); }); }); // Return nothing: effect root remains active, anchoring references to callback and source in memory } ``` #### Production Standard (Correct) > **Standard**: Wraps $effect.root in an explicit lifecycle handle, capturing the returned teardown closure and exposing an idempotent dispose method. This guarantees reactive boundaries can be destroyed immediately when the request or background work concludes. ```typescript // src/lib/utils/reactive-worker.ts export interface ReactiveScopeHandle { dispose: () => void; } export function createExternalWatcher( source: () => number, callback: (val: number) => void ): ReactiveScopeHandle { let cleanup: (() => void) | undefined; try { cleanup = $effect.root(() => { $effect(() => { callback(source()); }); }); } catch (err) { if (cleanup) cleanup(); throw err; } return { dispose: () => { if (cleanup) { cleanup(); cleanup = undefined; } } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Universal Runes SSR Isolation and Reactive Root Lifecycle Invariant

Svelte 5 Universal Runes SSR Isolation and Reactive Root Lifecycle Invariant defines an industrial-grade behavioral standard for frontend engineering. Enforces strict isolation of Svelte 5 universal runes ($state, $derived) and explicit lifecycle disposal of $effect.root instances during SSR. Prohibits module-level reactive state singletons in server runtimes to prevent cross-request memory retention, data contamination across tenants, and unbounded heap exhaustion. 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-Scoped Runes and Orphaned Effect Roots Inducing Cross-Request SSR State Leakage 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-Scoped Runes and Orphaned Effect Roots Inducing Cross-Request SSR State Leakage	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 NEVER declare module-level universal reactive state (`export const state = $state(...)` or top-level `$state` in `.svelte.ts`/`.ts` files) when executing in SSR environments

Engineers MUST NEVER declare module-level universal reactive state (`export const state = $state(...)` or top-level `$state` in `.svelte.ts`/`.ts` files) when executing in SSR environments; state MUST be scoped to Svelte component contexts via `setContext`/`getContext` or instantiated within request-scoped lifecycle boundaries.

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.