Svelte 5 Runes Async Derived State & Effect Teardown Standard

--- description: Svelte 5 Runes Async Derived State & Effect Teardown Standard - Enforces synchronous execution boundaries across Svelte 5 runes and mandates deterministic teardown with AbortController for asynchronous work initiated in $effect. Prevents silent memory leaks, orphaned network requests, and stale-state race conditions caused by async callbacks returning Promises instead of synchronous cleanup handlers. globs: src/**/*.{svelte,svelte.ts,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/svelte-5-async-derived-effect-teardown" --- # Svelte 5 Runes Async Derived State & Effect Teardown Standard > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Async Callback Directly Passed to $effect and Async Functions in $derived.by ## System Constraints You are a Principal Software Architect enforcing production reliability in Svelte 5 applications. You must enforce that $effect callbacks are strictly synchronous functions that return synchronous cleanup handlers or undefined. You must reject any usage of async functions as root callbacks in $effect, prohibit async functions inside $derived.by, and require explicit AbortController teardowns to prevent race conditions during reactive dependency updates. ## Strict Guidelines - Engineers MUST NEVER provide an async function directly as the root callback to `$effect`, `$effect.pre`, or `$effect.root`, because an async function returns a Promise, causing Svelte to drop teardown functions entirely. - Engineers MUST instantiate an `AbortController` synchronously at the start of any `$effect` triggering asynchronous I/O and return a synchronous teardown function `() => controller.abort()`. - Engineers MUST NOT declare `$derived.by(async () => ...)` to compute state, as derived runes must be pure, synchronous projections; asynchronous results must be managed via explicit `$state` mutated within an abortable `$effect` or handled via Svelte template `{#await}` blocks. - Code MUST guard all async state updates against cancelled signals (e.g., checking `signal.aborted` before mutating `$state`) to prevent out-of-order asynchronous resolution from clobbering newer state. - Services and custom rune utilities MUST encapsulate async resource lifecycles into typed reactive abstractions that expose read-only state and automatically handle cancellation upon destruction. ## Bad vs Good Implementations ### Async Effect Teardown with AbortController #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Declaring the $effect callback as async causes it to return a Promise that resolves to the cleanup function. Svelte requires the cleanup function to be returned synchronously; wrapping it in a Promise results in Svelte discarding the teardown handler, leading to orphaned network requests and stale data overwriting newer responses. ```typescript import { $state, $effect } from 'svelte'; let userId = $state('user-1'); let profile = $state<Profile | null>(null); // ANTI-PATTERN: async effect root callback returns Promise<() => void> // Svelte drops the returned cleanup function, causing leaks and race conditions $effect(async () => { const res = await fetch(`/api/users/${userId}`); const data = await res.json(); profile = data; return () => { // This will NEVER execute on userId change or component unmount console.log('Cleanup never called'); }; }); ``` #### Production Standard (Correct) > **Standard**: The $effect callback is strictly synchronous and returns a synchronous teardown closure that invokes controller.abort(). Inflight network operations are cancelled when userId changes or the component unmounts, and the signal check guarantees no out-of-order state mutations. ```typescript import { $state, $effect } from 'svelte'; let userId = $state('user-1'); let profile = $state<Profile | null>(null); let isLoading = $state(false); let error = $state<Error | null>(null); $effect(() => { const controller = new AbortController(); const { signal } = controller; const currentUserId = userId; isLoading = true; error = null; fetch(`/api/users/${currentUserId}`, { signal }) .then(async (res) => { if (!res.ok) throw new Error(`HTTP error ${res.status}`); return res.json(); }) .then((data: Profile) => { if (!signal.aborted) { profile = data; isLoading = false; } }) .catch((err: unknown) => { if (!signal.aborted) { error = err instanceof Error ? err : new Error(String(err)); isLoading = false; } }); // Synchronous teardown: aborts inflight requests before next run or unmount return () => { controller.abort(); }; }); ``` ### Encapsulating Async State in Custom Runes Instead of Async $derived.by #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: $derived and $derived.by must be pure, synchronous projections. Passing an async function stores an unmanaged Promise in the rune, which requires manual .then chaining or template {#await} without offering any teardown mechanism to cancel previous queries when query changes. ```typescript import { $state, $derived } from 'svelte'; let query = $state(''); // ANTI-PATTERN: $derived.by does not await promises; searchResults becomes Promise<Item[]> // This creates unhandled promise lifecycles, memory leaks, and race conditions const searchResults = $derived.by(async () => { if (!query) return []; const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`); return res.json(); }); ``` #### Production Standard (Correct) > **Standard**: The custom rune utility decouples reactivity from promise handling. It provides a synchronous interface (getters) around fine-grained $state, orchestrates asynchronous fetching within $effect, and guarantees teardown via AbortController. ```typescript import { $state, $effect } from 'svelte'; export function useSearch(getQuery: () => string) { let data = $state<Item[]>([]); let loading = $state(false); let error = $state<Error | null>(null); $effect(() => { const q = getQuery(); if (!q) { data = []; loading = false; return; } const controller = new AbortController(); loading = true; error = null; fetch(`/api/search?q=${encodeURIComponent(q)}`, { signal: controller.signal }) .then(async (res) => { if (!res.ok) throw new Error(`Search failed: ${res.statusText}`); return res.json(); }) .then((items: Item[]) => { if (!controller.signal.aborted) { data = items; loading = false; } }) .catch((err: unknown) => { if (!controller.signal.aborted) { error = err instanceof Error ? err : new Error(String(err)); loading = false; } }); return () => { controller.abort(); }; }); return { get data() { return data; }, get loading() { return loading; }, get error() { return error; } }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Svelte 5 Runes Async Derived State & Effect Teardown Standard

Svelte 5 Runes Async Derived State & Effect Teardown Standard defines an industrial-grade behavioral standard for frontend engineering. Enforces synchronous execution boundaries across Svelte 5 runes and mandates deterministic teardown with AbortController for asynchronous work initiated in $effect. Prevents silent memory leaks, orphaned network requests, and stale-state race conditions caused by async callbacks returning Promises instead of synchronous cleanup handlers. 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: Async Callback Directly Passed to $effect and Async Functions in $derived.by 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	Async Callback Directly Passed to $effect and Async Functions in $derived.by	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 provide an async function directly as the root callback to `$effect`, `$effect.pre`, or `$effect.root`, because an async function returns a Promise, causing Svelte to drop teardown functions entirely.

Engineers MUST NEVER provide an async function directly as the root callback to `$effect`, `$effect.pre`, or `$effect.root`, because an async function returns a Promise, causing Svelte to drop teardown functions entirely.

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.