Resumability vs Hydration
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.
Boot Architecture: Eager Hydration vs Resumability
Compare eager full-tree JS hydration on load against serialized HTML state with lazy interaction-time execution.
// 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 clickCreates the 'uncanny valley': buttons look clickable before hydration finishes.
<!-- 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>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.
- Hydration: Downloads component JS, reconstructs the VDOM tree in memory, diffs it against existing DOM nodes, and binds
addEventListenerper node. - Partial / Islands Hydration: Hydrates only interactive islands (
<CartWidget />), leaving static prose as zero-JS HTML. - Resumability: Serializes state (
<script type="qwik/json">) and handler URLs (on:click="./chunk.js#fn") into HTML, relying on DOM Event Propagation atdocumentto lazy-load code on demand.
<!-- 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
- Hydration mismatch cascades: Rendering
Date.now()orwindow.matchMediaduring 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 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
Full hydration replays component trees against existing DOM nodes, unlike resumability which skips tree walking.
Both hydration and resumability boot on top of server-rendered HTML streamed to the browser.
Resumability relies on a single root event-delegation listener to intercept clicks before component JS loads.
Heavy eager hydration directly degrades Total Blocking Time and early INP.
Streaming SSR still hydrates streamed HTML on the client, whereas resumability serializes listener boundaries to skip eager hydration.