Hydration Mismatch & Subtree Bailout Mechanics
During hydration, the runtime walks existing server DOM nodes with a cursor while executing components. When client output diverges from server markup, the engine bails out of Resumability vs Hydration recovery, tears down the subtree, and re-renders inside the nearest Streaming SSR boundary.
Hydration Cursor & Subtree Bailout
Trace how a DOM cursor detects SSR mismatches and isolates client re-renders to Suspense boundaries.
Hydrator matches <main> and <section> against server HTML without creating new DOM nodes.
tryToClaimNextHydratableInstance(fiber);- cursorNode
- <time>
- serverText
- 14:00:00 UTC
- clientText
- 06:00:00 AM
Under the Hood
Hydration attaches event listeners and internal fiber pointers to pre-existing DOM nodes without recreating them.
- DOM Cursor Walk: As each component renders, the hydrator advances
nextHydratableInstanceacross childElementandTextnodes, verifying tag names and critical text content. - Mismatch Detection: Non-deterministic inputs (
Date.now(),Intl.DateTimeFormattimezone differences,window.innerWidth) produce a client virtual node that fails tag or text comparison against the cursor. - Subtree Bailout: On mismatch, React throws a recoverable hydration error, walks up to the nearest
<Suspense>boundary (or root), deletes the server DOM inside that boundary, and schedules a client-only render pass.
function LocalTimestamp({ iso }: { iso: string }) {
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
return (
<time dateTime={iso}>
{mounted ? new Date(iso).toLocaleTimeString() : iso.slice(11, 19) + ' UTC'}
</time>
);
}Problem Genealogy
- 2015 (
ReactDOM.renderChecksum): React hashed rendered markup withadler32; any single-character mismatch nuked the entiredocument.bodyand rebuilt it synchronously. - 2017 (
hydrate()Per-Node Patching): Switched to per-node cursor walking and patched mismatched attributes in place, leaving structural mismatches silent and buggy. - 2022 (
hydrateRoot+ Suspense Bailouts): Enforced strict tree matching while isolating bailouts to<Suspense>boundaries so a footer mismatch no longer destroys the hero section.
Production Pitfalls
- Root-Level Bailouts: Placing no
<Suspense>boundaries above a mismatched component forces the hydrator to discard the entire page DOM, spiking Total Blocking Time by 150–400 ms. - Browser Extensions Mutating
<body>: Extensions that inject<style>or<div>siblings directly intodocument.bodyshift the cursor and trigger root mismatches if the app mounts directly on<body>.
- When not to use
suppressHydrationWarning: Never slapsuppressHydrationWarningon structural elements or containers with mismatched children; it only silences text/attribute warnings on a single leaf node and leaves wrong event targets attached.
Connections & Logical Next Steps
Full hydration replays component trees against existing DOM nodes, unlike resumability which skips tree walking.
Suspense boundaries isolate hydration mismatches to a single streamed chunk instead of bailing out the entire document.