Qwik Resumability: Architecture Note on Minimal Serialization and Runtime Checks

Problem

When a server‑rendered Qwik page is delivered to the browser, the goal is to make the UI interactive instantly without re‑executing the entire application bundle. This requires the framework to capture just enough information in the HTML so that the client can “resume” execution from where the server left off.

Requirements

1. Serialize only the reactive graph (signals, stores, DOM listeners) that is needed for the visible UI.
2. Produce a client‑side runner that can re‑hydrate that graph from the serialized blob.
3. Treat the blob as untrusted input; validate its structure and sandbox any user‑provided data.
4. Detect corruption or size violations and fall back to a full hydration safely.

Smallest Suitable Design

The design consists of two parts:

1. Lightweight serializer – runs during server‑side rendering. It walks the component tree, extracts each signal’s current value, the store’s mutable fields, and any attached DOM listeners (encoded as data-qwik-on* attributes). The output is a JSON object placed in a <script id="__QWIK_DATA__"></script> block.
2. Client‑side runner – a tiny runtime (~2 KB gzipped) that reads the blob, validates its schema, reconstructs the signal graph, and re‑attaches the listeners. If validation succeeds, the UI becomes interactive without downloading the full Qwik bundle.

Example Serialized Blob

{
  "signals": {
    "count": { "type": "number", "value": 0 },
    "name":  { "type": "string", "value": "" }
  },
  "stores": {
    "user": { "id": 123, "role": "editor" }
  },
  "listeners": [
    { "target": "button#increment", "event": "click", "handler": "incrementCount" },
    { "target": "input#name", "event": "input", "handler": "updateName" }
  ]
}

The runner recreates the count and name signals, binds the incrementCount and updateName handlers to the respective DOM nodes, and restores the user store.

Trust and Data Boundaries

The blob is considered untrusted because it travels with the HTML and could be altered by a proxy, CDN transformation, or malicious actor. Qwik enforces the following:

• Schema validation – only known signal types (number, string, boolean, object) and store shapes are accepted.
• Value sanitization – primitive values are accepted as‑is; objects are recursively checked for prototype pollution.
• Sandboxing – any string that looks like code (e.g., containing <script> or javascript:) is rejected and triggers a fallback.

Operational Checks and Failure Modes

At runtime the runner performs:

1. Checksum verification – a simple Adler‑32 checksum is included in the blob; if it does not match the recomputed value, the runner logs Qwik: blob checksum mismatch and initiates fallback.
2. Size limit – if the blob exceeds a configurable threshold (default 64 KB), the runner treats it as oversized and falls back.
3. Missing definitions – if a referenced signal or store key is absent in the blob, the runner logs a warning and falls back.

When a fallback occurs, the framework downloads the full Qwik bundle and re‑executes the application from scratch, guaranteeing UI correctness at the cost of the usual hydration latency.

Diagnostic Decision Flow

Start → Read __QWIK_DATA__ → Validate JSON schema →
   ├─ Fail → Log schema error → Fallback
   ├─ Pass → Verify checksum →
   │    ├─ Fail → Log checksum error → Fallback
   │    └─ Pass → Check size →
   │         ├─ Over limit → Log size error → Fallback
   │         └─ Under limit → Reconstruct graph → Attach listeners → Resume

Conditions That Would Necessitate a Redesign

• If intermediaries routinely strip or transform data-qwik-* attributes (e.g., aggressive HTML minifiers that remove unknown attributes), the assumption that the blob stays intact fails, making resumability unreliable.
• Applications that depend on global side‑effects during SSR (e.g., mutating a third‑party library’s singleton) would see those effects lost on the client because they are not captured in the minimal blob; a redesign would need to serialize those effects or provide an explicit escape hatch.
• If the target environment cannot execute the tiny runner (e.g., strict CSP that disallows inline script execution), the blob‑based approach would be unusable, requiring a different delivery mechanism such as a separate bundle.

Practical Verification Steps

1. Inspect the generated HTML for the data-qwik-on* attributes and the __QWIK_DATA__ script block.
2. Disable JavaScript temporarily, reload the page, and confirm that the UI appears static (no interactivity).
3. Re‑enable JavaScript, reload, and open the console. Look for a log like Qwik: resumed from blob and verify that clicking a button updates the UI without a network request for the main bundle.
4. To test the failure path, manually alter a single character inside the JSON blob (e.g., change a digit in a signal value) and reload. The console should show a validation warning and the network tab should display a request for the full Qwik bundle.

Limitations

• The resumability guarantee holds only if the HTML delivered to the client is byte‑identical to what the server serialized.
• Only the minimal reactive graph is serialized; any state that lives outside signals/stores (e.g., DOM‑only UI state) must be re‑created by the runner or will be lost.
• The fallback mechanism adds complexity to error handling; developers must ensure that any cleanup logic runs correctly in both resumable and full‑hydration paths.