# Resumability (Qwik)

> Skip hydration by serializing state and listeners directly into HTML.

Frontend architecture guidance from fearchitect, written by Abas Turabli and last reviewed 2026-06-21. Source: https://fearchitect.com/topics/resumability-qwik

Use it as reference for the task at hand. Before changing code, check this guidance against the codebase: where the code already makes a different, deliberate choice, flag the conflict instead of rewriting it. Library APIs move faster than this guide, so confirm exact signatures in the official docs linked at the end.

## Summary

Resumability is Qwik's alternative to hydration. The server serializes component state, subscriptions, and event-listener references into the HTML; the browser picks up exactly where the server left off. No JS executes on load — only the handler for the event the user actually triggers is downloaded.

## Diagram

```mermaid
sequenceDiagram
    participant Server
    participant HTML
    participant Browser
    participant ChunkServer as CDN (chunks)

    Server->>HTML: SSR: embed state + on:click="./handler.js#sym"
    HTML->>Browser: Parse — qwikloader registers one global listener
    Note over Browser: Page interactive. Zero component JS executed.
    Browser->>Browser: User clicks button
    Browser->>ChunkServer: Fetch ./handler.js (only this chunk)
    ChunkServer->>Browser: handler.js (~1 KB)
    Browser->>Browser: Execute handler, update signal, patch DOM
```

On load only qwikloader runs; the handler chunk is fetched only on the first click.

## Resume-on-interaction flow

### 1. SSR: serialize everything

Qwik's server renderer writes application state and component subscriptions into a `<script type="qwik/json">` block, and encodes each event listener as a DOM attribute: `on:click="./counter-abc123.js#Counter_onClick_0"`.

### 2. Browser: parse HTML

The browser receives fully-rendered HTML. No framework JS executes. The page is visually complete and readable the instant the HTML parses.

### 3. qwikloader registers one global listener

`qwikloader.js` (~1 KB, inlined) attaches a single event listener to the document. It intercepts every bubbling event and looks up the matching QRL attribute on the target element.

### 4. First user interaction: fetch the handler chunk

qwikloader reads the QRL attribute, fetches that one JS chunk from the CDN, and executes the handler. State is already deserialized — no component re-execution needed.

### 5. Signal update patches the DOM

The handler mutates a `useSignal` value. Qwik's fine-grained reactivity patches only the affected DOM nodes — no full re-render of the component tree.

## Counter with component$ and useSignal

Every `$`-suffixed boundary is split into its own lazy chunk by the optimizer. `useSignal(0)` creates reactive state that is serialized into the HTML on the server and deserialized transparently on the client.

**Counter with useSignal and onClick$**

```tsx
import { component$, useSignal } from "@builder.io/qwik";

export const Counter = component$(() => {
  const count = useSignal(0);

  return (
    <button onClick$={() => count.value++}>
      Count: {count.value}
    </button>
  );
});
```

`useSignal(0)` state is serialized into the HTML. The `onClick$` handler becomes its own chunk — downloaded only when the button is first clicked.

## Tradeoffs

**Pros**

- O(1) Time to Interactive regardless of app size — no JS runs on load.
- Fine-grained lazy loading: only the triggered handler's chunk is downloaded.
- Eliminates hydration waterfalls common in large SSR apps.
- Server state is already the source of truth; no double-data problem.

**Cons**

- First interaction adds a network round-trip to fetch the handler chunk.
- The optimizer and dollar-boundary rules add build complexity.
- Ecosystem is smaller than React/Vue — fewer libraries, less community tooling.
- Mental model shift: developers must internalize the $ boundary and serialization rules.

## Watch out: $ boundary rules are strict

Passing non-serializable values (closures, class instances) across a `$` boundary causes a runtime error. Importing a large library inside a `$` callback pulls the whole library into that chunk, defeating lazy loading.

## Key terms

- **Resumability**: Skipping hydration by serializing app state and listener references into HTML for instant startup.
- **QRL (Qwik URL)**: A lazy, serializable reference to a code chunk encoded as a URL + exported symbol (e.g. `./chunk.js#Symbol`), stored as a DOM attribute so Qwik lazy-loads code without running JS upfront.
- **Dollar boundary ($)**: The Qwik optimizer marker that splits a function into its own lazy-loaded chunk.
- **useSignal**: A Qwik hook that returns a reactive `Signal<T>` whose `.value` is serialized into HTML.
- **qwikloader**: A ~1 KB global script that intercepts DOM events and fetches the matching handler chunk on demand.

## Related topics

- [Hydration Strategies & Islands](https://fearchitect.com/topics/hydration-and-islands.md): Pay JS cost only for interactive regions, not the whole page.
- [React Server Components](https://fearchitect.com/topics/react-server-components.md): Server-rendered components that ship zero JS to the browser.
- [Partial Prerendering (PPR)](https://fearchitect.com/topics/partial-prerendering.md): Static CDN shell plus dynamic Suspense holes in one response.
- [Rendering Strategies: CSR / SSR / SSG / ISR](https://fearchitect.com/topics/rendering-strategies.md): Where and when HTML is generated: build, request, browser, or revalidated.
- [Streaming SSR](https://fearchitect.com/topics/streaming-ssr.md): Flush the HTML shell immediately, then stream the rest as Suspense resolves.

## Further reading

- [Qwik — Resumable vs Replayable](https://qwik.dev/docs/concepts/resumable/)
- [Qwik — Think Qwik](https://qwik.dev/docs/think-qwik/)
- [Qwik — Components overview](https://qwik.dev/docs/components/overview/)