completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

Hydration strategies

Compare full, selective and lazy hydration, server components and resumability on one React page: the JavaScript, the main-thread work and the first click.

By the end, you can
  • 01
    Compare five ways to wake up a pageFull, selective and lazy hydration, server components and resumability, by the code they send, the work they do and the first click.
  • 02
    Explain how React picks the clicked partFollow selective hydration through React's own source: boundaries wait, and a click on one hydrates it at once.
  • 03
    Choose a strategy for each part of a pageDecide what to wake at once, what to wake when it's seen, and what never needs code in the browser.

Six ways to wake up one page

In lesson 35.2, Ravi's Mint tea page learned to stream. Since then, the page has grown into a real shop page. It has a rating, a brewing guide, 24 reviews, questions and answers, and more teas. The reviews are written in Markdown, a simple text format. A library called marked turns them into HTML.

Ravi rebuilt the page with React. His server sends the whole page as HTML. Then React wakes it up in the browser, so the buttons work. That waking up is hydration: React runs the page's components again and attaches their click handlers. Lesson 23.3 measured what it costs.

Asha opens the page. It appears at once. She clicks 50 g to see the price of the small pouch. Nothing happens. She clicks again, and again. Then the price changes. Here are four real frames from her visit:

Four real frames of Asha's visit to the fully hydrated page. At 270 ms: £4.80 for 100 g, after 1 click. At 357 ms: £4.80 for 100 g, after 3 clicks. At 687 ms: £2.50 for 50 g, after 7 clicks. At 711 ms: £2.50 for 50 g, after 7 clicks. The photo is finished.270 msAt 270 ms: £4.80 for 100 g, after 1 click.£4.80 for 100 g1 click: no change357 msAt 357 ms: £4.80 for 100 g, after 3 clicks.£4.80 for 100 g3 clicks: no change687 msAt 687 ms: £2.50 for 50 g, after 7 clicks.£2.50 for 50 g7 clicks: changed711 msAt 711 ms: £2.50 for 50 g, after 7 clicks. The photo is finished.£2.50 for 50 gphoto finished
Real frames from Chrome, from the middle click load of the full page. Her first six clicks changed nothing. Her seventh did, and the photo finished even later.

Her first six clicks changed nothing. Ravi asks his friends why. Each one has an answer:

  • "Hydrate the page in parts. Then the part Asha clicks can go first."
  • "Only hydrate the parts Asha can see."
  • "Use server components. Then most of the page sends no code at all."
  • "Don't hydrate. Make the page resumable."

Which one makes her click work soonest? And what does each one cost? Ravi builds the same page six ways:

  • Full hydration: React hydrates the whole page in one go. This is the page above.
  • Selective hydration: React hydrates the page in parts, and the part Asha clicks goes first.
  • Lazy reviews: the reviews wake up only when Asha scrolls to them.
  • Server components: of Ravi's components, only the buy box sends its code to the browser.
  • Resumable: no hydration at all. The first click fetches the code it needs.
  • Resumable, prefetched: the same, but the code is fetched early, before any click.

Here is when the price changed on each page, counted from Asha's first click:

From the first click to the new pricePop out in the code editor (opens in a new tab)JavaScript
// Asha clicks 50 g every 50 ms, from the moment it's drawn.// Times are in ms after she opened the page.const ways = [  ["Full hydration", 253.4, 675.7],  ["Selective hydration", 251.6, 636.1],  ["Lazy reviews", 257.7, 574.7],  ["Server components", 262.3, 610.3],  ["Resumable", 261.4, 434.6],  ["Resumable, prefetched", 258.6, 350.7],]; for (const [way, firstClick, newPrice] of ways) {  console.log(`${way}: new price ${(newPrice - firstClick).toFixed(1)} ms after her first click`);}
  • Lines 1 and 2 are comments. Times are in milliseconds (ms).
  • Lines 4 to 9 hold each page: its name, Asha's first click, and the moment the new price was in the page.
  • Line 13 subtracts the first click from the new price, and prints one line per page.
  • It prints Full hydration: new price 422.3 ms after her first click.
  • Then Selective hydration: new price 384.5 ms after her first click and Lazy reviews: new price 317.0 ms after her first click.
  • Then Server components: new price 348.0 ms after her first click.
  • Last, Resumable: new price 173.2 ms after her first click and Resumable, prefetched: new price 92.1 ms after her first click.

Same page, same photo, same network. The resumable pages answered first, the prefetched one in 92.1 ms. Why? It comes down to how much work stands between a click and the page.

Real-life analogyA cashier who counts the whole till first

Leaf and Kettle opens at nine. Before the cashier sells anything, she counts every coin in the till. Asha is first in the queue, with one pouch of tea. She waits while the cashier counts coins her pouch will never need. Only then does she get her change.

