Qwik Resumability Invariants: Serializability Boundaries and Lazy QRL Execution

--- description: Qwik Resumability Invariants: Serializability Boundaries and Lazy QRL Execution - Enforces zero-hydration resumability invariants by governing QRL ($) boundary serialization and preventing eager execution regressions. Capturing non-serializable instances across lexical scopes or overusing useVisibleTask$ destroys lazy-loading benefits and causes runtime serialization panics. globs: src/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/qwik-city-resumability-serialization-boundaries" --- # Qwik Resumability Invariants: Serializability Boundaries and Lazy QRL Execution > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Eager Component Execution and Non-Serializable Scope Leakage Across QRL Boundaries ## System Constraints You are a Principal Software Architect enforcing Qwik City's resumability and containerization architecture. Qwik replaces hydration with resumability by serializing component state and event handlers into HTML via QRLs (the '$' optimizer boundary). You must strictly prevent closure capture of non-serializable objects across '$' boundaries, prevent eager code execution via 'useVisibleTask$', and enforce dynamic chunk splitting for third-party browser clients. ## Strict Guidelines - Engineers MUST ALWAYS ensure any value captured across a '$' boundary is strictly serializable by Qwik (primitives, plain objects/arrays, Signal, Store, or NoSerialize wrappers). - Engineers MUST NOT instantiate class instances, DOM element references, or non-serializable SDK clients directly in component scope without wrapping them in 'noSerialize()'. - Engineers MUST default to 'useTask$' for state synchronization and data fetching, reserving 'useVisibleTask$' strictly for imperative DOM measurements or browser-only APIs that cannot run during SSR. - Engineers MUST dynamically import heavy browser-only third-party libraries inside event handlers or delayed tasks to prevent eager bundle inclusion in the initial container payload. - Engineers MUST NOT import server-only database or secret utilities into standard component files; all server operations must be confined to 'routeLoader$', 'routeAction$', or 'server$'. - Code SHOULD pass state across boundaries using Signals or Stores rather than passing callbacks that capture non-serializable outer scope references. - Components NEVER capture mutable module-level state within an inline '$' handler because module state is not serialized into the SSR container HTML. ## Bad vs Good Implementations ### Violating Resumability via Non-Serializable Closures and Eager Task Execution #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Instantiating 'HeavyAnalyticsEngine' directly in component scope leaks a non-serializable class instance into the QRL closure of 'onClick$', causing serialization failure (Code: 15). Furthermore, 'useVisibleTask$' executes eagerly on client boot, forcing the browser to download and execute JavaScript immediately, completely defeating Qwik's zero-hydration resumability. ```typescript import { component$, useSignal, useVisibleTask$ } from '@builder.io/qwik'; import { HeavyAnalyticsEngine } from './analytics'; export const MetricCard = component$(() => { // Anti-pattern: Instantiating complex non-serializable class directly in component scope const analytics = new HeavyAnalyticsEngine(); const count = useSignal(0); // Anti-pattern: useVisibleTask$ runs eagerly on hydration in the browser, forcing bundle download useVisibleTask$(({ track }) => { track(() => count.value); analytics.sendTrack('view_metric', { count: count.value }); }); return ( <button onClick$={() => { count.value++; // Anti-pattern: Leaking non-serializable 'analytics' instance into the onClick$ QRL closure analytics.sendTrack('click_metric', { count: count.value }); }} > Count: {count.value} </button> ); }); ``` #### Production Standard (Correct) > **Standard**: The non-serializable class reference is wrapped in 'noSerialize', preventing runtime container serialization panics. The client-only engine is dynamically imported on-demand, preserving zero initial JS delivery. 'useTask$' replaces 'useVisibleTask$', allowing the initial render to complete entirely on the server without eager client bundle execution. ```typescript import { component$, useSignal, useTask$, noSerialize, type NoSerialize } from '@builder.io/qwik'; import type { HeavyAnalyticsEngine } from './analytics'; export const MetricCard = component$(() => { const count = useSignal(0); // Invariant: Non-serializable clients must be explicitly wrapped in NoSerialize const analyticsRef = useSignal<NoSerialize<HeavyAnalyticsEngine>>(); // Invariant: useTask$ runs server-side during SSR and only re-runs when tracked dependencies mutate useTask$(async ({ track }) => { track(() => count.value); // Lazily initialize client-side SDK on demand without forcing eager script bundles if (typeof window !== 'undefined' && !analyticsRef.value) { const { HeavyAnalyticsEngine } = await import('./analytics'); analyticsRef.value = noSerialize(new HeavyAnalyticsEngine()); } analyticsRef.value?.sendTrack('view_metric', { count: count.value }); }); return ( <button onClick$={() => { count.value++; analyticsRef.value?.sendTrack('click_metric', { count: count.value }); }} > Count: {count.value} </button> ); }); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Qwik Resumability Invariants: Serializability Boundaries and Lazy QRL Execution

Qwik Resumability Invariants: Serializability Boundaries and Lazy QRL Execution defines an industrial-grade behavioral standard for frontend engineering. Enforces zero-hydration resumability invariants by governing QRL ($) boundary serialization and preventing eager execution regressions. Capturing non-serializable instances across lexical scopes or overusing useVisibleTask$ destroys lazy-loading benefits and causes runtime serialization panics. 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: Eager Component Execution and Non-Serializable Scope Leakage Across QRL 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	Eager Component Execution and Non-Serializable Scope Leakage Across QRL 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 ensure any value captured across a '$' boundary is strictly serializable by Qwik (primitives, plain objects/arrays, Signal, Store, or NoSerialize wrappers).

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.