Hydration

A route app/about/page.tsx renders a Server Component heading and one Client Component, a button with a counter:

Source: Server and Client Components: Using Client Components.

After next build and next start, curl returns one HTML document that carries all three inputs. The part of the body that matters, trimmed:

Three things in it are worth reading slowly.

Source: Server and Client Components: On the client (first load).

When the scripts have loaded, Next.js starts React on the document with hydrateRoot. In this order:

The consequence that surprises most people the first time is in step 2: a Server Component is not re-rendered during hydration, only compared. A new Date() in a Server Component evaluates once, on the server, and the browser reads the result from the payload, so it can never disagree with itself. A new Date() in a Client Component evaluates twice, once for the server HTML and once in the browser, and the two answers will rarely be equal. This is why almost every hydration bug in an App Router application lives in a Client Component, and why the cheapest fix is often to move the volatile code to a Server Component.

Source: Server and Client Components, hydrateRoot.

Next.js calls hydrateRoot for you and does not expose its options. Knowing them is still useful, because every message you will see in the console comes from the same machinery, and because the same API is what you use in a plain React application or in a micro-frontend. The signature is hydrateRoot(domNode, reactNode, options?), and the documented options are:

A runnable demonstration outside Next.js, with the mismatch of this page’s running example: the server rendered the date in a Japanese locale (2026/6/15) and the client renders it in a US locale (6/15/2026). The server half uses renderToString, the client half bundles the same component with esbuild:

Loading the server HTML (<main><p id="added">Added on <!-- -→2026/6/15</p>…​) in Chrome, the callback received:

Source: hydrateRoot: Error logging in production.

Two practical notes. First, React’s default handler reports a recoverable error with reportError(), which fires a window error event; that is how the production message reaches the console and how the next section hooks in without owning hydrateRoot. Second, in Next.js the way to observe these errors is instrumentation-client.ts, a file that runs before the application becomes interactive; see Testing for Hydration Errors and Monitoring Them.

In the App Router the root layout renders <html> and <body>, so React hydrates the whole document, not a div#root. Two consequences are worth knowing before the catalogue. Attributes that something else adds to <html> or <body> (a theme script, a browser extension) are compared like any other attribute, so they produce a warning in development unless the element has suppressHydrationWarning (the catalogue below shows that the warning disappears with it). Extra elements are treated differently, and less uniformly than the React 19 announcement suggests. The announcement says that unexpected tags in <head> and <body> are skipped. In the scratch app (production build), an injected <style>, <link> or <script> placed in <head> or directly in <body> caused no error, but an injected <div> placed directly in <body>, or any element inside <main>, produced Minified React error 418. Count on the tolerance for stylesheets and scripts, not for visible elements.

Source: hydrateRoot: Hydrating an entire document, React 19: Compatibility with third-party scripts and extensions.

The first experiment shows that a boundary does not have to wait for another one. The page has two Suspense boundaries, each with a Client Component loaded with next/dynamic so that each lives in its own JavaScript chunk (with ssr left at its default, both are server-rendered):

Each widget is a Client Component with a counter button that records performance.now() in a useEffect (so the moment of hydration is observable) and again inside its click handler. A Playwright script holds the reviews chunk back for three seconds, as a slow network would, and clicks both buttons:

Read it from the top. Both boundaries were painted at about 390 ms. The shelf boundary hydrated at 376 ms and its button worked while the reviews boundary was still plain HTML waiting for its chunk. That is selective hydration: one slow chunk did not hold the rest of the page back. The reviews boundary hydrated at 3353 ms, the moment its code arrived.

The second lesson is the last line. The click on the reviews button at 1247 ms, while its chunk was still on the way, was lost: after hydration the label still read Helpful: 0 and the click handler never ran. A click can only be handled by code that is in the page. The same happened in a second run in which all the JavaScript was held back, the button was clicked twice, and the scripts were then released: Helpful: 0 afterwards. React does not queue a click on a boundary whose code has not arrived and play it back later (its priority mechanism, described next, works when the code is present); Angular’s withEventReplay() exists precisely to close this gap, see The Same Problem in Other Stacks.