In real life: Counting every coin in the till
In web performance: Hydrating every component on the page
In real life: Asha, first in the queue with one pouch
In web performance: Her click on 50 g
In real life: The coins her pouch needs
In web performance: The buy box
In real life: The first sale
In web performance: The new price on the page
The main idea

A hydration strategy decides how much of a page wakes up, and when. Full hydration wakes all of it before any click. The others wake less of it, later, or none of it. Each one pays for that in something else.

For how React hydrates, line by line, see Hydration inside. For islands, see Islands and partial hydration. For server components in a big app, see React Server Components. Here, you measure them.

How the course recorded it

  • Ravi's page: the Mint tea page at £4.80, with 24 reviews. React 19.3.1 and React DOM 19.3.1, built and minified for production.
  • The same HTML: every page was built ahead of time and sent at once, as lesson 35.1's static build was. So only the way the page wakes up changes.
  • Asha's network: the course's server played Fast 4G, as in lessons 35.1 and 35.2. Each answer reached Asha 165 ms after the server sent it.
  • Asha's computer: Chrome 157, in a window 500 pixels wide, with the CPU 4 times slower.
  • The loads: each page 5 times while Asha only watched, and 5 times while she clicked. The pages took turns. Every number comes from the middle load.
  • The clicks: mouse clicks on 50 g, every 50 ms, from the moment it was drawn until the price changed. DevTools passes mouse clicks straight to the page.

Full hydration: the whole page before any click

Start with the page in the frames. Its only script, full.js, is short:

full.jsx: read the data, then hydrate everythingJSX
import { hydrateRoot } from "react-dom/client";import { Page } from "./page-full.jsx"; const data = JSON.parse(document.getElementById("data").textContent);performance.mark("hydrate-start");hydrateRoot(document.getElementById("root"), <Page {...data} />); 
  • Line 1 imports hydrateRoot from React DOM. Line 2 imports Page, the same component the server ran.
  • Line 4 reads the data the server wrote into the page: the tea, the reviews and the rest.
  • Line 5 writes down the moment React starts. It's a mark, a named moment, as in lesson 11.6.
  • Line 6 hands React the box with the server's HTML, and the page that made it. React hydrates it all.

React sorts its work by how urgent it is. It calls each kind of work a lane. A page's first hydration goes in a lane React marks as blocking (ReactFiberLane.js, lines 684 to 694). Blocking work runs in one go, without a pause (ReactFiberWorkLoop.js, lines 1168 to 1181).

When Asha only watched, full.js arrived at 517.1 ms. Then the main thread ran two long tasks. A long task is one over 50 ms, as lesson 27.1 showed. The first, 84.2 ms, started React's code. The second, 51.4 ms, was hydration.

Now the clicks. Her first six came before React was listening, so they did nothing, as in lesson 23.3. Her seventh came while React's code was still starting. Here is that click:

The click that worked on the full pagePop out in the code editor (opens in a new tab)JavaScript
// The click that worked on the full page, as Event Timing saw it, in ms.const click = { pressed: 551.2, inputDelay: 57.8, processing: 53.5, presentation: 8.7 };const marks = { hydrateStart: 602.7, buyBoxReady: 660.8 }; const runs = click.pressed + click.inputDelay;console.log(`Waited until ${runs.toFixed(1)} ms, after React started at ${marks.hydrateStart} ms`);console.log(`Ran for ${click.processing} ms; the buy box was hydrated at ${marks.buyBoxReady} ms`);console.log(`The whole click: ${(click.inputDelay + click.processing + click.presentation).toFixed(1)} ms`);
  • Line 2 holds the click's parts. They come from Event Timing, the browser's API that times each click, as in lesson 11.4.
  • INP, Interaction to Next Paint, is how long a click takes to show its next frame. It has three parts, as lesson 26.2 showed: the wait, the running, and the wait for the frame.
  • Line 3 holds two marks the page wrote.
  • Line 5 adds the wait to the press: the moment her click began to run.
  • It prints Waited until 609.0 ms, after React started at 602.7 ms and Ran for 53.5 ms; the buy box was hydrated at 660.8 ms.
  • Then The whole click: 120.0 ms.

Read the marks. React had started, but hadn't hydrated anything yet, when her click ran. So React hydrated the whole page inside her click, and only then ran it. React's own code does exactly this. A click on a page that isn't hydrated yet makes React hydrate it at once (ReactFiberReconciler.js, lines 488 to 496).

Why it matters: her click paid for the reviews, the questions and the more teas. Only the buy box needed to work. The click's 120 ms is still a good INP, under 200 ms. But INP can't see the six clicks that did nothing.

Pick a page to see each of Asha's clicks:

