Svelte 5 Universal Runes SSR Isolation and Memory Leak Prevention

--- description: Svelte 5 Universal Runes SSR Isolation and Memory Leak Prevention - Enforces strict request-scoped lifecycle boundaries on Svelte 5 universal reactive runes ($state, $derived) within .svelte.ts modules. Prohibits module-level reactive singletons and unmanaged $effect.root allocations that persist across concurrent SSR requests and cause multi-tenant cross-contamination or memory 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-universal-runes-ssr-memory-isolation" --- # Svelte 5 Universal Runes SSR Isolation and Memory Leak Prevention > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Module-scoped universal runes persisting across concurrent SSR requests, causing data cross-contamination and heap leaks. ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Universal Runes SSR Memory Isolation. You must ensure that no reactive rune state or $effect.root escapes request-level boundaries in server-side rendering contexts. Module-level reactive state singletons in .svelte.ts files share memory across concurrent tenant requests on Node.js/Bun servers, leading to critical cross-tenant data leaks and unbounded memory growth. Enforce factory patterns coupled with Svelte's Context API or request-bound dependency injection containers. ## Strict Guidelines - Engineers MUST NOT declare module-scope mutable runes ($state, $state.raw) in universal '.svelte.ts' or '.svelte.js' modules. - Engineers MUST instantiate stateful rune classes/factories strictly inside component lifecycles, route load functions, or via Svelte's Context API (setContext/getContext). - Services that manage tenant or session data MUST encapsulate runes within explicit class instances created per request, never as exported global instances. - Engineers MUST ALWAYS invoke the teardown function returned by $effect.root() when explicitly spawned in non-component universal code. - Components NEVER rely on module-level shared collections (such as global Maps or Arrays) tracking rune dependencies on the server. - Code SHOULD leverage read-only immutable projections across boundaries where reactivity is not required on the server. - Engineers MUST verify that any global caches storing rune-based objects feature time-to-live (TTL) eviction or WeakRef mapping to prevent retained heap graphs. ## Bad vs Good Implementations ### Universal Store: Module Singleton vs Request Context Factory #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring `$state()` at the top-level of a `.svelte.ts` module binds the reactive proxy to the Node.js runtime process rather than an isolated request. In a multi-tenant SSR environment, concurrent requests will read and mutate this exact same instance, exposing sensitive tenant data and accumulating listeners that will never be garbage-collected. ```typescript // src/lib/stores/user-session.svelte.ts // CRITICAL FLAW: Module-scoped rune persists across concurrent SSR requests in Node/Bun. // Tenant A's session is retained and served to Tenant B. export const sessionStore = $state({ userId: null as string | null, role: 'guest', permissions: [] as string[] }); export function setSession(userId: string, role: string, permissions: string[]) { sessionStore.userId = userId; sessionStore.role = role; sessionStore.permissions = permissions; } ``` #### Production Standard (Correct) > **Standard**: Encapsulates reactive rune state into an instantiable class tied to Svelte's Context API (`setContext`/`getContext`). Each SSR render tree receives its own isolated instance that is automatically eligible for garbage collection when the request finishes rendering, guaranteeing strict memory isolation between tenants. ```typescript // src/lib/stores/user-session.svelte.ts import { getContext, setContext } from 'svelte'; interface SessionData { userId: string | null; role: string; permissions: string[]; } export class UserSession { #data = $state<SessionData>({ userId: null, role: 'guest', permissions: [] }); constructor(initialData?: Partial<SessionData>) { if (initialData) { Object.assign(this.#data, initialData); } } get userId() { return this.#data.userId; } get role() { return this.#data.role; } get permissions() { return this.#data.permissions; } update(data: Partial<SessionData>) { Object.assign(this.#data, data); } } const SESSION_CONTEXT_KEY = Symbol('USER_SESSION_CONTEXT'); export function initSessionContext(initialData?: Partial<SessionData>): UserSession { const session = new UserSession(initialData); setContext(SESSION_CONTEXT_KEY, session); return session; } export function getSessionContext(): UserSession { const session = getContext<UserSession>(SESSION_CONTEXT_KEY); if (!session) { throw new Error('UserSession context requested outside active component tree.'); } return session; } ``` ### Managing $effect.root Lifecycles in Universal Helpers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking `$effect.root()` without retaining its cleanup handle leaks reactive observer nodes and signal dependencies. While standard `$effect` does not execute during SSR, `$effect.root` will execute anywhere it is called, leaving orphaned tracking roots that never clean up their subscriptions. ```typescript // src/lib/observables/external-sync.svelte.ts export function observeDataStream(streamSource: { subscribe: (fn: (val: any) => void) => () => void }) { // CRITICAL FLAW: $effect.root spawned without lifecycle management or teardown. // On SSR, each call permanently leaks reactive computation nodes into the runtime heap. $effect.root(() => { let count = $state(0); streamSource.subscribe((val) => { count = val; }); }); } ``` #### Production Standard (Correct) > **Standard**: Retains the cleanup callback from `$effect.root()`, unhooks external data sources, and ties teardown deterministically to `onDestroy` while also exposing an explicit `destroy()` method for manual scope management outside component trees. ```typescript // src/lib/observables/external-sync.svelte.ts import { onDestroy } from 'svelte'; export function createManagedDataStream(streamSource: { subscribe: (fn: (val: any) => void) => () => void }) { let count = $state(0); let unsubscribeSource: (() => void) | undefined; // Return a bound dispose method and bind to Svelte component lifecycle if available const cleanupRoot = $effect.root(() => { unsubscribeSource = streamSource.subscribe((val) => { count = val; }); }); const teardown = () => { if (unsubscribeSource) unsubscribeSource(); cleanupRoot(); }; try { onDestroy(teardown); } catch { // Non-component invocation; consumer must manually invoke returned teardown } return { get count() { return count; }, destroy: teardown }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Universal Runes SSR Isolation and Memory Leak Prevention

Svelte 5 Universal Runes SSR Isolation and Memory Leak Prevention defines an industrial-grade behavioral standard for frontend engineering. Enforces strict request-scoped lifecycle boundaries on Svelte 5 universal reactive runes ($state, $derived) within .svelte.ts modules. Prohibits module-level reactive singletons and unmanaged $effect.root allocations that persist across concurrent SSR requests and cause multi-tenant cross-contamination or memory 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: Module-scoped universal runes persisting across concurrent SSR requests, causing data cross-contamination and heap leaks. 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	Module-scoped universal runes persisting across concurrent SSR requests, causing data cross-contamination and heap leaks.	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 module-scope mutable runes ($state, $state.raw) in universal '.svelte.ts' or '.svelte.js' modules.

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.