Source: React: Suspense, Next.js: Lazy Loading, Playwright: Modify responses.

The second experiment shows the order. The page has 200 sibling Suspense boundaries, each containing a Client Component whose render takes about 8 ms (a busy loop standing in for a big list, a chart or an expensive formatter), so hydrating all of them takes more than a second and a half. The test waits until hydration has started, then clicks the button of boundary number 150:

Source: React: Suspense, Lazy Loading.

The sequence of marks in the browser, from the two runs:

The button of boundary 150 was hydrated and handled the click within about 10 ms, while the page needed about 1.6 seconds to hydrate completely. React had started with boundaries 0 to 4 in order, saw the interaction, hydrated the target, and then went back to the front of the list; the six extra renders are the work it threw away when it interrupted boundaries it had started. Without Suspense boundaries the same page would be one block of work and the click would wait for all of it.

What to take from the two experiments:

Everything above applied to boundaries whose HTML was in the first chunk. A boundary that suspends on the server is sent later in the same response: first as a fallback, then as a hidden element plus a tiny inline script that swaps it in place (the streaming page shows the bytes). React treats the swapped-in HTML as a new dehydrated boundary and hydrates it when its code is loaded and the main thread is free, so late content hydrates later than early content by design. The PPR measurement in Hydration under Partial Prerendering shows this with timestamps.

Source: Streaming.

Next.js sends React and its router to every page, so there is a floor. The experiment below renders the same 60-book catalogue three ways and sums the JavaScript that the browser downloads (production build, Playwright, all script responses of the page counted once, gzip size computed with Node’s zlib). The catalogue is validated with zod and formatted by one function in a shared module, standing in for any logic that does not need the browser:

Source: Server and Client Components: Reducing JS bundle size, Interleaving Server and Client Components.

The all-client page ships about 380 KiB more JavaScript (about 90 KiB gzipped) than the floor, nearly all of it zod and the shared module, and the browser then runs the validation again just to rebuild HTML the server had already produced. The two server-first variants cost nothing over the floor: the validation and the 60 rows live only on the server, the browser receives the result (a larger HTML document, 17.2 KiB instead of 11.0 KiB) and hydrates only the input or the button. The HTML grows a little, the JavaScript does not grow at all, and that is the right side of the trade because HTML is cheap to parse and JavaScript is expensive to run.

Bytes are only half. The second experiment of Selective and Progressive Hydration measured render cost directly: 200 Client Components that each take 8 ms to render cost about 1.6 seconds of main-thread time during hydration, split into slices, but a total all the same. A real component does not busy-wait, but a formatter, a large map, a derived list or a chart library can easily reach a few milliseconds each. The same page rendered as Server Components would cost the browser no render time at all, because the work was done on the server and the browser compared the output with the payload.

The levers, in the order in which they usually pay off:

Source: Reducing JS bundle size, Lazy Loading, Package Bundling, useReportWebVitals, Third-Party Libraries, web.dev: Web Vitals.

The same event looks very different in the two modes, and in three different places.

When the first client render disagrees with the HTML, React cannot adopt the server DOM below the point of difference: the DOM nodes it would attach to are not the nodes the component describes. The Next.js preventing-flash guide describes the recovery: React falls back to client rendering from the nearest error or Suspense boundary. It discards the server DOM of that boundary (or of the whole root if there is none), renders the tree again in the browser and reports the error as recoverable.

The effect is measurable, and it is not cosmetic. The experiment uses a page with two inputs, one outside and one inside a section, and a Client Component that renders Date.now() (a guaranteed mismatch). The test script holds the JavaScript back, types into both inputs while the page is still plain HTML, marks the input nodes, then lets the JavaScript load and hydrate. Three variants: no mismatch, a mismatch with no Suspense boundary, and a mismatch inside a Suspense boundary.

Source: hydrateRoot: Handling different client and server content, Streaming.

The first line is the baseline: when nothing mismatches, the text the user typed before hydration is preserved, and the DOM nodes are the very same ones (hydration adopts them). The second line is the disaster: one volatile Date.now() anywhere in the page, outside any Suspense boundary, made React regenerate the whole document, and both inputs lost their text and their DOM nodes. The third is the mitigation: with a Suspense boundary around the section, the input outside kept both, and only the boundary was redone. The consequences in practice:

Reproduction. HTML has rules about what can contain what: a <p> cannot contain a <div>, an <a> cannot contain another <a>, a <table> cannot have <tr> as a direct child. React does not enforce them when it renders to a string, so the server happily writes the invalid markup. The browser’s HTML parser then repairs it while building the DOM, and the DOM that results is not the tree React expects.

The server sent exactly what the components describe, for example <p …​>Book details<div>Dune, by Frank Herbert</div></p>. The browser built a different DOM from it (parsed with DOMParser in Chrome):

The <p> was closed early and an empty <p> appeared; a <tbody> was inserted; the outer link was closed before the inner one started. React hydrates against that repaired DOM and finds a different structure than it expected.

Real messages (development). React detects the invalid nesting before it hydrates and says so explicitly:

and then the structural mismatch (Hydration failed because the server rendered HTML didn’t match the client; the overlay marks the offending elements with >). In production: Minified React error #418 with args[]=HTML.

Fix. Write valid HTML. The usual sources are a <div> inside a <p> (a component that renders a block element used inside a paragraph: an image wrapper, a card, a Markdown renderer), a link or button inside a link or button, a <form> inside a <form>, a list item outside a list, and tables without <tbody> produced by hand. The fixed versions:

Verified: the nesting and table pages loaded with no overlay and no console message. The nested link has no single-element fix; make the whole card a link and the author a plain <span>, or make the two links siblings. Because this error is detected by React itself, the development message appears even without a mismatch happening, so treat it as a bug to fix at once.

Source: react-hydration-error: Common Causes, WHATWG HTML: parsing rules, hydrateRoot.

Reproduction. A component branches on whether it is running in the browser. The branch is the mismatch: on the server the condition is one thing, in the browser it is the other, so the two renders differ by construction.

Real message (development).

The page ends up reading "Rendered on the client" (the browser’s version wins after the regeneration), and the production build reports error #418. The React documentation lists this exact pattern among the common causes.

Fix. The point is that the component wants different output in the browser. There are four honest ways to say so, and they are the subject of The Fix Toolbox: render the same thing first and change it after hydration (two-pass), do not server-render it (next/dynamic with ssr: false, or use(browser())), or read the browser value through useSyncExternalStore with a server snapshot. Do not branch on typeof window in render.

Source: react-hydration-error, hydrateRoot: Pitfall.

Reproduction. Reading a browser-only global in the body of a component fails earlier than a mismatch: on the server it does not exist.

Real behaviour. In next dev the request returns HTTP 500 and the overlay shows Runtime Error: localStorage is not defined at the line of the component. In a production build (next start) the same route answers HTTP 500 too, the server log has the error, the response carries no HTML for the page, and the browser renders the page from the RSC payload on the client, so a user sees a working page after the JavaScript runs while a crawler that does not run JavaScript gets an error. For a prerendered route, next build fails instead: in the run, a read of window in a Client Component of a static route stopped the build with ReferenceError: window is not defined and a link to the prerender-error page. The common "fix", typeof window !== "undefined" && localStorage…​, turns the crash into case 2: the server renders the empty value, the browser the real one, and you get a text mismatch.

Fix. The component needs a value that only exists in the browser, so tell React that: use(browser()) inside a <Suspense>, next/dynamic with ssr: false, useSyncExternalStore for a store, or an effect that reads the value after hydration. All four were run on this component, and none of them produced a message:

Both are explained, with their trade-offs, in The Fix Toolbox. Source: Lazy Loading: Skipping SSR, React: browser.

Reproduction. This is the case that the Next.js guide on preventing a flash before hydration is built around, and the one that is easiest to miss locally, because on a developer’s machine the server and the browser share a locale and a time zone. A server in a data centre usually runs in UTC with an en-US or C locale, and the user’s browser does not.

Rendered with iso="2026-06-15T23:30:00Z". Node.js takes its default locale from the environment (LANG) and its time zone from TZ, so starting the server as TZ=UTC LANG=ja_JP.UTF-8 makes the simulation exact. The two sides, from the runs:

Real message (development).

Note that the date and the time are two different bugs in one line: the locale changes the order and separators, the time zone changes the hour (and, here, would change the day for a user in Madrid, where the same instant is already June 16). In production the result was error #418 with args[]=text, and the page after regeneration read Added on 6/15/2026 at 7:30:00 PM.

Fixes, from the cheapest:

Source: Preventing flash before hydration, hydrateRoot.

Reproduction. Anything that returns a different value each time it is called gives the server one answer and the browser another. Two flavours were run:

Real messages (development). The timestamp is a text mismatch, where the diff shows two numbers that differ by the milliseconds between the two renders:

The random id is an attribute mismatch, so it is a "Console Error" and the tree is not regenerated:

In the production build there was no message at all, and the DOM kept the server’s id (for="b7zpfw" and id="b7zpfw" in the run), so the page worked by luck because both attributes came from the same server render. A mismatch that is silent in production is a trap: it passes every test and breaks the day something compares the two sides. In the development ESLint run, the React hooks rules (the react-hooks/purity rule of eslint-config-next 16.3.8) flagged both files: Cannot call impure function during render. Keep that rule on.

Fixes.

Verified: the page loaded with no overlay and no console message (for and id both R_aatpesnelb, an id that React generated and that is identical on both sides).

Source: React: useId, react-hydration-error.

Reproduction. A component adapts to the screen size, the colour scheme, the user agent, the connection state or the language, and it reads that from the browser during render, usually behind a typeof window guard to survive the server.

With a 500 px wide viewport the overlay read + compact and - wide: the server cannot know the viewport, so it renders the default, and every phone gets a mismatch. On a wide desktop browser the same code worked, which is exactly why this bug is found late: it appears only on the devices that you did not test.

Fixes.

Verified with the 500 px viewport: no overlay, and the paragraph read compact layout after hydration. Without the third argument React cannot render the component on the server at all, and says so:

In next dev the request returned HTTP 500 and the overlay showed that text. In the production build the server logged the same error, the response was again HTTP 500 without HTML for the page, and the browser rendered the page on the client: it works for users and is invisible to crawlers. Adding () ⇒ true as the server snapshot (see components/fixed/online-store.tsx in the scratch app) fixed both. For the user agent, do not branch on it in render: read it on the server with headers() in a Server Component (which makes the route dynamic) or use a responsive layout.

Source: React: useSyncExternalStore, react-hydration-error.

Reproduction. Extensions (translators, grammar checkers, password managers, dark-mode tools) and third-party scripts modify the DOM after the HTML is parsed and before React hydrates. React then finds nodes it did not render, or attributes that it did not set. You cannot reproduce this reliably with a real extension, so the experiment rewrites the server response in transit (a Playwright route that edits the HTML), which produces the same DOM a real injector would:

Three injections were tried against a page that renders <main><h1>…​</h1><p>Hello, Ada!…​</p></main> from Server Components (production build for the error counts, next dev for the messages):

Fix. For attributes on <html> or <body>, which is what most extensions and many theme libraries add, put suppressHydrationWarning on the element. It is the documented use: the attribute is not React’s, and the warning is noise. Verified: with <body suppressHydrationWarning> the data-gr-ext-installed injection produced no console message.

There is no code fix for an element that an extension inserts inside your content, because it is not your bug. What helps is diagnosis and containment: reproduce in a private window with extensions disabled (if the error vanishes, it is an extension); keep dynamic regions inside Suspense boundaries so that a regeneration is local (see What React Does with a Mismatch); avoid a <div> as the very first or last child of <body>; and count these errors separately in monitoring (see Testing for Hydration Errors and Monitoring Them) so that they do not hide real ones. The React issue that the Next.js documentation links for this cause is react/react#24430.

Source: react-hydration-error, React 19: Compatibility with third-party scripts and extensions, hydrateRoot: Suppressing unavoidable hydration mismatch errors.