Playground: what each of Asha's clicks did
Full: Asha's clicks
  1. Click 1, at 251 msNothing happened. React wasn't listening yet.
  2. Click 2, at 301.3 msNothing happened. React wasn't listening yet.
  3. Click 3, at 352 msNothing happened. React wasn't listening yet.
  4. Click 4, at 399.4 msNothing happened. React wasn't listening yet.
  5. Click 5, at 451.6 msNothing happened. React wasn't listening yet.
  6. Click 6, at 499.5 msNothing happened. React wasn't listening yet.
  7. Click 7, at 551.2 msWaited 57.8 ms, ran 53.5 ms, painted 8.7 ms later. The price changed.
  8. The new price on the page675.7 ms
  9. INP of this load120 ms
Try it yourself
Full hydration

Pick a way. Each row is one click on 50 g, at the moment Asha pressed it. The parts of a click come from Event Timing.

Chrome 157, a server that plays Fast 4G, a CPU 4 times slower. The middle of 5 loads.

Selective hydration: the clicked part first

The first fix changes no component, only the page's shape. A Suspense boundary is a <Suspense> around part of the page, as in lessons 23.3 and 35.2. Ravi puts three on his page:

page-selective.jsx: three boundariesJSX
<Product tea={tea}>  <Suspense>    <BuyBox prices={tea.prices} />  </Suspense></Product><Suspense>  <Reviews reviews={reviews} />  <Ready name="reviews" /></Suspense><Suspense>  <Questions questions={questions} />  <MoreTeas teas={teas} />  <Ready name="more" /></Suspense>
  • Lines 2 to 4 put a boundary around the buy box.
  • Lines 6 to 9 put one around the reviews.
  • Lines 10 to 14 put one around the questions and the more teas.
  • Lines 8 and 13 are Ready. It writes a mark when its part is hydrated, with a layout effect, as in lesson 23.3.

The HTML is the same. So is the code: 83.4 KB, gzipped. A KB is 1,024 bytes. What changes is the order React works in. React's working group calls it selective hydration. React's source follows three rules:

  • The shell goes first, in one go. The shell is everything outside a boundary.
  • Each boundary waits, then goes in pieces. React gives it a low priority. The comment in its code says it's "no rush" (ReactFiberBeginWork.js, lines 2965 to 2967). Between pieces, the browser can handle clicks. React's scheduler aims for pieces of 5 ms (SchedulerFeatureFlags.js, line 11).
  • A clicked boundary jumps the queue. If a click lands in a boundary that isn't hydrated yet, React hydrates that one at once, then runs the click (ReactDOMEventListener.js, lines 196 to 224).

The working group puts it this way: React will "synchronously hydrate the comments during the capture phase of the click event." The capture phase is the first part of a click's trip: from the page down to the button. So React hydrates the part before any handler sees the click.

Real-life analogyA librarian who helps the desk first

A librarian has a full cart of returned books. She shelves them in order, one at a time, and looks up between books. A reader comes to the desk and asks for one book. The librarian doesn't finish the cart first. She finds that book, then goes back to shelving.

In real life: The cart of books to shelve
In web performance: The boundaries still to hydrate
In real life: Shelving one book, then looking up
In web performance: Working in small pieces, with gaps for clicks
In real life: A reader asking for one book
In web performance: Asha's click on the buy box
In real life: Finding that book first
In web performance: Hydrating the clicked boundary at once

Here are the selective page's marks, once with no click and once with Asha's clicks:

The buy box, with and without a clickPop out in the code editor (opens in a new tab)JavaScript
// The selective page's marks, in ms after Asha opened it.const noClick = { shell: 624.3, buyBox: 667.8, reviews: 667.9 };const clicked = { shell: 619.8, buyBox: 621.9, newPrice: 636.1, reviews: 685 }; console.log(`No click: the buy box ${(noClick.buyBox - noClick.shell).toFixed(1)} ms after the shell`);console.log(`Clicked: the buy box ${(clicked.buyBox - clicked.shell).toFixed(1)} ms after the shell`);console.log(`Clicked: the reviews ${(clicked.reviews - clicked.newPrice).toFixed(1)} ms after the new price`);
  • Lines 2 and 3 hold the marks from each load.
  • Line 5 prints No click: the buy box 43.5 ms after the shell.
  • Line 6 prints Clicked: the buy box 2.1 ms after the shell.
  • Line 7 prints Clicked: the reviews 48.9 ms after the new price.

With no click, React hydrated the buy box with the reviews and the rest, in one low-priority pass. With a click, it hydrated the buy box alone, inside the click. The reviews waited until the new price was on the page.

The selective page's parts, in the order React finished them. With no click: the shell at 624.3 ms, then the buy box, the reviews and the rest together at 667.8 ms. When Asha clicked: the shell at 619.8 ms, the buy box alone at 621.9 ms, the new price at 636.1 ms, then the reviews and the rest at 685 ms.No clickshellbuy box, reviews, more624.3 ms667.8 msAsha clicksshellbuy boxnew pricereviews, more619.8 ms621.9 ms636.1 ms685 ms
React's marks on the selective page. With no click, the buy box finished with everything else. When Asha clicked, React hydrated it alone, and the reviews waited.

Now compare the click that worked on each page, part by part:

