Hydration

For a stretch of years, web pages moved toward being drawn entirely in the browser. The server sent an almost empty document, the browser downloaded code, ran it, and built the screen from there. That suited the people building it, but users spent several seconds looking at white space after clicking a link, and search engines collected the empty document and indexed nothing.

So rendering moved back to the server, which now sends finished HTML. The screen appears right away. What the server sends, though, is an arrangement of text and images — which produces a page that is fully visible and completely unresponsive.

In practice it shows up like this. The screen is there, so someone taps the login button and nothing happens. They tap twice more, and then all three taps fire at once. A tester reports that "the button sometimes doesn't work," and an engineer spends an afternoon failing to reproduce it, because on a fast laptop over a fast connection the window is too short to notice. Hydration is the name for the work that fills that gap.

The screen looks complete and nothing on it can be used yet. Text and images sit in their final positions and the page scrolls, but the buttons and inputs are shells with no code behind them.

The browser does three things during the stage.

1. Downloads the JavaScript the screen needs. At 300 kilobytes, that download alone runs past a second on a slow connection.
2. Runs that code to work out what structure the screen should have. The result has to match what the server already sent.
3. Compares the result against the delivered markup and attaches the behavior for each button and input. Clicks land only after this finishes.

The length of the stage therefore rides on both connection speed and device power. Work that takes 100 milliseconds on a current laptop can take two seconds on a three-year-old budget phone. Checked only on a developer's machine, the stage looks like it doesn't exist — which is why reports of dropped clicks split between people who see the problem constantly and people who never do.

When the structure calculated in step 2 differs from what arrived, that's a mismatch. The classic case is a timestamp: the server wrote "3 minutes ago" and the browser, running later, computes "5 minutes ago." The browser throws that section away and redraws it, so the screen flickers once. Anything computed from the current time, a random value, or something stored only in the browser tends to produce this. When the assumption that the delivered markup can be reused breaks, the benefit of sending it breaks with it.

One condition ends the stage. Once the needed code has arrived, finished running, and attached behavior to everything on screen that can be operated, the page moves into the state where taps do what they should.

Shortening the stage comes down to sending less JavaScript or splitting what gets sent.

1. Code splitting. Instead of downloading everything at once, the page pulls only what the current screen needs. A user who never opens settings has no reason to wait on the settings code, and on a list-heavy screen that one change often removes more than half the download.
2. Attaching piece by piece. Rather than wiring the whole screen in one pass, split it into pieces and connect what is visible or likely to be tapped first. A help panel at the very bottom can wait until someone scrolls to it.
3. Sending no code for parts that don't do anything. A marketing section of text and images has nothing to tap, so it can stay exactly as the server drew it. This shrinks the download itself rather than reordering it.

The three aim at slightly different things — the first at how much arrives, the second at the order of attachment, the third at how much needs attaching at all. When one screen is slow, find which of the three is the bottleneck before changing anything.

Confirm the result with numbers rather than by eye. Time-to-visible and time-to-usable are separate values, and slow hydration leaves the first untouched while the second degrades. A metric like Largest Contentful Paint (LCP), which measures when content finished drawing, won't show the problem at all. Measuring under simulated slow network and throttled CPU gives the length real users experience. Keeping that measurement in the regular check before release is what stops the stage from creeping back up as more code lands on the screen.

"The screen paints fast but hydration lags, so the first click gets eaten."

Time-to-visible and time-to-usable have come apart.

"Server and client output differ, so we're getting a hydration mismatch warning."

The same screen was computed twice with different answers, and the browser is redrawing.

"This section has no behavior, so let's leave it out of hydration."

A proposal to cut both the download and the number of things to wire up.

This came up on Pagedeck's document list screen. Testing turned up a report that the first item in the list sometimes doesn't open, and Theo couldn't reproduce it on his own laptop. With the network throttled and the CPU slowed to a quarter in developer tools, clicks did nothing for 1.4 seconds after the screen appeared.

Theo found that the editor code, which the list screen doesn't need, was being downloaded with the first screen, and split it out per screen. Mia added one thing on top: until attachment finishes, buttons should be dimmed rather than looking pressable. Where the delay can't be removed entirely, showing that something isn't ready beats letting people tap into nothing.

The most common mistake is taking "server rendering makes it faster" at face value. The moment the first screen becomes visible really does move earlier, so it feels true. What moves earlier is the visible moment; the usable moment stays where it was or slides later, because the work of reconciling the delivered markup gets added. Miss that distinction and you end up with metrics that improved and support tickets that went up.

The second is reading hydration as the process of drawing the screen again. The name suggests filling something in. The intent is the opposite — reuse the markup that already arrived instead of redrawing it, and add only behavior. If a redraw actually happened, that isn't the normal path but the mismatch described above, and the value of rendering on the server was lost by exactly that much.