What the documentation says. CSS-in-JS in the App Router needs three things: a style registry that collects the rules of a render, the useServerInsertedHTML hook (from next/navigation) to inject those rules into the stream before the content that uses them, and a Client Component that wraps the application in the registry. The CSS-in-JS guide lists the libraries that are supported in Client Components (among them styled-jsx, styled-components, @mui/material, chakra-ui, ant-design, pandacss, stylex, tss-react and vanilla-extract) and, on 2026-10-03, still lists emotion under "currently working on support". The Next.js error page for hydration says the same in one line: ensure that your code follows the official examples.

Reproduction. A library that is misconfigured fails in one of two ways, and both were reproduced.

First failure: class names that differ. A library that generates class names from a counter or a random seed produces different names on the server and in the browser. This hand-rolled stand-in has the same mechanism: the server module keeps counting across requests, the browser starts at zero.

It is an attribute mismatch, so nothing is regenerated and the server’s class stays in the DOM: the button keeps css-1 while React believes it is css-2, and the stylesheet that the library injects in the browser targets css-2. In production the failure is silent and looks like a styling bug.

Second failure: no registry. With styled-jsx and the registry omitted, there is no mismatch (its class names are content hashes, the same on both sides), but the server HTML contains no style rules, so the user sees unstyled content until hydration inserts them.

Fix. Use the library’s official App Router setup, never generate class names or ids in render with counters or random numbers (derive them from props, or use useId), and prefer zero-runtime solutions (CSS Modules, Tailwind CSS, vanilla-extract) when the choice is free: they have nothing to hydrate. The Layouts, Templates and Special Files page covers the root layout where the registry goes.

Source: CSS-in-JS, react-hydration-error.

Reproduction. Something between your server and the browser edits the HTML. The Next.js error page names the edge or CDN configurations that try to modify the HTML response, with Cloudflare’s Auto Minify as the example. HTML minifiers remove whitespace and comments. React’s server output uses an empty comment (<!-- -→) to separate two adjacent text nodes, as in Hello, <!-- -→Ada<!-- -→! You have <!-- -→3<!-- -→ books.. If the comments disappear, the browser parses Hello, Ada! You have 3 books. as one text node, and React expects four.

The experiment rewrote the response the same way (html.replace(/<!-- -→/g, "")) for a page with that paragraph:

In production: error #418 with args[]=text. The text is "the same" to a human, which is what makes this cause disorienting: the diff shows a single node on one side and a fragment on the other.

Fix. Turn off HTML minification and rewriting at the edge for the HTML responses of the app (the Next.js error page links Cloudflare’s instructions for Auto Minify). Let Next.js and its build pipeline optimize the HTML; an edge optimizer cannot know that comments are structural. The same goes for any proxy that injects scripts or banners into HTML (a corporate proxy, an ad-injecting ISP), and for tools that obfuscate e-mail addresses in markup. If you must use a CDN transformation, restrict it to static assets.

Source: react-hydration-error, Cloudflare: disable Auto Minify.

Reproduction. Safari on iOS scans text for phone numbers, e-mail addresses, dates and addresses and turns them into links in the DOM, after parsing and before hydration. A server-rendered phone number then arrives in React’s hands inside an <a> that React did not render. A component with several text children (the interpolation creates separate text nodes) is what makes the mismatch visible:

The simulation rewrites the server HTML the way iOS does (+1 415 555 0100 wrapped in an <a href="tel:…​">):

A subtlety measured on the way: when the paragraph’s only child is a single string (<p>Call the shop on +1 415 555 0100</p>), the same injection produced no error, because React compares the text of an element with a single text child by its textContent, which is unchanged by a wrapping link. The mismatch needs the text split in several nodes, which interpolations and mixed content do.

Fix. Tell Safari not to do it. The Next.js documentation shows the meta tag; in the App Router the metadata API generates it:

The page’s head then contained <meta name="format-detection" content="telephone=no, date=no, address=no, email=no"/>, which is what the documented tag says (telephone=no, date=no, email=no, address=no). If you want the phone number to be a link, render the <a href="tel:…​"> yourself, so that React and the browser agree.

Source: react-hydration-error: Common iOS issues, generateMetadata: formatDetection.