The click that worked, full and selectivePop out in the code editor (opens in a new tab)JavaScript
// The click that worked on each page, in ms.const full = { inputDelay: 57.8, processing: 53.5, presentation: 8.7 };const selective = { inputDelay: 54.9, processing: 19, presentation: 6.1 }; for (const [page, click] of [["Full", full], ["Selective", selective]]) {  const total = click.inputDelay + click.processing + click.presentation;  console.log(`${page}: ${click.inputDelay} + ${click.processing} + ${click.presentation} = ${total.toFixed(1)} ms`);}
  • Lines 2 and 3 hold each click's three parts, in ms.
  • Line 6 adds them up. Line 7 prints one line per page.
  • It prints Full: 57.8 + 53.5 + 8.7 = 120.0 ms and Selective: 54.9 + 19 + 6.1 = 80.0 ms.

Both clicks waited about 55 ms for React's code to start. The difference is the running part: 19 ms against 53.5. The selective click hydrated only the shell and the buy box. When Asha only watched, the selective page had no long task for hydration either. Its longest piece took 31.2 ms. Why it matters: boundaries don't make the code smaller. They make each piece of work smaller, and let the clicked part go first.

Compare both loads yourself:

Playground: the selective page, with and without a click
Watched, with no click
  1. React starts hydrating595.2 ms
  2. The shell is hydrated624.3 ms
  3. The buy box is hydrated667.8 ms
  4. The reviews are hydrated667.9 ms
  5. Questions and more teas are hydrated667.9 ms
Try it yourself
Watched, with no click

Pick a load. Each row is a moment the page wrote down, in time order. The marks come from layout effects in each part, as in lesson 23.3.

Chrome 157, a server that plays Fast 4G, a CPU 4 times slower. The middle of 5 loads.

Lazy hydration: the reviews wake when they're seen

The reviews start 931 pixels down the page. Asha's window is only 736 pixels tall. She may never scroll there. So why download their code, or hydrate them, before she does? Lazy hydration waits until a part is needed. Ravi changes how the selective page loads the reviews:

page-lazy.jsx: the reviews' code waitsJSX
const Reviews = lazy(() => whenSeen("reviews").then(() => import("./reviews.jsx")));

lazy takes a function that returns the component's code later. Here, it first waits for whenSeen("reviews"). Then import() downloads reviews.jsx, a file of its own, as in lesson 22.4. Here is whenSeen:

when-seen.js: wait until an element is on screenJavaScript
export function whenSeen(id) {  return new Promise((resolve) => {    const observer = new IntersectionObserver((entries) => {      if (entries.some((entry) => entry.isIntersecting)) {        observer.disconnect();        resolve();      }    });    observer.observe(document.getElementById(id));  });}
  • Line 2 returns a promise: a value that will be ready later.
  • Line 3 makes an IntersectionObserver. It tells your code when an element comes into view.
  • Lines 4 to 6 run when the element is on screen: stop watching, and resolve the promise.
  • Line 9 starts watching the element with that id.

While the promise waits, React leaves the reviews alone. Their HTML stays on screen, and none of their code runs. When it resolves, React hydrates them.

Real-life analogyCorridor lights on a motion sensor

The shop's back corridor has a motion sensor. Nobody pays to light it while it's empty. When someone walks in, the lights come on. They take a moment, but nobody waits in the dark for long.

In real life: The corridor at the back of the shop
In web performance: The reviews, below the screen
In real life: The motion sensor
In web performance: The IntersectionObserver
In real life: Someone walking into the corridor
In web performance: Asha scrolling to the reviews
In real life: The lights coming on
In web performance: The reviews' code loading, then hydration

The course scrolled to the reviews 3 seconds into a watched load:

The lazy page, before and after the scrollPop out in the code editor (opens in a new tab)JavaScript
// The lazy page, watched with no clicks. Times in ms, sizes in KB.const atLoad = { javascript: 69.5, buyBoxReady: 580.2 };const scroll = { at: 3170.4, reviewsAsked: 3174.6, reviewsReady: 3410.7, javascript: 15 }; console.log(`Before the scroll: ${atLoad.javascript} KB, buy box ready at ${atLoad.buyBoxReady} ms`);console.log(`The reviews' code was asked for ${(scroll.reviewsAsked - scroll.at).toFixed(1)} ms after the scroll`);console.log(`The reviews were hydrated ${(scroll.reviewsReady - scroll.at).toFixed(1)} ms after the scroll`);
  • Lines 2 and 3 hold what happened before the scroll, and after it.
  • Line 5 prints Before the scroll: 69.5 KB, buy box ready at 580.2 ms.
  • Line 6 prints The reviews' code was asked for 4.2 ms after the scroll.
  • Line 7 prints The reviews were hydrated 240.3 ms after the scroll.

The reviews' file was 15.0 KB, almost all of it marked. Without it, the page's code arrived and started sooner. The price changed at 574.7 ms, the soonest of the four React pages.

