Streaming SSR and selective hydration: HTML in waves

The pipeline: shell first, chunks as they resolve

renderToPipeableStream (Node; renderToReadableStream on edge runtimes) renders your tree on the server with Suspense boundaries as seams. Everything outside any boundary is the shell. The lifecycle:

1. React renders until the shell is complete. Suspended subtrees do not block it — in their place, React emits the boundary’s fallback HTML.
2. onShellReady fires; you pipe the response. The browser gets a complete, paintable page — layout, static content, skeletons — over one chunked HTTP response that stays open.
3. As each suspended subtree resolves on the server, React streams an additional chunk: the real HTML in a hidden <div>, followed by an inline <script> that moves it into the fallback’s slot in the DOM. No client JS framework needed for the swap — it works before your bundle loads.
4. When all boundaries flush, the stream closes (onAllReady is the hook crawlers/static generation use instead — wait for everything, then send, trading TTFB for complete HTML).

The failure mode falls out of step 1: any data dependency outside a boundary is shell-blocking. It does not matter that the rest of the page is stream-ready; the first byte waits for the slowest await above the boundary line. This is the same placement discipline as the loading-UI lesson, now with TTFB attached — boundary placement decides not just what disappears together, but what the server may postpone.

// ❌ in the shell: every user's TTFB now includes this lookup
const tier = await session.getTier(userId);   // p99 900ms

// ✅ under a boundary: shell streams immediately, badge streams later
<Suspense fallback={null}>
  <TierBadge userId={userId} />
</Suspense>

Selective hydration: per-boundary, interruptible, click-aware

On the client, hydrateRoot no longer hydrates the page as one synchronous monolith. Suspense boundaries divide hydration into independent units, and three properties follow:

• Hydration starts before everything arrives. The shell hydrates as soon as the bundle loads, even while later chunks are still streaming. Streamed-in boundaries hydrate as their code and content become available.
• Hydration is interruptible. Between boundaries, React yields to the browser — a long hydration no longer blocks input the way a single-pass hydrate() did, where a 600ms hydration meant 600ms of dead buttons.
• Interaction reprioritizes. If the user clicks inside a boundary that has not hydrated yet, React records the event, urgently hydrates that boundary first (jumping the queue ahead of earlier-in-tree boundaries), and then replays the click against the now-live handlers. The click is not lost and not handled by dead HTML — it is queued and delivered late. On a fast machine the gap is imperceptible; on a slow device the user notices a beat between tap and response, which is still strictly better than the pre-18 world where the tap silently did nothing.

The design consequence: boundaries are also hydration units. A page-wide boundary means click-anywhere hydrates everything; granular boundaries mean the comment box the user tapped hydrates in isolation, milliseconds instead of hundreds of them.

Hydration mismatches under streaming

Hydration compares the server HTML against the client’s first render and expects them identical. Streaming raises the stakes in two ways. First, the classic causes — Date.now(), new Date().toLocaleString(), Math.random(), user-agent branching, locale differences — now fire at different times per boundary: the server rendered the comments chunk 1.4s after the shell, so any time-derived value differs across boundaries as well as across server/client. Second, recovery is costlier than it looks: on a mismatch, React falls back to client-rendering the nearest Suspense boundary’s content from scratch, throwing away the streamed HTML for that boundary. The page does not crash, the console warns — and you silently pay double render cost plus a possible visual flicker for the region. A mismatch inside the shell (no boundary above it) is the expensive case: React re-creates a much larger region client-side. The discipline: anything nondeterministic renders identically (suppressHydrationWarning for a timestamp is a scalpel, not a lifestyle), or moves to an effect that runs only on the client, accepting the two-pass render for that node.

TTFB vs LCP: sizing the shell

Streaming gives you a dial, not a free lunch. Everything in the shell arrives at TTFB but delays it; everything behind a boundary improves TTFB but arrives in a later wave. The two Core Web Vitals in tension: TTFB (good under 800ms) rewards a thin shell; LCP (good under 2.5s) rewards having the largest contentful element in the first wave — if your hero image or article headline streams in as wave three, LCP is graded on wave three’s arrival. The senior heuristic: the shell contains layout plus the LCP element if and only if its data is reliably fast (single-digit-ms cache or no data at all); everything with a tail — personalization, recommendations, comments — goes behind boundaries. And measure the waves: a shell that is 90% of the page has merely renamed blocking SSR, while a shell that is an empty frame hands LCP to the second wave and loses what streaming bought.

Failure modes worth rehearsing

• Slow await in the shell — the Hook’s incident: one session lookup above the boundary line gates TTFB for every user. Audit what is outside boundaries the way you audit what is in a hot path.
• LCP element behind a slow boundary — TTFB looks great on the dashboard while LCP regresses; the metrics disagree because the headline streams in wave two.
• Nondeterministic render in the shell — a hydration mismatch with no boundary to contain it client-renders half the page, doubling work on the user’s device exactly when it is busiest.
• Page-wide hydration unit — one boundary around everything means first click anywhere pays full hydration; granular boundaries make the tapped widget interactive in isolation.