Reproduction. The last bullet of the message ("External changing data without sending a snapshot of it along with the HTML") covers everything that is not props or state: a global store, a cache, a router state read from window, a data-fetching hook that has its data on the client but not on the server. If a Client Component reads such a source during render and the server and the browser do not hold the same value, they render different output. Two shapes of it:

Fix. Send the snapshot with the HTML, so that the browser starts with what the server had: pass the data as props from a Server Component, or dehydrate a client cache on the server and rehydrate it in the browser (the HydrationBoundary of TanStack Query, the Apollo integration, SWR’s fallback). That is the subject of Hydrating Data Caches: TanStack Query and Apollo, with a measured example in which the client made zero requests for the data that the server had already fetched.

Source: react-hydration-error, React: useSyncExternalStore.

The oldest technique and the one in the Next.js error page ("Using useEffect to run on the client only"). The first render returns exactly what the server rendered, and an effect, which runs only in the browser after hydration, flips a flag and triggers a second render with the real value. The two renders are different but the first matches the server, and that is all hydration compares.

Verified: no overlay, no message. The costs are explicit in the React documentation: the component renders twice, hydration is slower, and on a slow connection the JavaScript can arrive much later than the HTML, so the user sees the server value (here the ISO date) for a while and then it changes, which can feel jarring. Setting state in an effect is also something the React Compiler’s lint rule dislikes: in the scratch app react-hooks/set-state-in-effect flagged this file. Use the technique when the extra render is cheap and a visible change is acceptable. For a browser-only component, use(browser()) states the intent more directly.

Source: react-hydration-error: Solution 1, hydrateRoot: Handling different client and server content.

next/dynamic is a composite of React.lazy and Suspense, and works the same in app and pages. With ssr: false the server does not render the component; it renders the loading component (or nothing) and the browser loads the chunk and renders the component after hydration. There is nothing to compare, so there is no mismatch.

Verified with the ShelfCount component of case 3: no overlay and no console message, with the loading text in the HTML and the real count after hydration.

Source: Lazy Loading: Skipping SSR, react-hydration-error: Solution 2.

React 19.3.0 (2026-09-09) added a first-class API for "this component only renders in the browser": the browser function from react-dom, passed to use. During server rendering the component suspends, so the nearest <Suspense> boundary’s fallback goes into the HTML. In the browser use(browser()) returns undefined and the component renders normally. The React announcement presents it as the replacement for the two older techniques (a mounted flag set in an effect, and a typeof window check).

The rules that the reference page states:

That is the component of case 3, shown above (components/fixed/shelf-count-browser.tsx). What the server sent, in the production build of the Bookshelf’s book page, where a LastOpened component uses it (see Worked Example: the Bookshelf Book Page):

The <!--$!-→ marker means "this boundary is to be rendered by the client"; the <p> is the fallback. In development the template carries data-msg="Switched to client rendering because a component requested it.", which is a more readable explanation than any documentation. Verified in a browser: no overlay, no console message, and the component’s content after hydration.

Source: React: browser, React: use(browser()), React 19.3: browser.

For any value that lives outside React (a Web API, a global store), useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot) is the type-correct answer. getServerSnapshot is used on the server and during hydration, so the first client render equals the server render by construction, and React then re-renders at once with getSnapshot if it differs. It also handles updates after hydration and avoids tearing. The case-6 example (matchMedia) and the Bookshelf shelf store of Worked Example: the Bookshelf Book Page are both of this kind. The snapshot functions must return stable, comparable values (a string or a number, not a fresh array).

Source: React: useSyncExternalStore.

suppressHydrationWarning on an element tells React to not report a text or attribute difference on that element and to keep what is in the DOM. It is an escape hatch for unavoidable differences (a timestamp, an attribute that an inline script or an extension sets). Three rules decide whether it is the right tool:

The first rule was verified. The same mismatching text rendered in a <time> inside a <p>, with the prop on the <time> and then on the <p>:

The first produced no message. The second produced "Hydration failed because the server rendered text didn’t match the client" and the whole-page regeneration, exactly as if the prop were not there. (ESLint’s react-hooks/purity rule flags Date.now() in both files; the rule is right in general, and this example is the narrow exception that the documentation describes.)