Astro, a framework built around this idea, has a setting for it. A component marked client:visible loads and hydrates "once the component has entered the user's viewport", its docs say, using an IntersectionObserver. One marked client:load hydrates "immediately on page load".

Why it matters: lazy hydration saves the code and the work for parts people may never reach. The cost comes later. When Asha scrolls, the reviews need 240 ms before they work. If she clicks one before its code arrives, React can't hydrate it. React's event code then stops the click, and it does nothing (ReactDOMEventListener.js, lines 215 to 222). Ravi's reviews have no buttons, so nothing is lost here.

Server components: code only for the buy box

Look at Ravi's components again. Only BuyBox has state or click handlers. The rest only turn data into HTML. So why send their code at all? React Server Components are components that run only on the server. React's docs say: "Server Components are not sent to the browser". Here is the top of the page as a server component:

page-rsc.jsx: a server componentJSX
import { BuyBox } from "./buy-box.jsx";
import { Footer, Header, MoreTeas, Product, Questions } from "./parts.jsx";
import { Reviews } from "./review-list.jsx";

Lines 1 to 3 import the buy box, the plain parts and the reviews. Nothing marks it as a server component: that's the default. The buy box's file is different:

buy-box.jsx: the only client componentJSX
"use client";import { useLayoutEffect, useState } from "react";

Line 1 is the "use client" directive: a line at the top of a file that tells the bundler how to treat it. React's docs say it marks "the module and its transitive dependencies as client code." That's the file and everything it imports. Only that code reaches the browser. Line 2 imports useState, which only works in client components.

Real-life analogyA wardrobe delivered built, with one drawer kit

Asha orders a wardrobe. The workshop builds it and delivers it whole. Only one drawer comes as a kit, with its own instructions, because she wants to choose its handle. The van also brings a delivery note that lists every part. She fits the drawer herself. She never sees the workshop's tools.

In real life: The parts built in the workshop
In web performance: Server components, rendered on the server
In real life: The delivery note listing every part
In web performance: The RSC payload
In real life: The drawer kit and its instructions
In web performance: The buy box and its code
In real life: Fitting the drawer at home
In web performance: Hydrating the buy box

What does the browser get instead of the components? The RSC payload: a description of what the server components rendered. Next.js's docs say it holds the rendered result, a placeholder for each client component with a reference to its file, and the props passed to it. Here are three real pieces of Ravi's payload:

The RSC payload, shortenedText
1:I["buy-box",[],"BuyBox"]
0:[["$","header",null,{…}],…["$","h1",null,{"children":"Mint tea"}],…
…["$","$L1",null,{"prices":{"50":"£2.50","100":"£4.80"}}],…
  • Line 1 says that BuyBox's code is in the module called buy-box.
  • Line 2 starts the page. The name, Mint tea, is plain data, with no code.
  • Line 3 is the buy box's placeholder, $L1, with its props: the two prices.

Frameworks such as Next.js build all of this for you. The course used no framework. It ran react-server-dom-webpack 19.3.1, React's own package that frameworks build on. It rendered the payload on the server, turned it into HTML, and put it in the page as a string. The browser's side looks like this:

rsc.jsx: read the payload, then hydrateJavaScript
import "./webpack-globals.js";import { hydrateRoot } from "react-dom/client";import { createFromReadableStream } from "react-server-dom-webpack/client.browser"; const payload = new Response(self.__rsc).body;const page = await createFromReadableStream(payload);performance.mark("hydrate-start");hydrateRoot(document.getElementById("root"), page);
  • Line 1 tells React's payload reader where the buy box's code is. In a framework, the bundler does this.
  • Line 5 turns the payload string into a stream.
  • Line 6 reads it into a tree of elements, with the buy box in its place.
  • Line 8 hydrates that tree.
What server components changedPop out in the code editor (opens in a new tab)JavaScript
// Downloaded before Asha's first click, gzipped, in KB.const full = { html: 4.4, javascript: 83.4 };const serverComponents = { html: 5.9, javascript: 75.3 }; console.log(`JavaScript: ${(full.javascript - serverComponents.javascript).toFixed(1)} KB less`);console.log(`HTML: ${(serverComponents.html - full.html).toFixed(1)} KB more`);
  • Lines 2 and 3 hold what each page sent before the first click.
  • It prints JavaScript: 8.1 KB less and HTML: 1.5 KB more.

Less JavaScript, because marked and the page's parts stayed on the server. But React DOM still came, and so did the payload reader. The HTML grew, because the payload describes the whole page again. Before gzip, it was 39,586 bytes. The full page's data was 5,651.

What each way downloaded before Asha's first click, gzipped, drawn to scale. Full hydration: 4.4 KB of HTML and 83.4 KB JavaScript. Selective hydration: 4.4 KB of HTML and 83.4 KB JavaScript. Lazy reviews: 4.4 KB of HTML and 69.5 KB JavaScript, then 15.0 KB after the scroll. Server components: 5.9 KB of HTML and 75.3 KB JavaScript. Resumable: 3.7 KB of HTML and no JavaScript, then 277 bytes on the click. Resumable, prefetched: 3.7 KB of HTML and 277 bytes JavaScript.Full87.8 KBSelective87.8 KBLazy73.9 KB, +15.0 KB laterServer comp.81.3 KBResumable3.7 KB, +277 bytes laterPrefetched4.0 KBHTMLJavaScript before the first click
Drawn to scale. Shaded: the HTML. Plain: JavaScript. "Later" came after the scroll (Lazy) or on the first click (Resumable). Server components sent less JavaScript and more HTML.

Hydration still covered the whole page, in one task. But it was quicker: one task of 20.5 ms, against the full page's 51.4. Server components don't run in the browser, so React only matched their elements to the HTML. Asha's click, though, had the longest input delay of the four React pages: 66.5 ms, behind React's code and the payload reader starting up.

Why it matters: server components cut the code of the parts that never change. They don't cut React, and the page carries its content twice.

Resumability: no hydration, code on the first click

Every page so far ran React before a click could work. The Qwik framework skips that. Its docs say hydration "replays all the application logic on the client." Qwik instead "pauses execution on the server, and resumes execution on the client." That's resumability, which lesson 23.3 met briefly.

Here is a small page, written by hand, that works the way Qwik's docs describe. Lesson 36.5 runs Qwik itself. The page has three parts. First, the HTML says which code handles each button:

A button that names its own handlerHTML
<button on:click="./buy.js#pickSize" class="size" type="button" data-size="50" aria-pressed="false">50 g</button><script type="application/json" id="state">{"size":100,"prices":{"50":"£2.50","100":"£4.80"}}</script>
  • Line 1 is the 50 g button. Its on:click attribute names a file and a function: pickSize in buy.js. Qwik's docs show the same form.
  • Line 2 is the state the server wrote: the chosen size and the prices.

Second, one listener for the whole page, inlined in the head:

The loader: one listener for every clickJavaScript
document.addEventListener("click", async (event) => {  const element = event.target.closest("[on\\:click]");  if (!element) return;  const [file, name] = element.getAttribute("on:click").split("#");  const code = await import(file);  code[name](event, element);});
  • Line 1 listens for every click on the page.
  • Line 2 finds the nearest element with an on:click attribute. Line 3 stops if there isn't one.
  • Line 4 splits the attribute into the file and the function's name.
  • Line 5 downloads and runs the file with import(), but only the first time. After that, it's already there.
  • Line 6 calls the function.

Qwik's own loader, the Qwikloader, works this way. Its docs say it's "about 1 kb minified". Third, the handler:

buy.js: the handler, which reads the stateJavaScript
const state = JSON.parse(document.getElementById("state").textContent); export function pickSize(event, button) {  state.size = Number(button.dataset.size);  for (const size of document.querySelectorAll(".size")) size.setAttribute("aria-pressed", String(size === button));  document.querySelector(".price").textContent = `${state.prices[state.size]} for ${state.size} g`;}
  • Line 1 reads the state the server wrote.
  • Line 4 sets the new size, from the button's data-size.
  • Line 5 marks the clicked button as pressed. Line 6 writes the new price.
Real-life analogyA shop with one bell and a helper on call

A small shop has no staff on the floor. Each shelf has a sign that says which helper knows it. When a customer rings the bell, that helper walks over from the back office. The walk takes a moment. If the helper is already waiting by the door, there's no walk at all.

In real life: The one bell by the door
In web performance: The loader's single click listener
In real life: The sign on each shelf
In web performance: The on:click attribute
In real life: The helper walking over from the back
In web performance: buy.js downloading
In real life: A helper already waiting by the door
In web performance: buy.js prefetched
The first click on each resumable pagePop out in the code editor (opens in a new tab)JavaScript
// The first click on each resumable page, in ms.const resumable = { firstClick: 261.4, buyJsArrived: 431.9, newPrice: 434.6 };const prefetched = { firstClick: 258.6, buyJsArrived: 346.6, newPrice: 350.7 }; for (const [page, click] of [["Resumable", resumable], ["Prefetched", prefetched]]) {  console.log(`${page}: new price ${(click.newPrice - click.firstClick).toFixed(1)} ms after the first click`);}
  • Lines 2 and 3 hold the first click, when buy.js arrived, and the new price.
  • It prints Resumable: new price 173.2 ms after the first click and Prefetched: new price 92.1 ms after the first click.

Her very first click worked. No click was lost, because the loader was there from the start. But it waited for buy.js: 277 bytes that took 168.6 ms to arrive, almost all of it the trip. Qwik's docs admit it: loading code on a click "would create a noticeable delay, especially on slow networks." So Qwik fetches the handlers early, with <link rel="modulepreload">.

The prefetched page did that. It asked for buy.js at 176.5 ms, and it arrived at 346.6 ms. Asha's first click, at 258.6 ms, came before it, so it still waited. Why it matters: fetching code on the first click saves all the work at load, but the first click pays for the trip.

One more thing. On the resumable page, Event Timing reported no click of 16 ms or more, the smallest it reports. The loader's handler returned at once, and INP stops at the next frame. The wait for buy.js came after that, so INP never saw it. Measure when the change is on screen, not only INP.

What each strategy costs

Here are all six pages side by side. Read each row across:

Ravi's page, six ways, on Asha's computer
WayJavaScript before the first clickMain thread busy, first 3 sPrice changed atINP of the click
Full hydration83.4 KB255.6 ms675.7 ms120 ms
Selective hydration83.4 KB253.4 ms636.1 ms80 ms
Lazy reviews69.5 KB, then 15.0 KB after the scroll206.1 ms574.7 ms64 ms
Server components75.3 KB204.5 ms610.3 ms96 ms
ResumableNone, then 277 bytes on the click101.7 ms434.6 msunder 16 ms
Resumable, prefetched277 bytes116.5 ms350.7 ms16 ms

Four things stand out.

  • The code kept the main thread busy. In the first 3 seconds, the full page kept it busy for 255.6 ms. The resumable page took 101.7 ms. Every page first spent about 90 ms reading the HTML, laying it out and painting it. The React pages then added their code.
  • The code slowed the photo too. React's file shared Asha's line with the photo, so the photo arrived at 530.4 ms instead of 443.5. Then its paint waited for React's long task. The photo was on screen at 620 ms on the full page, and at 464 ms on the resumable one.
  • Every React page lost clicks. React wasn't listening until its code had arrived and started.
  • INP missed what Asha felt. Every page was under 200 ms, a good INP. But INP can't see clicks that did nothing, or a wait that comes after the handler returns.

Here are Asha's clicks on each page, to scale:

Asha's clicks on 50 g on each page, from 200 to 700 ms, drawn to scale. Full hydration: 6 clicks did nothing; the click pressed at 551.2 ms waited 57.8 ms and ran 53.5 ms; new price at 675.7 ms. Selective hydration: 6 clicks did nothing; the click pressed at 549.8 ms waited 54.9 ms and ran 19 ms; new price at 636.1 ms. Lazy reviews: 5 clicks did nothing; the click pressed at 505.2 ms waited 39.2 ms and ran 20 ms; new price at 574.7 ms. Server components: 5 clicks did nothing; the click pressed at 508.8 ms waited 66.5 ms and ran 22.5 ms; new price at 610.3 ms. Resumable: first click at 261.4 ms, buy.js arrived at 431.9 ms, new price at 434.6 ms. Resumable, prefetched: first click at 258.6 ms, buy.js arrived at 346.6 ms, new price at 350.7 ms.FullSelectiveLazyServer comp.ResumablePrefetched200 ms300 ms400 ms500 ms600 ms700 msa clickwaitingrunningthe new price
Each thin mark is a click. Shaded: a click waiting, for the main thread or for buy.js. Plain: the click running. The dashed line is the new price on the page.

Some costs aren't in the numbers:

  • Selective hydration needs boundaries in the right places. A part that people click first needs its own.
  • Lazy hydration drops a click that lands before the part's code arrives.
  • Server components need a framework and a bundler that support them. React's docs warn that the APIs underneath "do not follow semver": even a minor React update can break them.
  • Resumability needs a framework built for it, such as Qwik. Every handler's code still has to arrive once.

web.dev's Rendering on the Web sums up the problem they all attack. Server rendering with hydration "can have a significant negative impact on TBT and INP, even if it improves FCP." TBT, Total Blocking Time, adds up how much long tasks blocked the main thread during the load. FCP, First Contentful Paint, is when the first text or image appears. Why it matters: no strategy is free. Each one moves work away from the first click, and pays in code, HTML, a later wait, or a framework.

Pick a page to see everything its watched load cost:

Playground: what each way cost
Full: the watched load
  1. HTML, gzipped4.4 KB
  2. JavaScript before the first click83.4 KB
  3. JavaScript laternone
  4. Main thread busy, first 3 s255.6 ms
  5. Long tasks, first 3 s84.2 ms, 51.4 ms
  6. Photo on screen (LCP)620 ms
  7. Buy box hydrated661.7 ms
Try it yourself
Full hydration

Pick a way. The sizes are what the server sent, gzipped. The times come from a load where Asha only watched, for 3 seconds.

Chrome 157, a server that plays Fast 4G, a CPU 4 times slower. The middle of 5 loads.

Wake it now, when it's seen, or never?

Each card is one part of a shop's page. Sort it by when it should get its code:

Wake it now, when it's seen, or never?
  • The size picker and Add to cart, at the top of a product page
  • A search box in the header
  • A Sort by menu above reviews, far down the page
  • A photo carousel below the screen
  • A chat button that few visitors open
  • The brewing guide's four steps
  • Reviews written in Markdown, with no buttons
  • The footer's links
Try it yourself
0 of 8 correct

Sort each part by when it should get its JavaScript.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

Common mix-ups

  • "Selective hydration sends less JavaScript." No. The selective page sent the same 83.4 KB. It changed the order of the work, and the size of each piece.
  • "Server components take React out of the browser." No. The buy box still needed React DOM, and the page needed React's payload reader: 75.3 KB in all.
  • "Server components make the HTML smaller." No. The payload describes the page again. The HTML grew from 4.4 to 5.9 KB, gzipped.
  • "A resumable page answers the first click at once." No. The first click waited 173.2 ms for buy.js. Prefetching cut that to 92.1 ms.
  • "A good INP means the click felt fast." No. The resumable page's clicks all stayed under 16 ms to INP, while the price took 173.2 ms to change.
  • "Lazy hydration hides the reviews until they wake." No. Their HTML is on screen from the start. Only their code and their hydration wait.

Practice exercises

Answer each one first, then open the hints if you need them.

Exercise 1 · Warm-upA click during hydration

Another shop hydrates its whole page in one task. Ben clicks in the middle of it. What does it print?

Starter codePop out in the code editor (opens in a new tab)JavaScript
// Another shop: React hydrates the whole page in one task,
// from 800 ms to 870 ms. Ben clicks at 820 ms.
const task = { start: 800, end: 870 };
const click = 820;

console.log(`Input delay: ${task.end - click} ms`);

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upWhich part goes first?

    Someone clicks the reviews before React has hydrated anything. What does this small model print?

    Starter codePop out in the code editor (opens in a new tab)JavaScript
    // A small model of selective hydration, not React's code:
    // parts are hydrated in page order, but a clicked part goes first.
    const parts = ["menu", "buy box", "reviews", "more teas"];
    const clicked = "reviews";
    
    const order = [clicked, ...parts.filter((part) => part !== clicked)];
    console.log(order.join(", "));

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeLost clicks on the lazy page

      On the lazy page, how many of Asha's clicks did nothing?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeThe server components page's main thread

        When Asha only watched, how long was the server components page's main thread busy in the first 3 seconds, in ms?

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeFind a boundary in the HTML

          Open the course's copy of the selective page. In the Elements panel, what comment sits just before the buy box?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeHydrate when the browser is idle

            Astro has a directive that waits until the browser is idle. What is it called?

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, ask two things: what had to run before the click, and what was still on its way?

              The hydration strategies quiz · 7 questionsScore: first tries count
              1. Question 1 of 7Asha clicks a part of the selective page that React hasn't hydrated yet, and its code is there. What does React do?

                Choose an answer to see the explanation.

              2. Question 2 of 7What does the second line of the two clicks example print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // The click that worked on each page, in ms.
                const full = { inputDelay: 57.8, processing: 53.5, presentation: 8.7 };
                const selective = { inputDelay: 54.9, processing: 19, presentation: 6.1 };
                
                for (const [page, click] of [["Full", full], ["Selective", selective]]) {
                  const total = click.inputDelay + click.processing + click.presentation;
                  console.log(`${page}: ${click.inputDelay} + ${click.processing} + ${click.presentation} = ${total.toFixed(1)} ms`);
                }

                Choose an answer to see the explanation.

              3. Question 3 of 7On the lazy page, when did the reviews' code download?

                Choose an answer to see the explanation.

              4. Question 4 of 7With server components, what does the browser get for the reviews?

                Choose an answer to see the explanation.

              5. Question 5 of 7Why did the resumable page's clicks look fast to INP, even though the price changed 173.2 ms after the first one?

                Choose an answer to see the explanation.

              6. Question 6 of 7Why did prefetching buy.js not make the first click instant?

                Choose an answer to see the explanation.

              7. Question 7 of 7All four React pages had an INP under 200 ms. What did that hide?

                Choose an answer to see the explanation.

              Key takeaways

              • Full hydration runs the whole page before a click can work. A click that comes early pays for all of it.
              • Selective hydration splits the work at Suspense boundaries, and hydrates the clicked part first. The code stays the same.
              • Lazy hydration waits until a part is seen. It saves code and work, but a click before its code arrives is lost.
              • Server components send no code for parts that never change. React and the payload still come.
              • Resumability skips hydration. The first click waits for its code, unless it was prefetched in time.
              • INP can't see lost clicks, or a wait for code after the handler returns. Measure when the change is on screen too.

              Remember the one-liner.
              Wake less of the page, later, or not at all, and check what each choice makes the first click pay.

              Sources

              The facts on this page come from these docs, posts and source files:

              Coming next: Rendering at the edge. So far, Ravi's server sat in one place. Next, you measure what changes when the page is built close to Asha.

              CompleteFrontend Clear concepts. Working examples.