Svelte 5 Runes Async Effect Teardown & Untracked Invariants

--- description: Svelte 5 Runes Async Effect Teardown & Untracked Invariants - Enforces synchronous cleanup registration in Svelte 5 $effect runes and explicit lifecycle cancellation boundaries. Prevents orphaned reactive subscriptions, uncollected event listeners, and post-unmount microtask race conditions caused by asynchronous effect callbacks. globs: src/**/*.svelte, src/**/*.svelte.ts, src/**/*.svelte.js, src/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-async-effect-teardown-invariants" --- # Svelte 5 Runes Async Effect Teardown & Untracked Invariants > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Passing Async Callbacks to $effect Runes and Omitting Synchronous Teardown Handlers ## System Constraints You are a Principal Software Architect enforcing Svelte 5 reactive graph invariants and memory hygiene. You must reject any usage of async functions passed directly to $effect or $effect.pre, ensure teardown callbacks are returned synchronously on the first tick, require AbortController patterns for asynchronous operations, and mandate untrack() for non-dependent reactive reads executed across microtask boundaries. ## Strict Guidelines - Engineers MUST NEVER pass an async function directly as the argument to $effect() or $effect.pre() because an async function returns a Promise, permanently discarding the teardown/cleanup contract. - Engineers MUST ALWAYS return a synchronous cleanup function directly from the root frame of $effect() when initiating asynchronous microtasks, event subscriptions, or timers. - Asynchronous operations initiated inside $effect() MUST be bound to an AbortController instance created synchronously in that effect run and triggered inside the returned teardown closure. - State assignments following an `await` tick MUST verify cancellation status (e.g., `!controller.signal.aborted`) before mutating any $state rune to prevent post-dismount state corruption and memory leaks. - Reactive dependencies accessed after an `await` tick MUST NOT be assumed to be tracked; engineers MUST explicitly read reactive dependencies synchronously at the top of the effect or explicitly decouple secondary reads using `untrack()`. - Components NEVER invoke unmanaged background promises inside $effect.root() without an explicit manual disposal pattern returned to the caller. ## Bad vs Good Implementations ### Asynchronous Data Fetching with Proper Teardown and Signal Guarding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Async functions implicitly return Promises. Svelte 5 expects a cleanup function or void from the effect callback; returning a Promise causes Svelte to ignore teardown registration entirely. Concurrent fetches race to overwrite state, and post-unmount microtask execution leaks memory and mutates orphaned graph nodes. ```typescript import { fetchUserData } from '$lib/api'; let userId = $state('usr_102'); let profile = $state<UserProfile | null>(null); // ANTI-PATTERN: Passing an async arrow function directly to $effect. // 1. Returns a Promise<void>; the teardown function cannot be registered. // 2. userId updates trigger new fetches while previous fetches remain in-flight (race condition). // 3. Dismounting during fetch causes post-unmount mutation to reactive graph. $effect(async () => { const data = await fetchUserData(userId); profile = data; }); ``` #### Production Standard (Correct) > **Standard**: The effect callback remains synchronous, ensuring the returned teardown function is immediately registered in Svelte 5's internal effect record. Stale fetches are canceled via AbortController before the next effect run, and signal checks prevent state mutation after dismount. ```typescript import { untrack } from 'svelte'; import { fetchUserData } from '$lib/api'; let userId = $state('usr_102'); let profile = $state<UserProfile | null>(null); // PRODUCTION STANDARD: Synchronous effect body with synchronous teardown closure. $effect(() => { // 1. Synchronously capture dependencies on the reactive tick const currentId = userId; const controller = new AbortController(); // 2. Dispatch self-contained async routine with cancellation signal (async () => { try { const data = await fetchUserData(currentId, { signal: controller.signal }); if (!controller.signal.aborted) { profile = data; } } catch (error: unknown) { if (error instanceof DOMException && error.name === 'AbortError') { return; } console.error('Failed to resolve profile for', currentId, error); } })(); // 3. Synchronously return teardown to abort stale microtasks upon re-run or unmount return () => { controller.abort(); }; }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async Effect Teardown & Untracked Invariants

Svelte 5 Runes Async Effect Teardown & Untracked Invariants defines an industrial-grade behavioral standard for frontend engineering. Enforces synchronous cleanup registration in Svelte 5 $effect runes and explicit lifecycle cancellation boundaries. Prevents orphaned reactive subscriptions, uncollected event listeners, and post-unmount microtask race conditions caused by asynchronous effect callbacks. 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: Passing Async Callbacks to $effect Runes and Omitting Synchronous Teardown Handlers 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	Passing Async Callbacks to $effect Runes and Omitting Synchronous Teardown Handlers	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 as the argument to $effect() or $effect.pre() because an async function returns a Promise, permanently discarding the teardown/cleanup contract.

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.