Use it for: a live clock, an attribute set by an inline script, <html> and <body> attributes set by theme libraries and extensions. Do not use it for: values that you can make deterministic, structure differences, and anything that spreads over several elements (it hides real errors).

Source: hydrateRoot: Suppressing unavoidable hydration mismatch errors, react-hydration-error: Solution 3.

The guide’s recipe, built here in a reusable form. The server renders the date with its own locale into an element, an inline script placed right after the element rewrites the text with the browser’s locale before the first paint, and suppressHydrationWarning tells React to accept the DOM as it is, because the script changed the text before React compared it. In a Client Component the markup is wrapped in <time> with a dateTime attribute, and a helper makes the script type text/javascript on the server and text/plain on the client, so that soft navigations (where scripts inserted by React do not run) fall back to the Client Component’s own render and React does not warn about script tags.

Used from a Server Component (the book page of the worked example is statically generated, with the date formatted at build time in the build machine’s locale):

Hard versus soft navigation: on a hard navigation (first load, reload) the script runs while the page is parsed and corrects the date; on a client-side navigation with <Link> the page is rendered from the payload, the script has type text/plain and is ignored, and toLocaleDateString() runs in the browser as part of the Client Component render, which is why LocalDate is a Client Component and not a Server Component. Use the <time> element so that search engines and screen readers can read the ISO value whatever the visible text.

Source: Preventing flash before hydration: Dates and formatting.

A page is server-rendered with a default theme and the user has a saved preference. The same technique: read the value and set a data-theme attribute on <html> before the first paint. <html> gets suppressHydrationWarning because the script changes an attribute React rendered.

Measured (production build, with the JavaScript bundles held back so that only the inline script could have acted): the attribute read dark before hydration, and dark after. The try/catch handles an unavailable localStorage. To keep the page static, read a theme cookie in the script (document.cookie.match(/(?:^|; )theme=([^;]*)/)) instead of with cookies() in the layout; the guide shows the pattern and the toggle code that persists the choice (document.cookie = "theme=…​; path=/; max-age=31536000; SameSite=Lax").

Source: Preventing flash before hydration: Themes.

For a Client Component whose React state must match what the script put in the DOM, use a lazy state initializer that reads from the same source as the script, with a server default, so that React’s first state equals the DOM the script produced. The guide’s accordion example does this with localStorage and the <details> element. The one-liner to remember: the script and the initializer must read the same key and agree. For a value that only has to be right after hydration, useSyncExternalStore does the same job without a script (see Worked Example: the Bookshelf Book Page); the script is for the cases where the correct value must be on screen before React is there.

Inline scripts with dangerouslySetInnerHTML are blocked by a strict Content Security Policy that does not allow 'unsafe-inline'. With a nonce-based policy set in proxy.ts, Next.js adds the nonce to its own scripts automatically, but not to yours: read it from the x-nonce request header that the proxy sets and put it on the script. Because the nonce is made per request, the page must be dynamically rendered. An experiment with the policy from the CSP guide (script-src 'self' 'nonce-…​' 'strict-dynamic') and the theme script:

Without the nonce the script is blocked, the page is painted in the light theme, and only a client-side safety net (a useLayoutEffect that re-applies the stored theme after hydration, as in the guide’s toggle) corrects it, with the flash you were trying to avoid. The nonce works through strict-dynamic, so the policy stays strict. The React 19.3 changelog also lists a fix for a false-positive hydration mismatch on nonce attributes, which is relevant to this setup.

The guide warns that in development, React’s Strict Mode remounts components once and, on that remount, resets <html>, <head> and <body> to only the attributes that JSX manages, clearing the attribute that the script set. The proposed fix is to re-apply the stored value in the component that owns the theme, in a useLayoutEffect (which runs before paint):

A caveat from the experiment: with Next.js 16.3.8 and React 19.3.0 the attribute was still there after hydration in next dev, both with and without this useLayoutEffect, so the remount-clears-the-attribute behaviour could not be reproduced in this setup (<html> had suppressHydrationWarning). The React 19.3 changelog says Strict Mode now double-invokes effects during hydration, matching client-rendered roots, and the Next.js guide still documents the problem, so keep the effect as a cheap safety net, but do not count it as proven for your own setup: test your theme in development with a reload.

