State & ArchitectureExperimental

Resumability vs Hydration

Mental Model

Hydration makes server-rendered HTML interactive by downloading and re-executing the entire component tree on the client just to attach event listeners. Resumability skips that replay: it serializes state into the HTML and uses a tiny root listener to fetch handler chunks only when clicked.

Interactive Simulator

Boot Architecture: Eager Hydration vs Resumability

Compare eager full-tree JS hydration on load against serialized HTML state with lazy interaction-time execution.

Lines of Code
Before
3
After
3
Reflows / Browser Cost
Before
O(N) component tree execution
After
O(1) startup (< 5ms JS)
BeforeEager Hydration (O(N) Boot on Load)
// Server rendered HTML, then client downloads & executes ALL components
hydrateRoot(document.getElementById('root'), <App initialData={window.__DATA__} />);
// Main thread blocked 400ms attaching listeners user may never click
Lines: 3Reflows: O(N) component tree executionDependencies: Full app bundle downloaded upfront

Creates the 'uncanny valley': buttons look clickable before hydration finishes.

After (Native)Resumability (O(1) Boot, Lazy Handler)
<!-- 1KB global listener delegates click; chunk loads only on tap -->
<button on:click="./chunk-cart.js#addItem" q:state="12">Add</button>
<script type="qwik/json">{"12":{"count":0}}</script>
Lines: 3Reflows: O(1) startup (< 5ms JS)Dependencies: Zero component JS until interaction

Execution resumes at the exact interaction point without replaying SSR.

Under the Hood

Hydration is like shipping a pre-assembled bicycle, then disassembling and reassembling every bolt in the driveway just to test the brakes. While that replay runs after Streaming SSR, users hit the "uncanny valley", stalling Core Web Vitals INP.

  1. Hydration: Downloads component JS, reconstructs the VDOM tree in memory, diffs it against existing DOM nodes, and binds addEventListener per node.
  2. Partial / Islands Hydration: Hydrates only interactive islands (<CartWidget />), leaving static prose as zero-JS HTML.
  3. Resumability: Serializes state (<script type="qwik/json">) and handler URLs (on:click="./chunk.js#fn") into HTML, relying on DOM Event Propagation at document to lazy-load code on demand.
HTML
<!-- Resumable boundary: zero JS executed until the user clicks -->
<button on:click="./cart-chunk.js#increment" data-state-id="4">
  Qty: <span>1</span>
</button>
<script type="application/json" id="state-4">{"qty":1}</script>

Problem Genealogy

  • 2013–2018 (Universal Hydration): Single-page frameworks bolted SSR onto client bundles, forcing every byte of HTML to be rendered twice.
  • 2020 (Islands Architecture & Selective Hydration): Astro and React 18 scoped hydration to interactive subtrees and yielded between Suspense boundaries.
  • 2022+ (Resumability & Zero-Bundle Server Components): Eliminated client-side replay for static and deferred interactive trees altogether.

Production Pitfalls

Production Pitfall
  • Hydration mismatch cascades: Rendering Date.now() or window.matchMedia during SSR causes client hydration to throw away the server DOM and repaint from scratch.
  • Uncached lazy chunks on slow 3G: Resumability trades boot JS for interaction-time chunk fetches; prefetch probable handlers via a Service Worker or <link rel="modulepreload"> so clicks stay under 200 ms INP.
When Not to Use
  • When not to use Resumability: In dense, always-interactive single-page tools (Figma-like canvases, IDE editors) where 95% of UI handlers are needed within the first second anyway.

Connections & Logical Next Steps

Seen in Architecture Autopsies

Mechanical Comparisons