Svelte 5 Module-Level Reactive Singletons and Effect Lifecycle Boundaries

--- description: Svelte 5 Module-Level Reactive Singletons and Effect Lifecycle Boundaries - Enforces strict encapsulation and lifecycle boundaries for module-level Svelte 5 runes ($state, $derived) shared across components. Prevents runaway reactive dependencies, dangling untracked effects, and memory leaks by forbidding naked effects in module scope and mandating explicit $effect.root cleanup contracts. globs: src/**/*.svelte.ts, src/**/*.svelte, src/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-runes-module-singleton-lifecycle-boundaries" --- # Svelte 5 Module-Level Reactive Singletons and Effect Lifecycle Boundaries > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Instantiating Naked $effect Calls in Module Scope and Leaking Cross-Component Signal Subscriptions ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes Signal Reactivity Lifecycle Boundaries. Module-level states in `.svelte.ts` files must never instantiate raw `$effect` invocations outside of an explicit `$effect.root()` lifecycle context. Enforce immutable signals, strict teardown methods for shared singletons, untracked boundary safety using `untrack()`, and ensure all reactive synchronization contracts guarantee deterministic garbage collection across component lifecycles. ## Strict Guidelines - Engineers MUST NEVER invoke `$effect()` directly at the top-level or constructor scope of a `.svelte.ts` module singleton; `$effect()` is strictly bound to component mounting lifecycles. - Engineers MUST wrap cross-component reactive synchronization outside components inside an explicit `$effect.root(() => { ... })` boundary and expose a corresponding teardown function. - Module-level stores MUST expose read-only state using getter properties (`get value()`) or `$derived` runes to prevent unintended external mutations from breaking reactivity tracking. - Side effects reading module signals inside listeners MUST explicitly wrap non-dependency signals with `untrack(() => ...)` to avoid cascading reactive recalculations. - Components consuming stateful module singletons with background tasks MUST invoke the singleton's teardown inside `onDestroy` or Svelte 5 `$effect` cleanup returns when bound to local component lifecycles. ## Bad vs Good Implementations ### Module-Level Signal Management and Lifecycle Boundary #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `$effect` inside a module-level class constructor throws a Svelte runtime error outside of component initialization or roots an untracked effect to whichever component first instantiates the module, causing catastrophic state cross-contamination and memory leaks. ```typescript // sessionStore.svelte.ts export class SessionStore { user = $state<{ id: string; role: string } | null>(null); sessionExpiry = $state<number>(Date.now()); constructor() { // VIOLATION: Naked $effect inside class/module scope without lifecycle boundary // This causes runtime exceptions or leaks across SPA navigations $effect(() => { if (this.user) { localStorage.setItem('auth_user', JSON.stringify(this.user)); } }); } } export const session = new SessionStore(); ``` #### Production Standard (Correct) > **Standard**: The updated class encapsulates state behind a getter, encapsulates reactive persistence inside `$effect.root`, insulates side-effects with `untrack`, and provides an explicit `destroy()` method that cleans up all internal signal listeners. ```typescript // sessionStore.svelte.ts import { untrack } from 'svelte'; export class SessionStore { #user = $state<{ id: string; role: string } | null>(null); #cleanup: (() => void) | null = null; get user() { return this.#user; } init(initialUser: { id: string; role: string } | null) { this.#user = initialUser; // COMPLIANT: Explicit effect root created with clean teardown mechanics this.#cleanup = $effect.root(() => { $effect(() => { const currentUser = this.#user; untrack(() => { if (currentUser) { localStorage.setItem('auth_user', JSON.stringify(currentUser)); } else { localStorage.removeItem('auth_user'); } }); }); }); } setUser(user: { id: string; role: string } | null) { this.#user = user; } destroy() { if (this.#cleanup) { this.#cleanup(); this.#cleanup = null; } } } export const session = new SessionStore(); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Module-Level Reactive Singletons and Effect Lifecycle Boundaries

Svelte 5 Module-Level Reactive Singletons and Effect Lifecycle Boundaries defines an industrial-grade behavioral standard for frontend engineering. Enforces strict encapsulation and lifecycle boundaries for module-level Svelte 5 runes ($state, $derived) shared across components. Prevents runaway reactive dependencies, dangling untracked effects, and memory leaks by forbidding naked effects in module scope and mandating explicit $effect.root cleanup contracts. 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: Instantiating Naked $effect Calls in Module Scope and Leaking Cross-Component Signal Subscriptions 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	Instantiating Naked $effect Calls in Module Scope and Leaking Cross-Component Signal Subscriptions	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 invoke `$effect()` directly at the top-level or constructor scope of a `.svelte.ts` module singleton

Engineers MUST NEVER invoke `$effect()` directly at the top-level or constructor scope of a `.svelte.ts` module singleton; `$effect()` is strictly bound to component mounting lifecycles.

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.