Source: Preventing flash before hydration, Content Security Policy, reactStrictMode, React 19.3.

The Next.js guide on flash prevention says it plainly: run the dev server with TZ and LANG set differently from your browser, for example TZ=UTC LANG=ja_JP.UTF-8 next dev, because most servers run in UTC. Node.js takes the default locale of toLocaleDateString() and Intl from LANG and the time zone from TZ; that is what the experiments of this page used:

For prerendered pages the build is the server, so set the variables on next build as well: a date formatted at build time in the build machine’s locale ships in the static HTML for every user. In the browser, change the same two things: Chrome DevTools has a "Sensors" panel that overrides the locale and the location (and so the time zone), and Playwright’s locale and timezoneId context options do it in tests. A third difference worth adding is a narrow viewport (a phone), for the cases of 6. The viewport, the user agent and other "environment" values.

Source: Preventing flash before hydration: Good to know, Chrome DevTools: Sensors.

A hydration error is a console error (and, in production, an uncaught error event). A smoke test that loads each important route in a browser with a different locale and zone and fails on any error catches nearly every case of the catalogue. This is the script that produced the results below, using only Playwright’s library API (@playwright/test would be the same with expect):

Run it against next dev for the full messages and against next build && next start for what users get, in CI after the build. Two notes: failing only on console.error also catches unrelated errors (a 404 for a favicon, for example), so filter if needed; and run the same routes with a narrow viewport and with a prefilled localStorage, because those are the other two inputs that servers never have.

Source: Playwright: browser.newContext (locale, timezoneId), Playwright: pageerror.

In production a hydration error is invisible to users and quiet in the console. Because React reports recoverable errors through reportError(), they arrive as window error events. Next.js lets you hook them without owning hydrateRoot: instrumentation-client.ts is a file in the project root (or in src) that runs before the application becomes interactive, and the documentation’s own example is an error listener. This one forwards hydration errors to an endpoint with navigator.sendBeacon:

Loading the date mismatch page in the production build produced the beacon below and the matching line in the server log:

Send the route, the error code and the args, the user agent (the extension and iOS causes cluster by browser), the locale and the time zone, and the release id; do not send page content, which can hold personal data. Group by route and code: a single noisy extension produces a stream of #418 from one browser family that you cannot fix, while a rise in #418 on one route right after a deploy is a code bug. The dedicated error-tracking SDKs hook the same events.

Source: instrumentation-client.js, hydrateRoot: Error logging in production.

The documented App Router pattern: a Server Component creates a QueryClient per request, prefetches, and wraps the Client Components in HydrationBoundary with the dehydrated state. HydrationBoundary is a Client Component, so the state travels in the RSC payload as props and the browser’s QueryClient is seeded when it renders. This was built and run with @tanstack/react-query 5.104.1:

Source: TanStack Query: Advanced Server Rendering.

Things to know:

GraphQL clients have the same two-step flow. The existing Apollo configuration page of this documentation describes the classic mechanism (client.extract() on the server, new InMemoryCache().restore(window.APOLLO_STATE) in the browser) in Apollo Client Configuration (the section "SSR hydration"). For the App Router the maintained package is @apollo/client-integration-nextjs (0.14.5 on 2026-10-03, with @apollo/client 4): its README describes registerApolloClient, which returns getClient, query and a PreloadQuery component for Server Components, and an ApolloNextAppProvider with a makeClient function for Client Components, so that data queried on the server is transported to the browser cache with the streamed response and useSuspenseQuery in a Client Component waits for the server’s request instead of making its own. The rules are the same as for TanStack Query: a client per request on the server, no secrets in preloaded data, and the same query and variables on both sides.

SWR seeds its cache with the fallback option of SWRConfig or a fallbackData prop in the same way; see the client-side rendering page of this section for the Next.js specifics and for when fetching on the client is the right choice at all.

Source: Apollo Client Integration for Next.js, TanStack Query: Advanced Server Rendering.