Svelte 5 Runes Async Lifecycle & $effect.root Teardown Standard

--- description: Svelte 5 Runes Async Lifecycle & $effect.root Teardown Standard - Enforces deterministic teardown of reactive dependencies and effects across asynchronous execution contexts and non-component modules in Svelte 5. Prevents catastrophic client-side memory leaks and zombie listeners caused by orphaned effects spawned across microtask boundaries or outside owner hierarchies. 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-async-lifecycle-effect-root-teardown" --- # Svelte 5 Runes Async Lifecycle & $effect.root Teardown Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Orphaned Reactive Effects via Async Microtasks and Unscoped Non-Component Root Subscriptions ## System Constraints You are a Principal Software Architect enforcing Svelte 5 Runes lifecycle safety. You must mandate deterministic teardown for all reactive dependencies, forbidding async functions as direct $effect callbacks and requiring $effect.root encapsulation for effects instantiated outside synchronous component initialization. ## Strict Guidelines - Engineers MUST NEVER pass an async function directly to `$effect()` or `$effect.pre()`, because returning a Promise prevents Svelte from registering the synchronous teardown function. - Engineers MUST instantiate an `AbortController` or explicit cancellation token synchronously within `$effect()` and invoke `controller.abort()` in the returned teardown closure to cancel pending asynchronous tasks. - Engineers MUST ALWAYS wrap reactive effects instantiated in non-component contexts (such as external state machines, classes in `.svelte.ts`, or global services) inside `$effect.root()`. - Engineers MUST explicitly capture and expose the cleanup function returned by `$effect.root()`, ensuring consumers invoke it during view transitions, route changes, or component unmounts. - Engineers MUST NOT spawn `$effect` or `$derived` declarations across asynchronous microtask boundaries (e.g., following an `await` statement or inside `setTimeout`), as the reactive owner context will be lost. - Components and services MUST use `untrack()` when reading transient signals inside an effect that should not re-trigger the asynchronous workflow. ## Bad vs Good Implementations ### Asynchronous Effect with Deterministic Abort Teardown #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing an async function to $effect causes it to return a Promise instead of a teardown function. Svelte 5 ignores Promise returns for teardown, causing in-flight network responses to mutate state after component unmount, leaking memory and producing stale UI updates. ```typescript import { $effect, $state } from 'svelte'; export function useLiveUserQuery(userId: () => string) { let user = $state<any>(null); // CRITICAL BUG: Async callback returns Promise<() => void>, bypassing cleanup registration $effect(async () => { const id = userId(); const res = await fetch(`/api/users/${id}`); user = await res.json(); return () => { // This cleanup is unreachable and never called by Svelte runtime console.log('Cleanup never executed'); }; }); return { get user() { return user; } }; } ``` #### Production Standard (Correct) > **Standard**: The effect callback is synchronous and immediately returns a cleanup function that triggers AbortController.abort(). The async task is safely encapsulated, preventing orphaned state mutations on rapid transitions. ```typescript import { $effect, $state, untrack } from 'svelte'; export function useLiveUserQuery(userId: () => string) { let user = $state<any>(null); $effect(() => { const id = userId(); const controller = new AbortController(); async function fetchUser() { try { const res = await fetch(`/api/users/${id}`, { signal: controller.signal }); if (!res.ok) throw new Error('Fetch failed'); const data = await res.json(); // Guard against writing if cancelled if (!controller.signal.aborted) { user = data; } } catch (err: unknown) { if ((err as Error).name !== 'AbortError') { throw err; } } } fetchUser(); // Synchronous teardown returned to Svelte's reactive engine return () => { controller.abort(); }; }); return { get user() { return user; } }; } ``` ### Stateful Service Isolation via $effect.root Outside Component Tree #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking $effect directly in a class or external utility without an active component owner fails or produces an orphan effect that cannot be automatically collected, leaking the DOM event listener permanently across view lifecycles. ```typescript import { $state, $effect } from 'svelte'; export class ViewportTracker { width = $state(typeof window !== 'undefined' ? window.innerWidth : 0); constructor() { // CRITICAL BUG: Creating $effect outside component boundary without owner scope // triggers Svelte runtime error 'effect_orphan' or creates an uncollected memory leak $effect(() => { const onResize = () => { this.width = window.innerWidth; }; window.addEventListener('resize', onResize); return () => window.removeEventListener('resize', onResize); }); } } ``` #### Production Standard (Correct) > **Standard**: $effect.root isolates and manages the reactive tree manually, returning a deterministic disposal function. Consumers can destroy the tracker during onMount teardown or page unloads, cleanly deregistering all reactive listeners. ```typescript import { $state, $effect } from 'svelte'; export class ViewportTracker { width = $state(typeof window !== 'undefined' ? window.innerWidth : 0); private cleanup: (() => void) | null = null; constructor() { // Explicitly establish an un-parented reactive root scope this.cleanup = $effect.root(() => { $effect(() => { const onResize = () => { this.width = window.innerWidth; }; window.addEventListener('resize', onResize); return () => window.removeEventListener('resize', onResize); }); }); } destroy(): void { if (this.cleanup) { this.cleanup(); this.cleanup = null; } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async Lifecycle & $effect.root Teardown Standard

Svelte 5 Runes Async Lifecycle & $effect.root Teardown Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic teardown of reactive dependencies and effects across asynchronous execution contexts and non-component modules in Svelte 5. Prevents catastrophic client-side memory leaks and zombie listeners caused by orphaned effects spawned across microtask boundaries or outside owner hierarchies. 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: Orphaned Reactive Effects via Async Microtasks and Unscoped Non-Component Root 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	Orphaned Reactive Effects via Async Microtasks and Unscoped Non-Component Root 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 pass an async function directly to `$effect()` or `$effect.pre()`, because returning a Promise prevents Svelte from registering the synchronous teardown 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.