Svelte 5 Universal Runes Boundary & Effect Destruction Invariants

--- description: Svelte 5 Universal Runes Boundary & Effect Destruction Invariants - Enforces strict lifecycle ownership, root scoping ($effect.root), and deterministic cleanup protocols for universal runes (.svelte.ts) spanning SSR hydration boundaries and component unmount lifecycles. Prevents reactive graph leaks, cross-request state contamination, and orphaned effect subscriptions in nested state domains. 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-boundary-effect-destruction" --- # Svelte 5 Universal Runes Boundary & Effect Destruction Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded Universal Effects and Leaked Nested Reactive Scopes Across Hydration Boundaries ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Universal Runes Boundary & Effect Destruction Invariants. Svelte 5 introduces universal runes ($state, $derived) in `.svelte.ts` files, allowing reactive business logic outside `.svelte` components. However, executing side-effects within universal stores requires strict architectural boundaries: `$effect` cannot run during SSR and will crash or leak if instantiated outside an active tracking context. Furthermore, universal classes managing internal reactive synchronization MUST wrap effects in `$effect.root()` and expose deterministic teardown hooks (`destroy()`). Never create shared global rune instances that retain per-request client data across SSR requests. ## Strict Guidelines - Engineers MUST ALWAYS wrap non-component reactive side-effects in `$effect.root()` within universal `.svelte.ts` modules and store the returned cleanup function. - Engineers MUST ALWAYS expose a deterministic `destroy()` or cleanup method on universal rune classes that executes the `$effect.root` disposal function and clears nested collections. - Engineers MUST NOT invoke bare `$effect` or `$effect.pre` inside `.svelte.ts` class constructors or standalone module functions; these runes only function inside active component effect tracking contexts. - Engineers MUST NOT declare mutable `$state` singletons at the root module scope in SSR-enabled applications, as this introduces cross-request state pollution and race conditions across concurrent server requests. - Components MUST bind universal state lifecycle to the component tree using Svelte's `onDestroy` or `$effect` unmount return callback to guarantee complete garbage collection of reactive nodes upon teardown. - Code MUST isolate browser-only APIs (window, document, storage, WebSockets) behind explicit runtime environment guards (`browser` checks from `$app/environment`) to prevent hydration mismatches and SSR execution failures. ## Bad vs Good Implementations ### Universal Reactive Store with Leaked Effects vs Controlled Effect Root Lifecycle #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly calling `$effect` inside a universal class constructor throws an error during server-side rendering (SSR) because effects do not run on the server. On the client, this effect lacks an encompassing component scope, creating an orphaned reactive computation that cannot be garbage collected. Exporting a shared module singleton causes concurrent SSR requests to read and mutate the exact same reactive proxy. ```typescript // src/lib/stores/workspace.svelte.ts // ANTI-PATTERN: Leaks effect root, crashes during SSR, and pollutes module scope export class WorkspaceSyncManager { items = $state<string[]>([]); activeCount = $derived(this.items.length); constructor() { // CRITICAL BUG: Direct $effect in a universal class throws on SSR // and creates an un-garbage-collected tracking node on the client $effect(() => { localStorage.setItem('workspace_cache', JSON.stringify(this.items)); }); } addItem(item: string) { this.items.push(item); } } // Leaked global singleton shared across SSR worker threads export const globalWorkspace = new WorkspaceSyncManager(); ``` #### Production Standard (Correct) > **Standard**: The refactored code safely separates initialization from SSR instantiation. Effects are encapsulated in an isolated `$effect.root()`, providing an explicit teardown function. The consuming Svelte component or context provider can deterministically call `destroy()` on unmount, completely pruning the reactive dependency graph and preventing micro-memory leaks. ```typescript // src/lib/stores/workspace.svelte.ts import { browser } from '$app/environment'; export class WorkspaceSyncManager { items = $state<string[]>([]); activeCount = $derived(this.items.length); #cleanup: (() => void) | null = null; constructor(initialItems: string[] = []) { this.items = initialItems; } /** * Explicitly initializes effects within a safe root boundary on the client. * Returns the disposal function for component unmount synchronization. */ init(): () => void { if (!browser || this.#cleanup) { return () => {}; } // Establish isolated reactive tracking context this.#cleanup = $effect.root(() => { $effect(() => { localStorage.setItem('workspace_cache', JSON.stringify(this.items)); }); return () => { // Sub-cleanup if specific listeners were bound }; }); return () => this.destroy(); } addItem(item: string): void { this.items.push(item); } destroy(): void { if (this.#cleanup) { this.#cleanup(); this.#cleanup = null; } this.items = []; } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Universal Runes Boundary & Effect Destruction Invariants

Svelte 5 Universal Runes Boundary & Effect Destruction Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces strict lifecycle ownership, root scoping ($effect.root), and deterministic cleanup protocols for universal runes (.svelte.ts) spanning SSR hydration boundaries and component unmount lifecycles. Prevents reactive graph leaks, cross-request state contamination, and orphaned effect subscriptions in nested state domains. 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: Unbounded Universal Effects and Leaked Nested Reactive Scopes Across Hydration Boundaries 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	Unbounded Universal Effects and Leaked Nested Reactive Scopes Across Hydration Boundaries	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 wrap non-component reactive side-effects in `$effect.root()` within universal `.svelte.ts` modules and store the returned cleanup function.

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.