# Hydration Proof documentation

> Detect React hydration errors in CI: hydration-proof compares real server HTML with the hydrated DOM in Next.js, Remix and Astro, then explains the cause.

Two packages: `hydration-proof` (CLI and Node API; install with `npm install -D hydration-proof`) and `eslint-plugin-hydration-proof` (ESLint rules; install with `npm install -D eslint-plugin-hydration-proof`). Docs: https://hydration.jscrate.dev. Source: https://github.com/re-sohail/hydration-proof.
This file contains every documentation page in order. The index with one line per page is https://hydration.jscrate.dev/llms.txt.

---

# Quick start

> Install hydration-proof, run it against your Next.js, Remix or Astro app, and read the report: every React hydration mismatch, its cause and the fix.

Source: https://hydration.jscrate.dev/docs/quick-start
Last updated: 2026-09-18

hydration-proof finds React hydration errors by loading every route of your
server-rendered app in a real browser and comparing the server HTML with what
React renders on the client. Install it, run `npx hydration-proof test`, and it
tells you which element differs, both values, the likely cause and the fix.

## Install hydration-proof

Add it as a dev dependency, then download the browser once:

```bash
npm install -D hydration-proof
npx hydration-proof install   # downloads Chromium
```

It needs Node.js 22.18 or newer, and works with npm, pnpm, Yarn (including
Plug'n'Play) and Bun. There are no install scripts: browsers are only
downloaded by the `install` command, into Playwright's shared cache, so a
project that already uses the same Playwright version does not download them
again.

To catch the same mistakes in your editor, add the
[ESLint plugin](https://hydration.jscrate.dev/docs/eslint) as well:

```bash
npm install -D eslint-plugin-hydration-proof
```

## Run your first test

```bash
npx hydration-proof init   # creates hydration-proof.config.ts
npx hydration-proof test
```

For Next.js, React Router, Remix and Astro apps that is all. hydration-proof:

1. discovers your routes from `app/`, `pages/` and the build output,
2. builds the app if there is no build yet, and starts it on a free port,
3. loads every route and compares the server HTML with the hydrated DOM,
4. exits with code `1` if it found a problem.

Vite SSR and custom Node servers are detected too. Any other setup works with
`--url` (see [adapters](https://hydration.jscrate.dev/docs/adapters)).

## Read the report

Each finding in the terminal shows the issue code, the element, the value on
each side, the source line and a fix:

```text
Hydration Proof — 20 pages on http://localhost:3000

  ✓ /pricing 684ms
  ✖ /dashboard 1.1s  1 error
    HP1001 Text differs between server and client  (timezone difference, 95%)
      #last-login  in LastLogin
      server: "Signed in at 5:00 AM"
      client: "Signed in at 10:00 AM"
      app/dashboard/LastLogin.tsx:14:10
      → Pass an explicit timeZone to the formatter (the same on both sides), or format the date after mount.

  Report: .hydration-proof/report/report.html
```

- `HP1001` is a stable [issue code](https://hydration.jscrate.dev/docs/issues/hp1001) with its own page.
- `timezone difference, 95%` is the [likely cause](https://hydration.jscrate.dev/docs/causes/timezone) and
  how sure hydration-proof is.

Open `.hydration-proof/report/report.html` for everything at once: filters,
the server and client values side by side, the code, screenshots with the
element outlined, and a timeline of the page. [Reports](https://hydration.jscrate.dev/docs/reports) covers
every output format.

## Test an app that is already running

```bash
npx hydration-proof test --url http://localhost:3000 --route / --route /pricing
```

With `--url`, nothing is built or started, and only the routes you name are
tested. Add `--sitemap` to test the pages in your sitemap, or `--crawl` to
follow links from the tested pages.

## Test development and production builds

Development builds give exact source lines. Production builds show what your
users get, including attribute mismatches React 19 never reports in
production. Test both in one run:

```bash
npx hydration-proof test --mode both
```

## Add it to CI

```yaml title=".github/workflows/hydration.yml"
- run: npm ci
- run: npx hydration-proof install --with-deps
- run: npx hydration-proof test
```

Or let `npx hydration-proof init --ci github` write the workflow for you.
[Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci) covers GitHub Actions, GitLab and
CircleCI, sharding, baselines and budgets.

## Configure it

The config file is optional for most apps. When you need it, it is TypeScript
with completion:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    // Example values for dynamic routes
    dynamic: { "/products/[id]": ["1", "42"] },
    exclude: ["/api/**"],
  },
  // The environments your users have
  scenarios: [
    { name: "default" },
    { name: "dark-mobile", colorScheme: "dark", viewport: "mobile" },
    { name: "karachi", locale: "ur-PK", timezoneId: "Asia/Karachi" },
  ],
});
```

See [configuration](https://hydration.jscrate.dev/docs/configuration) for every option, and
[scenarios](https://hydration.jscrate.dev/docs/scenarios) for signed-in pages.

## Related

- [How hydration-proof works](https://hydration.jscrate.dev/docs/how-it-works): the six snapshots it
  compares
- [What is hydration in React?](https://hydration.jscrate.dev/docs/guides/what-is-hydration)
- [All React hydration error messages](https://hydration.jscrate.dev/docs/errors), decoded
- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes) and their fixes
- [The CLI](https://hydration.jscrate.dev/docs/cli): every command and flag

---

# How it works

> How hydration-proof detects mismatches: it captures each page at six stages in a real browser, compares them, and explains every finding with a likely cause.

Source: https://hydration.jscrate.dev/docs/how-it-works
Last updated: 2026-09-18

Here is how hydration-proof detects mismatches: it loads each page in a real
browser, captures it at six stages, from the bytes the server sent to the
settled page, and compares neighboring stages to find where a difference
started. A small runtime, injected before any page script, connects to React
the way React DevTools does. Your app is not changed.

## Connecting to React

hydration-proof drives the browser with Playwright. Before any script of the
page runs, it injects a runtime of about 29 KB that stays out of the app's way.

React looks for `__REACT_DEVTOOLS_GLOBAL_HOOK__` when it loads, in development
and in production builds. The runtime provides that hook, or wraps an existing
one so React DevTools and Fast Refresh keep working, and React then tells it
about every renderer and every commit.

Inside a commit, React calls the hook before it reports recoverable errors. That
lets the runtime capture those errors with their component stack, even when the
app (or Next.js) installs its own error handler.

## How hydration-proof detects mismatches

### The six stages

| Stage                | How it is captured                                                                                                                                                                                   |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Server HTML       | The body of the document response the browser received, read from the same navigation (never fetched twice)                                                                                          |
| 2. Parsed HTML       | The same bytes loaded again in a page where a Content Security Policy blocks scripts. This is the browser's own parser, so repairs, `<noscript>` and `<template>` behave exactly as in the real page |
| 3. Pre-hydration DOM | Rebuilt by undoing the DOM mutations recorded during React's hydration commit                                                                                                                        |
| 4. Hydrated DOM      | Serialized inside the hydration commit (after layout effects), with the props React renders for each element                                                                                         |
| 5. After effects     | The first quiet moment after the hydration commit's effects                                                                                                                                          |
| 6. Stable            | When the page stays quiet for `ready.quietMs`                                                                                                                                                        |

Every node gets an identity, so the comparison knows whether React reused a
node or replaced it. When a page counts as quiet is set by the
[`ready` options](https://hydration.jscrate.dev/docs/configuration#ready).

### The four comparisons

| Compared        | Finds                                                                                                                |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| 1 → 2           | Invalid nesting the browser repaired, checked with React's own nesting rules                                         |
| 2 → 3           | Changes by other scripts and browser extensions before React hydrated (React's streaming moves are undone first)     |
| 3 → 4           | Branches React threw away and rendered again, with the exact text, attribute and element differences inside them     |
| 3 ↔ React props | Attributes, styles and text that differ from what React renders, which React 19 does not report or fix in production |

Findings from different comparisons are merged, so one bug is reported once,
with React's own error attached as evidence. Each finding gets a stable
[issue code](https://hydration.jscrate.dev/docs/issues), and which comparison it came from tells you where
the difference started: in the markup, in a script that ran before React, or in
the React render itself.

## Explaining a finding

For every finding, hydration-proof looks up three things:

- **The component and the source line.** In development builds React records
  where each element was created. hydration-proof maps that position through
  the page's source maps to your file and line, and shows the code. React 18
  uses the `__source` information the compiler adds. For elements created
  inside libraries (styled-components, UI kits), you get the location of the
  component that used them. In production builds, the code of the component
  that rendered the element is found in the loaded scripts and mapped through
  the browser source maps, when they are available.
- **The likely cause**, from the values that differ, the code around that line,
  the scenario, and the stage where the difference started. The
  [list of causes](https://hydration.jscrate.dev/docs/causes) has a fix guide for each one.
- **What to do about it:** advice for the cause, plus the general advice for the
  issue code.

When a location cannot be proven, the report says so instead of guessing.

## Proving a cause with probes

The likely cause is an informed guess. `--probe` turns it into proof. The page
is loaded again with the browser clock and random values fixed, then once for
each factor with exactly one thing changed: the clock, the random seed, the
locale, the timezone, the theme, the viewport, or browser storage.

If the client value changes, or the finding disappears, when only one factor
changed, that factor is the cause. A page that renders differently on an
identical reload points at server data. The server is never changed, so fixing
the clock in the browser does not hide a time-dependent value.

```bash
npx hydration-proof test --probe
```

[Probes](https://hydration.jscrate.dev/docs/probes) lists every factor and what it costs.

## Environments and flaky findings

The `matrix` option tests scenarios in combinations of locales, timezones,
themes, viewports, browsers, network and CPU speeds, cache states and custom
axes such as feature flags or tenants. Pairwise selection keeps the number of
combinations small while every pair of values is still tested at least once.
Afterwards, for each route, the report names the environment values that
separate the pages with a finding from the pages without it ("Only found with
locale de-DE"). See the [environment matrix](https://hydration.jscrate.dev/docs/environment-matrix).

`--repeat` loads every page several times. Findings that come and go are marked
flaky, and each page gets a flakiness score.

## Streaming, Suspense and navigation

Pages that stream HTML hydrate in steps: the root first, then every Suspense
boundary when its content and code arrive. Each of these commits is compared on
its own. A mismatch inside one boundary is reported for that boundary, and
content React reveals from the stream is not mistaken for a mismatch. A boundary
the server could not render, or that React switched to client rendering, is
reported with React's error.

The whole document is checked too:

- `<head>` values that hydration adds or changes ([HP1014](https://hydration.jscrate.dev/docs/issues/hp1014)).
  React 19 adds a new `<title>` or `<meta>` instead of fixing the server one.
- duplicate ids ([HP3003](https://hydration.jscrate.dev/docs/issues/hp3003))
- useId collisions between several React roots on one page
  ([HP3004](https://hydration.jscrate.dev/docs/issues/hp3004))

With `checks.navigation`, routes are also reached through the app's router, and
the result is compared with a direct load; RSC requests are recorded in the
timeline. With `checks.interactions`, the page's scripts are held back while the
tool types, clicks and scrolls, so what a user does before the page is
interactive is checked as well. [Interactions and navigation](https://hydration.jscrate.dev/docs/interactions)
covers both.

## Development and production builds

`--mode both` starts the app twice: a production build and the development
server.

- Development builds give component names and exact source lines.
- Production builds show what users get. React 19 in production does not
  report attribute mismatches at all.

Issues found in only one mode are marked, so you can tell a production-only
problem from one you can reproduce locally.

```bash
npx hydration-proof test --mode both
```

## What it does not change

Your application code and build are not modified. The runtime exists only in
the test browser, and nothing is added to your production bundle.

## Related

- [Quick start](https://hydration.jscrate.dev/docs/quick-start): install and run your first test
- [Prove the cause of a mismatch with probes](https://hydration.jscrate.dev/docs/probes)
- [Every issue code](https://hydration.jscrate.dev/docs/issues), from HP1001 to HP9010
- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes) and their fixes
- [Reports](https://hydration.jscrate.dev/docs/reports): the HTML report, JSON, JUnit and SARIF

---

# Hydration error tools compared

> Hydration error tools compared: the console, the Next.js dev overlay, react-hydration-overlay, Sentry, ESLint rules and hydration-proof, and when to use each.

Source: https://hydration.jscrate.dev/docs/comparison
Last updated: 2026-09-18

Here are the main hydration error tools compared, as of September 2026. React's
console errors and the Next.js dev overlay show one page at a time while you
develop. Sentry shows the mismatches real users hit. ESLint rules flag risky
code as you write it. hydration-proof tests every route of a build, locally or
in CI.

## Hydration error tools compared

| Tool                                   | Runs where                                                                  | When                                                     | What it catches                                                                                                                                                                                   | Production builds                                                          | CI                                                       |
| -------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
| Browser console (React's own errors)   | The browser tab you have open                                               | While you browse                                         | What React reports for that page, with a component stack in development                                                                                                                           | Minified codes such as #418; React 19 does not report attribute mismatches | No                                                       |
| Next.js dev overlay                    | The browser, with `next dev`                                                | Development only, one page at a time                     | The errors React reports; since Next.js 16.2 with a `+ Client` / `- Server` diff                                                                                                                  | No                                                                         | No                                                       |
| `@builder.io/react-hydration-overlay`  | The browser, wrapped around your app root, with a Next.js or webpack plugin | When a hydration error happens on the page you have open | A diff between the server and client renders                                                                                                                                                      | Not intended for production use                                            | No                                                       |
| Sentry Session Replay                  | Your users' browsers                                                        | After the fact, for errors captured with a replay        | A diff of the page before and after hydration (HTML and visual)                                                                                                                                   | Yes                                                                        | No                                                       |
| `eslint-plugin-react-hooks` (`purity`) | Your editor and lint step                                                   | Before the code runs                                     | Impure calls in components and hooks: `Date.now()`, `new Date()`, `Math.random()`, `crypto.randomUUID()`, `performance.now()`                                                                     | Not applicable                                                             | Yes, as a lint step                                      |
| `eslint-plugin-validate-jsx-nesting`   | Your editor and lint step                                                   | Before the code runs                                     | Invalid HTML nesting written in JSX, such as `<p>` inside `<p>`                                                                                                                                   | Not applicable                                                             | Yes, as a lint step                                      |
| `eslint-plugin-hydration-proof`        | Your editor and lint step                                                   | Before the code runs                                     | 15 rules for render code: time, random values, browser globals, storage, media queries, locale and timezone formatting, unstable ids, invalid nesting, `suppressHydrationWarning`                 | Not applicable                                                             | Yes, as a lint step                                      |
| hydration-proof                        | A real browser driven by Playwright, on your machine or a CI runner         | On demand, for every route                               | Text and structure mismatches, silent attribute mismatches, markup the browser repaired, changes made by scripts or extensions before hydration, CDN rewrites; each with a likely cause and a fix | Yes: production is the default, `--mode both` tests both                   | Yes: exit codes, JUnit, SARIF, GitHub and GitLab reports |

The tools answer different questions. Runtime tools (the console, the overlays,
Sentry, hydration-proof) see what actually differed. Lint rules see code that
is likely to differ, before it runs, but nothing that happens outside your
source: extensions, CDNs, or data that changed between the two renders.

## When to choose each

### The browser console and the Next.js dev overlay

Use them while you work on a page. They are already there, and in development
React names the component. They only cover the page you have open, and they do
not run in CI. Next.js 16.2 added a hydration diff to the overlay that labels
server and client content with a `+ Client` / `- Server` legend.
[hydration-proof vs the Next.js dev overlay](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay)
goes into the details.

### react-hydration-overlay

`@builder.io/react-hydration-overlay` (version 0.3.0) shows an overlay with a
diff between the server and client renders when a hydration error happens. You
wrap your app root in its component and add its plugin; it supports Next.js and
webpack. Its README describes it as a beta, not intended for production use.
See [hydration-proof vs react-hydration-overlay](https://hydration.jscrate.dev/docs/compare/react-hydration-overlay).

### Sentry

Sentry is the one tool here that sees your real users' sessions. With Session
Replay set up and a browser SDK version 7.90.0 or later, a hydration error
captured in a replay has an "Open Hydration Diff" button that compares the page
before and after React hydrated. It tells you a mismatch happened in
production, not how to prevent the next one.
See [hydration-proof vs Sentry](https://hydration.jscrate.dev/docs/compare/sentry-hydration-errors).

### ESLint rules

Lint rules are the cheapest check: they run in your editor and flag the code
before it ships.

- The `purity` rule of `eslint-plugin-react-hooks` is part of its recommended
  preset, which `eslint-config-next` includes. It flags impure calls such as
  `Date.now()` and `Math.random()` in components and hooks. See
  [hydration-proof vs eslint-plugin-react-hooks](https://hydration.jscrate.dev/docs/compare/eslint-plugin-react-hooks).
- `eslint-plugin-validate-jsx-nesting` (version 0.1.1) reports invalid HTML
  nesting in JSX. See
  [hydration-proof vs eslint-plugin-validate-jsx-nesting](https://hydration.jscrate.dev/docs/compare/eslint-plugin-validate-jsx-nesting).
- [`eslint-plugin-hydration-proof`](https://hydration.jscrate.dev/docs/eslint) has 15 rules aimed at
  hydration: browser globals, storage, `matchMedia`, locale and timezone
  formatting, generated ids and more.

### hydration-proof

Use it when you want every route checked, not only the page you have open, and
the production build checked the way users get it. It runs in CI, fails the
build with exit code 1, and reports the element, both values, the source line,
the likely cause and a fix. It adds nothing to your app. Start with the
[quick start](https://hydration.jscrate.dev/docs/quick-start), then [add it to CI](https://hydration.jscrate.dev/docs/ci).

## How the tools fit together

The tools do not replace each other. A typical setup:

1. Lint rules in the editor, so the common mistakes never get written.
2. The console or the dev overlay while you build a page.
3. hydration-proof in CI, for every route and the production build.
4. Sentry in production, for what only real users' browsers show.

## Sources

Claims about other tools, as of September 2026:

- Next.js 16.2 release notes, "Hydration Diff Indicator": https://nextjs.org/blog/next-16-2
- Next.js, "Text content does not match server-rendered HTML": https://nextjs.org/docs/messages/react-hydration-error
- Next.js ESLint plugin (`eslint-config-next` includes the `eslint-plugin-react-hooks` recommended rules): https://nextjs.org/docs/app/api-reference/config/eslint
- `@builder.io/react-hydration-overlay` README: https://github.com/BuilderIO/hydration-overlay
- Sentry changelog, "Diff hydration errors with Replay" (SDK 7.90.0 or later): https://sentry.io/changelog/2024-1-5-diff-hydration-errors-with-replay
- Sentry changelog, hydration error diff generally available: https://sentry.io/changelog/debug-hydration-errors-with-our-diff-tool---now-generally-available
- React, `purity` lint: https://react.dev/reference/eslint-plugin-react-hooks/lints/purity
- React, `eslint-plugin-react-hooks` presets: https://react.dev/reference/eslint-plugin-react-hooks
- `eslint-plugin-validate-jsx-nesting`: https://github.com/MananTank/eslint-plugin-validate-jsx-nesting

## Related

- [How hydration-proof detects mismatches](https://hydration.jscrate.dev/docs/how-it-works)
- [The ESLint plugin](https://hydration.jscrate.dev/docs/eslint) and [all its rules](https://hydration.jscrate.dev/docs/rules)
- [Debug a hydration error](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [React hydration error FAQ](https://hydration.jscrate.dev/docs/faq)

---

# React hydration error FAQ

> React hydration error FAQ: short answers to the most asked questions, from error #418 and suppressHydrationWarning to useEffect, useId and next-themes.

Source: https://hydration.jscrate.dev/docs/faq
Last updated: 2026-09-18

This React hydration error FAQ answers the questions developers search for most,
in a few sentences each. Every answer links to the page that covers the topic
in full, with the exact error strings, before-and-after code and a way to find
every instance in your app.

## What is a hydration error in React?

Hydration is the step where React attaches to HTML the server already rendered,
instead of creating the DOM from scratch. React expects its first client render
to produce exactly that HTML. A hydration error means it did not: React 19 then
throws away the mismatching part and renders it again on the client, or, for an
attribute in a production build, keeps the wrong value without telling you.
[React hydration errors](https://hydration.jscrate.dev/docs/guides/react-hydration-error) explains the
behavior in detail.

## What causes hydration errors in Next.js?

Render code that produces different output on the server and in the browser.
The usual suspects are the current time, random values, locale or timezone
formatting, browser-only APIs such as `window` and `localStorage`, invalid HTML
nesting, and things outside your code: browser extensions, scripts that run
before hydration, and CDNs that rewrite HTML. See the
[common causes of hydration errors](https://hydration.jscrate.dev/docs/causes) and the
[Next.js guide](https://hydration.jscrate.dev/docs/frameworks/nextjs).

## How do I fix "Hydration failed because the initial UI does not match what was rendered on the server"?

This is React 18's error for a mismatch it could not recover from in place:

```text
Hydration failed because the initial UI does not match what was rendered on the server.
```

Find the element that differs, then make the first client render produce what
the server rendered: read browser-only values in `useEffect`, pass values the
server computed as props, and fix invalid nesting. The full walkthrough is in
[hydration failed: initial UI does not match](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match).

## What does "the server rendered HTML didn't match the client" mean in React 19?

It is React 19's wording of the same problem:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
```

React discarded the server HTML for the affected tree and rendered it again in
the browser. The page still works, but the server rendering was wasted and any
state in that tree is reset. See
[the server rendered HTML didn't match the client](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client).

## How do I find which component is causing a hydration error?

In development, React's error message includes a component stack, and the
Next.js dev overlay shows it for the page you have open. Production builds only
give a minified code. `npx hydration-proof test` loads every route and reports
the element's selector, the component, the server and client values and, in
development builds, the file and line. [Debug hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
shows each approach.

## Is it safe to use suppressHydrationWarning?

It is safe on a single element whose own text or attributes are meant to
differ, such as a timestamp or a theme class that an inline script sets before
hydration. React then keeps the server value and does not patch it. It is not
a fix for a real mismatch: it hides the bug, and the user keeps the wrong value.
See [when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Why is suppressHydrationWarning not working?

It only works one level deep: it covers the element's own attributes and its
direct text, not its child elements. It also cannot hide structural
differences, such as an element that exists on one side only. Put it on the
element whose text differs, and fix the cause of anything structural. The
[suppressHydrationWarning guide](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning) has
examples of both.

## Can I ignore or disable hydration errors in Next.js?

React has no setting that turns the check off for a page. You can silence one
element with `suppressHydrationWarning`, or render a component only in the
browser with `next/dynamic` and `ssr: false`. Neither fixes the mismatch, so
use them for content that is meant to differ. For known findings you are not
fixing yet, hydration-proof has [ignore rules](https://hydration.jscrate.dev/docs/ignoring) with a reason
and an expiry date.

## Why do I only get hydration errors in production?

Production is where the two renders drift apart most: cached pages rendered
hours earlier, real users' locales, timezones and browser extensions, and CDNs
that minify HTML. Production builds also report only a minified code, and React
19 does not report attribute mismatches there at all. See
[hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production).

## Can browser extensions cause hydration errors?

Yes. Extensions such as Grammarly, ColorZilla and password managers add
attributes or elements to the page before React hydrates, and React reports the
difference as if your code caused it. Nothing needs to change in your app; test
in a clean browser profile. hydration-proof reports these changes as
[HP4002](https://hydration.jscrate.dev/docs/issues/hp4002), an info finding. See
[browser extension hydration errors](https://hydration.jscrate.dev/docs/causes/extension).

## What does "Extra attributes from the server: cz-shortcut-listen" mean?

`cz-shortcut-listen` is an attribute the ColorZilla extension adds to `<body>`.
React 18 found it in the DOM but not in what it rendered, and warned about it.
It is not a bug in your code, and it does not appear for users without the
extension. See [extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server).

## How do I show dates without a hydration mismatch?

Read the clock once on the server and pass the value down as a prop, so both
renders format the same number. Format with an explicit `locale` and `timeZone`,
never the runtime's defaults. For live values such as countdowns, render a
placeholder and fill it in from `useEffect`. The
[date and time guide](https://hydration.jscrate.dev/docs/causes/time) has code for each fix.

## Why does toLocaleString() cause a hydration error?

Without arguments, `toLocaleString()` uses the default locale and timezone of
the runtime: the server's on the server and the visitor's in the browser. The
same date then renders as two different strings. Pass an explicit locale and
`timeZone` on both sides. See [locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale).

## How do I use localStorage in Next.js without a hydration error?

`localStorage` only exists in the browser, so a value read from it during render
differs from what the server rendered. Render a neutral value first and read
storage in `useEffect`, or use `useSyncExternalStore` with a
`getServerSnapshot` that returns the server's value. See
[localStorage hydration errors](https://hydration.jscrate.dev/docs/causes/storage).

## How do I fix the next-themes hydration error?

The server cannot know the visitor's theme. next-themes sets the theme on
`<html>` with a script before hydration, so add `suppressHydrationWarning` to
`<html>`, as its README says. Anything that renders from `useTheme()`, such as
a theme toggle, must wait until the component has mounted. See
[theme hydration errors](https://hydration.jscrate.dev/docs/causes/theme).

## What is minified React error #418?

It is the production code for a hydration mismatch. In React 18 it stands for
"Hydration failed because the initial UI does not match what was rendered on
the server." In React 19 it stands for "Hydration failed because the server
rendered HTML didn't match the client," and it also covers text mismatches.
See [React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418).

## What's the difference between React errors #418, #423 and #425?

| Code | React 18                                                                                | React 19                                                                   |
| ---- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| #418 | Hydration failed because the initial UI does not match what was rendered on the server. | Hydration failed because the server rendered HTML didn't match the client. |
| #423 | There was an error while hydrating; the entire root switches to client rendering.       | React recovered by client rendering the entire root.                       |
| #425 | Text content does not match server-rendered HTML.                                       | Folded into #418                                                           |

In React 18 you often see all three for one bug: #425 for the text, #418 for
the failed hydration, and #423 for the fallback to client rendering. See
[minified React error codes](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes).

## Why can't a `<div>` be inside a `<p>` in React?

The HTML parser closes a `<p>` as soon as a block element such as `<div>`
starts. The browser's DOM then no longer matches the tree React rendered, and
hydration fails. Use a `<span>`, or make the outer element a `<div>`. See
[div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p).

## How do I disable SSR for one component in Next.js?

Import it with `next/dynamic` and `ssr: false` from a Client Component; the App
Router does not allow `ssr: false` in Server Components. The component then
renders only in the browser, after hydration. See
[next/dynamic with ssr: false](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false) and
[client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component).

## Does useEffect run on the server?

No. Effects run only in the browser, after React has committed the first
render. That is why reading browser values in `useEffect` keeps the first client
render identical to the server HTML. See
[useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering).

## What is the difference between hydrateRoot and createRoot?

`hydrateRoot` attaches React to HTML the server already rendered and reuses
those DOM nodes, so the first client render must match it. `createRoot` clears
whatever is inside the container the first time it renders, then builds the DOM
itself, so there is nothing to mismatch. Server-rendered and statically
generated apps must use `hydrateRoot`. See
[what is hydration in React](https://hydration.jscrate.dev/docs/guides/what-is-hydration).

## Do hydration errors hurt SEO or performance?

They cost performance: React 19 renders the mismatching tree again on the
client, which is slower and resets its state. They can also change what users
and crawlers see, because the content after hydration is not the content the
server sent, and attribute mismatches in production stay wrong. See
[hydration errors and SEO](https://hydration.jscrate.dev/docs/guides/hydration-errors-seo).

## Why does useId cause a hydration mismatch?

`useId` builds each id from the component's position in the tree, so it only
matches when the server and the client render the same tree. A branch that
renders on one side only shifts the ids after it. Several React roots on one
page also need different `identifierPrefix` values. See
[generated ids that differ](https://hydration.jscrate.dev/docs/causes/unstable-id).

## How do I test for hydration errors in Playwright or CI?

Listening for console errors in a Playwright test catches what React reports,
but production builds only print minified codes, and React 19 never reports
attribute mismatches there. `npx hydration-proof test` uses Playwright to load
every route, compares the server HTML with the hydrated page, and exits with
code 1 when it finds a problem. See [Playwright](https://hydration.jscrate.dev/docs/playwright) and
[detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci).

## Is there an ESLint rule that catches hydration errors?

Yes. `eslint-plugin-hydration-proof` has 15 rules for render code, such as
[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) and
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render).
The `purity` rule in `eslint-plugin-react-hooks` flags calls such as
`Date.now()` and `Math.random()` in render. Lint rules cannot see extensions,
CDNs or data differences, so pair them with a runtime test. See
[all ESLint rules](https://hydration.jscrate.dev/docs/rules).

## Related

- [All React hydration error messages](https://hydration.jscrate.dev/docs/errors)
- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes)
- [Debug a hydration error step by step](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Quick start with hydration-proof](https://hydration.jscrate.dev/docs/quick-start)
- [Hydration error tools compared](https://hydration.jscrate.dev/docs/comparison)

---

# Releases

> hydration-proof releases: every version of the CLI and the ESLint plugin, how versions are numbered, how to upgrade with migrate, and the history up to 1.0.

Source: https://hydration.jscrate.dev/docs/releases
Last updated: 2026-09-18

hydration-proof releases publish both packages, `hydration-proof` and
`eslint-plugin-hydration-proof`, together at the same version. The timeline
below lists every release on GitHub with its highlights. Version 1.0.0 is the
first stable release: from it on, the CLI, the config, the report schema, the
issue codes and the exit codes follow semver.

Release notes are on GitHub: https://github.com/re-sohail/hydration-proof/releases

The full notes are on
[GitHub releases](https://github.com/re-sohail/hydration-proof/releases) and
in each package's `CHANGELOG.md`.

## How versions are numbered

- **Lockstep.** The two packages are versioned together with Changesets, so a
  release always publishes both, even when only one of them changed.
- **Semver.** A patch release fixes bugs. A minor release adds detections and
  options. A major release is the only kind that may break something the
  [compatibility promise](https://hydration.jscrate.dev/docs/compatibility) covers.
- **What is not frozen.** Diagnosis keeps improving in minor releases: which
  cause a finding gets, confidence scores and the wording of messages. Pin the
  behavior you rely on with `ci.failOn` and `ci.budget`, not with the causes.

Releases are published from CI with npm trusted publishing, so every version
has a provenance attestation. You can check the packages you installed:

```sh
npm audit signatures
```

## How to upgrade

1. Update both packages to the new version.
2. Run `migrate` to see which config options were renamed or replaced.
3. Apply the safe renames with `--write`. The old file is kept as a backup, and
   anything that needs a judgment call is listed for you to change by hand.
4. Run your tests. Between minor versions, expect new findings: better detection
   is the point of a release.

```bash
npx hydration-proof migrate
npx hydration-proof migrate --write
```

If a release reports something you have decided to live with, park it with an
[ignore rule](https://hydration.jscrate.dev/docs/ignoring) that has a reason and an expiry date, or adopt the
release with `ci.newIssuesOnly` and a [baseline](https://hydration.jscrate.dev/docs/baselines) so the
pipeline stays green on day one. The [CLI reference](https://hydration.jscrate.dev/docs/cli#migrate) has
the details of `migrate`.

## hydration-proof releases from 0.1 to 1.0

| Version | What it added                                                                                                                                                                                                                                                                                                                                 |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.1.0   | The first release: `hydration-proof test` loads every route in Chromium, Firefox or WebKit through the React DevTools hook, and reports text, structure, attribute, class and style mismatches, invalid HTML, changes before hydration and CDN rewrites. Stable issue codes, fingerprints and exit codes, plus `init`, `install` and `doctor` |
| 0.2.0   | Findings explain themselves: a likely cause with a confidence score, the component and source line, the HTML report, `--mode both`, and the `suppressHydrationWarning` audit                                                                                                                                                                  |
| 0.3.0   | The whole app: pre-rendered dynamic pages, the not-found page, query variants, sitemaps and crawling; signed-in pages with `login`; API mocks; hooks; `--shard`; the route cache                                                                                                                                                              |
| 0.4.0   | Environments: the matrix, probes that prove a cause, and `--repeat` for flaky findings                                                                                                                                                                                                                                                        |
| 0.5.0   | The ESLint plugin: 15 rules for render code, with the `recommended`, `next` and `strict` presets                                                                                                                                                                                                                                              |
| 0.6.0   | Streaming and Suspense boundaries compared one by one, document checks, navigation and interaction checks                                                                                                                                                                                                                                     |
| 0.7.0   | CI and teams: JUnit, SARIF, GitHub and GitLab reports, baselines, budgets, owners, `--changed`, `merge-reports`, monorepos, trends and redaction                                                                                                                                                                                              |
| 0.8.0   | Adapters for React Router, Remix, Astro, Vite SSR and custom Node servers, `defineAdapter`, plugins, and the `dev`, `test --watch` and `ui` tools                                                                                                                                                                                             |
| 0.9.0   | Hardening: source maps only from the app's own origin (`sourceOrigins`), `migrate`, and a regression gate of recorded browser captures                                                                                                                                                                                                        |
| 1.0.0   | The written [compatibility promise](https://hydration.jscrate.dev/docs/compatibility), form controls and SVG attributes audited, causes limited to the element's own function, and baselines that survive a fingerprint change                                                                                                                                             |

The ESLint plugin first appeared in 0.5.0; its later releases have had no
changes of their own. At 1.0, the package's test suite covered 63 fixture
cases across the Next.js App Router and Pages Router: 40 broken pages and 23
correct control pages, each checked against React's own verdict.

## Related

- [Compatibility and stability](https://hydration.jscrate.dev/docs/compatibility): what each release may
  change
- [The CLI](https://hydration.jscrate.dev/docs/cli), including `migrate`
- [Baselines and budgets](https://hydration.jscrate.dev/docs/baselines) for adopting a new release
- [About hydration-proof](https://hydration.jscrate.dev/docs/about)
- [Quick start](https://hydration.jscrate.dev/docs/quick-start)

---

# About hydration-proof

> About hydration-proof: the open-source CLI and ESLint plugin for React hydration errors, its principles, its author, the MIT license and how to report issues.

Source: https://hydration.jscrate.dev/docs/about
Last updated: 2026-09-18

Everything about hydration-proof starts from one goal: find, explain and prevent
React hydration problems before users see them. It is an open-source project
with two npm packages, a CLI that tests every route of your app in a real
browser and an ESLint plugin that flags risky render code. Sohail Khan writes
it, under the MIT license.

## The two packages

| Package                         | What it does                                                                                                                                                                                                                                 | Start here                       |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `hydration-proof`               | A CLI and Node API. It loads every route of a server-rendered React app in a real browser through Playwright, compares the server HTML with the hydrated DOM, and reports each difference with a stable issue code, a likely cause and a fix | [Quick start](https://hydration.jscrate.dev/docs/quick-start) |
| `eslint-plugin-hydration-proof` | 15 ESLint rules that catch hydration mismatches in render code while you write it                                                                                                                                                            | [ESLint plugin](https://hydration.jscrate.dev/docs/eslint)    |

Both are released together, at the same version; see [releases](https://hydration.jscrate.dev/docs/releases).

## Principles

- **Nothing is added to your app.** The CLI injects its runtime into the test
  browser only. Your code and build are not modified, and nothing ships in your
  production bundle.
- **No telemetry.** Nothing about your app, your run or your machine is
  uploaded: no analytics, no crash reporting, no version check.
- **No install scripts.** The package has no `postinstall` or other lifecycle
  script. Browsers are only downloaded when you run `hydration-proof install`.
- **One runtime dependency.** `playwright-core` is the only one, and it has none
  of its own. The ESLint plugin has no runtime dependencies.
- **Stable interfaces.** Issue codes, exit codes, the report schema and
  fingerprints do not change their meaning. From 1.0 on, the
  [compatibility promise](https://hydration.jscrate.dev/docs/compatibility) says what follows semver.
- **Every detection is proven.** Each detection has a fixture case: a broken
  page and a correct control, checked against React's own verdict. Every false
  positive that gets fixed becomes a recorded control page, so it cannot come
  back.

## Who makes it

hydration-proof is written by [Sohail Khan](https://me.jscrate.dev). The source
is on GitHub at
[re-sohail/hydration-proof](https://github.com/re-sohail/hydration-proof), and
this site is its documentation.

Both packages are released under the MIT license, copyright Sohail Khan.

## Questions about hydration-proof

### Report a bug or ask for a feature

Open an issue on
[GitHub](https://github.com/re-sohail/hydration-proof/issues). A bug report
with a minimal reproduction is the most valuable contribution: include the
version, the command you ran and the output. The
[troubleshooting](https://hydration.jscrate.dev/docs/troubleshooting) page covers the common problems first.

### Report a security issue

Report vulnerabilities privately through
[GitHub security advisories](https://github.com/re-sohail/hydration-proof/security/advisories/new),
not in public issues. Include the version, the command you ran and, if you can,
an app that shows the problem. You get a first reply within a week, and security
fixes are released for the latest minor version. [Security](https://hydration.jscrate.dev/docs/security)
describes what hydration-proof does with your app's data.

### Contribute

[CONTRIBUTING.md](https://github.com/re-sohail/hydration-proof/blob/main/CONTRIBUTING.md)
has the setup and the checks to run. Contributions follow a few rules:

- No new runtime dependencies. Use Node built-ins or write the code.
- A new detection needs a fixture case, a broken page and a correct control,
  and must keep detection at 100% with 0 false positives.
- A user-visible change needs a changeset that describes it for the changelog.

## Related

- [How hydration-proof detects mismatches](https://hydration.jscrate.dev/docs/how-it-works)
- [Releases and changelog](https://hydration.jscrate.dev/docs/releases)
- [Compatibility and stability](https://hydration.jscrate.dev/docs/compatibility)
- [Security and your app's data](https://hydration.jscrate.dev/docs/security)
- [Quick start](https://hydration.jscrate.dev/docs/quick-start)

---

# What is hydration in React?

> What is hydration in React? How server HTML becomes an interactive page with hydrateRoot, what a mismatch means, and what Server Components change.

Source: https://hydration.jscrate.dev/docs/guides/what-is-hydration
Last updated: 2026-09-18

What is hydration in React? It is the step where React, running in the browser, takes over HTML the server already rendered. It renders the same components again, matches the result to the existing DOM nodes and attaches event handlers, instead of building the page from scratch. The page is visible before JavaScript loads and interactive after hydration.

## What is hydration in React, step by step

The steps of React hydration (SSR, then `hydrateRoot`) are:

1. **The server renders your components to HTML.** A framework such as Next.js or React Router does this for you with `react-dom/server`.
2. **The browser shows that HTML.** Text, images and links appear before any of your JavaScript has run. Buttons do nothing yet.
3. **The JavaScript bundle loads.** It contains the same components the server rendered.
4. **React hydrates.** It renders the component tree once more in the browser, walks the existing DOM alongside it, and attaches event handlers to the nodes it finds.
5. **The page is interactive.** From here on, React updates the DOM like in any client-rendered app.

Step 4 only works if the browser's first render produces exactly the HTML the server sent. The [hydrateRoot reference](https://react.dev/reference/react-dom/client/hydrateRoot) puts it plainly: the tree "needs to produce the same output as it did on the server."

## React hydration explained in code

Frameworks call this for you, but underneath it is one function. With a custom server, the client entry looks like this:

```tsx title="src/entry.client.tsx"
import { hydrateRoot } from "react-dom/client";
import { App } from "./App";

// The server already rendered <App /> into #root.
hydrateRoot(document.getElementById("root")!, <App />, {
  // Called when React recovers from an error, including a hydration mismatch.
  onRecoverableError(error, errorInfo) {
    console.error(error, errorInfo.componentStack);
  },
});
```

`hydrateRoot`, React's client API for server HTML, takes the DOM node, the same React element the server rendered, and options. The options include `onRecoverableError`, `onCaughtError`, `onUncaughtError` and `identifierPrefix` (the prefix for `useId`, which must match the one used on the server). Tutorials that write `ReactDOM.hydrateRoot` mean the same function, imported from `react-dom/client`.

## hydrateRoot vs createRoot

|                         | `hydrateRoot`                        | `createRoot`            |
| ----------------------- | ------------------------------------ | ----------------------- |
| Starts from             | HTML the server rendered             | An empty DOM node       |
| First render            | Adopts existing DOM nodes            | Creates every DOM node  |
| Needs                   | The same output on server and client | Nothing from the server |
| When the output differs | A hydration error                    | Not applicable          |

Use `createRoot` for an app that is rendered only in the browser. React's docs say calling `hydrateRoot` without server HTML is not supported. hydration-proof reports a page that mounts with `createRoot` as [HP9003](https://hydration.jscrate.dev/docs/issues/hp9003), for information: nothing on that page is hydrated.

## Hydration mismatch: meaning and consequences

A hydration mismatch means the first client render differs from the server HTML: different text, a different attribute, or a different element. React treats it as a bug. Its docs say: "You should treat mismatches as bugs and fix them."

What happens next depends on the React version and the build:

- **Text or structure differs (React 19):** React throws the server HTML away and renders that part of the tree again on the client. The whole root is rendered again if no Suspense boundary contains the mismatch. In development it logs a diff; in production, a minified error #418.
- **An attribute differs (React 19):** React keeps the server's value and does not patch it. Development builds warn; production builds report nothing at all.
- **React 18:** the same kinds of differences produce "Hydration failed because the initial UI does not match what was rendered on the server" and related warnings, or minified errors #418, #423 and #425 in production.

The [React hydration error guide](https://hydration.jscrate.dev/docs/guides/react-hydration-error) lists every message and cause, and [all error messages](https://hydration.jscrate.dev/docs/errors) decodes them one by one.

## What is hydration in web development?

Outside React, the word means the same thing. A server renders a page to HTML, and a client-side framework later takes over that HTML by attaching its state and event listeners rather than replacing the markup. The alternative is client-side rendering, where the server sends an empty shell and JavaScript builds the whole page.

Hydration gives you HTML for the first paint, for crawlers and for users on slow connections, plus a full client app afterwards. The cost is that the component code runs twice, once on each side, and both runs must agree. Astro applies the idea per component: each React island hydrates on its own, when its `client:*` directive says so.

## What is hydration in Next.js?

Next.js server-renders your pages and calls `hydrateRoot` for you. How much of the page hydrates depends on the router:

- **Pages Router:** the whole page is a client component tree. It is rendered on the server and hydrated in the browser.
- **App Router:** Server Components render only on the server. Client Components, the files marked `"use client"`, are also prerendered to HTML on the server and then hydrated. `"use client"` does not mean "client only".

That last point causes many mismatches: code in a Client Component that reads `window`, `localStorage` or the clock runs on the server too. See [Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs) for the common cases.

## Do Server Components hydrate?

No. With React Server Components, hydration covers only the Client Components. A Server Component's code never runs in the browser, so reading the clock or a random value there cannot cause a mismatch: the browser receives the result, not the code.

The HTML elements a Server Component renders are still part of the page React hydrates. Invalid nesting, such as a `<div>` inside a `<p>`, breaks hydration whether a Server Component or a Client Component wrote it.

## Streaming and selective hydration

With streaming server rendering, the server sends HTML in pieces: the shell first, then each Suspense boundary when its data is ready. React hydrates the root first and then each boundary once its HTML and code have arrived, and it hydrates the boundary the user interacts with first.

Boundaries also limit the damage of a mismatch. When hydration fails inside a Suspense boundary, React renders only that boundary again on the client. hydration-proof reports that as [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) and a whole-page re-render as [HP1011](https://hydration.jscrate.dev/docs/issues/hp1011). [How hydration-proof works](https://hydration.jscrate.dev/docs/how-it-works) explains how it checks each streamed boundary on its own.

## Check that your pages hydrate

Reading the console on one page at a time misses most mismatches. hydration-proof loads every route in a real browser and compares the server HTML with what React renders:

```bash
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test
```

The [quick start](https://hydration.jscrate.dev/docs/quick-start) walks through the first report.

## Related

- [React hydration errors: messages, causes and fixes](https://hydration.jscrate.dev/docs/guides/react-hydration-error)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes)
- [Client-only components in Next.js, Remix and TanStack](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [How hydration-proof compares the server and client renders](https://hydration.jscrate.dev/docs/how-it-works)

---

# React hydration errors

> A React hydration error means the server HTML and the first client render differ. The messages in React 18 and 19, what causes each one, and how to fix it.

Source: https://hydration.jscrate.dev/docs/guides/react-hydration-error
Last updated: 2026-09-18

A React hydration error means the HTML the server sent and the first render in the browser are different. React logs an error and, in React 19, throws that part of the server HTML away and renders it again on the client. The fix is to make both renders produce the same output.

## Hydration error meaning: what React is telling you

React renders your components twice: once on the server to produce HTML, and once in the browser during [hydration](https://hydration.jscrate.dev/docs/guides/what-is-hydration), where it expects the exact same output. A hydration error in React JS apps is the report that the two did not match.

A React hydration mismatch comes in three kinds:

- **Text:** the server wrote "5:00 AM", the browser rendered "10:00 AM".
- **Attributes:** a `className`, `style`, `href` or `data-*` value differs.
- **Structure:** one side rendered an element the other did not, or a different one.

Every hydration problem in React comes from one of two places: code that renders different output on the two sides, or something that changed the HTML between the server and React (the browser's parser, an extension, a script or a CDN).

## The messages you see

The wording depends on the React version and on the build. These are the ones people search for:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
Hydration failed because the initial UI does not match what was rendered on the server.
Text content does not match server-rendered HTML.
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
In HTML, <div> cannot be a descendant of <p>. This will cause a hydration error.
Minified React error #418; visit https://react.dev/errors/418
```

| Message                                                                   | Where you see it                                       | Decoded                                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Hydration failed because the server rendered HTML didn't match the client | React 19 (#418 in production)                          | [Page](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client) |
| A tree hydrated but some attributes … didn't match                        | React 19, development only                             | [Page](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)                 |
| Hydration failed because the initial UI does not match                    | React 18                                               | [Page](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)               |
| Text content does not match server-rendered HTML                          | React 18                                               | [Page](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)         |
| There was an error while hydrating                                        | React 18                                               | [Page](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating)                       |
| Prop `className` did not match                                            | React 18, development                                  | [Page](https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match)                             |
| Expected server HTML to contain a matching …                              | React 18, development                                  | [Page](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching)               |
| Extra attributes from the server                                          | React 18, development                                  | [Page](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server)                         |
| `<div>` cannot be a descendant of `<p>`                                   | React 19, development (React 18: `validateDOMNesting`) | [Page](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p)                          |
| Minified React error #418, #423, #425                                     | Production builds                                      | [Page](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)                               |

The full list, with the React 18 and 19 wording side by side, is on [React hydration error messages](https://hydration.jscrate.dev/docs/errors).

## What causes a hydration error in React?

Each cause below has its own fix guide. hydration-proof names the likely cause for every finding.

| Cause               | Typical code                                               | Fix guide                                              |
| ------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| The clock           | `Date.now()`, `new Date()` in render                       | [Time](https://hydration.jscrate.dev/docs/causes/time)                              |
| Timezone            | `toLocaleTimeString()` without `timeZone`                  | [Timezone](https://hydration.jscrate.dev/docs/causes/timezone)                      |
| Locale              | `toLocaleString()`, `Intl.NumberFormat()` without a locale | [Locale](https://hydration.jscrate.dev/docs/causes/locale)                          |
| Random values       | `Math.random()`, `crypto.randomUUID()`                     | [Random](https://hydration.jscrate.dev/docs/causes/random)                          |
| Browser-only APIs   | `typeof window !== "undefined"`, `navigator`               | [Browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api)               |
| Storage             | `localStorage.getItem()` in render or initial state        | [Storage](https://hydration.jscrate.dev/docs/causes/storage)                        |
| Screen size         | `matchMedia()`, `window.innerWidth`                        | [Media query](https://hydration.jscrate.dev/docs/causes/media-query)                |
| Theme               | dark mode read from storage                                | [Theme](https://hydration.jscrate.dev/docs/causes/theme)                            |
| Data                | the client fetches again and gets a different answer       | [Data](https://hydration.jscrate.dev/docs/causes/data)                              |
| Invalid HTML        | `<div>` in `<p>`, `<a>` in `<a>`, `<tr>` in `<table>`      | [Invalid HTML](https://hydration.jscrate.dev/docs/causes/invalid-html)              |
| CSS-in-JS           | class names generated in a different order                 | [CSS-in-JS](https://hydration.jscrate.dev/docs/causes/css-in-js)                    |
| Ids                 | counters or random ids instead of `useId()`                | [Unstable ids](https://hydration.jscrate.dev/docs/causes/unstable-id)               |
| Browser extensions  | attributes such as `cz-shortcut-listen`                    | [Extensions](https://hydration.jscrate.dev/docs/causes/extension)                   |
| Scripts             | a tag manager edits the DOM before React                   | [Third-party scripts](https://hydration.jscrate.dev/docs/causes/third-party-script) |
| CDN rewrites        | HTML minification at the edge                              | [CDN](https://hydration.jscrate.dev/docs/causes/cdn)                                |
| Server Action forms | `useActionState` with a permalink                          | [Form state](https://hydration.jscrate.dev/docs/causes/form-state)                  |

## How to fix a React hydration error

1. **Find the element.** Read the diff React logs in development, or let a tool point at it. [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors) covers both.
2. **Name the cause.** Compare the two values: a timestamp, a number in another format, a random token or a different class name each point at one row of the table above.
3. **Make the first client render match the server.** Pick the first fix that applies:
   - pass the value the server used as a prop, so both sides render the same data;
   - move browser-only reads into `useEffect`, so they happen after hydration ([two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering));
   - read external stores with `useSyncExternalStore` and a `getServerSnapshot` that returns the server's value;
   - render the component only in the browser ([client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component));
   - fix invalid nesting so the browser does not rewrite the HTML.
4. **Check every page again,** not only the one you fixed.

A typical fix, for a date formatted in the reader's timezone:

```tsx title="app/components/last-login.tsx"
"use client";

// Before: the server formats in its timezone, the browser in the reader's.
export function LastLogin({ at }: { at: number }) {
  return <p>Signed in at {new Date(at).toLocaleTimeString()}</p>;
}
```

```tsx title="app/components/last-login.tsx"
"use client";

// After: the same locale and timezone on both sides.
export function LastLogin({ at, timeZone }: { at: number; timeZone: string }) {
  return (
    <p>Signed in at {new Date(at).toLocaleTimeString("en-US", { timeZone })}</p>
  );
}
```

## How to solve a hydration error without hiding it

`suppressHydrationWarning` makes React stop reporting a difference in one element's own text and attributes. React keeps the server's value and does not patch it, so the user sees the stale value. It is for values that can never match, such as a live clock, not for bugs. [suppressHydrationWarning](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning) explains when it is safe and why it often does nothing.

## Which React hydration issues stay silent?

Not every hydration mismatch error throws:

- **React 19 production builds do not report attribute mismatches at all.** A wrong `className`, `style` or `href` stays on the page with no error in the console.
- **Production builds minify messages.** You get "Minified React error #418" with no element and no diff. See [errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production).
- **A hydration mismatch warning is a development feature.** React 18's "Warning: Prop `className` did not match" and React 19's attribute warning are never printed by production builds.

These are the ones a hydration warning in your console will never show you, and why hydration-proof compares every attribute with what React renders on the client.

## Framer Motion hydration error

Motion (formerly Framer Motion) renders the `initial` state of a `motion` component into the server HTML. Its docs say motion components "are fully compatible with server-side rendering, meaning the initial state of the component will be reflected in the server-generated output" ([motion.dev](https://motion.dev/docs/react-motion-component)).

So a framer motion hydration error appears when `initial` or `animate` depends on something only the browser knows: the window size, a random value, or a stored preference. The server writes one inline `style`, the browser computes another.

```tsx title="components/slide-in.tsx"
"use client";

import type { ReactNode } from "react";
import { motion } from "motion/react";

// Before: window.innerWidth is unknown on the server.
export function SlideIn({ children }: { children: ReactNode }) {
  const from = typeof window === "undefined" ? 0 : -window.innerWidth;
  return (
    <motion.div initial={{ x: from }} animate={{ x: 0 }}>
      {children}
    </motion.div>
  );
}
```

```tsx title="components/slide-in.tsx"
"use client";

import type { ReactNode } from "react";
import { motion } from "motion/react";

// After: the same starting value on both sides, in a unit that does not
// depend on the screen.
export function SlideIn({ children }: { children: ReactNode }) {
  return (
    <motion.div initial={{ x: "-100%" }} animate={{ x: 0 }}>
      {children}
    </motion.div>
  );
}
```

To skip the enter animation entirely, `initial={false}` renders the `animate` values on the server and in the browser. A style difference is an attribute mismatch, so React 19 production builds report nothing; hydration-proof reports it as [HP1003](https://hydration.jscrate.dev/docs/issues/hp1003).

## Tools that find hydration errors

| Tool                                                    | When it runs                                       | What it finds                                                           |
| ------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------- |
| React's console messages                                | Development, the page you have open                | The mismatches React reports, with a diff in React 19                   |
| [Next.js dev overlay](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay) | `next dev`, one page at a time                     | The same, with a code frame                                             |
| [eslint-plugin-hydration-proof](https://hydration.jscrate.dev/docs/eslint)           | Your editor and CI, on source code                 | Patterns that cause mismatches, before they run                         |
| [hydration-proof test](https://hydration.jscrate.dev/docs/quick-start)               | CI, every route, development and production builds | Mismatches that happen, including silent attribute ones, with the cause |
| [Sentry](https://hydration.jscrate.dev/docs/compare/sentry-hydration-errors)         | Production, real users                             | Errors React reports in your users' browsers                            |

```bash
npx hydration-proof test --mode both
```

## Related

- [What is hydration in React?](https://hydration.jscrate.dev/docs/guides/what-is-hydration)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes)
- [The ESLint rules that catch them early](https://hydration.jscrate.dev/docs/rules)

---

# Debugging hydration errors

> How to debug a hydration error: read React's diff, find the component, rule out browser extensions, and trace production-only mismatches to their cause.

Source: https://hydration.jscrate.dev/docs/guides/debug-hydration-errors
Last updated: 2026-09-18

To debug a hydration error, find the element that differs, compare the server's value with the client's, and let that difference tell you the cause. React 19's development build prints a diff that does most of this. For production-only errors and silent attribute mismatches, you need the server HTML and a tool that compares it for you.

## How to debug a hydration error, step by step

A typical React debug hydration error session takes five steps:

1. **Reproduce it in a clean browser profile.** Open the page in a guest or private window with extensions turned off. If the error disappears, an extension caused it (see [browser extensions](#rule-out-browser-extensions)).
2. **Run a development build.** Production builds only print minified codes. Development builds print the component stack and, in React 19, a diff.
3. **Read the diff.** Lines starting with `+` are what the client rendered, lines starting with `-` are what the server sent.
4. **Find the component.** Follow the component stack under the diff to your file.
5. **Name the cause from the two values,** then fix it and check the page again.

## Read the diff React prints

React 19 logs a single error with a diff of the mismatch and the tree around it. This is the example from the [React 19 release post](https://react.dev/blog/2024/12/05/react-19):

```text
Uncaught Error: Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if an SSR-ed Client Component used:
...
https://react.dev/link/hydration-mismatch

  <App>
    <span>
+    Client
-    Server
```

React 18 printed separate warnings instead, for example `Warning: Text content did not match. Server: "Server" Client: "Client"`, followed by "Hydration failed because the initial UI does not match what was rendered on the server."

The two values usually give the cause away:

| The values look like                            | Likely cause                                |
| ----------------------------------------------- | ------------------------------------------- |
| Two timestamps a few hundred milliseconds apart | [The clock](https://hydration.jscrate.dev/docs/causes/time)              |
| The same time, hours apart                      | [Timezone](https://hydration.jscrate.dev/docs/causes/timezone)           |
| `1,234.5` and `1.234,5`                         | [Locale](https://hydration.jscrate.dev/docs/causes/locale)               |
| Two random-looking tokens                       | [Random values or ids](https://hydration.jscrate.dev/docs/causes/random) |
| `light` and `dark`                              | [Theme](https://hydration.jscrate.dev/docs/causes/theme)                 |
| Desktop and mobile markup                       | [Media queries](https://hydration.jscrate.dev/docs/causes/media-query)   |
| Different records or counts                     | [Data](https://hydration.jscrate.dev/docs/causes/data)                   |
| Class names like `sc-a1b2` in a different order | [CSS-in-JS](https://hydration.jscrate.dev/docs/causes/css-in-js)         |

## How to find which component causes a hydration error

When the diff is not enough, narrow it down:

1. **Follow the component stack.** The first component in it that you wrote is usually the one to look at.
2. **Compare the server HTML with the DOM.** "View page source" shows the HTML the server sent. The Elements panel shows the DOM after React changed it. Search both for the text around the error.
3. **Turn JavaScript off.** In DevTools, disable JavaScript and reload: what you see is the server's version of the page.
4. **Bisect.** Comment out half of the page's children, or return `null` from them, and reload. Keep the half that still errors and repeat. A mismatch in a layout shows up on every page, one in a page component only there.
5. **Check shared components.** A header or footer that reads the clock, a cookie banner or a theme toggle breaks every route at once.

## Rule out browser extensions

Extensions such as password managers and grammar checkers add attributes to `<body>` or `<input>` before React hydrates. The diff then shows attributes you never wrote, for example `cz-shortcut-listen="true"` or `data-new-gr-c-s-check-loaded`. Nothing in your code is wrong: test in a clean profile, and read [browser extension hydration errors](https://hydration.jscrate.dev/docs/causes/extension) for the list of attributes.

## Debug hydration errors in Next.js

When you debug a hydration error, Next.js adds its own tools on top of React's:

- **The dev overlay.** Since Next.js 15, hydration errors show the source code of the error with suggestions. Since Next.js 16.2, the overlay labels the diff with a `+ Client` / `- Server` legend ([Next.js 16.2 release notes](https://nextjs.org/blog/next-16-2)).
- **The error page.** Next.js links the message to [its hydration error page](https://nextjs.org/docs/messages/react-hydration-error), which lists the usual causes.

The overlay shows one page at a time, while you browse, in development. [Next.js dev overlay compared](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay) covers what it does not see.

## Debug hydration mismatch reports in production

Production builds print `Minified React error #418` with no element and no diff, and React 19 production builds do not report attribute mismatches at all. To trace them:

1. Build and start the app locally in production mode, with the server's timezone and locale.
2. Turn on browser source maps (`productionBrowserSourceMaps: true` in Next.js) to map minified code to your files.
3. Test development and production builds side by side and compare what each reports.

[React hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production) walks through each step.

## Let hydration-proof do the search

hydration-proof loads every route, compares the server HTML with what React renders, and prints the element, both values, the component, the source line and the likely cause:

```bash
npx hydration-proof test
npx hydration-proof test --mode both   # development and production builds
npx hydration-proof test --probe       # prove the cause
```

With `--probe`, each page with a value mismatch is loaded again with one thing changed at a time: the clock, the random seed, the locale, the timezone, the theme, the viewport or storage. The factor that changes the value is the cause ([probes](https://hydration.jscrate.dev/docs/probes)).

While you work on a page, `npx hydration-proof dev` opens the app with an overlay that shows the findings of every page you open, highlights the element and opens the source line in your editor ([dev overlay](https://hydration.jscrate.dev/docs/dev-overlay)).

## Related

- [React hydration errors: messages and causes](https://hydration.jscrate.dev/docs/guides/react-hydration-error)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes)
- [The hydration-proof CLI](https://hydration.jscrate.dev/docs/cli)
- [Reading hydration-proof reports](https://hydration.jscrate.dev/docs/reports)

---

# Hydration errors only in production

> A React hydration error only in production usually means different data, timezone or HTML rewrites on the server. How to reproduce it, read #418 and fix it.

Source: https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production
Last updated: 2026-09-18

A React hydration error only in production usually means the production server renders something your machine does not: another timezone or locale, cached HTML, different data, or HTML that a CDN rewrites on the way. Production builds also say less, with minified codes, no diff and, in React 19, no report at all for attribute mismatches.

## Why you get a React hydration error only in production

A random React hydration error 418 that shows up only on prod (on Vercel or any other host) usually has one of these causes:

| Cause                               | Why production differs                                                                                          | Fix guide                                              |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| The server's timezone               | Servers usually run in UTC; your laptop runs in your timezone                                                   | [Timezone](https://hydration.jscrate.dev/docs/causes/timezone)                      |
| The server's locale                 | Numbers and dates formatted with the server's default locale                                                    | [Locale](https://hydration.jscrate.dev/docs/causes/locale)                          |
| Cached or prerendered HTML          | A statically generated page was rendered at build time; "today" or "3 minutes ago" is days old when it hydrates | [Time](https://hydration.jscrate.dev/docs/causes/time)                              |
| HTML rewritten by a CDN             | Minification or email obfuscation changes the HTML after it leaves your server                                  | [CDN](https://hydration.jscrate.dev/docs/causes/cdn)                                |
| Scripts that only run in production | Analytics, tag managers or A/B testing tools edit the DOM before React hydrates                                 | [Third-party scripts](https://hydration.jscrate.dev/docs/causes/third-party-script) |
| Different data                      | Feature flags, personalization or a second fetch on the client return other values                              | [Data](https://hydration.jscrate.dev/docs/causes/data)                              |
| Your users' browsers                | Extensions, translation tools and in-app browsers that you do not use                                           | [Extensions](https://hydration.jscrate.dev/docs/causes/extension)                   |

Some of these also happen in development but go unnoticed there. React 19 development builds warn about an attribute mismatch; production builds keep the server's attribute silently and never log it.

## What production builds show you

React's production build replaces messages with codes:

```text
Minified React error #418; visit https://react.dev/errors/418
Minified React error #423; visit https://react.dev/errors/423
Minified React error #425; visit https://react.dev/errors/425
```

- [#418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418): hydration failed. In React 19 it means "Hydration failed because the server rendered HTML didn't match the client", and React renders the tree again on the client.
- [#423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423) and [#425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425): React 18's messages for a root that switched to client rendering and for text that did not match.

None of them names the element. [Minified React error codes](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes) lists the others you may see alongside them.

## How to debug a Next.js hydration error that only shows up in production

1. **Build and run production locally.** Most of these errors reproduce with a production build on your machine:

   ```sh
   npm run build
   npm run start
   ```

2. **Use the server's timezone and locale.** Start the server the way your host does. On Linux and macOS:

   ```sh
   TZ=UTC LANG=en_US.UTF-8 npm run start
   ```

   If the error appears now, the cause is [timezone](https://hydration.jscrate.dev/docs/causes/timezone) or [locale](https://hydration.jscrate.dev/docs/causes/locale) formatting.

3. **Turn on browser source maps.** They map minified code back to your files:

   ```ts title="next.config.ts"
   import type { NextConfig } from "next";

   const nextConfig: NextConfig = {
     productionBrowserSourceMaps: true,
   };

   export default nextConfig;
   ```

4. **Compare what the origin sends with what the browser gets.** If they differ, something between them rewrites the HTML:

   ```sh
   curl -s https://origin.example.com/pricing > origin.html
   curl -s https://www.example.com/pricing > edge.html
   diff origin.html edge.html
   ```

5. **Check cached pages.** If only prerendered or cached pages fail, look for the clock in render: the HTML was made at build time.
6. **Test both builds with hydration-proof** (below). Findings that appear only in the production build are marked as such.

## Test production builds before you deploy

`hydration-proof test` tests the production build by default. `--mode both` starts a production build and the development server and tests every route in each, so you get React's full development messages and the production behavior in one run:

```bash
npx hydration-proof test --mode both
```

It compares every attribute with the props React renders on the client, so it also finds the attribute mismatches React 19 never reports in production. To test a deployed preview instead, point it at the URL:

```bash
npx hydration-proof test --url https://preview.example.com --sitemap
```

Production servers rarely share your timezone. Add scenarios for the environments your users and your servers have:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  scenarios: [
    { name: "default" },
    { name: "utc", timezoneId: "UTC", locale: "en-US" },
    { name: "berlin", timezoneId: "Europe/Berlin", locale: "de-DE" },
  ],
});
```

See [scenarios](https://hydration.jscrate.dev/docs/scenarios) and [the environment matrix](https://hydration.jscrate.dev/docs/environment-matrix) for more combinations, and [CI](https://hydration.jscrate.dev/docs/ci) to run this on every pull request.

## Related

- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
- [Cloudflare Auto Minify and other CDN rewrites](https://hydration.jscrate.dev/docs/causes/cdn)
- [Timezone hydration mismatches](https://hydration.jscrate.dev/docs/causes/timezone)
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)

---

# suppressHydrationWarning

> What suppressHydrationWarning does in React, why it only works one level deep, when it is safe, and why you cannot turn hydration errors off in Next.js.

Source: https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning
Last updated: 2026-09-18

`suppressHydrationWarning` is a React prop that stops React from reporting a hydration mismatch in one element's own attributes and text. React keeps the server's value and does not patch it. Use it for values that can never match, such as a timestamp or the theme class on `<html>`, and fix everything else.

## What suppressHydrationWarning does

React's docs describe it as a boolean that, when `true`, makes React "not warn you about mismatches in the attributes and the content of that element. It only works one level deep, and is intended to be used as an escape hatch. Don't overuse it." ([react.dev](https://react.dev/reference/react-dom/components/common))

In practice:

- **It covers the element's own attributes and its direct text.** Nothing inside its child elements.
- **React keeps the server value.** The [hydrateRoot docs](https://react.dev/reference/react-dom/client/hydrateRoot) say React "will not attempt to patch mismatched text content". The user sees the server's value until the next render changes it.
- **It does not cover structure.** If the server and client render different elements, the prop cannot hide it.

```tsx title="components/current-date.tsx"
"use client";

export function CurrentDate() {
  // The server's date and the browser's date can differ around midnight.
  return (
    <time suppressHydrationWarning>{new Date().toLocaleDateString()}</time>
  );
}
```

## When is it safe to use?

It is safe when the difference is expected, harmless, and fixed by the next render:

- **A timestamp or a live clock** whose first value does not matter, on the element that shows it.
- **`<html>` or `<body>` attributes a script sets before hydration,** such as the theme class written by next-themes or a similar inline script.

It is not safe as a way to hide a bug. On a price formatted in the wrong locale, it leaves the wrong price on the page with no error. Prefer the fixes in [the causes guides](https://hydration.jscrate.dev/docs/causes): pass the server's value as a prop, or render the value after hydration with [two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering).

## Why is suppressHydrationWarning not working?

When you add the prop and the error stays, it is one of these:

1. **It is on a parent, and the difference is in a child.** It only works one level deep.
2. **It is on a component, not an HTML element.** `<RelativeTime suppressHydrationWarning />` does nothing unless the component passes the prop to an element.
3. **The difference is structural.** An element exists on one side only, or is a different element. React re-renders the tree regardless.
4. **The error is about invalid nesting.** "In HTML, `<div>` cannot be a descendant of `<p>`" comes from the browser rewriting the HTML, which no prop can hide.
5. **It is on the wrong element.** next-themes changes `<html>`, so the prop belongs on `<html>`, not on `<body>`.

The first case is the most common:

```tsx title="components/clock.tsx"
"use client";

export function Clock() {
  return (
    // Does nothing: the text is inside the <span>, one level down.
    <div suppressHydrationWarning>
      <span>{new Date().toLocaleTimeString()}</span>
    </div>
  );
}
```

```tsx title="components/clock.tsx"
"use client";

export function Clock() {
  return (
    <div>
      {/* Works: the prop is on the element that holds the text. */}
      <span suppressHydrationWarning>{new Date().toLocaleTimeString()}</span>
    </div>
  );
}
```

## suppressHydrationWarning: Next.js root layout

The usual place for it in Next.js is `<html>` in the root layout, because theme libraries set a class or `style` there before React hydrates. shadcn/ui's [dark mode guide](https://ui.shadcn.com/docs/dark-mode/next) and next-themes both tell you to add it:

```tsx title="app/layout.tsx"
import type { ReactNode } from "react";
import { ThemeProvider } from "@/components/theme-provider";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}
```

Because it works one level deep, it covers only the attributes of `<html>` itself. A theme toggle that renders a different icon for the current theme still needs its own fix; see [theme hydration errors](https://hydration.jscrate.dev/docs/causes/theme).

## suppressHydrationWarning: React Router root

In React Router's framework mode, `<html>` is rendered by the `Layout` export of `app/root.tsx`. The `Layout` in [React Router's docs](https://reactrouter.com/api/framework-conventions/root.tsx) does not include the prop. Add it only when a script changes `<html>` before hydration, for example to set the theme:

```tsx title="app/root.tsx"
import type { ReactNode } from "react";
import { Links, Meta, Scripts, ScrollRestoration } from "react-router";

export function Layout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <meta charSet="utf-8" />
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <Scripts />
        <ScrollRestoration />
      </body>
    </html>
  );
}
```

## Can you ignore, disable or hide a hydration error in Next.js?

No. Neither React nor Next.js has a setting that turns hydration errors off for a whole app, and [Next.js's hydration error page](https://nextjs.org/docs/messages/react-hydration-error) offers three fixes: `useEffect`, disabling SSR for a component, and `suppressHydrationWarning` on the element.

There is a reason for that. The message is a symptom: by the time it appears, React 19 has already thrown the server HTML away and rendered the tree again on the client. Hiding the log does not stop the re-render, the lost state or the layout shift. And for attributes, React 19 production builds already stay silent while the wrong value stays on the page.

What you can do instead:

- **Fix the cause.** Each cause has a local fix; [the React hydration error guide](https://hydration.jscrate.dev/docs/guides/react-hydration-error) maps each message to one.
- **Render the part on the client only** with a [client-only component](https://hydration.jscrate.dev/docs/guides/client-only-component) or `next/dynamic` with `ssr: false`.
- **Use `suppressHydrationWarning`** on the one element whose value cannot match.
- **Ignore extension noise in tests,** not in the app: a clean browser profile has no extensions, and hydration-proof has [ignore rules](https://hydration.jscrate.dev/docs/ignoring) for attributes you cannot control.

In a custom React setup, the `onRecoverableError` option of `hydrateRoot` decides how recovered errors are logged. It changes the log, not what React does.

## hydration-proof vs suppressHydrationWarning

They answer different questions. `suppressHydrationWarning` hides a difference from React's warnings. hydration-proof finds differences, including the hidden ones, and tells you what each suppression hides.

|                             | `suppressHydrationWarning`                                         | hydration-proof                                                       |
| --------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- |
| What it does                | Stops React reporting one element's attribute and text differences | Loads every route and compares the server HTML with the client render |
| Scope                       | One element, one level deep                                        | Every element on every tested page                                    |
| The page                    | Keeps the server's value                                           | Unchanged: nothing is added to your app                               |
| Hidden differences          | Invisible from then on                                             | Listed as [HP6001](https://hydration.jscrate.dev/docs/issues/hp6001), for information              |
| Structural differences      | Not hidden                                                         | [HP6002](https://hydration.jscrate.dev/docs/issues/hp6002): the prop cannot hide this              |
| A prop with nothing to hide | Not reported                                                       | [HP6003](https://hydration.jscrate.dev/docs/issues/hp6003): remove it before it hides a future bug |

The ESLint rule [`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning) catches the misplaced ones while you type: the prop on an element with child elements, on an element with only static content, or on a component. It accepts `<html>` and `<body>` by default, and it checks Server Components too, because the root layout is one.

## Related

- [Intentional differences and how hydration-proof lists them](https://hydration.jscrate.dev/docs/causes/suppressed)
- [Next-themes and dark mode hydration errors](https://hydration.jscrate.dev/docs/causes/theme)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [Ignoring findings in hydration-proof](https://hydration.jscrate.dev/docs/ignoring)
- [React hydration errors: messages and causes](https://hydration.jscrate.dev/docs/guides/react-hydration-error)

---

# useEffect and two-pass rendering

> A useEffect hydration error means browser-only code ran during render. Effects never run on the server, so render the server's output first, then update.

Source: https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering
Last updated: 2026-09-18

A useEffect hydration error usually means code that belongs in an effect runs during render instead. Effects never run on the server, so the fix for most mismatches is two-pass rendering: render exactly what the server rendered first, then read the browser and update in `useEffect` once hydration is done.

## Does useEffect run on the server?

No. React's docs say: "Effects only run on the client. They don't run during server rendering." ([useEffect](https://react.dev/reference/react/useEffect)). The same is true of `useLayoutEffect`.

That makes the effect the one place where the server and the browser are allowed to differ. Everything else in a component, including the body of the function, `useState` initializers and `useMemo`, runs on the server and again in the browser during hydration, and must produce the same output both times.

## What a useEffect hydration error really is

The error is rarely caused by an effect. It is caused by code that should have been in one:

```tsx title="components/greeting.tsx"
"use client";

import { useState } from "react";

export function Greeting() {
  // Runs on the server (no window: "Guest") and during hydration ("Ada").
  const [name] = useState(() =>
    typeof window === "undefined" ? "Guest" : localStorage.getItem("name")
  );
  return <p>Hello, {name}</p>;
}
```

The `typeof window` check stops the server from crashing, but the two renders still disagree. Other forms of the same bug:

- `useState(typeof window !== "undefined")` as an "is client" flag;
- `window.innerWidth` or `matchMedia()` in render or in initial state;
- `new Date()` or `Math.random()` in render.

## Two-pass rendering with useEffect

Render the server's version first. After hydration, the effect runs, reads the browser, and sets state, which triggers a second render with the real value:

```tsx title="components/greeting.tsx"
"use client";

import { useEffect, useState } from "react";

export function Greeting() {
  const [name, setName] = useState("Guest"); // the same on both sides

  useEffect(() => {
    setName(localStorage.getItem("name") ?? "Guest");
  }, []);

  return <p>Hello, {name}</p>;
}
```

This is the pattern React's [hydrateRoot docs](https://react.dev/reference/react-dom/client/hydrateRoot) call "two-pass rendering". The first client render matches the server, so hydration succeeds, and "an additional pass will happen synchronously right after hydration."

The cost is real, and React's docs name it:

- **Components render twice,** which makes hydration slower.
- **Users on slow connections see the first version for a while.** The JavaScript can load seconds after the HTML, so a big change after hydration feels jarring.

Keep the first version close to the final one: a placeholder with the same size, not an empty space that jumps.

## An isClient flag without an extra effect

When many components need to know whether they are past hydration, read it from `useSyncExternalStore`. React calls `getServerSnapshot` on the server and during hydration, and `getSnapshot` afterwards:

```tsx title="hooks/use-is-client.ts"
import { useSyncExternalStore } from "react";

const subscribe = () => () => {};

export function useIsClient() {
  return useSyncExternalStore(
    subscribe,
    () => true, // in the browser, after hydration
    () => false // on the server and during hydration
  );
}
```

`false` on the server and during hydration, `true` after it. [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component) build a reusable `ClientOnly` wrapper on the same idea.

## The useLayoutEffect warning

React 16 to 18 printed this warning when a component with `useLayoutEffect` rendered on the server:

```text
Warning: useLayoutEffect does nothing on the server, because its effect cannot be encoded into the server renderer's output format. This will lead to a mismatch between the initial, non-hydrated UI and the intended UI. To avoid this, useLayoutEffect should only be used in components that render exclusively on the client. See https://reactjs.org/link/uselayouteffect-ssr for common fixes.
```

React 19 removed it, but the reason for it stays: a layout effect measures the page before paint, and the server has no layout to measure. The [useLayoutEffect docs](https://react.dev/reference/react/useLayoutEffect) suggest these fixes:

1. **Use `useEffect` instead** when showing the first render without the measurement is acceptable.
2. **Render the component only on the client,** with a fallback on the server ([client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)).
3. **Render it only after hydration,** with an `isMounted` state set in an effect.
4. **Use `useSyncExternalStore`** if the value comes from an external store.

## When not to use two-pass rendering

Two-pass rendering fixes a useEffect hydration error by delaying the value. Often you can avoid the delay:

| Instead of reading in an effect | Do this                                                                                        |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| Screen size for layout          | CSS media queries: render both layouts, let CSS pick ([media query](https://hydration.jscrate.dev/docs/causes/media-query)) |
| The current time                | Pass the time the server used as a prop ([time](https://hydration.jscrate.dev/docs/causes/time))                            |
| A saved preference              | Store it in a cookie and read it on the server ([storage](https://hydration.jscrate.dev/docs/causes/storage))               |
| The theme                       | Set the class with an inline script before hydration ([theme](https://hydration.jscrate.dev/docs/causes/theme))             |

## Catch it before it ships

The ESLint plugin treats effects as "not render" and everything else as render code, so it reports browser reads in the places that break hydration:

- [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state): browser values in `useState`, `useReducer` and `useRef` initial values.
- [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch): `typeof window` checks that change the output.
- [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render) and [`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render): storage and media queries outside effects.

`hydration-proof test` finds the ones that reach a page, as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) for text and [HP1009](https://hydration.jscrate.dev/docs/issues/hp1009) for an element only the client renders:

```bash
npx hydration-proof test
```

## Related

- [What is hydration in React?](https://hydration.jscrate.dev/docs/guides/what-is-hydration)
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [localStorage hydration errors](https://hydration.jscrate.dev/docs/causes/storage)
- [Browser-only APIs during render](https://hydration.jscrate.dev/docs/causes/browser-api)
- [Missing getServerSnapshot](https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot)

---

# Client-only components

> Build a ClientOnly Next.js component that renders a fallback on the server and its children after hydration, plus the Remix and TanStack versions.

Source: https://hydration.jscrate.dev/docs/guides/client-only-component
Last updated: 2026-09-18

A ClientOnly Next.js component renders a fallback on the server and during hydration, then its children once React runs in the browser. Both renders that React compares show the fallback, so there is no mismatch. Use it for parts that cannot render on the server: a map, a chart, or anything that depends on the window.

## Build a ClientOnly Next.js component

`useSyncExternalStore` returns the server snapshot on the server and during hydration, and the client snapshot afterwards. That is exactly the switch a client-only wrapper needs:

```tsx title="components/client-only.tsx"
"use client";

import { useSyncExternalStore, type ReactNode } from "react";

const subscribe = () => () => {};

export function ClientOnly({
  children,
  fallback = null,
}: {
  children: ReactNode;
  fallback?: ReactNode;
}) {
  const isClient = useSyncExternalStore(
    subscribe,
    () => true, // in the browser, after hydration
    () => false // on the server and during hydration
  );
  return isClient ? children : fallback;
}
```

```tsx title="app/stores/page.tsx"
import { ClientOnly } from "@/components/client-only";
import { StoreMap } from "./store-map";

export default function Page() {
  return (
    <ClientOnly fallback={<div className="h-96 rounded bg-muted" />}>
      <StoreMap />
    </ClientOnly>
  );
}
```

The same wrapper with `useEffect` works too: start with `useState(false)` and set it to `true` in an effect. React's docs describe that version as [two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering).

Two things to keep in mind:

- **The child's module still loads on the server.** `ClientOnly` stops the child from rendering there, not from being imported. A library that touches `window` when it is imported needs [`next/dynamic` with `ssr: false`](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false) instead.
- **Give the fallback the final size.** Otherwise the content jumps when the real component replaces it.

## How to render components in Next.js only on the client

`"use client"` is not enough: Client Components are still prerendered to HTML on the server, then hydrated. To keep a component out of the server render, pick one of these:

| Option                              | Server renders         | Code is loaded             | Use it for                                                |
| ----------------------------------- | ---------------------- | -------------------------- | --------------------------------------------------------- |
| `ClientOnly` wrapper                | The fallback           | With the page              | Components that read the browser while rendering          |
| `next/dynamic` with `ssr: false`    | The `loading` fallback | Separately, in the browser | Libraries that need `window` when imported, large widgets |
| Two-pass rendering in the component | Its server version     | With the page              | One value that differs, such as a stored preference       |

## ClientOnly Remix and React Router: remix-utils

[remix-utils](https://github.com/sergiodxa/remix-utils) ships a `ClientOnly` component for React Router and Remix apps. Its children are a function, so the component inside is only created in the browser:

```tsx title="app/routes/dashboard.tsx"
import { ClientOnly } from "remix-utils/client-only";
import { Chart } from "~/components/chart";

export default function Dashboard() {
  return (
    <ClientOnly fallback={<div className="h-64" />}>
      {() => <Chart />}
    </ClientOnly>
  );
}
```

Its README describes the flow: on the server and on the first client render it always renders the fallback, then it updates to the real component, and later renders skip the fallback. It is built on the package's `useHydrated` hook, which you can use directly for smaller differences. More on the framework in [Remix hydration errors](https://hydration.jscrate.dev/docs/frameworks/remix).

## ClientOnly TanStack Router and Start

TanStack Router exports its own [`ClientOnly`](https://tanstack.com/router/latest/docs/framework/react/api/router/clientOnlyComponent), with a `fallback` prop for the render before JavaScript loads:

```tsx title="src/routes/dashboard.tsx"
import { ClientOnly, createFileRoute } from "@tanstack/react-router";
import { Charts, FallbackCharts } from "~/components/charts";

export const Route = createFileRoute("/dashboard")({
  component: Dashboard,
});

function Dashboard() {
  return (
    <ClientOnly fallback={<FallbackCharts />}>
      <Charts />
    </ClientOnly>
  );
}
```

See [TanStack Start](https://hydration.jscrate.dev/docs/frameworks/tanstack-start) for testing those routes.

## Can you disable hydration or only partially hydrate a Next.js app?

There is no switch that disables hydration for a Client Component while keeping its server HTML. What you can do is decide which parts need hydrating at all:

- **Keep static parts as Server Components.** Their code never runs in the browser, and nothing about them needs hydrating except the plain HTML elements. This is how the App Router lets you only partially hydrate a Next.js app.
- **Mark only the interactive leaves `"use client"`.** A button or a form hydrates; the article around it does not ship its code.
- **Render browser-only parts on the client** with a `ClientOnly` wrapper or `next/dynamic` with `ssr: false`.
- **Split the page with Suspense boundaries.** Each boundary hydrates on its own, and a mismatch inside one re-renders only that boundary.

## What client-only rendering costs

- **No HTML for that part.** Crawlers, link previews and users without JavaScript see the fallback.
- **It appears later.** The content waits for hydration, or for its own chunk to load.
- **Layout shift,** unless the fallback has the size of the final content.

hydration-proof checks the result: a correct client-only part produces no finding, while a component that still renders differently on the server is reported with the element and both values.

```bash
npx hydration-proof test
```

## Related

- [next/dynamic with ssr: false](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [Browser-only APIs during render](https://hydration.jscrate.dev/docs/causes/browser-api)
- [Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [window is not defined in Next.js](https://hydration.jscrate.dev/docs/errors/window-is-not-defined)

---

# next/dynamic with ssr: false

> How next/dynamic ssr: false skips prerendering a component, why the App Router only allows it in Client Components, and when a ClientOnly wrapper is better.

Source: https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false
Last updated: 2026-09-18

With `next/dynamic`, `ssr: false` skips prerendering one component: the server sends its `loading` fallback, and the browser loads the component's code and renders it after hydration. Both renders React compares show the fallback, so the component cannot cause a mismatch. In the App Router, the call must be inside a Client Component.

## How next/dynamic ssr: false works

`next/dynamic` is a composite of `React.lazy()` and Suspense, and it "behaves the same way in the `app` and `pages` directories" ([Next.js lazy loading docs](https://nextjs.org/docs/app/guides/lazy-loading)). By default, a dynamically imported Client Component is still prerendered. With `ssr: false`, it is not:

```tsx title="app/stores/store-finder.tsx"
"use client";

import dynamic from "next/dynamic";

// The map library reads window when it is imported.
const StoreMap = dynamic(() => import("./store-map"), {
  ssr: false,
  loading: () => <div className="h-96 rounded bg-muted" />,
});

export function StoreFinder() {
  return <StoreMap />;
}
```

What happens on a page load:

1. **The server** renders `StoreFinder` and puts the `loading` fallback where the map goes. The map's module does not run on the server.
2. **Hydration** renders the fallback in the same place, so it matches.
3. **The browser** loads the map's chunk and replaces the fallback with the map.

Because the module does not run on the server, this is the fix for libraries that touch `window` or `document` at import time, which a plain [client-only component](https://hydration.jscrate.dev/docs/guides/client-only-component) cannot help with.

## Next.js dynamic import (ssr: false) in the App Router

Since Next.js 15, `ssr: false` is not allowed in Server Components. Calling it in `app/page.tsx` without `"use client"` fails with:

```text
`ssr: false` is not allowed with `next/dynamic` in Server Components. Please move it into a Client Component.
```

Move the call into a Client Component and render that from the page:

```tsx title="app/stores/page.tsx"
// A Server Component: no "use client", no ssr: false here.
import { StoreFinder } from "./store-finder";

export default function Page() {
  return (
    <main>
      <h1>Find a store</h1>
      <StoreFinder />
    </main>
  );
}
```

`store-finder.tsx` above is the Client Component that holds the `dynamic()` call. The Next.js docs add that `ssr: false` only works for Client Components and that the client code-splitting works properly only there.

In the Pages Router there are no Server Components, so `dynamic(() => import("…"), { ssr: false })` works in any page or component.

## When to use ssr: false

Use it when a component cannot render on the server at all:

- a library that reads `window`, `document` or `navigator` when it is imported (maps, some chart and editor libraries);
- a widget whose output depends entirely on the browser, where a server version would be wrong anyway;
- a large component you want out of the first bundle, which also should not block the first paint.

Do not use it to silence a mismatch in content that could render on the server. A date, a price or a user's name can almost always be rendered the same way on both sides, and search engines and link previews then get the content. The [causes guides](https://hydration.jscrate.dev/docs/causes) show how.

## ssr: false vs a ClientOnly component

|                      | `next/dynamic` with `ssr: false`                        | `ClientOnly` wrapper                              |
| -------------------- | ------------------------------------------------------- | ------------------------------------------------- |
| Server HTML          | The `loading` fallback                                  | The `fallback` prop                               |
| Module on the server | Not run                                                 | Imported and run, not rendered                    |
| Code splitting       | A separate chunk                                        | Bundled with the page                             |
| Where it can be used | Client Components (App Router), any file (Pages Router) | Anywhere, including Server Components as a parent |

## Check the result

A correct `ssr: false` component produces no hydration finding. What goes wrong is usually around it: a fallback of a different size shifts the layout, or a sibling still reads the browser during render. hydration-proof tests every route, so a component that moved from the server render to the client render is checked on every page that uses it:

```bash
npx hydration-proof test
```

## Related

- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [window is not defined in Next.js](https://hydration.jscrate.dev/docs/errors/window-is-not-defined)
- [Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [Browser-only APIs during render](https://hydration.jscrate.dev/docs/causes/browser-api)

---

# Fix the Zustand persist hydration error

> A Zustand hydration error happens when persist loads saved state before hydration. Fix it with skipHydration and rehydrate(), or wait for hydration to finish.

Source: https://hydration.jscrate.dev/docs/guides/zustand-hydration-error
Last updated: 2026-09-18

A Zustand hydration error happens when a store that uses the `persist` middleware loads saved state from `localStorage` before React hydrates. The server has no storage and renders the default state; the browser's first render already shows the saved state. Delay loading the saved state until after hydration.

## Why the Zustand hydration error happens

`persist` hydrates the store from storage. Zustand's docs explain that with a synchronous storage such as `localStorage`, "the Zustand store will already have been hydrated at its creation" ([persisting store data](https://zustand.docs.pmnd.rs/reference/integrations/persisting-store-data)). In a server-rendered app, that means:

1. **On the server,** there is no `localStorage`, so the store keeps its initial state: `bears: 0`.
2. **In the browser,** the store is created, reads storage and holds `bears: 7` before React renders anything.
3. **During hydration,** the component renders `7` where the server HTML says `0`.

The Zustand docs list the messages you get in Next.js:

```text
Text content does not match server-rendered HTML
Hydration failed because the initial UI does not match what was rendered on the server
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering
```

React 19 reports the same bug as "Hydration failed because the server rendered text didn't match the client". A store value used in a `className` or `style` is worse: React 19 production builds keep the server's attribute without any error.

## Fix the Zustand Next.js hydration error

All three fixes make the first client render use the same state as the server, then switch to the saved state.

### Skip hydration and rehydrate after mount

Zustand skip hydration (`skipHydration: true`) stops the store from reading storage when it is created. You call `rehydrate()` yourself, in an effect, after React has hydrated the page:

```ts title="stores/bear-store.ts"
import { create } from "zustand";
import { persist } from "zustand/middleware";

type BearState = {
  bears: number;
  addBear: () => void;
};

export const useBearStore = create<BearState>()(
  persist(
    (set) => ({
      bears: 0,
      addBear: () => set((state) => ({ bears: state.bears + 1 })),
    }),
    {
      name: "bear-storage",
      skipHydration: true,
    }
  )
);
```

```tsx title="components/store-hydration.tsx"
"use client";

import { useEffect } from "react";
import { useBearStore } from "@/stores/bear-store";

export function StoreHydration() {
  useEffect(() => {
    void useBearStore.persist.rehydrate();
  }, []);
  return null;
}
```

Render `<StoreHydration />` once, near the root, for example in `app/layout.tsx`. Every component reads the default state during hydration and re-renders with the saved state right after.

### Wait for hydration before showing stored values

If showing the default for a moment is wrong (a logged-out state for a logged-in user), render a placeholder until the store has hydrated. The Zustand docs build a hook from `onFinishHydration` and `hasHydrated`:

```tsx title="hooks/use-store-hydrated.ts"
"use client";

import { useEffect, useState } from "react";
import { useBearStore } from "@/stores/bear-store";

export function useStoreHydrated() {
  const [hydrated, setHydrated] = useState(false);

  useEffect(() => {
    const unsubHydrate = useBearStore.persist.onHydrate(() =>
      setHydrated(false)
    );
    const unsubFinish = useBearStore.persist.onFinishHydration(() =>
      setHydrated(true)
    );
    setHydrated(useBearStore.persist.hasHydrated());
    return () => {
      unsubHydrate();
      unsubFinish();
    };
  }, []);

  return hydrated;
}
```

```tsx title="components/bear-count.tsx"
"use client";

import { useBearStore } from "@/stores/bear-store";
import { useStoreHydrated } from "@/hooks/use-store-hydrated";

export function BearCount() {
  const bears = useBearStore((state) => state.bears);
  const hydrated = useStoreHydrated();
  return <span>{hydrated ? bears : "–"}</span>;
}
```

`hydrated` starts as `false` on the server and during hydration, so both render the placeholder.

### Read the store through a delayed hook

The Zustand docs' Next.js section suggests a small `useStore` wrapper that returns `undefined` on the first render and the store's value after an effect. It needs no change to the store, but every component has to read the store through it and handle `undefined`.

## Should the server know the value?

Every fix above shows the default first. When the value matters for the first paint (a theme, a cart count, a language), keep it where the server can read it, such as a cookie, and pass it to the page as a prop. Then the server renders the real value and nothing changes after hydration. The [storage cause guide](https://hydration.jscrate.dev/docs/causes/storage) covers the cookie approach.

## Find the pages it breaks

The ESLint plugin reads one file at a time, so it cannot see what `persist` loads from storage. `hydration-proof test` loads the page in a real browser instead. Give a [scenario](https://hydration.jscrate.dev/docs/scenarios) the saved state your users have, so the store has something to load:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  scenarios: [
    { name: "default" },
    {
      name: "returning-user",
      localStorage: {
        "bear-storage": JSON.stringify({ state: { bears: 7 }, version: 0 }),
      },
    },
  ],
});
```

A mismatch is reported as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) for text or [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) for a class name, with the likely cause "localStorage / sessionStorage read during render". With `--probe`, the page is loaded again without the scenario's storage; if the value changes, the cause is proven:

```bash
npx hydration-proof test --probe
```

## Related

- [localStorage hydration errors](https://hydration.jscrate.dev/docs/causes/storage)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [Proving a cause with probes](https://hydration.jscrate.dev/docs/probes)

---

# Fix shadcn/ui hydration errors

> A shadcn hydration error usually comes from dark mode, the Sidebar skeleton, dates in the Calendar, or a Button nested in a trigger. The fix for each one.

Source: https://hydration.jscrate.dev/docs/guides/shadcn-hydration-error
Last updated: 2026-09-18

A shadcn hydration error is rarely a bug in shadcn/ui itself. The components are copied into your project, and the mismatches come from how they meet the server: a theme class set before hydration, a random skeleton width, dates formatted in another timezone, or a `<Button>` nested inside a trigger that is already a `<button>`.

## Which shadcn hydration error do you have?

| What you see                                                               | Section                                        |
| -------------------------------------------------------------------------- | ---------------------------------------------- |
| A `class` or `style` difference on `<html>`                                | [Dark mode](#shadcn-dark-mode-hydration-error) |
| A `--skeleton-width` style difference, or a sidebar that opens differently | [Sidebar](#shadcn-sidebar-hydration-error)     |
| A date or day that differs by one                                          | [Calendar](#shadcn-calendar-hydration-error)   |
| "In HTML, `<button>` cannot be a descendant of `<button>`"                 | [Button](#shadcn-button-hydration-error)       |

On Next.js 14, a shadcn app shows these bugs as "Hydration failed because the initial UI does not match what was rendered on the server." React 19 apps see "Hydration failed because the server rendered HTML didn't match the client" instead. The causes and fixes are the same.

## shadcn dark mode hydration error

shadcn/ui's dark mode uses next-themes, which reads the saved theme in an inline script and sets the class on `<html>` before React hydrates. The server rendered `<html>` without it, so the attributes differ. shadcn's [dark mode guide](https://ui.shadcn.com/docs/dark-mode/next) says to "add the `suppressHydrationWarning` prop to the `html` tag":

```tsx title="app/layout.tsx"
import type { ReactNode } from "react";
import { ThemeProvider } from "@/components/theme-provider";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}
```

The prop works [one level deep](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning): it covers `<html>` and nothing inside. A component that renders differently for the current theme still breaks. next-themes' README explains why: the `theme` from `useTheme` is `undefined` on the server, so any UI that depends on it must wait until the component has mounted, or render both versions and let CSS (`dark:` classes) hide one. [Theme hydration errors](https://hydration.jscrate.dev/docs/causes/theme) has both fixes.

## shadcn sidebar hydration error

Two things in the Sidebar component render differently on the server and in the browser.

**`SidebarMenuSkeleton` picks a random width.** The component in shadcn's registry computes its width with `Math.random()` inside `useMemo`, and writes it to a `--skeleton-width` style. The server and the browser pick different numbers, so the `style` attribute differs. React 19 production builds keep the server's style without reporting it. Because the file is in your project, change it to take the width as a prop:

```tsx title="components/ui/sidebar.tsx"
function SidebarMenuSkeleton({
  className,
  showIcon = false,
  width = "70%", // was: a random width between 50% and 90%
  ...props
}: React.ComponentProps<"div"> & {
  showIcon?: boolean;
  width?: string;
}) {
  // ...render as before, with style={{ "--skeleton-width": width }}
}
```

**The open state.** `SidebarProvider` saves the open state in a `sidebar_state` cookie. To restore it on reload without a mismatch, read that cookie on the server and pass it as `defaultOpen`. Reading `document.cookie` or `localStorage` during render gives the server and the browser different answers:

```tsx title="app/(dashboard)/layout.tsx"
import type { ReactNode } from "react";
import { cookies } from "next/headers";
import { SidebarProvider } from "@/components/ui/sidebar";
import { AppSidebar } from "@/components/app-sidebar";

export default async function DashboardLayout({
  children,
}: {
  children: ReactNode;
}) {
  const cookieStore = await cookies();
  const defaultOpen = cookieStore.get("sidebar_state")?.value !== "false";

  return (
    <SidebarProvider defaultOpen={defaultOpen}>
      <AppSidebar />
      <main>{children}</main>
    </SidebarProvider>
  );
}
```

The `useIsMobile` hook that ships with the Sidebar reads `matchMedia` in an effect and returns `false` until then, so it does not cause a mismatch. A version that calls `matchMedia` during render does; see [media query hydration errors](https://hydration.jscrate.dev/docs/causes/media-query).

## shadcn calendar hydration error

The Calendar is built on React DayPicker, and dates depend on the timezone. shadcn's [Calendar docs](https://ui.shadcn.com/docs/components/calendar) pass a `timeZone` prop and detect it in an effect, because "detecting the timezone during render would cause hydration mismatches, as the server and client may be in different timezones":

```tsx title="components/calendar-with-timezone.tsx"
"use client";

import { useEffect, useState } from "react";
import { Calendar } from "@/components/ui/calendar";

export function CalendarWithTimezone() {
  const [date, setDate] = useState<Date | undefined>(undefined);
  const [timeZone, setTimeZone] = useState<string | undefined>(undefined);

  useEffect(() => {
    setTimeZone(Intl.DateTimeFormat().resolvedOptions().timeZone);
  }, []);

  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
      timeZone={timeZone}
    />
  );
}
```

The same applies to dates you format around the Calendar, in a date picker's button label for example. Format them with an explicit `timeZone` and locale, or after mount; see [timezone](https://hydration.jscrate.dev/docs/causes/timezone) and [date](https://hydration.jscrate.dev/docs/causes/time) hydration errors.

## shadcn button hydration error

shadcn's triggers, such as `TooltipTrigger`, `DialogTrigger`, `PopoverTrigger` and `DropdownMenuTrigger`, render a `<button>` by default. Putting a `<Button>` inside one without `asChild` nests a button in a button:

```text
In HTML, <button> cannot be a descendant of <button>. This will cause a hydration error.
```

The browser's HTML parser closes the first button when it meets the second, so the DOM no longer matches what React rendered. Pass `asChild`, so the trigger passes its behavior to your `<Button>` instead of rendering its own:

```tsx title="components/save-button.tsx"
"use client";

import { Button } from "@/components/ui/button";
import {
  Tooltip,
  TooltipContent,
  TooltipTrigger,
} from "@/components/ui/tooltip";

export function SaveButton() {
  return (
    <Tooltip>
      {/* Without asChild: <button><button>Save</button></button> */}
      <TooltipTrigger asChild>
        <Button>Save</Button>
      </TooltipTrigger>
      <TooltipContent>Save the draft</TooltipContent>
    </Tooltip>
  );
}
```

For a link that looks like a button, shadcn's Radix-based Button documents `<Button asChild>` around the link; the Base UI version recommends `buttonVariants()` on a plain `<a>`. Wrapping a `<Button>` in a `<Link>` instead puts a button inside a link, which is invalid HTML. See [invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html).

## Find every one in your app

The ESLint rule [`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting) reports nesting it can see in one file, such as a `<button>` written inside an `<a>`. A `<Button>` inside `<TooltipTrigger>` crosses two components, so no linter sees it. [`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render) reports the `Math.random()` in the skeleton, because `useMemo` callbacks run during render.

`hydration-proof test` loads each page in a browser and finds all four, including the nesting across components (reported as [HP3002](https://hydration.jscrate.dev/docs/issues/hp3002)). Test dark mode and a phone viewport too, because the theme and the sidebar only differ there:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  scenarios: [
    { name: "default" },
    { name: "dark-mobile", colorScheme: "dark", viewport: "mobile" },
  ],
});
```

```bash
npx hydration-proof test
```

## Related

- [Next-themes and dark mode hydration errors](https://hydration.jscrate.dev/docs/causes/theme)
- [validateDOMNesting errors](https://hydration.jscrate.dev/docs/errors/validatedomnesting)
- [suppressHydrationWarning, and why it works one level deep](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Random values in render](https://hydration.jscrate.dev/docs/causes/random)

---

# Do hydration errors affect SEO?

> Do hydration errors affect SEO? Not as a ranking factor, but their effects can: content that differs, metadata React never fixes, slow pages, layout shift.

Source: https://hydration.jscrate.dev/docs/guides/hydration-errors-seo
Last updated: 2026-09-18

Do hydration errors affect SEO? Not directly: Google does not describe hydration errors as a ranking factor, and it indexes the page as rendered in its browser. What they do to the page can matter, though: content that differs between server and client, metadata React never corrects, extra work that slows the page, and layout shift.

## How Google sees a server-rendered React page

Google's [JavaScript SEO basics](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics) describe three phases: crawling, rendering and indexing. Googlebot renders pages with "an evergreen version of Chromium", and indexing uses the rendered HTML. The same page also says that "server-side or pre-rendering is still a great idea because it makes your website faster for users and crawlers."

So Google sees roughly what a user's browser sees after hydration. A page that hydrates badly is not hidden from Google, but it is slower, and it may not say what the server HTML said.

## Do hydration errors affect SEO directly?

Not according to anything Google documents. A hydration error is a message in the browser console. What Google describes evaluating is the result: the content it renders and the experience of the page. That is where hydration problems can show up.

## The effects that can matter

| What happens                             | Why                                                                                            | Can it matter for search?                                                                      |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| React renders a tree again on the client | In React 19, a text or structure mismatch makes React throw away the server HTML for that tree | More main-thread work during load, which can hurt responsiveness and paint timing              |
| Content changes after load               | The client renders different text than the server sent                                         | Layout shift, and a crawler that does not run JavaScript sees other content than one that does |
| An attribute stays wrong                 | React 19 keeps the server's attribute and does not patch it                                    | A wrong `href`, `lang` or `alt` stays in the page                                              |
| `<head>` differs                         | A title or meta tag rendered differently on the client                                         | Search engines and link previews can read different metadata                                   |
| Interactivity breaks                     | Lost state and input when a branch is replaced                                                 | Affects users; not a search signal on its own                                                  |

Google's [Core Web Vitals page](https://developers.google.com/search/docs/appearance/core-web-vitals) says good Core Web Vitals align with what its core ranking systems seek to reward, alongside other page experience aspects. The targets are an LCP within 2.5 seconds, an INP under 200 milliseconds and a CLS under 0.1. A hydration mismatch does not guarantee a bad score, and fixing one does not guarantee a good one; it removes work and movement from the page.

## Metadata is where a mismatch hurts most

The attributes Google relies on live in `<head>`: the canonical URL, `hreflang` alternates, robots directives, the title and the description. Google's JavaScript guide warns against changing the canonical URL with JavaScript to something other than the canonical in the original HTML, and notes that a `noindex` in the original HTML may stop Google from rendering the page at all.

If a `<head>` value differs between server and client, for example a title built from a browser-only value or an `hreflang` computed from the visitor's locale, the server HTML and the rendered page disagree about what the page is. hydration-proof reports a changed title, meta tag, stylesheet or script in `<head>` as [HP1014](https://hydration.jscrate.dev/docs/issues/hp1014), and [how it works](https://hydration.jscrate.dev/docs/how-it-works) notes that React 19 adds a new `<title>` or `<meta>` instead of fixing the server one.

## Check the pages that get indexed

Test the pages in your sitemap, in a production build, the way crawlers get them:

```bash
npx hydration-proof test --sitemap
```

`--sitemap` adds every route listed in your sitemap (it also reads `robots.txt` to find it). Fix [head mismatches](https://hydration.jscrate.dev/docs/issues/hp1014) first, then text mismatches that make React re-render ([HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) and [HP1011](https://hydration.jscrate.dev/docs/issues/hp1011)), then attribute ones. [Routes](https://hydration.jscrate.dev/docs/routes) covers the other ways to choose pages.

## Related

- [What is hydration in React?](https://hydration.jscrate.dev/docs/guides/what-is-hydration)
- [React hydration errors: messages and causes](https://hydration.jscrate.dev/docs/guides/react-hydration-error)
- [Hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [How hydration-proof works](https://hydration.jscrate.dev/docs/how-it-works)
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)

---

# Next.js hydration errors

> A Next.js hydration error means the server HTML and the browser's first render differ. The messages, common causes, fixes, and how to test every route.

Source: https://hydration.jscrate.dev/docs/frameworks/nextjs
Last updated: 2026-09-18

A Next.js hydration error means the HTML the server sent differs from what
React renders in the browser on its first pass. The usual causes are the clock,
the locale or timezone, browser-only APIs, invalid HTML nesting and browser
extensions. Render the same output on both sides first, then change it in an
effect after hydration.

## Common hydration errors in Next.js

The Next.js hydration failed message depends on the React version your app
runs. Next.js explains all of them on one page of its docs,
[react-hydration-error](https://nextjs.org/docs/messages/react-hydration-error).

### The Next.js 15 hydration error (React 19)

The App Router in Next.js 15 and 16 uses React 19, which reports a mismatch
with one of these messages and a diff of the two renders:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
Hydration failed because the server rendered text didn't match the client.
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

See [server rendered HTML didn't match the client](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)
for what each part of the message means.

### Next.js 13 and 14 (React 18)

With React 18, the same bug shows up as:

```text
Hydration failed because the initial UI does not match what was rendered on the server.
Text content does not match server-rendered HTML.
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

### Warnings and production builds

Some of these are logged rather than thrown: React 19's attribute message, and
React 18's `Warning: Text content did not match` lines. A Next.js hydration
warning still means the page differs from the server HTML. React does not patch
attributes during hydration, so the server's value stays on the page.

In development, the Next.js dev overlay shows the error for the page you have
open ([how it compares](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay)). Production builds
print a minified code such as
[Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418) instead of
the message, and some mismatches only happen there. See
[hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production).

## What causes a Next.js hydration error?

Every Next.js React hydration error comes from the same place: the server and
the browser rendered the same component with different inputs. A Next.js
hydration mismatch usually has one of these causes:

| Cause               | Typical code                                                         | Fix                                                              |
| ------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| The clock           | `new Date()`, `Date.now()`, "3 minutes ago"                          | [Time-dependent values](https://hydration.jscrate.dev/docs/causes/time)                       |
| Timezone and locale | `toLocaleString()`, `Intl` formatters without a `timeZone` or locale | [Timezone](https://hydration.jscrate.dev/docs/causes/timezone), [locale](https://hydration.jscrate.dev/docs/causes/locale) |
| Browser-only APIs   | `typeof window !== "undefined"`, `window`, `navigator` in render     | [Browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api)                         |
| Storage             | `localStorage` read during render or in initial state                | [localStorage](https://hydration.jscrate.dev/docs/causes/storage)                             |
| Theme               | dark mode read on the client, `next-themes`                          | [Theme](https://hydration.jscrate.dev/docs/causes/theme)                                      |
| Invalid HTML        | `<div>` inside `<p>`, `<a>` inside `<a>`                             | [Invalid nesting](https://hydration.jscrate.dev/docs/causes/invalid-html)                     |
| Browser extensions  | attributes added by password managers and translators                | [Extensions](https://hydration.jscrate.dev/docs/causes/extension)                             |
| CSS-in-JS           | styled-components without its style registry                         | [CSS-in-JS](https://hydration.jscrate.dev/docs/causes/css-in-js)                              |
| Scripts             | a script that changes the page before React hydrates it              | [Third-party scripts](https://hydration.jscrate.dev/docs/causes/third-party-script)           |
| CDN                 | Cloudflare Auto Minify rewriting the HTML                            | [CDN rewrites](https://hydration.jscrate.dev/docs/causes/cdn)                                 |

The Next.js docs also mention iOS, which turns phone numbers, email addresses
and dates in text into links. A
`<meta name="format-detection" content="telephone=no, date=no, email=no, address=no" />`
tag turns that off.

### Why does a Next.js "use client" hydration error happen?

`"use client"` does not prevent a hydration error. It marks where the client
part of your app starts, but Client Components are still rendered to HTML on the
server: Next.js uses them to
[prerender the page](https://nextjs.org/docs/app/getting-started/server-and-client-components),
then hydrates them in the browser. `Date.now()` in a Client Component runs
twice, at two different moments.

Server Components never hydrate. They render once, on the server, and the
browser receives their result without running them again. Time, random values
or `window` checks in a Server Component cannot cause a mismatch on their own.

In the Pages Router there are no Server Components: every component on a page
renders on the server and hydrates in the browser.

## How to fix a hydration error in Next.js

How to solve a React hydration error in Next.js depends on the cause, and
hydration-proof names it for each finding. These fixes cover most of them, in
the order to try them.

### Render the same thing first, then update in an effect

Render output that does not depend on the browser, then change it in
`useEffect`, which only runs in the browser after hydration:

```tsx title="app/components/greeting.tsx"
"use client";

import { useEffect, useState } from "react";

export function Greeting() {
  const [name, setName] = useState<string | null>(null);

  useEffect(() => {
    setName(localStorage.getItem("name"));
  }, []);

  return <p>Hello{name ? `, ${name}` : ""}</p>;
}
```

[useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
explains the pattern and when the flash of the first value matters.

### Skip server rendering with next/dynamic

A component that cannot render on the server (a map, a chart that measures the
window) can skip it. `ssr: false` only works in Client Components; a Server
Component that uses it fails with an error:

```tsx title="app/store/map-client.tsx"
"use client";

import dynamic from "next/dynamic";

const StoreMap = dynamic(() => import("./store-map"), {
  ssr: false,
  loading: () => <p>Loading map…</p>,
});

export function MapClient() {
  return <StoreMap />;
}
```

See [next/dynamic with ssr: false](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false) for the
trade-offs.

### Pass server values down as props

When the value comes from the server (the time the page was rendered, the
user's locale from a cookie), read it once in a Server Component and pass it to
the Client Component. Both renders then use the same value.

### Use suppressHydrationWarning sparingly

`suppressHydrationWarning` on an element tells React to keep the server's text
without reporting it. It only works one level deep, and React does not patch
the text, so the page shows the server value. It suits a timestamp whose first
value does not matter, and the `<html>` element that `next-themes` changes
before hydration. Everywhere else it hides a real bug. See
[when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Test every route with hydration-proof

hydration-proof loads every route of your app in a real browser, compares the
server HTML with the hydrated DOM and reports each difference with its element,
both values, the likely cause and the fix. The `next` [adapter](https://hydration.jscrate.dev/docs/adapters)
is picked when `package.json` has a `next` dependency or the project has a
`next.config.*` file:

- **Build and start:** `next build` (or your `build` script when it runs
  `next build`), then `next start --port {port}`. The app is built only when
  `.next/BUILD_ID` is missing.
- **Development mode:** `next dev`, opened on `localhost` because Next.js
  blocks development resources for other hosts.
- **Routes:** discovered from `app/` and `pages/`, with route groups, parallel
  routes and private folders handled and API routes skipped. Dynamic routes get
  up to three example values from the pages the build pre-rendered
  (`generateStaticParams` and `getStaticPaths`).
- **Not-found page:** a URL that does not exist is loaded too, to check that
  the not-found page hydrates.
- **Navigation:** with `--navigation`, client-side navigation with
  `router.push` (App Router and Pages Router) is compared with loading each
  route directly.

```bash
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test --mode both
```

`--mode both` tests the development and production builds in one run and
marks findings that appear in only one of them. Development builds give exact
source lines. Production builds show what your users get, including attribute
mismatches React 19 never reports in production.

A config is optional. Add one for the values discovery cannot know:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    // One real value per dynamic segment, or the route is skipped.
    dynamic: {
      "/blog/[slug]": ["hello-world"],
      "/products/[id]": ["1", "42"],
    },
    exclude: ["/api/**", "/admin/**"],
  },
});
```

For file and line numbers in production builds, turn on browser source maps:

```ts title="next.config.ts"
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  productionBrowserSourceMaps: true,
};

export default nextConfig;
```

### Catch it in your editor

The [ESLint plugin](https://hydration.jscrate.dev/docs/eslint) finds the same causes as you type. Its `next`
preset skips Server Components, where the clock and `window` checks are safe:

```bash
npm install -D eslint-plugin-hydration-proof
```

```js title="eslint.config.mjs"
import hydrationProof from "eslint-plugin-hydration-proof";

export default [hydrationProof.configs.next];
```

## Related

- [React hydration errors](https://hydration.jscrate.dev/docs/guides/react-hydration-error), outside Next.js
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors) step by step
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)
- [Quick start](https://hydration.jscrate.dev/docs/quick-start)

---

# React Router hydration errors

> A React Router hydration error means the server HTML and the first client render differ. Causes in framework mode, HydrateFallback, and testing every route.

Source: https://hydration.jscrate.dev/docs/frameworks/react-router
Last updated: 2026-09-18

A React Router hydration error means the HTML the server rendered differs from
what React renders in the browser on its first pass. In framework mode, React
Router hydrates the whole document, so a date in a route, a `clientLoader` that
returns other data, or an attribute an extension adds to `<body>` can each
cause it.

## Common hydration errors in React Router

React Router has no hydration messages of its own. A React Router v7 hydration
error, or one in a later version, is React's message, and with React 19 it
reads:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

React 18 words the same bugs differently; [all React hydration error
messages](https://hydration.jscrate.dev/docs/errors) lists every variant, and production builds show a
minified code such as [#418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418).

### Why does a React Router hydration mismatch happen?

The default `entry.client.tsx` calls `hydrateRoot(document, <HydratedRouter />)`:
React owns `<html>`, `<head>` and `<body>`, and compares all of them. The
common causes:

| Cause               | In React Router                                                                      | Fix                                                                              |
| ------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Client data         | A `clientLoader` with `hydrate = true` that returns other data than the `loader`     | [Below](#render-a-fallback-during-hydration-in-react-router)                     |
| The clock           | `new Date()` or `Date.now()` in a route component                                    | [Time](https://hydration.jscrate.dev/docs/causes/time)                                                        |
| Locale and timezone | `toLocaleString()` without an explicit locale or `timeZone`                          | [Locale](https://hydration.jscrate.dev/docs/causes/locale), [timezone](https://hydration.jscrate.dev/docs/causes/timezone)                 |
| Browser-only APIs   | `window`, `localStorage` or `matchMedia` read during render                          | [Browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api), [storage](https://hydration.jscrate.dev/docs/causes/storage)        |
| Invalid HTML        | `<div>` inside `<p>`, `<a>` inside `<a>`                                             | [Invalid nesting](https://hydration.jscrate.dev/docs/causes/invalid-html)                                     |
| The document        | Attributes an extension adds to `<html>` or `<body>`, tags a script adds to `<head>` | [Extensions](https://hydration.jscrate.dev/docs/causes/extension), [scripts](https://hydration.jscrate.dev/docs/causes/third-party-script) |

A common React Router v7 hydration mismatch comes from client data. The React
Router docs say it directly: without a `HydrateFallback`, the route component
is rendered on the server and the `clientLoader` runs during hydration, so the
`loader` and the `clientLoader` must return the same data on the first load.

## How to fix a React Router hydration error

### Render the same thing first

Render output that does not depend on the browser, then change it in
`useEffect`, which only runs in the browser after hydration:

```tsx title="app/routes/greeting.tsx"
import { useEffect, useState } from "react";

export default function Greeting() {
  const [name, setName] = useState<string | null>(null);

  useEffect(() => {
    setName(localStorage.getItem("name"));
  }, []);

  return <p>Hello{name ? `, ${name}` : ""}</p>;
}
```

For values the server knows (the user's locale from a cookie, the time of the
request), return them from the `loader` and render from `loaderData` on both
sides.

### Render a fallback during hydration in React Router

When a route needs data that only the browser has, set
`clientLoader.hydrate = true` and export a `HydrateFallback`. React Router then
renders the fallback on the server and while the page hydrates, and renders
the route component only once the `clientLoader` has finished. The server and
the first client render agree, because both are the fallback.

```tsx title="app/routes/game.tsx"
import type { Route } from "./+types/game";
import { GameBoard, loadLocalGameData } from "../game";

export async function clientLoader() {
  return loadLocalGameData();
}
clientLoader.hydrate = true as const;

export function HydrateFallback() {
  return <p>Loading game…</p>;
}

export default function Game({ loaderData }: Route.ComponentProps) {
  return <GameBoard data={loaderData} />;
}
```

See the React Router guide to
[client data](https://reactrouter.com/how-to/client-data) for the other
patterns.

### Keep suppressHydrationWarning for small, known differences

`suppressHydrationWarning` on an element tells React to keep the server's text
without reporting it, one level deep. It suits a timestamp whose first value
does not matter; everywhere else it hides a real bug. See
[when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Test every route with hydration-proof

hydration-proof loads every route in a real browser and compares the server
HTML with the hydrated DOM. The `react-router` [adapter](https://hydration.jscrate.dev/docs/adapters) is
picked when `package.json` has `@react-router/dev` or the project has a
`react-router.config.*` file. It supports framework mode; the package's
fixtures run version 8.4.

- **Build and start:** `react-router build` (or your `build` script when it
  runs `react-router build`), then `react-router-serve ./build/server/index.js`.
  The app is built only when `build/server/index.js` is missing.
- **Development mode:** `react-router dev`, with `--mode development` or
  `--mode both`.
- **Routes:** from `react-router routes --json`, in `app/` or `src/app/`.
  `:id`, `*` and `:lang?` become `[id]`, `[...slug]` and `[[lang]]`, the
  syntax `routes.dynamic` uses.
- **Not-found page:** a URL that does not exist is loaded too, to check that
  the not-found page hydrates.
- **Navigation:** with `--navigation`, a client-side navigation through
  `window.__reactRouterDataRouter.navigate` is compared with loading each route
  directly.

```bash
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test --mode both
```

Dynamic routes need example values, or they are skipped:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    dynamic: { "/products/[id]": ["1", "42"] },
  },
});
```

If you serve the build with your own server instead of `react-router-serve`,
set `server.command` (and `server.build`, since a custom start command only
gets a build step when one is configured) and keep the `react-router` adapter
for its routes. The
[ESLint plugin](https://hydration.jscrate.dev/docs/eslint)'s `recommended` preset catches the clock, random
values and browser globals in route components as you type.

## Related

- [Remix hydration errors](https://hydration.jscrate.dev/docs/frameworks/remix), React Router's predecessor
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [Test every route for hydration errors](https://hydration.jscrate.dev/docs/routes)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)
- [Adapters](https://hydration.jscrate.dev/docs/adapters)

---

# Remix hydration errors

> A Remix hydration error means the server HTML and the first client render differ. Common causes in Remix v2, ClientOnly, HydrateFallback, and route tests.

Source: https://hydration.jscrate.dev/docs/frameworks/remix
Last updated: 2026-09-18

A Remix hydration error means the HTML the server rendered differs from what
React renders in the browser on its first pass. Remix v2 hydrates the whole
document, so the cause can be anywhere: a date in a route, a `clientLoader`
that returns other data, or an attribute a browser extension adds to `<body>`.

## Common hydration errors in Remix

Remix shows React's own messages. With React 18, the version Remix v2 declares
as its peer dependency, they read:

```text
Hydration failed because the initial UI does not match what was rendered on the server.
Text content does not match server-rendered HTML.
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

Production builds show only a minified code such as
[#418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418).
[All React hydration error messages](https://hydration.jscrate.dev/docs/errors) lists every variant.

The default `entry.client.tsx` calls `hydrateRoot(document, <RemixBrowser />)`,
so React compares `<html>`, `<head>` and `<body>` as well as your routes. The
usual causes:

| Cause               | In Remix                                                                         | Fix                                                                       |
| ------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Client data         | A `clientLoader` with `hydrate = true` that returns other data than the `loader` | [Below](#render-a-fallback-while-the-client-loader-runs)                  |
| The clock           | `new Date()` or `Date.now()` in a route component                                | [Time](https://hydration.jscrate.dev/docs/causes/time)                                                 |
| Locale and timezone | `toLocaleString()` without an explicit locale or `timeZone`                      | [Locale](https://hydration.jscrate.dev/docs/causes/locale), [timezone](https://hydration.jscrate.dev/docs/causes/timezone)          |
| Browser-only APIs   | `window`, `localStorage` or `matchMedia` read during render                      | [Browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api), [storage](https://hydration.jscrate.dev/docs/causes/storage) |
| Invalid HTML        | `<div>` inside `<p>`, `<a>` inside `<a>`                                         | [Invalid nesting](https://hydration.jscrate.dev/docs/causes/invalid-html)                              |
| The document        | Attributes an extension adds to `<html>` or `<body>`                             | [Extensions](https://hydration.jscrate.dev/docs/causes/extension)                                      |

## How to fix a Remix hydration error

### Render a component only in the browser

The `ClientOnly` component from [remix-utils](https://github.com/sergiodxa/remix-utils)
renders its fallback on the server and during hydration, then the real
component. Its children are a function, so the component is not even created on
the server:

```tsx title="app/routes/stores.tsx"
import { ClientOnly } from "remix-utils/client-only";
import { StoreMap, StoreMapPlaceholder } from "~/components/store-map";

export default function Stores() {
  return (
    <ClientOnly fallback={<StoreMapPlaceholder />}>
      {() => <StoreMap />}
    </ClientOnly>
  );
}
```

remix-utils 7.x is the line for Remix v2; newer majors target React Router.
Without a library, the same pattern is a `useEffect` that flips a flag after
hydration; see [client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component).

### Render a fallback while the client loader runs

When a route needs data only the browser has, set `clientLoader.hydrate = true`
and export a `HydrateFallback`. Remix renders the fallback on the server and
calls the `clientLoader` during hydration. Without a `HydrateFallback`, the
route component is rendered on the server, so the `loader` and the
`clientLoader` must return the same data on the first load.

```tsx title="app/routes/game.tsx"
import { useLoaderData } from "@remix-run/react";
import { GameBoard, loadLocalGameData } from "~/game";

export async function clientLoader() {
  return loadLocalGameData();
}
clientLoader.hydrate = true;

export function HydrateFallback() {
  return <p>Loading game…</p>;
}

export default function Game() {
  const data = useLoaderData<typeof clientLoader>();
  return <GameBoard data={data} />;
}
```

### Return server values from the loader

For values the server knows (the user's locale from a cookie, the time of the
request), return them from the `loader` and render from `useLoaderData()` on
both sides. The browser then renders with the same value the server used.

## Test every route with hydration-proof

hydration-proof loads every route in a real browser and compares the server
HTML with the hydrated DOM. The `remix` [adapter](https://hydration.jscrate.dev/docs/adapters) is picked
when `package.json` has `@remix-run/dev`:

|             | With Vite                             | Classic compiler               |
| ----------- | ------------------------------------- | ------------------------------ |
| Build       | `remix vite:build`                    | `remix build`                  |
| Start       | `remix-serve ./build/server/index.js` | `remix-serve ./build/index.js` |
| Development | `remix vite:dev`                      | `remix dev`                    |

The Vite commands are used when the project has a `vite.config.*` file. Your
own `build` script is used when it runs `remix`.

- **Routes:** from `remix routes --json`, with `:id`, `*` and `:lang?`
  converted to `[id]`, `[...slug]` and `[[lang]]`.
- **Not-found page:** a URL that does not exist is loaded too, to check that
  the not-found page hydrates.
- **Navigation:** with `--navigation`, a client-side navigation through
  `window.__remixRouter.navigate` is compared with loading each route directly.

```bash
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test --mode both
```

Give dynamic routes example values, or they are skipped:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    dynamic: { "/products/[id]": ["1", "42"] },
  },
});
```

Remix v2's successor is React Router's framework mode. When you upgrade, the
`react-router` adapter takes over; see
[React Router hydration errors](https://hydration.jscrate.dev/docs/frameworks/react-router).

## Related

- [React Router hydration errors](https://hydration.jscrate.dev/docs/frameworks/react-router)
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)
- [Test every route with the CLI](https://hydration.jscrate.dev/docs/routes)

---

# Astro hydration errors

> An Astro hydration error comes from a React island whose server HTML differs from its first client render. Causes, client directives, useId, and tests.

Source: https://hydration.jscrate.dev/docs/frameworks/astro
Last updated: 2026-09-18

An Astro hydration error comes from a React island: a component with a
`client:*` directive whose server-rendered HTML differs from what React renders
when the island hydrates in the browser. Astro's own markup never hydrates, so
look inside the island for dates, locale formatting, browser APIs, random
values and ids.

## Common hydration errors in Astro

An Astro React hydration error is React's own message, logged in the browser
console for the island that failed. With React 19:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

[All React hydration error messages](https://hydration.jscrate.dev/docs/errors) lists the React 18 wording
and the minified production codes.

### How does Astro island hydration work?

A React component in an `.astro` page renders to HTML on the server. Without a
client directive, that HTML is all the browser gets: no JavaScript, and nothing
to hydrate. A directive makes it an island that hydrates on its own:

| Directive             | When the island hydrates                                                         |
| --------------------- | -------------------------------------------------------------------------------- |
| `client:load`         | Immediately on page load                                                         |
| `client:idle`         | Once the page has finished its initial load and `requestIdleCallback` fires      |
| `client:visible`      | Once the component enters the viewport                                           |
| `client:only="react"` | Never: the server renders no HTML, and the component renders only in the browser |

Each `<astro-island>` is its own React root. A mismatch in one island does not
affect the others, and React reports it for that island alone.

### Why does an Astro hydration mismatch happen?

| Cause               | Typical code                                                | Fix                                                                       |
| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
| The clock           | `new Date()` or `Date.now()` in the component               | [Time](https://hydration.jscrate.dev/docs/causes/time)                                                 |
| Locale and timezone | `toLocaleString()` without an explicit locale or `timeZone` | [Locale](https://hydration.jscrate.dev/docs/causes/locale), [timezone](https://hydration.jscrate.dev/docs/causes/timezone)          |
| Browser-only APIs   | `window`, `localStorage` or `matchMedia` read during render | [Browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api), [storage](https://hydration.jscrate.dev/docs/causes/storage) |
| Random values       | `Math.random()`, `crypto.randomUUID()` in render            | [Random values](https://hydration.jscrate.dev/docs/causes/random)                                      |
| Duplicate ids       | `useId` in several islands without an `identifierPrefix`    | [Generated ids](https://hydration.jscrate.dev/docs/causes/unstable-id)                                 |
| Invalid HTML        | `<div>` inside `<p>`, `<a>` inside `<a>` in the component   | [Invalid nesting](https://hydration.jscrate.dev/docs/causes/invalid-html)                              |

## How to fix an Astro hydration error

### Pass values from the page as props

The frontmatter of an `.astro` page runs only on the server. Compute a value
there and pass it to the island: Astro serializes the props into the page, so
the island hydrates with the same value the server rendered.

```astro title="src/pages/index.astro"
---
import LastUpdated from "../components/LastUpdated.tsx";

const renderedAt = Date.now();
---

<LastUpdated client:load renderedAt={renderedAt} />
```

### Read browser values after hydration

Render output that does not depend on the browser, then change it in
`useEffect`, which only runs after the island has hydrated:

```tsx title="src/components/Greeting.tsx"
import { useEffect, useState } from "react";

export default function Greeting() {
  const [name, setName] = useState<string | null>(null);

  useEffect(() => {
    setName(localStorage.getItem("name"));
  }, []);

  return <p>Hello{name ? `, ${name}` : ""}</p>;
}
```

### Skip server rendering with client:only

For a component that cannot render on the server at all, use
`client:only="react"`. There is no server HTML to compare, so there is no
mismatch, but the component's content only appears once its JavaScript has
run.

### Keep useId unique across islands

Two React roots that both call `useId` generate the same ids unless each has
its own `identifierPrefix`. Astro's React integration sets one per island. If
you render React roots yourself, pass the same `identifierPrefix` to the server
render and to `hydrateRoot`, and a different one for each root.
hydration-proof reports a collision as [HP3004](https://hydration.jscrate.dev/docs/issues/hp3004).

## Test every route with hydration-proof

hydration-proof loads every page in a real browser and compares each island's
server HTML with its hydrated DOM. The `astro` [adapter](https://hydration.jscrate.dev/docs/adapters) is
picked when `package.json` has `astro` or the project has an `astro.config.*`
file:

- **Build and start:** `astro build` (or your `build` script when it runs
  `astro`). With `@astrojs/node`, the built server runs as
  `node ./dist/server/entry.mjs`; otherwise `astro preview` serves the build.
- **Development mode:** `astro dev`, with `--mode development` or
  `--mode both`.
- **Routes:** from `src/pages`. Astro's `[id]` and `[...slug]` are already the
  syntax `routes.dynamic` uses.
- **Islands:** each island is compared on its own. The attributes Astro changes
  while it loads an island (`ssr`, `props`, `client` and others), its loader
  script and the dev toolbar are never compared.
- **Pages without React** are normal in an Astro site and are not reported.
- **Not-found page:** a URL that does not exist is loaded too, to check that
  the not-found page hydrates.

```bash
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test
```

Give dynamic pages example values, or they are skipped:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    dynamic: { "/blog/[slug]": ["hello-world"] },
  },
});
```

To test islands in other locales, timezones or screen sizes, add
[scenarios](https://hydration.jscrate.dev/docs/scenarios) or an
[environment matrix](https://hydration.jscrate.dev/docs/environment-matrix).

## Related

- [Vite SSR hydration](https://hydration.jscrate.dev/docs/frameworks/vite-ssr)
- [Generated ids that differ](https://hydration.jscrate.dev/docs/causes/unstable-id)
- [HP3004: two React roots generate the same ids](https://hydration.jscrate.dev/docs/issues/hp3004)
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [Adapters](https://hydration.jscrate.dev/docs/adapters)

---

# Vite SSR hydration errors

> Vite SSR hydration fails when entry-server and entry-client render different output. The setup, the common causes, duplicate React copies, and route tests.

Source: https://hydration.jscrate.dev/docs/frameworks/vite-ssr
Last updated: 2026-09-18

Vite SSR hydration works in two halves: `entry-server` renders your app to HTML
with `renderToString` or `renderToPipeableStream`, and `entry-client` calls
`hydrateRoot` on that HTML. A hydration error means the two halves rendered
different output, usually because of the clock, the locale, a browser API, or
different data on each side.

## How Vite SSR hydration works

A Vite SSR app has an `index.html` with a placeholder for the server markup, a
server (`server.js`) that fills it in, and two entry files. The server entry
renders the app:

```tsx title="src/entry-server.tsx"
import { StrictMode } from "react";
import { renderToString } from "react-dom/server";
import App from "./App";

export function render(url: string) {
  const html = renderToString(
    <StrictMode>
      <App url={url} />
    </StrictMode>
  );
  return { html };
}
```

The client entry hydrates the same tree in the browser:

```tsx title="src/entry-client.tsx"
import { StrictMode } from "react";
import { hydrateRoot } from "react-dom/client";
import App from "./App";

hydrateRoot(
  document.getElementById("root")!,
  <StrictMode>
    <App url={window.location.pathname} />
  </StrictMode>
);
```

Everything `App` renders on its first pass in the browser must match what
`render` produced on the server: the same elements, the same text, the same
attributes. The [Vite SSR guide](https://vite.dev/guide/ssr) covers the server
side, and its `create-vite-extra` templates include React.

## Common hydration errors in Vite SSR

A Vite hydration error is React's own message, logged in the browser console.
With React 19:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

[All React hydration error messages](https://hydration.jscrate.dev/docs/errors) lists the React 18 wording
and the minified production codes. The causes:

| Cause               | Typical code                                                         | Fix                                                              |
| ------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Different trees     | A provider, wrapper or route rendered by one entry and not the other | Render the same `App` with the same props in both entries        |
| Different data      | The server renders with data the client fetches again                | [Server and client data](https://hydration.jscrate.dev/docs/causes/data)                      |
| The clock           | `new Date()` or `Date.now()` in a component                          | [Time](https://hydration.jscrate.dev/docs/causes/time)                                        |
| Locale and timezone | `toLocaleString()` without an explicit locale or `timeZone`          | [Locale](https://hydration.jscrate.dev/docs/causes/locale), [timezone](https://hydration.jscrate.dev/docs/causes/timezone) |
| Browser-only APIs   | `window`, `localStorage` or `matchMedia` read during render          | [Browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api)                         |
| Generated ids       | counters or random ids instead of `useId`                            | [Generated ids](https://hydration.jscrate.dev/docs/causes/unstable-id)                        |

### Two copies of React

If the server bundle and a linked package resolve different copies of `react`,
hooks throw "Invalid hook call" and the page fails instead of hydrating. This
happens with hoisting and with linked packages in monorepos. Vite's
[`resolve.dedupe`](https://vite.dev/config/shared-options#resolve-dedupe)
forces one copy; read its note on SSR builds before relying on it:

```ts title="vite.config.ts"
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react()],
  resolve: { dedupe: ["react", "react-dom"] },
});
```

## How to fix them

1. **Render the same tree.** Both entries render one `App` component with the
   same props. Anything the server knows (the URL, the user's locale from a
   header or cookie) goes in as a prop, and the client reads it from the page.
2. **Send the server's data along.** Serialize the data the server rendered
   with into the page and hydrate from it, instead of fetching again in the
   browser. See [different data](https://hydration.jscrate.dev/docs/causes/data).
3. **Read browser values after hydration.** Render a neutral value first and
   change it in `useEffect`. See
   [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering).
4. **Use `useId` for ids.** With several React roots on one page, give each its
   own `identifierPrefix`, the same on the server and in `hydrateRoot`.

## Test every route with hydration-proof

hydration-proof starts your server, loads each route in a real browser and
compares the server HTML with the hydrated DOM. The `vite`
[adapter](https://hydration.jscrate.dev/docs/adapters) is picked when `package.json` has `vite` and
`react-dom`, and the project has a `server.js` (or `server.mjs`, `server.ts`)
or a `src/entry-server.*` file:

- **Build and start:** your `build` script, then your `start` script (or
  `serve`, or `preview`). The app is built only when `dist` is missing.
- **Development mode:** your `dev` script, with `--mode development` or
  `--mode both`.
- **Port:** the server must listen on the port hydration-proof chooses. It is
  in the `PORT` environment variable, and `{port}` in a configured command is
  replaced with it.
- **Framework markup:** Vite's client script and the React Refresh preamble
  are never compared.
- **Streaming:** with `renderToPipeableStream`, Suspense boundaries that
  hydrate later are compared on their own.

A Vite app has no file-based routes, so list them in the config. Without any
routes, only `/` is tested:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    paths: ["/", "/about", "/products/1"],
    crawl: true, // also follow links found on those pages
  },
});
```

```bash
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test
```

`--sitemap` adds the pages in your sitemap. The
[ESLint plugin](https://hydration.jscrate.dev/docs/eslint) catches the clock, random values and browser
globals in components as you type.

## Related

- [Custom React servers](https://hydration.jscrate.dev/docs/frameworks/custom-server) with Express and
  streaming
- [Astro hydration errors](https://hydration.jscrate.dev/docs/frameworks/astro)
- [What is hydration in React?](https://hydration.jscrate.dev/docs/guides/what-is-hydration)
- [Test every route for hydration errors](https://hydration.jscrate.dev/docs/routes)
- [Adapters](https://hydration.jscrate.dev/docs/adapters)

---

# TanStack Start hydration errors

> A TanStack Start hydration error means the server HTML and the first client render differ. The causes, ClientOnly, selective SSR, and how to test your routes.

Source: https://hydration.jscrate.dev/docs/frameworks/tanstack-start
Last updated: 2026-09-18

A TanStack Start hydration error means the HTML the server rendered differs
from what React renders in the browser on its first pass. TanStack's own
[hydration errors guide](https://tanstack.com/start/latest/docs/framework/react/guide/hydration-errors)
names the usual causes: `Intl` locale and time zone formatting, `Date.now()`,
random ids, responsive-only logic, feature flags and user preferences.

## Common hydration errors in TanStack Start

TanStack Start shows React's own messages. With React 19:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

A TanStack Start hydration mismatch has the same causes as in any
server-rendered React app:

| Cause                | Typical code                                                                         | Fix                                                                   |
| -------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Locale and time zone | `Intl.DateTimeFormat()`, `toLocaleString()` without an explicit locale or `timeZone` | [Locale](https://hydration.jscrate.dev/docs/causes/locale), [timezone](https://hydration.jscrate.dev/docs/causes/timezone)      |
| The clock            | `Date.now()`, `new Date()` in a component                                            | [Time](https://hydration.jscrate.dev/docs/causes/time)                                             |
| Random values        | random ids, `Math.random()` in render                                                | [Random values](https://hydration.jscrate.dev/docs/causes/random)                                  |
| Screen size          | responsive logic that reads `window` or `matchMedia`                                 | [Media queries](https://hydration.jscrate.dev/docs/causes/media-query)                             |
| User preferences     | theme or flags read from the browser                                                 | [Theme](https://hydration.jscrate.dev/docs/causes/theme), [browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api) |

## How to fix a TanStack Start hydration error

TanStack's guide lists five strategies.

### Make the server and the client agree

Pick the locale and time zone on the server, deterministically, and use the
same values on the client. The guide recommends a cookie as the source of
truth, with the `Accept-Language` header as a fallback, computed once on the
server and passed down. Until the browser has told the server its time zone,
render in UTC.

### Let the client report its environment

On the first visit, set a cookie with the browser's time zone from an effect.
The next request renders on the server with the right zone, and the first
render never depends on the browser.

### Render unstable UI on the client only

`ClientOnly` from `@tanstack/react-router` skips server rendering for its
children and shows the `fallback` until the page has hydrated:

```tsx title="src/components/last-seen.tsx"
import { ClientOnly } from "@tanstack/react-router";
import { RelativeTime } from "./relative-time";

export function LastSeen({ ts }: { ts: number }) {
  return (
    <ClientOnly fallback={<span>—</span>}>
      <RelativeTime ts={ts} />
    </ClientOnly>
  );
}
```

### Turn off server rendering for a route

Selective SSR renders a route's data on the server but not its component
(`ssr: "data-only"`), or skips the server for that route (`ssr: false`):

```tsx title="src/routes/unstable.tsx"
import { createFileRoute } from "@tanstack/react-router";
import { ExpensiveViz } from "../components/expensive-viz";

export const Route = createFileRoute("/unstable")({
  ssr: "data-only",
  component: ExpensiveViz,
});
```

### Suppress the warning as a last resort

`suppressHydrationWarning` on a small, known-different element keeps the
server's text without a warning. Use it sparingly; see
[when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Test every route with hydration-proof

hydration-proof has no built-in TanStack Start adapter, so it does not discover
routes or know the build commands on its own. It still tests any
server-rendered React page, in one of three ways.

### Test an app you started

Start the production build yourself, then point hydration-proof at it and name
the routes:

```bash
npx hydration-proof test --url http://localhost:3000 --route / --route /posts
```

With `--url`, nothing is built or started, and only the routes you name are
tested. Add `--sitemap` to test the pages in your sitemap, or `--crawl` to
follow links from the tested pages.

### Let hydration-proof build and start it

Use `adapter: "none"` and give it your commands:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  adapter: "none",
  server: {
    build: "npm run build",
    command: "npm run start", // must listen on process.env.PORT
  },
  routes: { paths: ["/", "/posts", "/posts/1"] },
});
```

hydration-proof picks a free port and passes it in the `PORT` environment
variable; `{port}` in the command is replaced with it too. Without an adapter,
it cannot tell whether a build already exists, so it runs `server.build` on
every run. Set `server.buildWhen: "never"` when an earlier CI step builds the
app.

`npx hydration-proof doctor` shows which adapter `adapter: "auto"` would pick.
An app with `react-dom` and a `start` script matches the generic `node` adapter,
which runs your `build`, `start` and `dev` scripts; routes still come from the
config.

### Write an adapter

To discover routes from `src/routes` and skip rebuilding when a build exists,
write a small adapter with `defineAdapter`: a `detect` function, the commands,
a `buildOutput` file and a `discoverRoutes` function. See
[writing an adapter](https://hydration.jscrate.dev/docs/adapters#write-an-adapter-with-defineadapter).

## Related

- [React Router hydration errors](https://hydration.jscrate.dev/docs/frameworks/react-router)
- [Vite SSR hydration](https://hydration.jscrate.dev/docs/frameworks/vite-ssr)
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [Timezone hydration mismatches](https://hydration.jscrate.dev/docs/causes/timezone)
- [Adapters](https://hydration.jscrate.dev/docs/adapters)

---

# Custom React server hydration errors

> A renderToPipeableStream hydration error means your server's HTML and the first hydrateRoot render differ. Fix it in Express or any Node.js server.

Source: https://hydration.jscrate.dev/docs/frameworks/custom-server
Last updated: 2026-09-18

A renderToPipeableStream hydration error means the HTML your server streamed
differs from what `hydrateRoot` renders in the browser on its first pass. In an
Express or other custom Node.js server, look for a difference between the
server and client entries, data the client never receives, or values such as
the time that change between the two renders.

## Common hydration errors in custom React servers

Your server shows React's own messages. With React 19:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

[All React hydration error messages](https://hydration.jscrate.dev/docs/errors) lists the React 18 wording
and the minified production codes. The causes:

| Cause                       | Typical code                                                                   | Fix                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Different trees             | The server wraps `App` in a provider or passes props the client entry does not | Render the same tree with the same props                                                    |
| Different data              | The server renders with data the client fetches again                          | [Server and client data](https://hydration.jscrate.dev/docs/causes/data)                                                 |
| The clock, locale, timezone | `Date.now()`, `toLocaleString()` without an explicit locale or `timeZone`      | [Time](https://hydration.jscrate.dev/docs/causes/time), [locale](https://hydration.jscrate.dev/docs/causes/locale), [timezone](https://hydration.jscrate.dev/docs/causes/timezone) |
| Browser-only APIs           | `window` or `localStorage` read during render                                  | [Browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api)                                                    |
| Several roots               | two roots that call `useId` without their own `identifierPrefix`               | [Generated ids](https://hydration.jscrate.dev/docs/causes/unstable-id)                                                   |

## How to fix a renderToPipeableStream hydration error

### Render the same tree on both sides

When `App` renders the whole document, from `<html>` down, the server streams it
and the client hydrates `document`:

```tsx title="server.tsx"
import express from "express";
import { renderToPipeableStream } from "react-dom/server";
import { App } from "./src/app";

const server = express();
server.use(express.static("dist/client"));

server.use((request, response) => {
  const { pipe } = renderToPipeableStream(<App url={request.url} />, {
    bootstrapScripts: ["/client.js"],
    onShellReady() {
      response.setHeader("content-type", "text/html");
      pipe(response);
    },
  });
});

server.listen(Number(process.env.PORT ?? 3000));
```

```tsx title="src/client.tsx"
import { hydrateRoot } from "react-dom/client";
import { App } from "./app";

hydrateRoot(document, <App url={window.location.pathname} />);
```

Every prop the server passes must reach the client with the same value. For
data, serialize what the server rendered with into the page, for example in the
inline script of the `bootstrapScriptContent` option (escape `<` in it), and
read it in the client entry instead of fetching again.

### Let Suspense boundaries fail on their own

With streaming, each Suspense boundary hydrates when its content arrives. If a
component inside a boundary throws on the server, React sends the boundary's
fallback and retries rendering it in the browser. A mismatch inside a boundary
makes React render that boundary again on the client, not the whole page.
hydration-proof reports these as [HP2003](https://hydration.jscrate.dev/docs/issues/hp2003) (a boundary
switched to client rendering) and [HP2006](https://hydration.jscrate.dev/docs/issues/hp2006) (the server
could not finish rendering a boundary).

### Give each root its own identifierPrefix

With several React roots on one page, each needs an `identifierPrefix` for
`useId`, and the prefix has to be the same on the server and in `hydrateRoot`:

```tsx title="src/cart.server.tsx"
import { renderToPipeableStream } from "react-dom/server";
import { Cart } from "./cart-widget";

export function renderCart() {
  return renderToPipeableStream(<Cart />, { identifierPrefix: "cart-" });
}
```

```tsx title="src/cart.client.tsx"
import { hydrateRoot } from "react-dom/client";
import { Cart } from "./cart-widget";

export function hydrateCart(element: HTMLElement) {
  hydrateRoot(element, <Cart />, { identifierPrefix: "cart-" });
}
```

Two roots with the same ids are reported as [HP3004](https://hydration.jscrate.dev/docs/issues/hp3004).

### Web streams: renderToReadableStream

On runtimes with Web Streams, `renderToReadableStream` does the same job and
the same rules apply: the same tree, the same props, one `identifierPrefix`
per root.

## Test every route with hydration-proof

hydration-proof starts your server (building it first when a build is
configured), loads each route in a real browser and compares the server HTML
with the hydrated DOM. Streaming is
supported with `renderToPipeableStream` and `renderToReadableStream`: every
Suspense boundary that hydrates later is compared on its own.

The `node` [adapter](https://hydration.jscrate.dev/docs/adapters) is picked when `package.json` has
`react-dom` and a `start` script. It runs your `build`, `start` and `dev`
scripts. To use other commands, set them yourself, with `adapter: "node"` or
`adapter: "none"`:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  adapter: "node",
  server: {
    build: "npm run build",
    command: "node dist/server.js", // listens on process.env.PORT
    devCommand: "node --watch dist/server.js",
  },
  routes: { paths: ["/", "/pricing", "/products/1"] },
});
```

- **Port:** hydration-proof picks a free port and passes it in the `PORT`
  environment variable. `{port}` in a command is replaced with it too, for a
  server that takes the port as an argument.
- **Build:** a custom start command only gets a build step when
  `server.build` is set.
- **Routes:** a custom server has no route files to discover, so list the
  routes. Without any, only `/` is tested; `--crawl` follows links from the
  tested pages and `--sitemap` reads your sitemap.
- **Development mode:** `server.devCommand` is used with `--mode development`
  or `--mode both`.

```bash
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test --crawl
```

## Related

- [Vite SSR hydration](https://hydration.jscrate.dev/docs/frameworks/vite-ssr)
- [Adapters](https://hydration.jscrate.dev/docs/adapters) and custom servers
- [What is hydration in React?](https://hydration.jscrate.dev/docs/guides/what-is-hydration)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Test every route for hydration errors](https://hydration.jscrate.dev/docs/routes)

---

# React hydration error messages

> All React hydration error messages from React 18 and 19, with the minified code and a page that explains each. Find the text you see and go to the fix.

Source: https://hydration.jscrate.dev/docs/errors
Last updated: 2026-09-18

React hydration error messages mean React could not reuse the HTML the
server sent: the first render in the browser produced different markup, or
something failed while React attached to the page. The wording depends on your
React version and on whether the build is minified. Find the text you see
below and open its page for the fix.

## Every message, by React version

React 19 merged most of the React 18 messages into one error with a diff, and
production builds replace every message with a numbered code.

| Page                                                                                                       | React 18 wording                                                                                                      | React 19 wording                                                                                      | Code                   |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------- |
| [Server rendered HTML didn't match](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client) | Not in React 18                                                                                                       | `Hydration failed because the server rendered HTML didn't match the client.`                          | #418                   |
| [Initial UI does not match](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)                       | `Hydration failed because the initial UI does not match what was rendered on the server.`                             | Replaced by the row above                                                                             | #418                   |
| [Text content does not match](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)               | `Text content does not match server-rendered HTML.` and the warning `Text content did not match. Server: … Client: …` | `Hydration failed because the server rendered text didn't match the client.`                          | #425 in 18, #418 in 19 |
| [Attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)                           | One warning per attribute (the next two rows)                                                                         | `A tree hydrated but some attributes of the server rendered HTML didn't match the client properties.` | None: development only |
| [Prop className did not match](https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match)                                  | ``Warning: Prop `className` did not match. Server: … Client: …``                                                      | A line in the attribute diff                                                                          | None                   |
| [Expected server HTML to contain](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching)                 | `Warning: Expected server HTML to contain a matching <div> in <div>.`                                                 | A `+` or `-` element in the diff                                                                      | #418 follows it        |
| [Extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server)                          | `Warning: Extra attributes from the server: class,style`                                                              | A `-` line in the attribute diff                                                                      | None                   |
| [Error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating)                                   | `There was an error while hydrating.` (root) or `…this Suspense boundary.`                                            | `There was an error while hydrating but React was able to recover…`                                   | #423, #422             |
| [div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p)                            | `validateDOMNesting(...): <div> cannot appear as a descendant of <p>.`                                                | `In HTML, <div> cannot be a descendant of <p>.`                                                       | None: development only |
| [validateDOMNesting](https://hydration.jscrate.dev/docs/errors/validatedomnesting)                                                      | `validateDOMNesting(...): <tr> cannot appear as a child of <table>.`                                                  | `In HTML, <tr> cannot be a child of <table>.`                                                         | None: development only |
| [Update before hydrating](https://hydration.jscrate.dev/docs/errors/suspense-boundary-received-update-before-hydrating)                 | `This Suspense boundary received an update before it finished hydrating.`                                             | No longer reported                                                                                    | #421                   |
| [Missing getServerSnapshot](https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot)                                        | `Missing getServerSnapshot, which is required for server-rendered content.`                                           | Same                                                                                                  | #407                   |
| [window is not defined](https://hydration.jscrate.dev/docs/errors/window-is-not-defined)                                                | `ReferenceError: window is not defined`                                                                               | Same: a server crash, not a React error                                                               | None                   |

The production codes have their own pages:
[minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418),
[#423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423),
[#425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425), and
[every hydration code in one table](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes).

## Which one am I seeing?

Look at how the message starts:

| It starts with                       | What happened                                                         | Go to                                                                                                                                                    |
| ------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Minified React error #`             | A production build. The text is replaced by a code                    | [Minified React error codes](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)                                                                                    |
| `Hydration failed because`           | React threw the server HTML away and rendered it again in the browser | [React 19](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client) or [React 18](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match) |
| `Warning:`                           | A React 18 development warning that names the element and both values | The matching row in the table above                                                                                                                      |
| `A tree hydrated but`                | React 19 kept the page, but an attribute differs and stays wrong      | [Attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)                                                                         |
| `In HTML,` or `validateDOMNesting`   | Invalid tag nesting that the browser rewrites before React runs       | [validateDOMNesting](https://hydration.jscrate.dev/docs/errors/validatedomnesting)                                                                                                    |
| `There was an error while hydrating` | The follow-up to an earlier error. Scroll up to the first one         | [Error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating)                                                                                 |
| `ReferenceError`                     | The server crashed before any hydration happened                      | [window is not defined](https://hydration.jscrate.dev/docs/errors/window-is-not-defined)                                                                                              |

React prints several of these for one bug. In React 18 a single mismatch
often logs a warning, then `Hydration failed…` or
`Text content does not match…`, then `There was an error while hydrating…`. The first message is the
one that names the element. Fix that one first.

To see which wording you get, check the React version your app uses:

```sh
npm ls react react-dom   # pnpm why react · yarn why react · bun pm ls
```

Next.js 15 and later run the App Router on React 19. Next.js 13 and 14 print
the React 18 wording.

## Find the cause, whatever the message

Each message is a symptom. The same few causes produce all of them: the clock,
the user's locale or timezone, `window` and `localStorage` read during render,
invalid HTML, CSS-in-JS class names, browser extensions and scripts that edit
the page first. [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes) has a fix
guide for each, and the [React hydration error guide](https://hydration.jscrate.dev/docs/guides/react-hydration-error)
explains the mechanism behind all of them.

To find every mismatch in an app at once, instead of one console message at a
time, load every route with hydration-proof:

```bash
npx hydration-proof test --mode both
```

It reports each difference with a stable [issue code](https://hydration.jscrate.dev/docs/issues), the
element, the server and client values, the source line and the likely cause.

## Related

- [What is hydration in React?](https://hydration.jscrate.dev/docs/guides/what-is-hydration)
- [How to debug a hydration error](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Hydration errors that only happen in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [Fix hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Get started with hydration-proof](https://hydration.jscrate.dev/docs/quick-start)

---

# Hydration failed because the server rendered HTML didn't match the client

> Hydration failed because the server rendered HTML didn't match the client: how to read React 19's diff, find the value that differs and fix each cause.

Source: https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client
Last updated: 2026-09-18

"Hydration failed because the server rendered HTML didn't match the client"
is the error React 19 throws when the first render in the browser produces
different elements or text than the HTML the server sent. React throws that
HTML away and renders the tree again on the client. The diff under the message
shows what to fix.

## The error

In development, React 19 prints the message, the causes it suspects, a link
and a diff of the first difference it found:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:

- A server/client branch `if (typeof window !== 'undefined')`.
- Variable input such as `Date.now()` or `Math.random()` which changes each time it's called.
- Date formatting in a user's locale which doesn't match the server.
- External changing data without sending a snapshot of it along with the HTML.
- Invalid HTML tag nesting.

It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.

https://react.dev/link/hydration-mismatch

  <Clock>
    <p>
+     12:04:33
-     12:04:31
```

Newer React 19 releases say "text" instead of "HTML" when only text differs:

```text
Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client.
```

A production build prints only a code, `Minified React error #418`, with no
diff. [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
explains how to get the full message back.

## Why hydration failed because the server rendered HTML didn't match the client

Hydration reuses the server's HTML instead of building the page again. React
renders your components in the browser once, walks the existing DOM alongside
that render, and attaches event handlers to the nodes it finds. That only works
when the two agree node for node.

When an element or a text node differs, React stops. "This tree will be
regenerated" means React discards the server HTML up to the nearest
`<Suspense>` boundary, or the whole page if there is none, and renders that
part again in the browser. The page still works, but:

- the server's work is wasted and the page renders twice,
- the content can flash while it is replaced,
- text a user typed and the focused element are lost.

This is the React 19 hydration error for elements and text. A React 19
hydration mismatch in an attribute (`className`, `style`, `href`) is
different: React keeps the page and only warns, with
["A tree hydrated but some attributes… didn't match"](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match).

The Next.js 15 "Hydration failed because the server rendered HTML didn't match
the client" overlay shows the same React message and diff: Next.js 15 runs the
App Router on React 19.

### How to read the diff

The diff is written like a code review, from the client's point of view:

- Lines starting with `+` are what the browser rendered.
- Lines starting with `-` are what the server HTML contained.
- Unmarked lines are the path from the component down to the difference.

A `+` and `-` pair on the same element is a changed value. A `+` line alone is
an element the server never sent, and a `-` line alone is one the browser did
not render. React stops at the first difference, so fix it and reload: there
may be more.

## Common causes

React's own list covers most cases. Each row links to the fix guide:

| Cause                                                                  | Typical diff                         | Fix guide                                                                                                  |
| ---------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| A `typeof window` check, `window` or `navigator` read during render    | `+ <canvas>` against `- <div>`       | [Browser-only APIs](https://hydration.jscrate.dev/docs/causes/browser-api)                                                              |
| `localStorage`, theme or screen size read during render                | A different element or class         | [Storage](https://hydration.jscrate.dev/docs/causes/storage), [theme](https://hydration.jscrate.dev/docs/causes/theme), [media queries](https://hydration.jscrate.dev/docs/causes/media-query)    |
| `Date.now()`, `new Date()` or relative times                           | `+ 12:04:33` against `- 12:04:31`    | [Time-dependent values](https://hydration.jscrate.dev/docs/causes/time)                                                                 |
| `Math.random()` or counters                                            | Two different ids or keys            | [Random values](https://hydration.jscrate.dev/docs/causes/random), [unstable ids](https://hydration.jscrate.dev/docs/causes/unstable-id)                             |
| Dates and numbers formatted in the user's locale or timezone           | `+ 18/09/2026` against `- 9/18/2026` | [Locale](https://hydration.jscrate.dev/docs/causes/locale), [timezone](https://hydration.jscrate.dev/docs/causes/timezone)                                           |
| Data fetched again in the browser                                      | Two different prices or lists        | [Server and client data](https://hydration.jscrate.dev/docs/causes/data)                                                                |
| Invalid HTML nesting, such as `<div>` in `<p>`                         | An element in an unexpected parent   | [Invalid HTML](https://hydration.jscrate.dev/docs/causes/invalid-html)                                                                  |
| A browser extension, a third-party script or a CDN that edits the HTML | Nodes nobody rendered                | [Extensions](https://hydration.jscrate.dev/docs/causes/extension), [scripts](https://hydration.jscrate.dev/docs/causes/third-party-script), [CDNs](https://hydration.jscrate.dev/docs/causes/cdn) |

## How to fix it

1. **Open the page in development and read the diff.** Find the first `+`
   and `-` pair and the component name above it.
2. **Find where the value comes from.** Match it against the table above:
   a time, a locale-formatted number, a value from `window` or storage.
3. **Make the first client render produce the server's output.** Either
   compute the value on the server and pass it down, or render a neutral value
   first and switch to the browser value after hydration:

   ```tsx title="components/greeting.tsx"
   "use client";

   // Before: the server renders "guest", the browser renders the stored name.
   export function Greeting() {
     const name =
       typeof window !== "undefined" ? localStorage.getItem("name") : null;
     return <p>Hello, {name ?? "guest"}</p>;
   }
   ```

   ```tsx title="components/greeting.tsx"
   "use client";

   import { useEffect, useState } from "react";

   // After: both renders say "guest", then the effect loads the stored name.
   export function Greeting() {
     const [name, setName] = useState<string | null>(null);

     useEffect(() => {
       setName(localStorage.getItem("name"));
     }, []);

     return <p>Hello, {name ?? "guest"}</p>;
   }
   ```

   [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
   explains the pattern. For a component that cannot render on the server at
   all, use a [client-only component](https://hydration.jscrate.dev/docs/guides/client-only-component).

4. **Reload and check the console again.** React reports one difference per
   boundary, so the next one appears once the first is fixed.
5. **Wrap slow or risky parts in `<Suspense>`.** It does not fix the
   mismatch, but React then re-renders only that boundary instead of the page.

`suppressHydrationWarning` hides a text or attribute difference on one element,
one level deep. It does not help when elements differ. See
[when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Find every instance

The console shows one mismatch per load, in the page you have open.
hydration-proof loads every route in a real browser and compares the server
HTML with the hydrated DOM:

```bash
npx hydration-proof test --mode both
```

It reports the exact difference as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) (text),
[HP1007](https://hydration.jscrate.dev/docs/issues/hp1007) (a different element),
[HP1008](https://hydration.jscrate.dev/docs/issues/hp1008) (an element only in the server HTML) or
[HP1009](https://hydration.jscrate.dev/docs/issues/hp1009) (an element missing from it), and what React did
about it as [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) (one branch rendered again) or
[HP1011](https://hydration.jscrate.dev/docs/issues/hp1011) (the whole page). When React reports the error
but the DOM comparison cannot place it, you get [HP2001](https://hydration.jscrate.dev/docs/issues/hp2001).
Each finding has the source line and the likely cause.

In the editor, the [ESLint plugin](https://hydration.jscrate.dev/docs/eslint) catches the code patterns
React lists: [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch),
[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render),
[`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render),
[`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale)
and [`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting).

## Related

- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418): the production form
- [The React 18 wording: "initial UI does not match"](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)
- [React hydration errors explained](https://hydration.jscrate.dev/docs/guides/react-hydration-error)
- [Find which component causes a hydration error](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)

---

# Hydration failed because the initial UI does not match what was rendered on the server

> Hydration failed because the initial UI does not match what was rendered on the server: React 18's error, the warning that names the element, and fixes.

Source: https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match
Last updated: 2026-09-18

"Hydration failed because the initial UI does not match what was rendered on
the server" is React 18's error for a structural mismatch: the first render in
the browser has a different element than the server's HTML. React discards
the HTML and renders the page again. The warning logged just before it names
the element to fix.

## The error

In development, React 18 logs a warning that names the element, then throws
the error, then reports that it switched to client rendering:

```text
Warning: Expected server HTML to contain a matching <div> in <div>.
Uncaught Error: Hydration failed because the initial UI does not match what was rendered on the server.
Uncaught Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

Next.js 13 and 14 add a link to the error:

```text
Error: Hydration failed because the initial UI does not match what was rendered on the server.
See more info here: https://nextjs.org/docs/messages/react-hydration-error
```

A production build prints the code instead:

```text
Minified React error #418; visit https://reactjs.org/docs/error-decoder.html?invariant=418 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

React 19 renamed it to
["Hydration failed because the server rendered HTML didn't match the client"](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)
and added a diff.

## What hydration failed because the initial UI does not match what was rendered on the server means

React 18 hydrates by walking the server HTML and your first client render side
by side. The React 18 "Hydration failed because the initial UI does not match"
error is thrown when it expects an element and finds a different one, or finds
nothing. Text is checked separately: a text difference throws
["Text content does not match server-rendered HTML"](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
instead.

After the error, React renders the nearest `<Suspense>` boundary, or the whole
root, again in the browser. That is the third line:
["There was an error while hydrating"](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating).
The page works, but it renders twice, can flash, and loses any input the user
typed before hydration.

The error itself never says which element. The warning above it does:

| Warning                                                               | Meaning                                                            |
| --------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `Expected server HTML to contain a matching <div> in <div>`           | The browser rendered a `<div>` the server HTML does not have there |
| `Did not expect server HTML to contain a <div> in <div>`              | The server HTML has a `<div>` the browser did not render           |
| `validateDOMNesting(...): <div> cannot appear as a descendant of <p>` | Invalid nesting that the browser rewrote before React ran          |

React 18 logs only the first mismatch per page load. If you fix one, reload:
the next one appears.

Next.js 13 and 14 print the React 18 wording, so in Next.js 13 "Hydration
failed because the initial UI does not match" is what any structural mismatch
looks like, in both routers. It is a common error: the Stack Overflow question
with this message as its title has about 690,000 views.

## Common causes

Anything that renders a different element in the browser than on the server:

- **Invalid HTML nesting.** A `<div>` inside a `<p>`, or a `<tr>` without
  `<tbody>`. The browser repairs the server HTML while parsing it, so React
  finds a different tree. See [invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html).
- **A `typeof window` branch.** `typeof window !== 'undefined' ? <A /> : <B />`
  renders `<B />` on the server and `<A />` in the browser. See
  [browser-only APIs](https://hydration.jscrate.dev/docs/causes/browser-api).
- **Screen size, theme or storage read during render.** A mobile menu chosen
  from `window.innerWidth`, a logged-in header chosen from `localStorage`. See
  [media queries](https://hydration.jscrate.dev/docs/causes/media-query), [theme](https://hydration.jscrate.dev/docs/causes/theme) and
  [storage](https://hydration.jscrate.dev/docs/causes/storage).
- **Different data.** The browser fetched the list again and got one more
  item. See [server and client data](https://hydration.jscrate.dev/docs/causes/data).
- **Something edited the HTML first.** A browser extension, a third-party
  script or a CDN that minifies HTML. See
  [browser extensions](https://hydration.jscrate.dev/docs/causes/extension),
  [third-party scripts](https://hydration.jscrate.dev/docs/causes/third-party-script) and
  [CDNs](https://hydration.jscrate.dev/docs/causes/cdn).

## How to fix it

1. **Run the app in development** and find the warning logged before the
   error. It names the element and its parent, and the component stack under
   it names your component.
2. **Decide why that element differs.** Use the causes above.
3. **Render the same element on both sides.** A layout that depends on the
   screen size is a common case. Before, the server always renders the desktop
   navigation:

   ```tsx title="components/nav.tsx"
   "use client";

   import { DesktopNav, MobileNav } from "./navs";

   export function Nav() {
     const isMobile = typeof window !== "undefined" && window.innerWidth < 768;
     return isMobile ? <MobileNav /> : <DesktopNav />;
   }
   ```

   After, both navigations are in the HTML and CSS picks one, so the server
   and the browser render the same elements:

   ```tsx title="components/nav.tsx"
   import { DesktopNav, MobileNav } from "./navs";

   export function Nav() {
     return (
       <>
         <div className="md:hidden">
           <MobileNav />
         </div>
         <div className="hidden md:block">
           <DesktopNav />
         </div>
       </>
     );
   }
   ```

   When the value must come from the browser, render a default first and read
   it in an effect: see
   [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering).

4. **Reload and check the console** for the next mismatch.
5. **Put unstable parts in a `<Suspense>` boundary.** React then re-renders
   only that boundary when hydration fails, not the whole root.

## Find every instance

hydration-proof loads every route, compares the server HTML with the hydrated
DOM and names the element, even in production builds where React only prints
#418:

```bash
npx hydration-proof test
```

Structural differences are [HP1007](https://hydration.jscrate.dev/docs/issues/hp1007) (a different
element), [HP1008](https://hydration.jscrate.dev/docs/issues/hp1008) (only in the server HTML) and
[HP1009](https://hydration.jscrate.dev/docs/issues/hp1009) (missing from it). Nesting the browser repaired
is [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001), and a page React rendered again is
[HP1011](https://hydration.jscrate.dev/docs/issues/hp1011). Add `--mode development` to get React's own
warnings attached.

The [ESLint plugin](https://hydration.jscrate.dev/docs/eslint) flags the usual sources while you type:
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch),
[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render),
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render) and
[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting).

## Related

- [Expected server HTML to contain a matching element](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching)
- [Minified React error #418 in production](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
- [Fix Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [How to debug hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Every React hydration error message](https://hydration.jscrate.dev/docs/errors)

---

# Text content does not match server-rendered HTML

> Text content does not match server-rendered HTML is React 18's error (#425) for text that differs between server and browser, usually a time, date or number.

Source: https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html
Last updated: 2026-09-18

"Text content does not match server-rendered HTML" is the error React 18
throws when a piece of text in the first browser render differs from the
server's HTML. It is usually a time, a formatted date or number, or a random
value. Render the same text on both sides, or set the changing value after
hydration.

## The error

In development, React 18 first warns with both values, then throws:

```text
Warning: Text content did not match. Server: "12:04:31" Client: "12:04:33"
Uncaught Error: Text content does not match server-rendered HTML.
Uncaught Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

A production build prints only the code:

```text
Minified React error #425; visit https://reactjs.org/docs/error-decoder.html?invariant=425 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

React 19 no longer has this message. A text difference throws the general
hydration error, #418, with the word "text":

```text
Hydration failed because the server rendered text didn't match the client.
```

See [the React 19 error](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)
for its diff.

## What it means

React 18 checks every text node while it hydrates. The warning names the text content that did not match, with the server value first and the client value second. React then gives up on the server HTML for that part of the page and renders it again in the browser, up to the nearest `<Suspense>` boundary or the whole root.

Two details make it harder to track down:

- React 18 logs the warning only for the first mismatch on a page. Fix it,
  reload, and the next one appears.
- The error itself carries no values. In production you get #425 and nothing
  else, so users' consoles do not tell you which text it was.

## Text content does not match server-rendered HTML (Next.js)

Next.js 13 and 14 use React 18, so they show this error in the dev overlay,
often next to "Hydration failed because the initial UI does not match…". The
causes are the same as in any React app. Two details are specific to Next.js:

- **Static pages keep the build's text.** A page pre-rendered at build time
  keeps that moment's date, and every visitor's browser renders a new one.
- **Server Components are not the problem.** Text a Server Component renders
  is never re-rendered in the browser. The mismatch is in a Client Component
  (`"use client"`), which renders on the server and again in the browser.

On Next.js 15 and later you get the React 19 wording instead.

## Common causes

| The text is                               | Why it differs                                                  | Fix guide                                                  |
| ----------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
| A time or "3 minutes ago"                 | The clock moves between the two renders                         | [Time-dependent values](https://hydration.jscrate.dev/docs/causes/time)                 |
| A date or time of day                     | The server formats in UTC, the browser in the user's timezone   | [Timezone](https://hydration.jscrate.dev/docs/causes/timezone)                          |
| A number, price or date format            | `toLocaleString()` uses the server's locale, then the browser's | [Locale](https://hydration.jscrate.dev/docs/causes/locale)                              |
| An id, a shuffled item, a random greeting | `Math.random()` returns a new value                             | [Random values](https://hydration.jscrate.dev/docs/causes/random)                       |
| A name, count or cart total               | Read from `localStorage` or fetched again                       | [Storage](https://hydration.jscrate.dev/docs/causes/storage), [data](https://hydration.jscrate.dev/docs/causes/data) |
| Translated or corrected text              | A browser extension edited it                                   | [Browser extensions](https://hydration.jscrate.dev/docs/causes/extension)               |

## How to fix it

1. **Find the text.** The warning shows both values. In production, run the
   app in development, or use hydration-proof (below).
2. **Pass the value from the server** when both sides can use the same one.
   Before, each render reads its own clock and its own timezone:

   ```tsx title="components/last-updated.tsx"
   "use client";

   export function LastUpdated() {
     return <p>Updated at {new Date().toLocaleTimeString()}</p>;
   }
   ```

   After, the server's timestamp arrives as a prop, and the format names its
   locale and timezone:

   ```tsx title="components/last-updated.tsx"
   "use client";

   export function LastUpdated({ updatedAt }: { updatedAt: number }) {
     const time = new Date(updatedAt).toLocaleTimeString("en-US", {
       timeZone: "UTC",
     });
     return <p>Updated at {time}</p>;
   }
   ```

3. **Set live values after hydration.** A ticking clock or a value only the
   browser knows starts from a placeholder and is filled in by an effect.
   [Render the time after hydration](https://hydration.jscrate.dev/docs/causes/time#render-the-time-after-hydration)
   shows the pattern.
4. **Suppress only what is meant to differ.** For a timestamp whose first
   value does not matter, `suppressHydrationWarning` on that one element keeps
   the server text without an error. Read
   [when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
   first.

## Find every instance

hydration-proof compares the text of every element on every route and
reports each difference as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001), with both values,
the component and the likely cause:

```bash
npx hydration-proof test --probe
```

```text
  ✖ /blog 912ms  1 error
    HP1001 Text differs between server and client  (time-dependent value, 97%)
      p  in LastUpdated
      server: "Updated at 12:04:31"
      client: "Updated at 12:04:33"
      components/last-updated.tsx:4:10
      → Pass the timestamp the server used as a prop, or render the time after mount (useEffect).
```

`--probe` reloads the page with one thing changed at a time (the clock, the
locale, the timezone) to prove the cause. See [probes](https://hydration.jscrate.dev/docs/probes).

The ESLint rules catch the source in the editor:
[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render),
[`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render),
[`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale)
and [`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone).

## Related

- [Minified React error #425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425)
- [Fix date and time hydration errors](https://hydration.jscrate.dev/docs/causes/time)
- [toLocaleString and locale mismatches](https://hydration.jscrate.dev/docs/causes/locale)
- [HP1001: text differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1001)
- [All React hydration error messages](https://hydration.jscrate.dev/docs/errors)

---

# A tree hydrated but some attributes of the server rendered HTML didn't match

> A tree hydrated but some attributes of the server rendered HTML didn't match: React 19 kept the page but not the attribute. Why, and how to fix it for good.

Source: https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match
Last updated: 2026-09-18

"A tree hydrated but some attributes of the server rendered HTML didn't match
the client properties" is a React 19 development warning. Hydration worked,
but an attribute such as `className`, `style`, `href` or `id` differs, and
React keeps the server's value. Users see the wrong attribute until that prop
changes. Make the attribute identical in both renders.

## The error

React 19 logs it in development, with a diff of every attribute that differs:

```text
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up. This can happen if a SSR-ed Client Component used:

- A server/client branch `if (typeof window !== 'undefined')`.
- Variable input such as `Date.now()` or `Math.random()` which changes each time it's called.
- Date formatting in a user's locale which doesn't match the server.
- External changing data without sending a snapshot of it along with the HTML.
- Invalid HTML tag nesting.

It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.

https://react.dev/link/hydration-mismatch

  <Sidebar>
    <aside
+     className="sidebar wide"
-     className="sidebar"
    >
```

There is no production form and no minified code: production builds of
React 19 do not compare attributes at all.

In React 18 the same problem produced one warning per attribute, such as
[`Prop className did not match`](https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match)
and [`Extra attributes from the server`](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server).

## Why a tree hydrated but some attributes of the server rendered HTML didn't match

For attributes, React does not throw the page away as it does for text and
elements. It attaches to the server's DOM and leaves the attribute as the
server wrote it: that is what "this won't be patched up" means.

Later renders do not repair it either. React compares each new render with its
own previous props, not with the DOM, so the DOM keeps the server's value
until the prop itself changes. A `className` computed from the screen width
stays wrong for as long as the width stays the same.

Read the diff like this:

- `+` and `-` on the same attribute: the value differs.
- A `-` line alone: the attribute is only in the server HTML. Often a script
  or a browser extension added it before React loaded.
- A `+` line alone: the browser render has an attribute the server did not
  send.

> **Production is silent**
>
> React 19 checks attributes only in development. The same mismatch in
> production logs nothing, and your users keep the wrong value. Test the
> production build with a tool that compares attributes itself (see below).

## Common causes

| Attribute                              | Usual source                                           | Fix guide                                                |
| -------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------- |
| `class` or `style` on `<html>`         | A theme script sets dark mode before React loads       | [Theme](https://hydration.jscrate.dev/docs/causes/theme)                              |
| `className` on components              | CSS-in-JS class names generated in a different order   | [CSS-in-JS](https://hydration.jscrate.dev/docs/causes/css-in-js)                      |
| `className` from the screen size       | `window.innerWidth` or `matchMedia` read during render | [Media queries](https://hydration.jscrate.dev/docs/causes/media-query)                |
| `id`, `htmlFor`, `aria-*`              | Ids from `Math.random()` or a counter                  | [Unstable ids](https://hydration.jscrate.dev/docs/causes/unstable-id)                 |
| `datetime`, `title`, `aria-label`      | A formatted time or date                               | [Time](https://hydration.jscrate.dev/docs/causes/time), [locale](https://hydration.jscrate.dev/docs/causes/locale) |
| Attributes on `<body>` nobody rendered | A browser extension                                    | [Browser extensions](https://hydration.jscrate.dev/docs/causes/extension)             |

## How to fix it

1. **Read the attribute name and both values** in the diff, and the component
   above it.
2. **Compute the attribute from data both sides have.** Before, the class
   depends on the window, which the server does not have:

   ```tsx title="components/sidebar.tsx"
   "use client";

   export function Sidebar() {
     const wide = typeof window !== "undefined" && window.innerWidth > 1024;
     return <aside className={wide ? "sidebar wide" : "sidebar"} />;
   }
   ```

   After, both renders use the default and an effect updates it. Because this
   is a state change, React applies it to the DOM:

   ```tsx title="components/sidebar.tsx"
   "use client";

   import { useEffect, useState } from "react";

   export function Sidebar() {
     const [wide, setWide] = useState(false);

     useEffect(() => {
       const update = () => setWide(window.innerWidth > 1024);
       update();
       window.addEventListener("resize", update);
       return () => window.removeEventListener("resize", update);
     }, []);

     return <aside className={wide ? "sidebar wide" : "sidebar"} />;
   }
   ```

   For layout alone, a CSS media query avoids the second render entirely.

3. **For ids, use `useId()`.** It produces the same id on the server and in
   the browser.
4. **For attributes a pre-hydration script sets on purpose** (a theme class on
   `<html>`), add `suppressHydrationWarning` to that one element. It covers the
   element's own attributes only. See
   [suppressHydrationWarning](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Find every instance

hydration-proof compares every attribute in the page with the props React
rendered, in development and in production, where React itself stays silent:

```bash
npx hydration-proof test --mode both
```

Differences are reported as [HP1002](https://hydration.jscrate.dev/docs/issues/hp1002) (an attribute),
[HP1003](https://hydration.jscrate.dev/docs/issues/hp1003) (inline style),
[HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) (class), [HP1005](https://hydration.jscrate.dev/docs/issues/hp1005) (only
in the server HTML) and [HP1006](https://hydration.jscrate.dev/docs/issues/hp1006) (missing from it).

In the editor:
[`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render),
[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render),
[`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) and
[`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state)
report the code that produces these attributes.

## Related

- [Hydration failed: the React 19 error for text and elements](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)
- [Fix the next-themes hydration warning](https://hydration.jscrate.dev/docs/causes/theme)
- [CSS-in-JS class name mismatches](https://hydration.jscrate.dev/docs/causes/css-in-js)
- [HP1002: attribute differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1002)
- [Errors that only show up in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)

---

# Prop className did not match

> Prop className did not match: React 18 found a different class in the server HTML, usually from styled-components, Emotion, MUI or a theme. How to fix it.

Source: https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match
Last updated: 2026-09-18

Prop className did not match is a React 18 development warning: an element's
`class` in the server HTML differs from the `className` React computed in the
browser. It usually comes from a CSS-in-JS library that generated class names
in a different order, or from a theme or screen size read during render. React
keeps the server's class.

## The error

React 18 prints the prop name and both values, then a component stack:

```text
Warning: Prop `className` did not match. Server: "sc-abc" Client: "sc-xyz"
```

The same warning exists for every prop. These are the ones you see most:

```text
Warning: Prop `className` did not match. Server: "MuiBox-root css-1rs9h4" Client: "MuiBox-root css-8kq2d1"
Warning: Prop `id` did not match. Server: "react-select-2-live-region" Client: "react-select-3-live-region"
Warning: Prop `style` did not match. Server: "color:black" Client: "color:white"
Warning: Prop `dangerouslySetInnerHTML` did not match. Server: "<b>Hi</b>" Client: "<b>Hello</b>"
```

Production builds do not check props, so there is no minified code. In React
19 the warning is replaced by a diff line in
["A tree hydrated but some attributes… didn't match"](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match).

## What prop className did not match means

React 18 hydrates an element by comparing each prop of your first client
render with the attribute in the server HTML. When they differ, it warns and
moves on. It does not update the attribute, so the element keeps the server's
class, and the styles written for the client's class name do not apply. The
component looks unstyled or wrongly styled until it re-renders with a
different class.

React 18 warns only once per page load, for the first difference it finds.
Fixing one can reveal the next.

## Common causes

- **styled-components without server rendering set up.** Class names such as
  `sc-abc` come from a component id and a hash of the styles. Without the
  compiler plugin, the ids depend on the order components were created, which
  differs between the server and the browser. See
  [CSS-in-JS class names](https://hydration.jscrate.dev/docs/causes/css-in-js).
- **Emotion or MUI without the cache provider.** `css-` hashes are inserted in
  a different order on each side. MUI's Next.js integration,
  `@mui/material-nextjs`, provides the `AppRouterCacheProvider` for this.
- **Styled components created inside render.** Every render creates a new
  component with a new id.
- **Theme classes.** A `dark` class chosen from `localStorage` or
  `matchMedia` during render. See [theme hydration errors](https://hydration.jscrate.dev/docs/causes/theme).
- **Screen size.** A class chosen from `window.innerWidth`. See
  [media queries](https://hydration.jscrate.dev/docs/causes/media-query).
- **Ids from counters or `Math.random()`**, including libraries that count
  instances, such as react-select. See [unstable ids](https://hydration.jscrate.dev/docs/causes/unstable-id).
- **`dangerouslySetInnerHTML` built from values that differ,** such as a date
  or a user's locale.

## How to fix it

1. **Set up your CSS-in-JS library for server rendering.** For
   styled-components in Next.js, turn on the compiler support, then add the
   style registry described in [CSS-in-JS](https://hydration.jscrate.dev/docs/causes/css-in-js):

   ```ts title="next.config.ts"
   import type { NextConfig } from "next";

   const nextConfig: NextConfig = {
     compiler: {
       styledComponents: true,
     },
   };

   export default nextConfig;
   ```

2. **Define styled components once, at module level.** Before, a new
   component is created on every render:

   ```tsx title="components/badge.tsx"
   "use client";

   import styled from "styled-components";

   export function Badge({ tone }: { tone: string }) {
     const Pill = styled.span`
       color: ${tone};
     `;
     return <Pill>New</Pill>;
   }
   ```

   After, the component is created once and the value is passed as a prop:

   ```tsx title="components/badge.tsx"
   "use client";

   import styled from "styled-components";

   const Pill = styled.span<{ $tone: string }>`
     color: ${(props) => props.$tone};
   `;

   export function Badge({ tone }: { tone: string }) {
     return <Pill $tone={tone}>New</Pill>;
   }
   ```

3. **Generate ids with `useId()`.** For react-select, pass a stable
   `instanceId`:

   ```tsx title="components/country-select.tsx"
   "use client";

   import { useId } from "react";
   import Select from "react-select";

   export function CountrySelect() {
     return <Select instanceId={useId()} options={[]} />;
   }
   ```

4. **Move theme and screen size classes out of render.** Read them on the
   server (a cookie) or after hydration, or use CSS media queries.

## Find every instance

hydration-proof compares each attribute with the props React rendered and
reports class differences as [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004), other attributes
as [HP1002](https://hydration.jscrate.dev/docs/issues/hp1002), inline styles as
[HP1003](https://hydration.jscrate.dev/docs/issues/hp1003) and injected HTML as
[HP1013](https://hydration.jscrate.dev/docs/issues/hp1013). For elements a library created, it points at
the component that used the library:

```bash
npx hydration-proof test
```

No linter can see CSS-in-JS class generation, but the
[ESLint plugin](https://hydration.jscrate.dev/docs/eslint) catches the other sources:
[`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id),
[`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render),
[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) and
[`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render).

## Related

- [Fix styled-components hydration errors](https://hydration.jscrate.dev/docs/causes/css-in-js)
- [useId and generated id mismatches](https://hydration.jscrate.dev/docs/causes/unstable-id)
- [The React 19 attribute warning](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)
- [HP1004: class name differs](https://hydration.jscrate.dev/docs/issues/hp1004)
- [Extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server)

---

# Expected server HTML to contain a matching element

> Expected server HTML to contain a matching div in div: React 18 rendered an element in the browser that the server HTML lacks. Each variant and its fix.

Source: https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching
Last updated: 2026-09-18

Expected server HTML to contain a matching `<div>` in `<div>` is a React 18
development warning: the first browser render has an element that the server's
HTML does not have. "Did not expect server HTML to contain"
is the reverse. Something renders on one side only, or the browser moved
invalid markup. Render the same elements on both sides.

## The error

The two forms, as React 18 prints them:

```text
Warning: Expected server HTML to contain a matching <div> in <div>.
Warning: Did not expect server HTML to contain a <div> in <div>.
```

The tags change with your markup. These are the variants people see most:

```text
Warning: Expected server HTML to contain a matching <div> in <body>.
Warning: Expected server HTML to contain a matching <tr> in <table>.
Warning: Expected server HTML to contain a matching <table> in <div>.
Warning: Expected server HTML to contain a matching <meta> in <head>.
Warning: Expected server HTML to contain a matching text node for "Loading…" in <div>.
Warning: Did not expect server HTML to contain the text node "Loading…" in <div>.
```

Right after the warning, React 18 throws
["Hydration failed because the initial UI does not match what was rendered on the server"](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match),
or #418 in production. React 19 shows the same thing as a `+` line (only in
the browser) or a `-` line (only on the server) in the diff of
[its hydration error](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client).

## What expected server HTML to contain a matching element means

Read the warning as "child in parent":

| Warning                                                 | The first tag is           | Meaning                                                        |
| ------------------------------------------------------- | -------------------------- | -------------------------------------------------------------- |
| `Expected server HTML to contain a matching <X> in <Y>` | In the browser render only | The server did not render `<X>` there, or the browser moved it |
| `Did not expect server HTML to contain a <X> in <Y>`    | In the server HTML only    | The browser render has nothing there, or something else        |

The component stack printed under the warning names the component that
renders the parent. React 18 logs only the first difference per page, then
renders the page again in the browser.

## Common causes

### An element rendered on one side only

A `typeof window` check, a value from `localStorage`, a "mounted" flag read
during render or a feature flag the browser reads again: the server renders
nothing (or a placeholder) and the browser renders the element. See
[browser-only APIs](https://hydration.jscrate.dev/docs/causes/browser-api) and
[storage](https://hydration.jscrate.dev/docs/causes/storage).

### A table without `<tbody>`

The `<tr>` in `<table>` variant is almost always this. The HTML parser adds a
`<tbody>` around rows it finds directly in a `<table>`, so React finds a
`<tbody>` where it expected your `<tr>`. See
[validateDOMNesting](https://hydration.jscrate.dev/docs/errors/validatedomnesting).

### Invalid nesting the browser repaired

A `<div>`, `<table>` or list inside a `<p>` is moved out of the `<p>` while
the page is parsed. React then expects the element inside the paragraph and
does not find it. See
[div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p).

### Something else changed the page first

For `<div>` in `<body>`, a browser extension or a third-party script (chat
widgets, consent banners) often inserted or removed elements before React
loaded. For `<meta>` in `<head>`, check tags rendered from browser-only values
and scripts that add their own tags. See
[browser extensions](https://hydration.jscrate.dev/docs/causes/extension) and
[third-party scripts](https://hydration.jscrate.dev/docs/causes/third-party-script).

## How to fix it

1. **Match the tags to your code.** The warning names the child and the
   parent. The component stack names the component.
2. **Wrap table rows in `<tbody>`.** Before:

   ```tsx title="components/prices.tsx"
   type Row = { id: string; name: string; price: string };

   export function Prices({ rows }: { rows: Row[] }) {
     return (
       <table>
         {rows.map((row) => (
           <tr key={row.id}>
             <td>{row.name}</td>
             <td>{row.price}</td>
           </tr>
         ))}
       </table>
     );
   }
   ```

   After:

   ```tsx title="components/prices.tsx"
   type Row = { id: string; name: string; price: string };

   export function Prices({ rows }: { rows: Row[] }) {
     return (
       <table>
         <tbody>
           {rows.map((row) => (
             <tr key={row.id}>
               <td>{row.name}</td>
               <td>{row.price}</td>
             </tr>
           ))}
         </tbody>
       </table>
     );
   }
   ```

3. **Render browser-only elements after hydration.** Before, the banner
   exists only in the browser render:

   ```tsx title="components/cookie-banner.tsx"
   "use client";

   export function CookieBanner() {
     if (typeof window === "undefined") return null;
     if (localStorage.getItem("consent")) return null;
     return <div className="banner">We use cookies.</div>;
   }
   ```

   After, both renders start with nothing, and an effect shows it:

   ```tsx title="components/cookie-banner.tsx"
   "use client";

   import { useEffect, useState } from "react";

   export function CookieBanner() {
     const [show, setShow] = useState(false);

     useEffect(() => {
       setShow(!localStorage.getItem("consent"));
     }, []);

     if (!show) return null;
     return <div className="banner">We use cookies.</div>;
   }
   ```

4. **Test in a clean browser profile** when the parent is `<body>` or
   `<head>`. If the warning disappears, an extension caused it.

## Find every instance

hydration-proof reports an element only the browser rendered as
[HP1009](https://hydration.jscrate.dev/docs/issues/hp1009), one only in the server HTML as
[HP1008](https://hydration.jscrate.dev/docs/issues/hp1008) and a different element in the same place as
[HP1007](https://hydration.jscrate.dev/docs/issues/hp1007). A missing `<tbody>` and other repaired markup
is [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001), and `<head>` differences are
[HP1014](https://hydration.jscrate.dev/docs/issues/hp1014):

```bash
npx hydration-proof test
```

[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
reports `<tr>` directly in `<table>` and block elements in `<p>`, and
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) and
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
report the one-sided renders.

## Related

- [Hydration failed: initial UI does not match](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)
- [Invalid HTML nesting and hydration](https://hydration.jscrate.dev/docs/causes/invalid-html)
- [Render a component only in the browser](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [HP1009: element missing from the server HTML](https://hydration.jscrate.dev/docs/issues/hp1009)
- [All hydration error messages](https://hydration.jscrate.dev/docs/errors)

---

# Extra attributes from the server

> Warning: Extra attributes from the server means the page had attributes React did not render, often class and style from next-themes or a browser extension.

Source: https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server
Last updated: 2026-09-18

"Extra attributes from the server" is a React 18 development warning: an
element has attributes that React's first client render does not produce.
Usually something changed the HTML before React loaded: a theme script that
adds `class` and `style` to `<html>`, or a browser extension that marks
`<body>`. It is a warning, not a failed hydration.

## The error

React 18 lists the attribute names, separated by commas:

```text
Warning: Extra attributes from the server: class,style
Warning: Extra attributes from the server: style
Warning: Extra attributes from the server: cz-shortcut-listen
Warning: Extra attributes from the server: data-new-gr-c-s-check-loaded,data-gr-ext-installed
```

The component stack under it ends at the element, often `at body` or
`at html`. Production builds do not check attributes, so there is no minified
code.

React 19 dropped the separate warning. The same attributes appear as `-`
lines in the diff of
["A tree hydrated but some attributes… didn't match"](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match),
for example `- cz-shortcut-listen="true"`.

## What extra attributes from the server means

React 18 compares the attributes of each hydrated element with the props you
rendered. Attributes that exist in the page but not in your props are "extra".
React does not remove them and does not render the page again: it logs the
warning once and continues.

The name is misleading. "From the server" means "in the DOM React found",
which includes anything a script or an extension added after the HTML
arrived. Your server often never sent these attributes.

## Common causes

| Attribute                                               | Added by                                               | What to do                                                                            |
| ------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `class`, `style` on `<html>`                            | next-themes or your own theme script, before hydration | Add `suppressHydrationWarning` to `<html>`. See [theme](https://hydration.jscrate.dev/docs/causes/theme)           |
| `cz-shortcut-listen` on `<body>`                        | The ColorZilla extension                               | Nothing in your code. See [extensions](https://hydration.jscrate.dev/docs/causes/extension)                        |
| `data-new-gr-c-s-check-loaded`, `data-gr-ext-installed` | Grammarly                                              | Nothing in your code                                                                  |
| Other `data-*` or `style`                               | A/B testing, analytics or chat scripts                 | Load them after hydration. See [third-party scripts](https://hydration.jscrate.dev/docs/causes/third-party-script) |
| Attributes on many elements                             | A CDN or proxy rewriting HTML                          | Turn the rewriting off. See [CDNs](https://hydration.jscrate.dev/docs/causes/cdn)                                  |

Extensions are a known problem with no fix on React's side yet: React issue
[#24430](https://github.com/facebook/react/issues/24430) about them is still
open.

## How to fix it

1. **Read the attribute names** and decide who added them, using the table.
2. **Test in a private window or a clean browser profile.** If the warning
   disappears, an extension added the attribute. Your users will see it too,
   but nothing is broken.
3. **For a theme script, mark `<html>` as expected to differ.** next-themes
   sets `class` and `style` on `<html>` before React loads, on purpose, to
   avoid a flash of the wrong theme:

   ```tsx title="app/layout.tsx"
   import { ThemeProvider } from "next-themes";
   import type { ReactNode } from "react";

   export default function RootLayout({ children }: { children: ReactNode }) {
     return (
       <html lang="en" suppressHydrationWarning>
         <body>
           <ThemeProvider attribute="class">{children}</ThemeProvider>
         </body>
       </html>
     );
   }
   ```

   `suppressHydrationWarning` covers only the element's own attributes and
   text, one level deep, so mismatches inside the page are still reported.

4. **For extensions on `<body>`,** you can add `suppressHydrationWarning` to
   `<body>` to silence them in development. It hides your own `<body>`
   attribute differences too, so keep it off `<body>` if you set attributes
   there. See [when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).
5. **For scripts,** load them after hydration so they change the page once
   React owns it.

## Find every instance

hydration-proof reports an attribute that only the page has as
[HP1005](https://hydration.jscrate.dev/docs/issues/hp1005). When it can tell that a script or extension
added it before hydration, it reports [HP4001](https://hydration.jscrate.dev/docs/issues/hp4001) or
[HP4002](https://hydration.jscrate.dev/docs/issues/hp4002) instead:

```bash
npx hydration-proof test
```

The test browser runs without extensions. If you simulate one, or if your
own scripts add attributes on purpose, skip those attributes in the config:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    attributes: ["cz-shortcut-listen", /^data-gr-/],
  },
});
```

[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
reviews every `suppressHydrationWarning` you add, so none of them hides more
than intended. [Ignoring findings](https://hydration.jscrate.dev/docs/ignoring) covers the other options.

## Related

- [Browser extensions that cause hydration errors](https://hydration.jscrate.dev/docs/causes/extension)
- [The next-themes hydration warning](https://hydration.jscrate.dev/docs/causes/theme)
- [Prop className did not match](https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match)
- [suppressHydrationWarning explained](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [HP1005: attribute only present in the server HTML](https://hydration.jscrate.dev/docs/issues/hp1005)

---

# There was an error while hydrating

> There was an error while hydrating means React gave up on the server HTML after an earlier error and rendered a Suspense boundary or the whole page again.

Source: https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating
Last updated: 2026-09-18

"There was an error while hydrating" is a follow-up, not the bug itself: React
logs it after another error during hydration, to say it discarded the server
HTML and rendered that part in the browser instead. Error #423 means the whole
page; #422 means one Suspense boundary. Fix the error logged before it.

## The error

React 18, when the failure is outside any `<Suspense>` boundary (#423):

```text
Uncaught Error: There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

React 18, inside a boundary (#422):

```text
Uncaught Error: There was an error while hydrating this Suspense boundary. Switched to client rendering.
```

React 18 also logs this warning in development when the whole root falls
back. The tag is your root container: `<div>` for a `#root` or `#__next`
element, `<#document>` when React hydrates the whole document:

```text
Warning: An error occurred during hydration. The server HTML was replaced with client content in <div>.
```

React 19 reworded both:

```text
There was an error while hydrating but React was able to recover by instead client rendering the entire root.
There was an error while hydrating but React was able to recover by instead client rendering from the nearest Suspense boundary.
```

Production builds print `Minified React error #423` or `#422`. See
[minified React error #423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423).

## What there was an error while hydrating means

Hydration failed somewhere, and React recovered by rendering part of the page
from scratch in the browser. Which part depends on where the failure was:

| Where it failed                | React 18 | React 19 | What React renders again        |
| ------------------------------ | -------- | -------- | ------------------------------- |
| Outside any `<Suspense>`       | #423     | #423     | The whole root: the entire page |
| Inside a `<Suspense>` boundary | #422     | #422     | Only that boundary              |

The page keeps working, which is why this is a recoverable error. But the
server's work is thrown away, the content may flash, and anything a user typed
before hydration is lost.

The cause differs by version:

- **React 18** logs it after every hydration mismatch, following
  ["Hydration failed because the initial UI does not match"](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)
  (#418) or
  ["Text content does not match server-rendered HTML"](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
  (#425). Fix that first error.
- **React 19** logs a mismatch as #418 only. It logs #422 or #423 when a
  component threw an exception while hydrating. The original exception is the
  error's `cause`: expand it in the console.

## Common causes

- **A hydration mismatch** (React 18): a time, a locale-formatted value, a
  `typeof window` branch, invalid nesting. See
  [common causes of hydration errors](https://hydration.jscrate.dev/docs/causes).
- **A component that throws only in the browser**: it reads a property of
  data that the browser does not have yet, or calls an API that fails there.
  See [server and client data](https://hydration.jscrate.dev/docs/causes/data).
- **`useSyncExternalStore` without a server snapshot**, which throws
  ["Missing getServerSnapshot"](https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot).

A boundary that React 18 rendered again because it received an update too
early has its own message:
[Suspense boundary received an update before hydrating](https://hydration.jscrate.dev/docs/errors/suspense-boundary-received-update-before-hydrating)
(#421).

## How to fix it

1. **Scroll up to the first error.** In React 18, it is the warning and the
   error logged just before this one. In React 19, expand `cause`.
2. **Fix that error** using its page in
   [the list of hydration error messages](https://hydration.jscrate.dev/docs/errors).
3. **Add `<Suspense>` boundaries around independent parts of the page.** A
   failure then costs one boundary (#422) instead of the whole root (#423):

   ```tsx title="app/dashboard/page.tsx"
   import { Suspense } from "react";

   import { ActivityFeed } from "./activity-feed";
   import { Stats } from "./stats";

   export default function Dashboard() {
     return (
       <main>
         <Stats />
         <Suspense fallback={<p>Loading activity…</p>}>
           <ActivityFeed />
         </Suspense>
       </main>
     );
   }
   ```

   A boundary limits the damage. It does not fix the mismatch inside it.

## Find every instance

hydration-proof reports a boundary React rendered again as
[HP2003](https://hydration.jscrate.dev/docs/issues/hp2003) and a root as [HP2004](https://hydration.jscrate.dev/docs/issues/hp2004),
with React's error attached, and the mismatch that started it (for example
[HP1001](https://hydration.jscrate.dev/docs/issues/hp1001)) as its own finding with the source line:

```bash
npx hydration-proof test --mode both
```

A page rendered again from scratch is also reported as
[HP1011](https://hydration.jscrate.dev/docs/issues/hp1011), and a single branch as
[HP1010](https://hydration.jscrate.dev/docs/issues/hp1010). The [ESLint rules](https://hydration.jscrate.dev/docs/rules) catch most of
the mismatches that start the chain.

## Related

- [Minified React error #423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423)
- [Hydration failed because the initial UI does not match](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)
- [HP2004: the root switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2004)
- [All minified React hydration codes](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)

---

# In HTML, div cannot be a descendant of p

> In HTML, div cannot be a descendant of p: the browser closes the paragraph before the div, so hydration fails. Why, and how to fix it in your code or MUI.

Source: https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p
Last updated: 2026-09-18

In HTML, `<div>` cannot be a descendant of `<p>`: a paragraph may only
contain text-level elements. When the server sends a `<div>` inside a `<p>`,
the browser closes the paragraph before the `<div>`, so the DOM no longer
matches what React rendered and hydration fails. Use a `<span>` inside, or
make the outer element a `<div>`.

## The error

React 19 logs this in development:

```text
In HTML, <div> cannot be a descendant of <p>.
This will cause a hydration error.
```

Under it, React prints the component tree from the `<p>` down to the `<div>`,
with both lines marked `>`. When the two elements are in different components,
it logs a second message, `<p> cannot contain a nested <div>.`, whose stack
points at the component that renders the `<p>`.

React 18 logs it as a `validateDOMNesting` warning with a component stack:

```text
Warning: validateDOMNesting(...): <div> cannot appear as a descendant of <p>.
    at div
    at p
    at Card (webpack-internal:///./components/card.tsx:9:11)
```

The same message appears for every block element inside a paragraph:

```text
In HTML, <p> cannot be a descendant of <p>.
In HTML, <ul> cannot be a descendant of <p>.
In HTML, <ol> cannot be a descendant of <p>.
In HTML, <pre> cannot be a descendant of <p>.
In HTML, <table> cannot be a descendant of <p>.
In HTML, <h2> cannot be a descendant of <p>.
```

These are development warnings, with no production form. What you get in
production is the hydration error that follows: #418.

## Why div cannot be a descendant of p

A `<p>` element can only hold phrasing content: text, `<span>`, `<a>`,
`<strong>`, `<img>` and similar. When the HTML parser meets the start of a
block element, such as `<div>`, `<p>`, `<ul>`, `<ol>`, `<pre>`, `<table>` or a
heading, while a paragraph is open, it closes the paragraph first. The `</p>`
that comes later has nothing to close, so the parser adds an empty paragraph:

```text
server HTML:  <p>Intro<div>Details</div></p>
browser DOM:  <p>Intro</p><div>Details</div><p></p>
```

React then hydrates this DOM, expects the `<div>` inside the `<p>`, and does
not find it. React 19 throws
["Hydration failed because the server rendered HTML didn't match the client"](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client),
and React 18 throws
["Hydration failed because the initial UI does not match…"](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match).
Either way the page is rendered again in the browser.

Pages rendered only in the browser do not break, because DOM methods do not
repair nesting the way the parser does. That is why the warning says it "will
cause a hydration error": server rendering is what exposes it.

## Common causes

- **A `<div>` or a list written inside a `<p>`** in your own JSX.
- **A component that renders a block element, used inside a paragraph.**
  `<p><Card /></p>` looks fine until `Card` renders a `<div>`.
- **Component libraries whose text component is a `<p>`.** MUI's
  `<Typography>` renders a `<p>` for body text by default, and Chakra's
  `<Text>` does too. A `<Box>` (a `<div>`) or another `<Typography>` inside it
  is a `<div>` or `<p>` in a `<p>`.
- **Markdown renderers.** They wrap images in a `<p>`. A custom image
  component that renders a `<figure>` or a `<div>` ends up inside it.
- **HTML from a CMS** injected with `dangerouslySetInnerHTML` into a `<p>`.
  React cannot warn about it, but the browser splits it the same way.

See [invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html) for the other rules the
parser enforces.

## How to fix it

1. **Find the paragraph.** In React 18, the `validateDOMNesting(...): <div> cannot appear as a descendant of <p>` warning names no file in the error itself, so read its component stack from the top: the first component listed renders the `<div>`, and the first one after `at p` renders the paragraph.
2. **Change one of the two elements.** Use a `<span>` (styled as a block if
   needed) inside, or a `<div>` outside. Before:

   ```tsx title="components/card.tsx"
   import type { ReactNode } from "react";

   export function Card({
     title,
     children,
   }: {
     title: string;
     children: ReactNode;
   }) {
     return (
       <p className="card">
         <strong>{title}</strong>
         <div className="card-body">{children}</div>
       </p>
     );
   }
   ```

   After:

   ```tsx title="components/card.tsx"
   import type { ReactNode } from "react";

   export function Card({
     title,
     children,
   }: {
     title: string;
     children: ReactNode;
   }) {
     return (
       <div className="card">
         <p>
           <strong>{title}</strong>
         </p>
         <div className="card-body">{children}</div>
       </div>
     );
   }
   ```

3. **In MUI, change what `Typography` renders.** Its `component` prop picks
   the element:

   ```tsx title="components/total.tsx"
   import Box from "@mui/material/Box";
   import Typography from "@mui/material/Typography";

   export function Total() {
     return (
       <Typography component="div">
         <Box sx={{ display: "flex", gap: 1 }}>
           <span>Total</span>
           <strong>$42</strong>
         </Box>
       </Typography>
     );
   }
   ```

4. **In Markdown renderers,** render images with inline elements only, or
   render paragraphs as `<div>`.

## Find every instance

A linter only sees nesting inside one component. hydration-proof reads the
real server HTML, so it also finds `<p><Card /></p>` across components and
HTML from a CMS. It reports each case as [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001), with
the line in the server HTML:

```bash
npx hydration-proof test
```

[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
reports every element that closes an open `<p>`, including in Server
Components, while you type.

## Related

- [validateDOMNesting: tables, links and buttons](https://hydration.jscrate.dev/docs/errors/validatedomnesting)
- [Invalid HTML nesting and hydration errors](https://hydration.jscrate.dev/docs/causes/invalid-html)
- [HP3001: invalid HTML nesting](https://hydration.jscrate.dev/docs/issues/hp3001)
- [The no-invalid-interactive-nesting rule](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
- [eslint-plugin-validate-jsx-nesting compared](https://hydration.jscrate.dev/docs/compare/eslint-plugin-validate-jsx-nesting)

---

# validateDOMNesting: invalid HTML nesting warnings

> validateDOMNesting warnings mean the browser will rearrange your HTML: a row without tbody, text in a tr, a link in a link. What each says and how to fix it.

Source: https://hydration.jscrate.dev/docs/errors/validatedomnesting
Last updated: 2026-09-18

validateDOMNesting is the check React runs on your elements against HTML's
nesting rules. React 18 prints its warnings as `validateDOMNesting(...)`, and
React 19 starts them with "In HTML,". Each one means the browser will
rearrange the server HTML, for example a row without `<tbody>` or a link
inside a link, so hydration will fail. Fix the markup.

## The error

React 19 prints the rule, then "This will cause a hydration error." on the
next line. The most common one is a table row placed directly in a table:

```text
In HTML, <tr> cannot be a child of <table>. This will cause a hydration error.
```

For that case the full console message puts a hint between the two sentences:
"Add a `<tbody>`, `<thead>` or `<tfoot>` to your code to match the DOM tree
generated by the browser." The other React 19 messages:

```text
In HTML, <td> cannot be a child of <tbody>.
In HTML, <th> cannot be a child of <thead>.
In HTML, <div> cannot be a child of <tbody>.
In HTML, text nodes cannot be a child of <tr>.
In HTML, whitespace text nodes cannot be a child of <table>. Make sure you don't have any extra whitespace between tags on each line of your source code.
In HTML, <a> cannot be a descendant of <a>.
<a> cannot contain a nested <a>.
In HTML, <button> cannot be a descendant of <button>.
In HTML, <form> cannot be a descendant of <form>.
```

React 18 prints the same rules as `Warning: validateDOMNesting(...)`:

```text
Warning: validateDOMNesting(...): <tr> cannot appear as a child of <table>. Add a <tbody>, <thead> or <tfoot> to your code to match the DOM tree generated by the browser.
Warning: validateDOMNesting(...): <th> cannot appear as a child of <thead>.
Warning: validateDOMNesting(...): <div> cannot appear as a child of <tbody>.
Warning: validateDOMNesting(...): Text nodes cannot appear as a child of <tr>.
Warning: validateDOMNesting(...): <a> cannot appear as a descendant of <a>.
Warning: validateDOMNesting(...): <button> cannot appear as a descendant of <button>.
```

Older React versions call a text node `#text`:

```text
Warning: validateDOMNesting(...): #text cannot appear as a child of <tr>.
```

All of these are development warnings. In production you only see the
hydration error that follows them, #418.

A block element inside a paragraph has its own page:
[div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p).

## What validateDOMNesting checks

React renders exactly the tree you wrote. The browser does not: it parses the
server HTML with the HTML parser, which repairs markup that breaks the
content model before any script runs. React knows those rules and warns
about each place where the parser will change your tree:

| Your markup                                                    | What the browser does                               |
| -------------------------------------------------------------- | --------------------------------------------------- |
| `<tr>` directly in `<table>`                                   | Adds a `<tbody>` around it                          |
| `<td>` or `<th>` directly in `<table>`, `<tbody>` or `<thead>` | Adds a `<tr>` around it                             |
| `<div>` or text in `<table>`, `<tbody>` or `<tr>`              | Moves it out, in front of the table                 |
| `<a>` inside `<a>`                                             | Closes the outer link before the inner one starts   |
| A button in a button                                           | Closes the outer button before the inner one starts |
| `<form>` inside `<form>`                                       | Drops the inner `<form>` tag                        |

"Child" in the message means a direct child, and "descendant" means anywhere
inside. When React then hydrates, the DOM has a different shape than the tree
it rendered, and hydration fails.

A page rendered only in the browser keeps the invalid tree, because DOM
methods do not repair nesting. That is why the problem appears with server
rendering.

## Common causes

- **Tables without `<tbody>`.** A `.map()` of rows written directly in
  `<table>`.
- **Missing `<tr>` or `<td>`.** A row component that returns cells, used
  without a row, or text written straight into a `<tr>`.
- **A number rendered by `&&`.** `{items.length && <td>…</td>}` renders the
  text `0` in the row when the list is empty.
- **Spaces between tags on one line**, such as `<tr> {cells} </tr>`, which
  JSX keeps as whitespace text.
- **Cards wrapped in a link that contain another link or a button.** A
  `<Link>` around a card with a "Read more" link or a "Save" button inside.
- **Components that render interactive elements**, such as a tooltip trigger
  that is a `<button>`, placed inside another `<button>`.

## How to fix it

1. **Tables: write every level.** `<table>`, then `<thead>` or `<tbody>`,
   then `<tr>`, then `<td>` or `<th>`. Before:

   ```tsx title="components/orders.tsx"
   type Order = { id: string; total: string };

   export function Orders({ orders }: { orders: Order[] }) {
     return (
       <table>
         {orders.map((order) => (
           <tr key={order.id}>
             {order.id}
             <td>{order.total}</td>
           </tr>
         ))}
       </table>
     );
   }
   ```

   After:

   ```tsx title="components/orders.tsx"
   type Order = { id: string; total: string };

   export function Orders({ orders }: { orders: Order[] }) {
     return (
       <table>
         <tbody>
           {orders.map((order) => (
             <tr key={order.id}>
               <td>{order.id}</td>
               <td>{order.total}</td>
             </tr>
           ))}
         </tbody>
       </table>
     );
   }
   ```

2. **Guard with a boolean, not a number.** Write
   `{items.length > 0 && …}` instead of `{items.length && …}`.
3. **Take nested links and buttons out of the outer one.** Make them
   siblings. Before, the card is one big link with a button inside:

   ```tsx title="components/card-link.tsx"
   "use client";

   export function CardLink({
     href,
     onSave,
   }: {
     href: string;
     onSave: () => void;
   }) {
     return (
       <a href={href}>
         <h3>Title</h3>
         <button onClick={onSave}>Save</button>
       </a>
     );
   }
   ```

   After, the link and the button sit side by side:

   ```tsx title="components/card-link.tsx"
   "use client";

   export function CardLink({
     href,
     onSave,
   }: {
     href: string;
     onSave: () => void;
   }) {
     return (
       <div className="card">
         <a href={href}>
           <h3>Title</h3>
         </a>
         <button onClick={onSave}>Save</button>
       </div>
     );
   }
   ```

   To keep the whole card clickable, stretch the link over the card with CSS
   instead of wrapping the card in it.

## Find every instance

hydration-proof compares the server HTML with what the browser parsed and
reports each repair with the line in the server HTML: invalid nesting as
[HP3001](https://hydration.jscrate.dev/docs/issues/hp3001), and a link, button or form inside another as
[HP3002](https://hydration.jscrate.dev/docs/issues/hp3002). It sees nesting across components too:

```bash
npx hydration-proof test
```

In the editor,
[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
reports links in links, buttons in buttons, forms in forms, interactive
content inside links and buttons, `<tr>` directly in `<table>` and cells
outside a row, within one component.

## Related

- [div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p)
- [Invalid HTML nesting as a cause of hydration errors](https://hydration.jscrate.dev/docs/causes/invalid-html)
- [HP3002: interactive element nested in another](https://hydration.jscrate.dev/docs/issues/hp3002)
- [Button inside button: the ESLint rule](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
- [Other JSX nesting linters compared](https://hydration.jscrate.dev/docs/compare/eslint-plugin-validate-jsx-nesting)

---

# Minified React error codes for hydration

> Minified React error 418, 423, 425 and the other hydration codes (407, 419, 421, 422, 424) decoded: the React 18 and 19 message behind each, and the fix.

Source: https://hydration.jscrate.dev/docs/errors/minified-react-error-codes
Last updated: 2026-09-18

Minified React error 418, 423, 425 and the other codes on this page are
React's hydration errors as a production build prints them: a number and a
link instead of the message. #418 is a mismatch, #425 is a text mismatch in
React 18, and #423 says React re-rendered the whole page. Decode yours below.

## The error

A React 19 production build prints:

```text
Minified React error #418; visit https://react.dev/errors/418?args[]=HTML&args[]= for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

React 18 links to the old decoder instead:

```text
Minified React error #423; visit https://reactjs.org/docs/error-decoder.html?invariant=423 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

The number identifies the message. The `args[]` values fill in its
placeholders; for #418 in newer React 19 releases that is only the word
`HTML` or `text`, never the element.

## Minified React error 418, 423, 425 and the rest, decoded

| Code | React 18 message                                                                                                                                                                                             | React 19 message                                                                                                                 | Reported by hydration-proof as                                                               |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| #407 | Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.                                                                                                   | Same                                                                                                                             | [HP2003](https://hydration.jscrate.dev/docs/issues/hp2003), [HP2004](https://hydration.jscrate.dev/docs/issues/hp2004)                                 |
| #418 | Hydration failed because the initial UI does not match what was rendered on the server.                                                                                                                      | Hydration failed because the server rendered HTML (or text) didn't match the client.                                             | The exact difference, such as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) or [HP1007](https://hydration.jscrate.dev/docs/issues/hp1007) |
| #419 | The server could not finish this Suspense boundary, likely due to an error during server rendering. Switched to client rendering.                                                                            | Same                                                                                                                             | [HP2006](https://hydration.jscrate.dev/docs/issues/hp2006)                                                                |
| #421 | This Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering. The usual way to fix this is to wrap the original update in startTransition. | No longer reported                                                                                                               | [HP2005](https://hydration.jscrate.dev/docs/issues/hp2005)                                                                |
| #422 | There was an error while hydrating this Suspense boundary. Switched to client rendering.                                                                                                                     | There was an error while hydrating but React was able to recover by instead client rendering from the nearest Suspense boundary. | [HP2003](https://hydration.jscrate.dev/docs/issues/hp2003)                                                                |
| #423 | There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.                                                              | There was an error while hydrating but React was able to recover by instead client rendering the entire root.                    | [HP2004](https://hydration.jscrate.dev/docs/issues/hp2004)                                                                |
| #424 | This root received an early update, before anything was able hydrate. Switched the entire root to client rendering.                                                                                          | Same                                                                                                                             | [HP2005](https://hydration.jscrate.dev/docs/issues/hp2005)                                                                |
| #425 | Text content does not match server-rendered HTML.                                                                                                                                                            | Not used: text mismatches are #418                                                                                               | [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001)                                                                |

### The mismatch codes: #418 and #425

These are the bug. [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
is an element or text that differs between the server HTML and the first
client render. In React 18, a text difference has its own code,
[#425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425).

### The recovery codes: #422 and #423

These say what React did about an earlier error. Minified React error #422
means it rendered one Suspense boundary again in the browser, and
[#423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423) means it rendered the whole
root again. In React 18 they follow every mismatch. In React 19 they follow a
component that threw during hydration. See
[there was an error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating).

### The server code: #419

Minified React error #419 means the server threw while rendering a Suspense
boundary, sent its fallback, and left the browser to render it. The real error
is in your server logs, not in the browser.

### The early update codes: #421 and #424

Minified React error #421 means a Suspense boundary received an update
before it finished hydrating, and minified React error #424 means the same for
the root. See
[Suspense boundary received an update before hydrating](https://hydration.jscrate.dev/docs/errors/suspense-boundary-received-update-before-hydrating).

### The API code: #407

`useSyncExternalStore` was called without its third argument during server
rendering or hydration. See
[Missing getServerSnapshot](https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot).

## Why React minifies its errors

Production builds of React replace every error message with its number, so
the long strings are not shipped to every user. The development build keeps
the full text, the diff, the component stack and the warnings, such as
`Warning: Text content did not match`, that production does not print at all.

That is why a React 18 production console often shows #418 followed by #423
and nothing else: the warnings that named the element exist only in development.

## How to get the full message

1. **Open the link in the error.** react.dev/errors decodes the number and
   fills in the arguments. It will not tell you which element, because
   production does not record it.
2. **Reproduce it in development.** Run the same page with a development build
   (`next dev`, `vite dev`) and read the full message and diff.
3. **If it only happens in production,** test the production build and the
   development build side by side:

   ```bash
   npx hydration-proof test --mode both
   ```

   hydration-proof finds the difference in the production build itself, by
   comparing the DOM, and marks findings that appear in only one mode. With
   browser source maps (`productionBrowserSourceMaps: true` in Next.js) it
   also names the component. See
   [hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production).

## Find every instance

Minified codes arrive one at a time from users' browsers. To find all of them
before users do, run hydration-proof on every route in CI; see
[detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci). Each code is mapped to a stable
[issue code](https://hydration.jscrate.dev/docs/issues) with the element, both values and the likely cause.

## Related

- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
- [Minified React error #423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423)
- [Minified React error #425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425)
- [Why hydration errors only happen in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [All hydration error messages in full](https://hydration.jscrate.dev/docs/errors)

---

# Minified React error #418

> Minified React error #418 is a hydration mismatch in a production build. What it means in React 18 and 19, how to get the full message, and how to fix it.

Source: https://hydration.jscrate.dev/docs/errors/minified-react-error-418
Last updated: 2026-09-18

Minified React error #418 is a hydration mismatch in a production build: the
HTML the server sent differs from the first render in the browser, so React
threw it away and rendered the page again. Production hides which element.
Reproduce it in development, or test the production build with a tool that
compares the DOM, to find it.

## The error

React 19:

```text
Minified React error #418; visit https://react.dev/errors/418?args[]=HTML&args[]= for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

React 18:

```text
Minified React error #418; visit https://reactjs.org/docs/error-decoder.html?invariant=418 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

In React 18 it is usually followed by
[#423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423), which says React rendered the
whole page again.

## What minified React error #418 means

React error 418 is the hydration mismatch error. Its full text depends on the
React version:

| Version  | Full message behind #418                                                                                                                            | Covers                                                                         |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| React 18 | [Hydration failed because the initial UI does not match what was rendered on the server.](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match)  | Elements. Text has its own code, [#425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425) |
| React 19 | [Hydration failed because the server rendered HTML didn't match the client.](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client) | Elements and text. Newer releases pass `text` or `HTML` as the argument        |

The react.dev error 418 page decodes the number with the current React
wording, even if your app runs React 18. Neither version puts the element or
the values in the production message: the diff and the warnings that name
the element exist only in development builds.

Attribute differences never produce #418. React 19 does not check attributes
in production at all, so a wrong `class` or `href` stays silent there.

### Why it can appear only in production

The production server often renders in different conditions than your
machine: another timezone (servers usually run in UTC), another locale, cached
or statically built HTML, a CDN that minifies HTML, and real users' browser
extensions. Each can create a mismatch you never see locally. See
[hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production).

## How to fix error 418

1. **Get the full message.** Load the same page with a development build and
   read the error and its diff. If development does not reproduce it, test the
   production build directly (see below).
2. **Find the value that differs** from the diff, or from the finding
   hydration-proof reports.
3. **Fix its cause.** Most production-only cases are dates, numbers and
   locales. Before, the number uses the server's locale on the server and the
   user's in the browser:

   ```tsx title="components/price.tsx"
   export function Price({ amount }: { amount: number }) {
     return <span>{amount.toLocaleString()}</span>;
   }
   ```

   After, both sides use the locale the server chose, for example from the
   URL or a cookie:

   ```tsx title="components/price.tsx"
   export function Price({
     amount,
     locale,
   }: {
     amount: number;
     locale: string;
   }) {
     return <span>{amount.toLocaleString(locale)}</span>;
   }
   ```

   The [common causes of hydration errors](https://hydration.jscrate.dev/docs/causes) each have a fix
   guide.

4. **Deploy and watch the error rate.** One mismatch can hide the next,
   because React reports the first one per boundary.

## Find every instance

hydration-proof tests the production build by default, and compares the DOM
itself, so it names the element React's minified error leaves out:

```bash
npx hydration-proof test --mode both
```

`--mode both` also runs the development server and marks findings that
appear in only one mode. The difference is reported with its own code, such
as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) (text) or [HP1007](https://hydration.jscrate.dev/docs/issues/hp1007) (an
element), and what React did as [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) or
[HP1011](https://hydration.jscrate.dev/docs/issues/hp1011). When React reports #418 but the DOM
comparison cannot place it, you get [HP2001](https://hydration.jscrate.dev/docs/issues/hp2001). With
browser source maps (`productionBrowserSourceMaps: true` in Next.js), the
production finding also names the component.

## Related

- [All minified React hydration codes](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)
- [The full React 19 message and its diff](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)
- [Hydration errors that only show up in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [Timezone mismatches between server and browser](https://hydration.jscrate.dev/docs/causes/timezone)
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)

---

# Minified React error #423

> Minified React error #423 means hydration failed outside any Suspense boundary and React re-rendered the whole page. Find the error that caused it and fix it.

Source: https://hydration.jscrate.dev/docs/errors/minified-react-error-423
Last updated: 2026-09-18

Minified React error #423 means hydration failed outside any Suspense
boundary, so React discarded the server HTML for the whole page and rendered
it again in the browser. It is not the root cause. In React 18 it follows a
mismatch (#418 or #425); in React 19, an error thrown during hydration. Fix
the error logged before it.

## The error

React 18:

```text
Minified React error #423; visit https://reactjs.org/docs/error-decoder.html?invariant=423 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

React 19:

```text
Minified React error #423; visit https://react.dev/errors/423 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

The full messages behind the code:

| Version  | Full message                                                                                                                                    |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| React 18 | There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering. |
| React 19 | There was an error while hydrating but React was able to recover by instead client rendering the entire root.                                   |

## What it means

React error 423 is a recovery message. Hydration failed somewhere that no
`<Suspense>` boundary contains, so React had nothing smaller to fall back to:
it rendered the entire root again, as if the page had no server HTML. The
page works, but it renders twice, the content can flash, and anything typed
before hydration is lost.

What came before it depends on the version:

- **React 18** logs #423 after every mismatch outside a boundary, right after
  [#418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418) (an element differs) or
  [#425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425) (text differs).
- **React 19** logs a mismatch as #418 alone. It logs #423 when a component
  threw an exception during hydration; the exception is attached as the
  error's `cause`.

Inside a boundary, the same failure is #422 and costs only that boundary. See
[there was an error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating)
for both.

## Minified React error #423 (Next.js)

In the Next.js App Router, React hydrates the whole document, so a mismatch in
the root layout, or in a page with no `loading.tsx` or other `<Suspense>`
above it, renders everything again. A `loading.tsx` file wraps its segment
in a Suspense boundary, so a failure inside it renders only that segment
again, and React logs #422 instead of #423. In the Pages Router the root is the `#__next` element.

Next.js production builds do not show an overlay, so the code only appears in
the browser console and in your error tracking.

## How to fix it

1. **Find the error logged before #423** and decode it: usually #418. Its
   page tells you how to find the element.
2. **Fix that error.** When #423 is the only error, in React 19, expand its
   `cause` or reproduce the page in development to see the exception.
3. **Add Suspense boundaries** so the next failure costs one part of the page.
   In the Next.js App Router, a `loading.tsx` does it for a route segment:

   ```tsx title="app/dashboard/loading.tsx"
   export default function Loading() {
     return <p>Loading dashboard…</p>;
   }
   ```

## Find every instance

hydration-proof reports the whole-root fallback as
[HP2004](https://hydration.jscrate.dev/docs/issues/hp2004) and the discarded page as
[HP1011](https://hydration.jscrate.dev/docs/issues/hp1011), and the mismatch that started it as its own
finding, with the element and the source line:

```bash
npx hydration-proof test --mode both
```

The [ESLint rules](https://hydration.jscrate.dev/docs/rules) catch the usual sources of that first
mismatch, such as the clock, `window` and locale formatting, in the editor.

## Related

- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
- [There was an error while hydrating: the full message](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating)
- [Every minified React hydration code](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)
- [Hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [HP2004: the root switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2004)

---

# Minified React error #425

> Minified React error #425 is React 18's text hydration mismatch in production: a date, time or number differs between server and browser. Find and fix it.

Source: https://hydration.jscrate.dev/docs/errors/minified-react-error-425
Last updated: 2026-09-18

Minified React error #425 is React 18's production code for "Text content
does not match server-rendered HTML": a text node in the first browser render
differs from the server's HTML. It is almost always a date, a time, a
formatted number or a random value. Find the text, then make both renders
produce it.

## The error

```text
Minified React error #425; visit https://reactjs.org/docs/error-decoder.html?invariant=425 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

It is usually followed by
[#423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423) (React rendered the whole page
again) or #422 (one Suspense boundary).

The full message is:

```text
Text content does not match server-rendered HTML.
```

React 19 no longer uses this code. A text mismatch there is
[#418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418), with `text` as its argument.
If you see #425, the page runs React 18.

## What minified React error #425 means

React error 425 carries no values, and in production React 18 does not print
the warning that names them. In development, the same mismatch logs:

```text
Warning: Text content did not match. Server: "5:00 AM" Client: "10:00 AM"
```

To find the text, reproduce it in development or compare the page yourself.
A difference that appears only in production usually comes from the server's
environment: servers usually run in UTC and with a default locale, while
your users' browsers do not. A statically built page also keeps the text from
the moment it was built.

## Common causes

| Text                                          | Fix guide                                     |
| --------------------------------------------- | --------------------------------------------- |
| "Updated 3 minutes ago", a clock, a countdown | [Time-dependent values](https://hydration.jscrate.dev/docs/causes/time)    |
| A date or time of day                         | [Timezone differences](https://hydration.jscrate.dev/docs/causes/timezone) |
| A price or number in the user's format        | [Locale formatting](https://hydration.jscrate.dev/docs/causes/locale)      |
| A random id, greeting or order                | [Random values](https://hydration.jscrate.dev/docs/causes/random)          |
| A name or count from `localStorage`           | [Storage](https://hydration.jscrate.dev/docs/causes/storage)               |

## How to fix it

1. **Find the text.** Run the page in development and read the warning, or
   run hydration-proof against the production build (below).
2. **Format it with fixed options.** Before, the time uses each side's
   timezone:

   ```tsx title="components/signed-in-at.tsx"
   "use client";

   export function SignedInAt({ at }: { at: string }) {
     return <p>Signed in at {new Date(at).toLocaleTimeString()}</p>;
   }
   ```

   After, the locale and timezone are explicit, so the server and the browser
   produce the same text. Pass the user's timezone from the server (a cookie
   or a profile setting) to show local time:

   ```tsx title="components/signed-in-at.tsx"
   "use client";

   export function SignedInAt({
     at,
     timeZone,
   }: {
     at: string;
     timeZone: string;
   }) {
     const time = new Date(at).toLocaleTimeString("en-US", { timeZone });
     return <p>Signed in at {time}</p>;
   }
   ```

3. **Render live values after hydration,** for clocks and "time ago" labels.
   See [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering).

## Find every instance

hydration-proof reports each text difference as
[HP1001](https://hydration.jscrate.dev/docs/issues/hp1001), with both values and the likely cause, in the
production build:

```bash
npx hydration-proof test --probe
```

`--probe` proves the cause by changing one thing at a time: the clock, the
locale or the timezone. The ESLint rules
[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) and
[`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone)
catch the code before it ships.

## Related

- [Text content does not match server-rendered HTML](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
- [Minified React errors 418, 423 and 425 compared](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)
- [Timezone hydration mismatches](https://hydration.jscrate.dev/docs/causes/timezone)
- [HP1001: text differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1001)

---

# This Suspense boundary received an update before it finished hydrating

> Suspense boundary received an update before it finished hydrating (#421): why an early update discards the server HTML, and the startTransition fix.

Source: https://hydration.jscrate.dev/docs/errors/suspense-boundary-received-update-before-hydrating
Last updated: 2026-09-18

"This Suspense boundary received an update before it finished hydrating" is a
React 18 error (#421): a state or context change reached a `<Suspense>`
boundary whose server HTML React had not hydrated yet, so React discarded that
HTML and rendered the boundary in the browser. Wrap the update in
`startTransition`, or make it after hydration.

## The error

React 18 in development:

```text
This Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering. The usual way to fix this is to wrap the original update in startTransition.
```

In production:

```text
Minified React error #421; visit https://reactjs.org/docs/error-decoder.html?invariant=421 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

The root has its own version, error #424, when the page is updated before any
of it has hydrated:

```text
This root received an early update, before anything was able hydrate. Switched the entire root to client rendering.
```

React 19 no longer reports #421. It still tries to hydrate the boundary
before applying the update, and when it cannot, it renders the boundary on
the client without a message. The cost is the same; only the error is gone.
#424 still exists in React 19.

## Why a Suspense boundary received an update before it finished hydrating

React hydrates a page in pieces. The shell hydrates first, then each
`<Suspense>` boundary when its code and data are ready. Until then, the
boundary is still the server's HTML, with no components behind it.

Effects in the already-hydrated part run in the meantime. If one of them sets
state or changes a context value that the waiting boundary uses, React has an
update for components that do not exist yet. It first tries to hydrate the
boundary right away. If the boundary is still waiting, for example for a lazy
component's code, React throws the server HTML away and renders the boundary
from scratch, with its fallback first. Users see the content disappear and
come back.

A `startTransition` update is different: React may keep showing the server
HTML, finish hydrating the boundary, and apply the update afterwards.

## Common causes

- **A provider that sets state in an effect on load**: a user, theme or cart
  context read from `localStorage` or a cookie, above a boundary that is still
  hydrating. See [storage](https://hydration.jscrate.dev/docs/causes/storage).
- **A store that rehydrates on load**, such as Zustand's `persist`, changing
  props passed into the boundary. See
  [the Zustand hydration error](https://hydration.jscrate.dev/docs/guides/zustand-hydration-error).
- **Lazy or streamed content**: `React.lazy`, `next/dynamic` or a streamed
  Server Component below the provider, which is exactly the kind of boundary
  that hydrates late.
- **Calling `root.render()`** on a root created by `hydrateRoot` before it has
  hydrated, which is #424.

## How to fix it

1. **Find the update.** The component stack of the error points at the
   boundary. Look above it for effects that call a state setter on mount, and
   for store subscriptions.
2. **Wrap the update in `startTransition`.** Before:

   ```tsx title="app/user-provider.tsx"
   "use client";

   import { createContext, useEffect, useState, type ReactNode } from "react";

   export const UserContext = createContext<string | null>(null);

   export function UserProvider({ children }: { children: ReactNode }) {
     const [user, setUser] = useState<string | null>(null);

     useEffect(() => {
       setUser(localStorage.getItem("user"));
     }, []);

     return (
       <UserContext.Provider value={user}>{children}</UserContext.Provider>
     );
   }
   ```

   After:

   ```tsx title="app/user-provider.tsx"
   "use client";

   import {
     createContext,
     startTransition,
     useEffect,
     useState,
     type ReactNode,
   } from "react";

   export const UserContext = createContext<string | null>(null);

   export function UserProvider({ children }: { children: ReactNode }) {
     const [user, setUser] = useState<string | null>(null);

     useEffect(() => {
       startTransition(() => {
         setUser(localStorage.getItem("user"));
       });
     }, []);

     return (
       <UserContext.Provider value={user}>{children}</UserContext.Provider>
     );
   }
   ```

3. **Keep the value stable during hydration when you can.** A value the server
   can know (a cookie) needs no update at all: read it on the server and pass
   it down.
4. **Updates from `useSyncExternalStore` are always synchronous,** and a
   transition does not change that. Delay the store change until the page has
   hydrated, or keep the changed value out of the waiting boundary's props.

## Find every instance

hydration-proof reports an update that arrived before hydration finished as
[HP2005](https://hydration.jscrate.dev/docs/issues/hp2005), for #421 and #424, and the boundary React
rendered again as [HP2003](https://hydration.jscrate.dev/docs/issues/hp2003). In React 19, where no error is
logged, the discarded server HTML is still reported, as
[HP1010](https://hydration.jscrate.dev/docs/issues/hp1010):

```bash
npx hydration-proof test --mode both
```

The ESLint rule
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
points you to reading storage in an effect instead of during render; the
update that effect makes is the one to wrap in `startTransition`.

## Related

- [There was an error while hydrating (#422, #423)](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating)
- [Every minified React hydration code](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [HP2005: an update arrived before hydration finished](https://hydration.jscrate.dev/docs/issues/hp2005)
- [localStorage and hydration](https://hydration.jscrate.dev/docs/causes/storage)

---

# Missing getServerSnapshot, which is required for server-rendered content

> Missing getServerSnapshot means useSyncExternalStore ran on the server without its third argument. Add one that returns the same value on both sides.

Source: https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot
Last updated: 2026-09-18

"Missing getServerSnapshot, which is required for server-rendered content"
means a component called `useSyncExternalStore` during server rendering or
hydration without its third argument. The server has no browser store to
read, so React needs a value to use instead. Pass a `getServerSnapshot`
function that returns the same value on the server and during hydration.

## The error

React 18 and 19, in development:

```text
Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering.
```

In production it is error #407:

```text
Minified React error #407; visit https://react.dev/errors/407 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.
```

## What missing getServerSnapshot means

`useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)` reads a
value from a store outside React, such as `navigator.onLine`, the window size
or `localStorage`. React calls the three functions at different times:

| When                      | React calls                                               |
| ------------------------- | --------------------------------------------------------- |
| Server rendering          | `getServerSnapshot`                                       |
| Hydration, in the browser | `getServerSnapshot` again, and expects the server's value |
| After hydration           | `getSnapshot`, and re-renders if the value changed        |

Without the third function, React cannot render the component on the server
at all. It throws this error, and "will revert to client rendering" means the
nearest `<Suspense>` boundary is sent without its content and rendered in the
browser instead. With no boundary above it, the server render fails.

## Common causes

- **A hook written for client-only React**, then used in a server-rendered
  app.
- **A copied example** that shows only two arguments.
- **A store library** whose hook calls `useSyncExternalStore` without a server
  snapshot, in an older version or a custom wrapper.

## How to fix it

1. **Find the hook.** The component stack under the error names the component
   that called it.
2. **Add a `getServerSnapshot`** that returns what the page should show before
   the browser value is known. Before:

   ```ts title="hooks/use-online.ts"
   import { useSyncExternalStore } from "react";

   function subscribe(callback: () => void) {
     window.addEventListener("online", callback);
     window.addEventListener("offline", callback);
     return () => {
       window.removeEventListener("online", callback);
       window.removeEventListener("offline", callback);
     };
   }

   export function useOnline() {
     return useSyncExternalStore(subscribe, () => navigator.onLine);
   }
   ```

   After:

   ```ts title="hooks/use-online.ts"
   import { useSyncExternalStore } from "react";

   function subscribe(callback: () => void) {
     window.addEventListener("online", callback);
     window.addEventListener("offline", callback);
     return () => {
       window.removeEventListener("online", callback);
       window.removeEventListener("offline", callback);
     };
   }

   export function useOnline() {
     return useSyncExternalStore(
       subscribe,
       () => navigator.onLine,
       () => true
     );
   }
   ```

3. **Keep `getServerSnapshot` free of browser values.** It runs in the
   browser during hydration too. `() => localStorage.getItem("theme")` as the
   third argument crashes on the server, and a `typeof window` check inside it
   returns one value on the server and another during hydration, which is a
   hydration mismatch. Return a constant, or a value the server passed down
   as a prop.

For values such as the theme, the server can often know the real value from a
cookie. See [storage in server-rendered apps](https://hydration.jscrate.dev/docs/causes/storage).

## Find every instance

[`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
reports `useSyncExternalStore` calls without a third argument, and browser
reads, the clock and `typeof window` checks inside `getServerSnapshot`:

```bash
npm install -D eslint-plugin-hydration-proof
```

hydration-proof reports the fallback at runtime:
[HP2006](https://hydration.jscrate.dev/docs/issues/hp2006) when the server could not render the boundary,
and [HP2003](https://hydration.jscrate.dev/docs/issues/hp2003) or [HP2004](https://hydration.jscrate.dev/docs/issues/hp2004) when React
fell back while hydrating, each with React's message attached:

```bash
npx hydration-proof test
```

## Related

- [The require-stable-server-snapshot rule](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
- [useSyncExternalStore with localStorage](https://hydration.jscrate.dev/docs/causes/storage)
- [Browser-only APIs during render](https://hydration.jscrate.dev/docs/causes/browser-api)
- [There was an error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating)
- [Every minified React hydration code](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)

---

# ReferenceError: window is not defined

> ReferenceError: window is not defined: Next.js ran browser code on the server. Why a typeof window check causes a hydration error, and the fixes that work.

Source: https://hydration.jscrate.dev/docs/errors/window-is-not-defined
Last updated: 2026-09-18

`ReferenceError: window is not defined` (Next.js, Remix or any server-rendered
React app) means code that needs the browser ran on the server, where
`window` does not exist. It is a server crash, not a hydration mismatch. A
`typeof window` check in render stops the crash but causes a mismatch. Read
browser values in an effect instead.

## The error

The server throws before any HTML is sent, so the message appears in your
terminal and in the framework's error page, not in the browser console:

```text
ReferenceError: window is not defined
ReferenceError: document is not defined
ReferenceError: localStorage is not defined
ReferenceError: self is not defined
```

Each one names a browser global:

- `window is not defined`: Next.js rendered a component or imported a module
  that reads `window` on the server.
- `document is not defined`: Next.js ran code that queries or changes the
  page, such as `document.querySelector` or `document.cookie`.
- `localStorage is not defined`: Next.js ran a storage read during render,
  often in a `useState` initializer.
- `self is not defined`: usually a library bundled for browsers only.

The same crash can stop `next build`, when Next.js pre-renders static pages.

## Why window is not defined: Next.js renders on the server

Every server-rendered page is rendered twice: once in Node.js to produce the
HTML, and once in the browser to hydrate it. Node.js has no `window`,
`document` or `localStorage`, so reading them during the first render throws.

`"use client"` does not change this. It marks a Client Component, which is
still rendered on the server for the first HTML. Only a Server Component
never runs in the browser, and only code in effects and event handlers never
runs on the server.

Three places run on the server:

- **The component body**, including `useState` and `useReducer` initializers.
- **Module-level code** in any file the page imports: a line such as
  `const width = window.innerWidth` at the top of a file runs on import.
- **Libraries that touch `window` when imported**, such as some chart, map and
  editor packages.

## Why typeof window is the wrong fix

The quick fix people reach for is a guard:

```tsx title="components/greeting.tsx"
"use client";

export function Greeting() {
  // Stops the crash, and causes a hydration mismatch.
  const host = typeof window !== "undefined" ? window.location.hostname : "";
  return <p>Hello from {host || "our site"}</p>;
}
```

The server now renders "Hello from our site" and the browser renders "Hello
from example.com". The crash becomes a
[hydration error](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client):
React throws the server HTML away and renders the component again. React's
own error message lists this exact pattern as the first cause.

|              | `window is not defined`                | Hydration mismatch                                   |
| ------------ | -------------------------------------- | ---------------------------------------------------- |
| Where        | On the server, before any HTML is sent | In the browser, after the HTML arrived               |
| What you see | A server error page, a failed build    | The page renders twice, content flashes              |
| Cause        | A browser global read on the server    | The server and the browser rendered different output |

## How to fix it

1. **Read browser values in an effect.** Effects run only in the browser,
   after hydration, so both renders start from the same value:

   ```tsx title="components/greeting.tsx"
   "use client";

   import { useEffect, useState } from "react";

   export function Greeting() {
     const [host, setHost] = useState<string | null>(null);

     useEffect(() => {
       setHost(window.location.hostname);
     }, []);

     return <p>Hello from {host ?? "our site"}</p>;
   }
   ```

   See [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering).

2. **Render a component only in the browser** when it cannot run on the
   server at all, such as a map. In Next.js, load it with `next/dynamic` and
   `ssr: false`, from a Client Component:

   ```tsx title="app/store-locator/map-loader.tsx"
   "use client";

   import dynamic from "next/dynamic";

   const Map = dynamic(() => import("./map"), {
     ssr: false,
     loading: () => <p>Loading map…</p>,
   });

   export function MapLoader() {
     return <Map />;
   }
   ```

   `ssr: false` is not allowed in a Server Component. See
   [next/dynamic with ssr: false](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false), and
   [client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component) for other
   frameworks.

3. **Import browser-only libraries inside an effect**, with
   `await import("…")`, when you only need them after the page loads.
4. **Move module-level browser reads into functions** that run in effects or
   event handlers.
5. **Read what the server can know on the server.** A theme, a language or a
   signed-in user can come from a cookie, so the first render needs no
   browser value. See [storage](https://hydration.jscrate.dev/docs/causes/storage).

## Find every instance

The [ESLint plugin](https://hydration.jscrate.dev/docs/eslint) finds both the crash and the mismatch
before you run the app:

- [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render)
  reports `window`, `document`, `navigator` and `location` read during render.
- [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
  reports `localStorage` and `sessionStorage`.
- [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) reports the
  `typeof window` guard in render.
- [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state)
  reports browser values in `useState` initializers.

```bash
npm install -D eslint-plugin-hydration-proof
```

hydration-proof loads every route: a page whose server render crashed is
reported as [HP9005](https://hydration.jscrate.dev/docs/issues/hp9005) (an error status), or
[HP2006](https://hydration.jscrate.dev/docs/issues/hp2006) when the crash was inside a Suspense boundary
that React then rendered in the browser. The mismatch a `typeof window` guard
leaves behind is reported with the cause
[browser-only API used during render](https://hydration.jscrate.dev/docs/causes/browser-api):

```bash
npx hydration-proof test
```

## Related

- [Browser-only APIs and hydration](https://hydration.jscrate.dev/docs/causes/browser-api)
- [Render a component only on the client](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [The no-window-render-branch rule](https://hydration.jscrate.dev/docs/rules/no-window-render-branch)
- [localStorage in Next.js without errors](https://hydration.jscrate.dev/docs/causes/storage)
- [Fix Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs)

---

# Common causes of hydration errors

> The common causes of hydration errors in React and Next.js, how hydration-proof picks the cause of each finding, and the ESLint rule that catches each one.

Source: https://hydration.jscrate.dev/docs/causes
Last updated: 2026-09-18

The common causes of hydration errors all break one rule: the first render in
the browser must produce exactly the HTML the server sent. Clocks, random
values, locales, time zones, browser-only APIs, storage, themes, different data
and invalid nesting each break it in their own way. Every cause below has a fix
guide.

## All common causes of hydration errors

hydration-proof attaches one of these cause ids to each finding, and links the
finding to the page for that id:

| Cause id | What it means |
| --- | --- |
| [time](https://hydration.jscrate.dev/docs/causes/time) | Time-dependent value |
| [timezone](https://hydration.jscrate.dev/docs/causes/timezone) | Timezone difference |
| [locale](https://hydration.jscrate.dev/docs/causes/locale) | Locale-dependent formatting |
| [random](https://hydration.jscrate.dev/docs/causes/random) | Random value |
| [browser-api](https://hydration.jscrate.dev/docs/causes/browser-api) | Browser-only API used during render |
| [storage](https://hydration.jscrate.dev/docs/causes/storage) | localStorage or sessionStorage read during render |
| [media-query](https://hydration.jscrate.dev/docs/causes/media-query) | Screen size or media query read during render |
| [theme](https://hydration.jscrate.dev/docs/causes/theme) | Theme preference (dark or light mode) |
| [data](https://hydration.jscrate.dev/docs/causes/data) | Server and client used different data |
| [invalid-html](https://hydration.jscrate.dev/docs/causes/invalid-html) | Invalid HTML nesting |
| [css-in-js](https://hydration.jscrate.dev/docs/causes/css-in-js) | CSS-in-JS class names differ |
| [extension](https://hydration.jscrate.dev/docs/causes/extension) | Browser extension |
| [third-party-script](https://hydration.jscrate.dev/docs/causes/third-party-script) | A script changed the page before hydration |
| [cdn](https://hydration.jscrate.dev/docs/causes/cdn) | HTML rewritten by a CDN or proxy |
| [unstable-id](https://hydration.jscrate.dev/docs/causes/unstable-id) | Generated id differs |
| [form-state](https://hydration.jscrate.dev/docs/causes/form-state) | Server Action form state |
| [suppressed](https://hydration.jscrate.dev/docs/causes/suppressed) | Intentional difference (suppressHydrationWarning) |

## What React lists as the causes

React 19 prints its own short list with every hydration error. Each line maps to
one or more of the pages above:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:

- A server/client branch `if (typeof window !== 'undefined')`.
- Variable input such as `Date.now()` or `Math.random()` which changes each time it's called.
- Date formatting in a user's locale which doesn't match the server.
- External changing data without sending a snapshot of it along with the HTML.
- Invalid HTML tag nesting.

It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.
```

| React's line                       | Cause pages                                                                                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| A server/client branch             | [Browser APIs](https://hydration.jscrate.dev/docs/causes/browser-api), [storage](https://hydration.jscrate.dev/docs/causes/storage), [media queries](https://hydration.jscrate.dev/docs/causes/media-query), [theme](https://hydration.jscrate.dev/docs/causes/theme) |
| `Date.now()` or `Math.random()`    | [Time](https://hydration.jscrate.dev/docs/causes/time), [random values](https://hydration.jscrate.dev/docs/causes/random), [generated ids](https://hydration.jscrate.dev/docs/causes/unstable-id)                                        |
| Date formatting in a user's locale | [Locale](https://hydration.jscrate.dev/docs/causes/locale), [timezone](https://hydration.jscrate.dev/docs/causes/timezone)                                                                                  |
| External changing data             | [Data](https://hydration.jscrate.dev/docs/causes/data), [form state](https://hydration.jscrate.dev/docs/causes/form-state)                                                                                  |
| Invalid HTML tag nesting           | [Invalid HTML](https://hydration.jscrate.dev/docs/causes/invalid-html)                                                                                                         |
| A browser extension                | [Extensions](https://hydration.jscrate.dev/docs/causes/extension), [third-party scripts](https://hydration.jscrate.dev/docs/causes/third-party-script), [CDNs](https://hydration.jscrate.dev/docs/causes/cdn)                            |

The list leaves out [CSS-in-JS class names](https://hydration.jscrate.dev/docs/causes/css-in-js), which
differ when a style library generates them in a different order on each side,
and [intentional differences](https://hydration.jscrate.dev/docs/causes/suppressed) hidden with
`suppressHydrationWarning`.

## How hydration-proof picks a cause

The likely cause is an informed guess built from four kinds of evidence. The
strongest signal wins, and every other signal that points at the same cause
adds a little confidence:

1. **The two values.** Millisecond timestamps, the same number with different
   separators, random decimals and UUIDs, class names that look generated
   (`sc-`, `css-`, `emotion-`), theme classes (`dark`, `light`), React ids and
   whitespace-only differences each point at one cause.
2. **The code near the line.** hydration-proof maps the element to your source
   file and scans the component that rendered it for `Date.now()`,
   `localStorage`, `matchMedia`, `fetch`, `typeof window` and similar calls.
   Code in a neighboring component never explains a finding.
3. **The scenario.** A browser timezone or locale that differs from the
   server's, dark mode, a mobile viewport or pre-filled storage.
4. **The stage.** Markup the browser's parser repaired is invalid nesting. A
   change between parsing and hydration came from a script or an extension. A
   form the server rendered with Server Action state is form state. A
   difference on an element with `suppressHydrationWarning` is intentional.

The report shows the cause with a confidence score, for example
`timezone difference, 95%`, and the reason next to it. Below 35%, no cause is
named. Some causes cannot be read off the values at all: a `typeof window`
branch only shows in the code, so run in development mode for exact source
lines. [How it works](https://hydration.jscrate.dev/docs/how-it-works) covers the six snapshots behind each
comparison.

## Prove the cause with probes

`--probe` turns the guess into proof. hydration-proof loads the page again with
the browser clock and random values fixed, then once for each factor with
exactly one thing changed:

| Factor     | What changes                                                                              |
| ---------- | ----------------------------------------------------------------------------------------- |
| `time`     | The browser clock moves by 3 days, 7 hours, 11 minutes and 13 seconds                     |
| `random`   | A different seed for `Math.random()` and `crypto.getRandomValues()`                       |
| `locale`   | The server's locale, or another one                                                       |
| `timezone` | The server's timezone, or another one                                                     |
| `theme`    | Light and dark swap                                                                       |
| `viewport` | Desktop and mobile swap                                                                   |
| `storage`  | The page loads without the scenario's `localStorage`, `sessionStorage` and `storageState` |

If the client value changes, or the finding disappears, when only one factor
changes, that factor is the proven cause, and the report says `proven` instead
of a percentage. A page that renders differently on an
identical reload depends on server data. The server is never changed, so a
fixed browser clock cannot hide a time-dependent value. See
[probes](https://hydration.jscrate.dev/docs/probes) for the options.

```bash
npx hydration-proof test --probe
```

## Causes, ESLint rules and issue codes

The [ESLint plugin](https://hydration.jscrate.dev/docs/eslint) catches most causes while you type.
hydration-proof catches all of them in the running app, including the ones no
linter can see. Confidence is what the package's own fixture suite measured for
a production build.

| Cause                                                 | Typical issue codes                                                  | ESLint rules                                                                                                                                                                                                           | Measured confidence |
| ----------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| [time](https://hydration.jscrate.dev/docs/causes/time)                             | [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001), [HP1002](https://hydration.jscrate.dev/docs/issues/hp1002)         | [`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render)                                                                                                                                                                   | 97%                 |
| [timezone](https://hydration.jscrate.dev/docs/causes/timezone)                     | HP1001                                                               | [`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone)                                                                                                                           | 95%                 |
| [locale](https://hydration.jscrate.dev/docs/causes/locale)                         | HP1001                                                               | [`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale)                                                                                                                                   | 98%                 |
| [random](https://hydration.jscrate.dev/docs/causes/random)                         | HP1001, HP1002                                                       | [`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render)                                                                                                                                                               | 94%                 |
| [browser-api](https://hydration.jscrate.dev/docs/causes/browser-api)               | HP1001, HP1002, [HP1003](https://hydration.jscrate.dev/docs/issues/hp1003)                        | [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render), [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch), [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state) | 57–59%              |
| [storage](https://hydration.jscrate.dev/docs/causes/storage)                       | HP1001                                                               | [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)                                                                                                                                             | 94%                 |
| [media-query](https://hydration.jscrate.dev/docs/causes/media-query)               | HP1001, [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004)                                | [`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render)                                                                                                                                                     | 89%                 |
| [theme](https://hydration.jscrate.dev/docs/causes/theme)                           | HP1004, HP1002                                                       | [`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)                                                                                                                                     | 99%                 |
| [data](https://hydration.jscrate.dev/docs/causes/data)                             | HP1001, [HP1007](https://hydration.jscrate.dev/docs/issues/hp1007)–[HP1009](https://hydration.jscrate.dev/docs/issues/hp1009)  | none                                                                                                                                                                                                                   | 68%                 |
| [invalid-html](https://hydration.jscrate.dev/docs/causes/invalid-html)             | [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001), [HP3002](https://hydration.jscrate.dev/docs/issues/hp3002)         | [`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)                                                                                                                                         | 97%                 |
| [css-in-js](https://hydration.jscrate.dev/docs/causes/css-in-js)                   | HP1004                                                               | none                                                                                                                                                                                                                   | 90%                 |
| [extension](https://hydration.jscrate.dev/docs/causes/extension)                   | [HP4002](https://hydration.jscrate.dev/docs/issues/hp4002), [HP4001](https://hydration.jscrate.dev/docs/issues/hp4001)         | none                                                                                                                                                                                                                   | not measured        |
| [third-party-script](https://hydration.jscrate.dev/docs/causes/third-party-script) | HP4001                                                               | none                                                                                                                                                                                                                   | 80%                 |
| [cdn](https://hydration.jscrate.dev/docs/causes/cdn)                               | [HP1015](https://hydration.jscrate.dev/docs/issues/hp1015), [HP4003](https://hydration.jscrate.dev/docs/issues/hp4003)         | none                                                                                                                                                                                                                   | 88%                 |
| [unstable-id](https://hydration.jscrate.dev/docs/causes/unstable-id)               | HP1002, [HP3003](https://hydration.jscrate.dev/docs/issues/hp3003), [HP3004](https://hydration.jscrate.dev/docs/issues/hp3004) | [`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id), [`no-global-render-counter`](https://hydration.jscrate.dev/docs/rules/no-global-render-counter)                                                                                                     | not measured        |
| [form-state](https://hydration.jscrate.dev/docs/causes/form-state)                 | [HP1012](https://hydration.jscrate.dev/docs/issues/hp1012)                                        | none                                                                                                                                                                                                                   | not measured        |
| [suppressed](https://hydration.jscrate.dev/docs/causes/suppressed)                 | [HP6001](https://hydration.jscrate.dev/docs/issues/hp6001)–[HP6003](https://hydration.jscrate.dev/docs/issues/hp6003)          | [`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)                                                                                                                                     | not measured        |

`browser-api` scores lower because the values alone never show it: the cause
comes from the code, which is exact in development builds and depends on
source maps in production.

## Related

- [React hydration errors explained](https://hydration.jscrate.dev/docs/guides/react-hydration-error)
- [Every React hydration error message](https://hydration.jscrate.dev/docs/errors), decoded
- [All hydration-proof issue codes](https://hydration.jscrate.dev/docs/issues)
- [The 15 ESLint rules](https://hydration.jscrate.dev/docs/rules)
- [Proving a cause with probes](https://hydration.jscrate.dev/docs/probes)

---

# Fix date and time hydration errors

> Why new Date() and Date.now() cause a Next.js date hydration error, and three fixes: pass the server time as a prop, render after mount, or format the date.

Source: https://hydration.jscrate.dev/docs/causes/time
Last updated: 2026-09-18

A Next.js date hydration error happens when a component reads the current time
while it renders: the server renders at one moment, the browser hydrates a few
hundred milliseconds (or, for a cached page, days) later, and the text no
longer matches. Pass the time the server used as a prop, or read the clock
after the page has hydrated.

## Symptoms

The same bug shows up under several names, depending on the React version and
the build:

```text
Hydration failed because the server rendered text didn't match the client.
Text content does not match server-rendered HTML.
Warning: Text content did not match. Server: "12:04:31" Client: "12:04:33"
Minified React error #418; visit https://react.dev/errors/418
```

hydration-proof reports it as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) (text) or
[HP1002](https://hydration.jscrate.dev/docs/issues/hp1002) (an attribute such as `datetime`), with the cause
**Time-dependent value**. In the package's own test suite that cause is
identified with 97% confidence.

A date hydration error that only appears on some visits usually means the
value is rounded ("3 minutes ago"): the two renders differ only when they fall
on either side of a boundary.

## Why it happens

Any of these in render code produces a new value on each render:

- `Date.now()`, `new Date()` and `Date()` with no arguments
- `performance.now()` and `Temporal.Now.*()`
- relative formatting built on them: "3 minutes ago", countdowns, "today"

React compares the first client render with the server HTML. A new Date() hydration
mismatch or a Date.now() hydration mismatch is guaranteed as soon as the clock
moves between the two renders, and it always does.

## How to fix it

### Pass the server's time as a prop

Read the clock once, on the server, and send the value to the client. Both
renders then use the same number:

```tsx title="app/post/[slug]/page.tsx"
// A Server Component: it only renders on the server.
export default async function Page() {
  const post = await getPost();
  return <PostDate publishedAt={post.publishedAt} renderedAt={Date.now()} />;
}
```

```tsx title="app/post/[slug]/post-date.tsx"
"use client";

export function PostDate({
  publishedAt,
  renderedAt,
}: {
  publishedAt: number;
  renderedAt: number;
}) {
  const minutes = Math.round((renderedAt - publishedAt) / 60_000);
  return <p>Updated {minutes} minutes ago</p>;
}
```

### Render the time after hydration

When the value must be live (a clock, a countdown), render a placeholder on the
server and fill it in from an effect. Effects never run on the server, so the
first client render still matches:

```tsx title="countdown.tsx"
"use client";

import { useEffect, useState } from "react";

export function Countdown({ endsAt }: { endsAt: number }) {
  const [now, setNow] = useState<number | null>(null);

  useEffect(() => {
    setNow(Date.now());
    const id = setInterval(() => setNow(Date.now()), 1000);
    return () => clearInterval(id);
  }, []);

  if (now === null) return <span>–</span>;
  return <span>{Math.round((endsAt - now) / 1000)}s left</span>;
}
```

[useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
explains the pattern and when the flash of the placeholder matters.

### Format a fixed date, not "now"

A date built from a stored value is deterministic: `new Date(post.publishedAt)`
is the same on both sides. It can still differ if you format it in the reader's
timezone or locale; see [timezone](https://hydration.jscrate.dev/docs/causes/timezone) and
[locale](https://hydration.jscrate.dev/docs/causes/locale) differences for that half of the problem.

## How to solve hydration errors related to dates in React without hiding them

`suppressHydrationWarning` on the element that shows the time makes React keep
the server text without reporting it. That is acceptable for a live clock
whose first value does not matter, and wrong everywhere else: the page shows
the server's stale value until the next render. See
[when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Catch it with ESLint

[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) reports `Date.now()`,
`new Date()`, `performance.now()` and `Temporal.Now` in render code, and skips
Server Components with the `next` preset:

```bash
npm install -D eslint-plugin-hydration-proof
```

[`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone)
catches the formatting half.

## Catch it in CI

`hydration-proof test` loads every route and reports each time-dependent value
as HP1001 or HP1002. With `--probe`, it reloads the page with the browser clock
moved by 3 days, 7 hours, 11 minutes and 13 seconds; if the client value
changes, the cause is proven rather than guessed. See [probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe
```

## Related

- [Timezone hydration mismatches](https://hydration.jscrate.dev/docs/causes/timezone)
- [toLocaleString and locale formatting](https://hydration.jscrate.dev/docs/causes/locale)
- [Text content does not match server-rendered HTML](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
- [HP1001: text differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1001)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)

---

# Fix a timezone hydration mismatch

> A timezone hydration mismatch: the server formats dates in UTC, the browser in the visitor's zone. Pass one explicit timeZone to both, or format after mount.

Source: https://hydration.jscrate.dev/docs/causes/timezone
Last updated: 2026-09-18

A timezone hydration mismatch happens when a component formats a date in the
runtime's time zone. The server usually runs in UTC and the browser in the
visitor's zone, so "5:00 AM" on the server becomes "10:00 AM" in Karachi. Pass
the same explicit `timeZone` to the formatter on both sides, or format the date
after mount.

## Symptoms

React reports a text difference, and only for visitors whose zone gives a
different result than the server's:

```text
Hydration failed because the server rendered text didn't match the client.
Text content does not match server-rendered HTML.
Warning: Text content did not match. Server: "Signed in at 5:00 AM" Client: "Signed in at 10:00 AM"
Minified React error #418; visit https://react.dev/errors/418
```

hydration-proof reports it as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) with the cause
**Timezone difference**, and names both zones in the reason:

```text
HP1001 Text differs between server and client  (timezone difference, 95%)
  #last-login  in LastLogin
  server: "Signed in at 5:00 AM"
  client: "Signed in at 10:00 AM"
  app/dashboard/LastLogin.tsx:14:10
  → Pass an explicit timeZone to the formatter (the same on both sides), or format the date after mount.
```

Times differ for almost every visitor. Dates differ only near midnight, which
makes the bug look random: a "Posted on May 3" line breaks for some visitors in
the evening and for nobody in the morning.

## Why a timezone hydration mismatch happens

A `Date` holds one moment. Turning it into text or into parts (hours, day,
month) needs a time zone, and every JavaScript formatter uses the runtime's
zone unless you pass one.
Mixing local dates in the browser timezone with UTC dates on the server is the classic case.

These read the runtime's zone:

- `toLocaleDateString()`, `toLocaleTimeString()`, and `toLocaleString()` on a date
- `new Intl.DateTimeFormat()` without a `timeZone` option
- `getHours()`, `getMinutes()`, `getDate()`, `getDay()`, `getMonth()`,
  `getFullYear()` and `getTimezoneOffset()`
- `toDateString()`, `toTimeString()` and `toString()` on a date
- `Intl.DateTimeFormat().resolvedOptions().timeZone`, which returns the zone itself

The date does not need to be "now". `new Date(post.publishedAt)` is the same
moment on both sides, and still prints a different hour in Karachi than in UTC.
When the value really is the current time, fix that first: see
[date and time hydration errors](https://hydration.jscrate.dev/docs/causes/time).

## How to fix it

### Use one time zone on both sides

Decide the zone on the server and pass it down. The visitor's own zone works if
the server can know it, for example from a profile setting or a cookie the
browser set on an earlier visit:

```tsx title="app/dashboard/page.tsx"
import { cookies } from "next/headers";
import { LastLogin } from "./last-login";

export default async function Page() {
  const timeZone = (await cookies()).get("tz")?.value ?? "UTC";
  const user = await getUser();
  return <LastLogin at={user.lastLoginAt} timeZone={timeZone} />;
}
```

```tsx title="app/dashboard/last-login.tsx"
"use client";

export function LastLogin({ at, timeZone }: { at: number; timeZone: string }) {
  const time = new Date(at).toLocaleTimeString("en-US", {
    timeZone,
    hour: "numeric",
    minute: "2-digit",
  });
  return <p id="last-login">Signed in at {time}</p>;
}
```

Set the cookie from the browser once, after hydration, so the next request
renders in the right zone:

```tsx title="app/timezone-cookie.tsx"
"use client";

import { useEffect } from "react";

export function TimeZoneCookie() {
  useEffect(() => {
    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
    document.cookie = `tz=${zone}; path=/; max-age=31536000; samesite=lax`;
  }, []);
  return null;
}
```

The first visit renders in UTC. Every visit after it matches the visitor.

### Intl.DateTimeFormat timeZone: hydration-safe formatting

When one zone is right for everyone (an event schedule, a log viewer, a
changelog), pin it in the formatter. Replace local getters with their UTC
versions:

```tsx title="schedule.tsx"
// Before: the runtime's zone, different on each side
const localFormat = new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium",
  timeStyle: "short",
});

// After: the same zone everywhere
const format = new Intl.DateTimeFormat("en-US", {
  timeZone: "UTC",
  dateStyle: "medium",
  timeStyle: "short",
});

export function Posted({ at }: { at: number }) {
  const date = new Date(at);
  // getUTCDate() instead of getDate(), getUTCMonth() instead of getMonth()
  return (
    <p>
      {format.format(date)} ({date.getUTCDate()}/{date.getUTCMonth() + 1})
    </p>
  );
}
```

A locale-sensitive formatter also needs an explicit locale, or the two sides
still disagree about the format. See [locale formatting](https://hydration.jscrate.dev/docs/causes/locale).

### Format in the visitor's zone after mount

If the server cannot know the zone and the time must be local, render a neutral
value first and replace it in an effect. Effects never run on the server, so
the first client render still matches:

```tsx title="local-time.tsx"
"use client";

import { useEffect, useState } from "react";

export function LocalTime({ at }: { at: number }) {
  const [text, setText] = useState(() =>
    new Date(at).toISOString().slice(0, 10)
  );

  useEffect(() => {
    setText(
      new Date(at).toLocaleString("en-US", {
        dateStyle: "medium",
        timeStyle: "short",
      })
    );
  }, [at]);

  return <time dateTime={new Date(at).toISOString()}>{text}</time>;
}
```

The [two-pass rendering pattern](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
explains the trade-off: the placeholder shows until the page hydrates.

### i18n libraries

next-intl and similar libraries format with a configured zone. Set `timeZone`
in the request config so the server and the client provider use the same one.
The [locale guide](https://hydration.jscrate.dev/docs/causes/locale#fix-an-i18n-hydration-error-in-next-intl)
shows the setup.

## Catch it with ESLint

[`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone)
reports every formatter and getter above in render code. It suggests adding
`timeZone: 'UTC'` (or the zone in its `defaultTimeZone` option) and swapping
`getHours()` for `getUTCHours()`. Server Components are skipped, because they
only render on the server.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

The default scenario uses the machine's own timezone, and a server started on
the same machine renders with it, so the two sides agree. Test other zones with
the environment matrix:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  matrix: {
    timezoneId: ["UTC", "Asia/Karachi", "America/Los_Angeles"],
  },
});
```

Each finding is reported as HP1001, and the report names the values that
separate failing pages from passing ones ("Only found with timezone
Asia/Karachi"). With `--probe`, hydration-proof reloads the page with only the
browser's timezone switched to the server's. If the finding disappears, the
timezone is the proven cause. See the [environment matrix](https://hydration.jscrate.dev/docs/environment-matrix)
and [probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe
```

## Related

- [Date and time hydration errors](https://hydration.jscrate.dev/docs/causes/time)
- [Locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale)
- [HP1001: text differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1001)
- [The no-timezone-without-explicit-timezone rule](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)

---

# Fix the toLocaleString hydration mismatch

> A toLocaleString hydration mismatch happens when the server formats with its locale and the browser with the visitor's. Pass an explicit locale to both.

Source: https://hydration.jscrate.dev/docs/causes/locale
Last updated: 2026-09-18

A toLocaleString hydration mismatch happens when a number or date is formatted
without an explicit locale. The server formats with its own default (often
`en-US`), the browser with the visitor's language, and "1,234.5" becomes
"1.234,5" during hydration. Pass the same locale, from the URL or a cookie, to
the formatter on both sides.

## Symptoms

```text
Hydration failed because the server rendered text didn't match the client.
Text content does not match server-rendered HTML.
Warning: Text content did not match. Server: "Total: 1,234,567.891" Client: "Total: 1.234.567,891"
Minified React error #418; visit https://react.dev/errors/418
```

A toLocaleTimeString hydration error looks the same with a time: "5:00:00 PM" on
the server, "17:00:00" in the browser. React 19 lists this cause itself in the
error message: "Date formatting in a user's locale which doesn't match the
server."

hydration-proof reports it as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) with the cause
**Locale-dependent formatting**. It recognizes the same digits with different
separators, and in the package's own test suite names this cause with 98%
confidence.

## Why a toLocaleString hydration mismatch happens

Every locale-sensitive API falls back to the runtime's default locale when you
leave the locale out. On the server that is whatever the container sets (`LANG`,
`LC_ALL`, or the Node.js build's default). In the browser it is the visitor's
language. They rarely agree.

These use the default locale:

- `value.toLocaleString()`, `toLocaleDateString()` and `toLocaleTimeString()`
- `a.localeCompare(b)` without its second argument
- `Intl.NumberFormat`, `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat`,
  `Intl.PluralRules`, `Intl.Collator`, `Intl.ListFormat` and
  `Intl.DisplayNames` without a locale, or with `undefined`
- `Intl.NumberFormat().resolvedOptions().locale`, which returns the default itself

Dates have a second problem on top of this one: the time zone. A date formatted
with an explicit locale can still differ by the zone, covered in
[timezone differences](https://hydration.jscrate.dev/docs/causes/timezone).

## How to fix it

### Pass the locale from the request

The server knows the locale from the URL (`/de/pricing`), a cookie or the
`Accept-Language` header. Pass it down, and use it on both sides:

```tsx title="app/[locale]/pricing/page.tsx"
import { Price } from "./price";

export default async function Page({
  params,
}: {
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  return <Price amount={1234.5} locale={locale} />;
}
```

```tsx title="app/[locale]/pricing/price.tsx"
"use client";

export function Price({ amount, locale }: { amount: number; locale: string }) {
  // Before: amount.toLocaleString() used each runtime's default
  const text = amount.toLocaleString(locale, {
    style: "currency",
    currency: "EUR",
  });
  return <p>Total: {text}</p>;
}
```

### Pin one locale where it does not matter

An admin tool, a log viewer or a fixed-market site can use one locale
everywhere:

```tsx title="percent.tsx"
const percent = new Intl.NumberFormat("en-US", { style: "percent" });

export function Percent({ value }: { value: number }) {
  return <span>{percent.format(value)}</span>;
}
```

The same goes for comparisons: `a.localeCompare(b, "en")`. A list sorted with
`localeCompare` and no locale can come out in a different order on each side,
which the [`require-deterministic-list-order`](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order)
rule reports.

### Fix an i18n hydration error in next-intl

A next-intl hydration error almost always means the server and the client
provider disagree about the locale, the time zone or "now". Configure all three
once, in the request config:

```ts title="src/i18n/request.ts"
import { getRequestConfig } from "next-intl/server";

export default getRequestConfig(async () => ({
  locale: "en",
  // One zone for both sides. Read it from the user's profile or a cookie if it varies.
  timeZone: "Europe/Berlin",
  // One "now" for both sides, used by relative time formatting.
  now: new Date(),
}));
```

A `NextIntlClientProvider` rendered by a Server Component inherits the locale,
messages, time zone, `now` and formats from that config, so Client Components
format exactly like the server did. If you render the provider from a Client
Component instead, pass `locale` and `timeZone` to it yourself. next-intl
warns with `ENVIRONMENT_FALLBACK` when no time zone is configured; treat that
warning as this bug. The next-intl guide to
[reliable date formatting](https://next-intl.dev/blog/date-formatting-nextjs)
covers the details.

### Format after mount when only the browser knows

If the page must use the browser's own locale and the server cannot know it,
render a neutral value first and format in an effect. See
[useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering).

## Catch it with ESLint

[`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale)
reports every call above when the locale is missing, `undefined` or `[]`. A
variable is accepted (`toLocaleString(locale)`), because passing the locale
from the server is the fix. The rule suggests the locale from its
`defaultLocale` option (`en-US` by default) but never inserts it on its own:
the right locale is a product decision.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

The default scenario uses the machine's locale, and a server on the same
machine renders with the same one. Add the locales your visitors use:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  matrix: {
    locale: ["en-US", "de-DE", "ar-EG"],
  },
});
```

A scenario's `locale` also sets the `Accept-Language` header, so a server that
negotiates the locale sees the same one. Findings are HP1001, with the locale
that separates failing runs from passing ones. With `--probe`, hydration-proof
reloads the page with only the browser locale changed; if the value follows
it, the locale is the proven cause. See [probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe
```

## Related

- [Timezone hydration mismatches](https://hydration.jscrate.dev/docs/causes/timezone)
- [Date and time values in render](https://hydration.jscrate.dev/docs/causes/time)
- [The no-locale-without-explicit-locale rule](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale)
- [Text content does not match server-rendered HTML](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
- [Testing locales with the environment matrix](https://hydration.jscrate.dev/docs/environment-matrix)

---

# Fix the Math.random hydration error

> Why a Math.random hydration error happens when render code calls Math.random(), crypto.randomUUID() or uuid, and how to pick the value once or use useId.

Source: https://hydration.jscrate.dev/docs/causes/random
Last updated: 2026-09-18

A Math.random hydration error happens when a component generates a random value
while it renders. The server rolls one number, the browser rolls another during
hydration, and the HTML no longer matches. Generate the value once on the server
and pass it down, use `useId` for element ids, or pick the value in an effect
after hydration.

## Symptoms

```text
Hydration failed because the server rendered text didn't match the client.
Text content does not match server-rendered HTML.
Warning: Text content did not match. Server: "Lucky number 0.72810394" Client: "Lucky number 0.19420517"
Minified React error #418; visit https://react.dev/errors/418
```

A crypto.randomUUID hydration mismatch works the same way, with a UUID in place
of the decimal. In an attribute (`className`, `style`, `data-*`) the result is
worse: React 19 keeps the server's value in production without reporting it, so
the page silently runs with the wrong attribute.

hydration-proof reports text as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) and attributes as
[HP1002](https://hydration.jscrate.dev/docs/issues/hp1002), with the cause **Random value**. It recognizes
random-looking decimals and UUIDs on both sides; in the package's test suite it
names the cause with 94% confidence for `Math.random()` and 89% for
`crypto.randomUUID()`.

## Why the Math.random hydration error happens

Hydration is a render. Anything random that runs during render runs twice, once
on the server and once in the browser, and the two results differ:

- `Math.random()`
- `crypto.randomUUID()` and `crypto.getRandomValues()`, and `randomUUID`,
  `randomBytes` and `randomInt` from `node:crypto`
- `v1`, `v4`, `v6` and `v7` from `uuid` (`v3` and `v5` are deterministic)
- `nanoid()`, and generators made with `customAlphabet()` or `customRandom()`
- `uniqueId`, `random` and `sample` from lodash

A state initializer does not help: `useState(() => Math.random())` runs on the
server and again during hydration.

## How to fix it

### Pick the value on the server and pass it down

A Server Component renders once, so a random choice there is made once and sent
to the client as a prop:

```tsx title="app/tips/page.tsx"
import { Tip } from "./tip";

// A Server Component: the choice is made once, on the server.
export default async function Page() {
  const tips = await getTips();
  const tip = tips[Math.floor(Math.random() * tips.length)];
  return <Tip tip={tip} />;
}
```

```tsx title="app/tips/tip.tsx"
"use client";

export function Tip({ tip }: { tip: string }) {
  return <p>{tip}</p>;
}
```

For many random values, send a seed instead and use a seeded generator on both
sides: the same seed produces the same sequence.

### Use useId for element ids

Random ids for `id`, `htmlFor` and `aria-*` attributes are the most common
source of this bug. React's `useId` returns the same id on the server and during
hydration:

```tsx title="email-field.tsx"
import { useId } from "react";

export function EmailField() {
  // Before: const id = `email-${Math.random()}`;
  const id = useId();
  return (
    <>
      <label htmlFor={id}>Email</label>
      <input id={id} type="email" />
    </>
  );
}
```

[Generated id mismatches](https://hydration.jscrate.dev/docs/causes/unstable-id) covers counters, several
React roots and component libraries.

### Randomize after hydration

When the value should change on every visit and nothing depends on it before
the page is interactive, start from a stable value and randomize in an effect:

```tsx title="shuffle-tip.tsx"
"use client";

import { useEffect, useState } from "react";

// A Math.random hydration error, Next.js or any SSR app: never roll the dice in render.
export function ShuffleTip({ tips }: { tips: string[] }) {
  const [tip, setTip] = useState(tips[0]);

  useEffect(() => {
    setTip(tips[Math.floor(Math.random() * tips.length)]);
  }, [tips]);

  return <p>{tip}</p>;
}
```

Event handlers run after hydration too, so a `crypto.randomUUID()` inside
`onClick` or `onSubmit` is fine.

## Catch it with ESLint

[`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render) reports every call in
the list above in render code, and skips Server Components with the `next`
preset. Random values that end up in ids are reported by
[`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) instead, with a message that
points at `useId`.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

`hydration-proof test` reports each random value as HP1001 or HP1002. With
`--probe`, it reloads the page with a different seed for `Math.random()` and
`crypto.getRandomValues()` in the browser. If the client value changes with
only the seed changed, randomness is the proven cause. The server keeps its
real random values, so fixing the seed never hides the bug. See
[probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe
```

## Related

- [Generated ids that differ](https://hydration.jscrate.dev/docs/causes/unstable-id)
- [Date.now() and other time values](https://hydration.jscrate.dev/docs/causes/time)
- [The no-random-in-render rule](https://hydration.jscrate.dev/docs/rules/no-random-in-render)
- [HP1002: attribute differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1002)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)

---

# Fix a browser API hydration mismatch

> A browser API hydration mismatch happens when render code reads window or navigator, or branches on typeof window. Read browser values after mount instead.

Source: https://hydration.jscrate.dev/docs/causes/browser-api
Last updated: 2026-09-18

A browser API hydration mismatch happens when a component reads `window`,
`document`, `navigator` or `location` while it renders, or branches on
`typeof window`. The server takes one branch, the browser takes the other
during hydration, and the HTML differs. Read browser values in `useEffect`, or
render the component on the client only.

## Symptoms

The error depends on what the branch changes: text, an attribute, a style or a
whole element.

```text
Hydration failed because the server rendered HTML didn't match the client.
Warning: Text content did not match. Server: "Rendered for server" Client: "Rendered for Chromium"
Warning: Prop `href` did not match. Server: "/pricing?region=eu-west" Client: "/pricing?region=us-east"
Warning: Expected server HTML to contain a matching <canvas> in <div>.
```

hydration-proof reports text as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001), attributes as
[HP1002](https://hydration.jscrate.dev/docs/issues/hp1002) and inline styles as
[HP1003](https://hydration.jscrate.dev/docs/issues/hp1003), with the cause **Browser-only API used during
render**. Attribute and style differences are the dangerous ones: React 19 does
not report or fix them in production, so the page keeps the server's value.

The values alone rarely show this cause, so hydration-proof finds it in the
code: it maps the element to its source line and looks for `typeof window`,
`navigator.`, `window.` and flags like `isServer` or `canUseDOM` in the
component. That is why its confidence is lower (57–59% in the test suite) and
why development builds, with exact source lines, name it most reliably.

## Why a browser API hydration mismatch happens

The server renders in Node.js, where `window`, `document` and `location` do
not exist. Code that needs them has to do something else on the server, and
that something else is what the browser then fails to match.

### Why does typeof window cause a hydration mismatch?

The check exists to keep the server from crashing with
`ReferenceError: window is not defined`. It does that, but it also makes the
two renders take different branches:

```tsx title="chart.tsx"
export function Chart({ data }: { data: number[] }) {
  // false on the server, true during hydration: two different trees
  if (typeof window === "undefined")
    return <div className="chart-placeholder" />;
  return <Canvas data={data} />;
}
```

React compares the first client render with the server HTML, not with what
the server would have rendered in a browser. Any value that exists only in the
browser (`innerWidth`, `navigator.language`, `location.hostname`,
`document.cookie`, `devicePixelRatio`) has the same effect, with or without the
check.

`typeof navigator` is not a safe test either: Node.js 21 and later have a
`navigator` global, so the check is true on the server and
`navigator.userAgent` there describes Node.js.

## How to fix it

### Read browser values in useEffect

Start from a value the server can render, and switch after hydration:

```tsx title="greeting.tsx"
"use client";

import { useEffect, useState } from "react";

export function Greeting() {
  // Before: typeof window !== "undefined" ? window.location.hostname : null
  const [host, setHost] = useState<string | null>(null);

  useEffect(() => {
    setHost(window.location.hostname);
  }, []);

  return <p>{host ? `Hello from ${host}` : "Hello"}</p>;
}
```

[useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
covers when the switch is visible and how to keep layout from jumping.

### Know when you are on the client with useSyncExternalStore

A hook that returns `false` during server rendering and hydration, and `true`
afterward, replaces every `typeof window` check in render:

```ts title="use-is-client.ts"
import { useSyncExternalStore } from "react";

const subscribe = () => () => {};

export function useIsClient() {
  return useSyncExternalStore(
    subscribe,
    () => true, // in the browser, after hydration
    () => false // on the server and during hydration
  );
}
```

```tsx title="chart.tsx"
"use client";

import { useIsClient } from "./use-is-client";

export function Chart({ data }: { data: number[] }) {
  const isClient = useIsClient();
  if (!isClient) return <div className="chart-placeholder" />;
  return <Canvas data={data} />;
}
```

The same pattern works for any browser value with a sensible server default:
`useSyncExternalStore(subscribe, () => navigator.onLine, () => true)`.

### Render the component on the client only

When a component cannot render on the server at all (a map, a chart library that
touches `window` on import), skip it during server rendering. In Next.js, load
it with `next/dynamic` and `ssr: false` from a Client Component:

```tsx title="app/map-section.tsx"
"use client";

import dynamic from "next/dynamic";

const Map = dynamic(() => import("./map"), {
  ssr: false,
  loading: () => <div className="map-placeholder" />,
});

export function MapSection() {
  return <Map />;
}
```

The server renders the placeholder, and so does the first client render. See
[next/dynamic with ssr: false](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false) and
[client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component) for other
frameworks.

### Use the framework instead of globals

Most browser reads have a server-safe equivalent. Use `usePathname()` or your
router's hook instead of `location.pathname`, and read request headers such as
`user-agent` on the server and pass the result down, instead of reading
`navigator.userAgent` in render.

## Catch it with ESLint

Three rules cover this cause, each for a different pattern:

- [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render)
  reports `window`, `document`, `navigator`, `location`, `innerWidth` and other
  browser globals in render code.
- [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) reports
  `typeof window` checks and flags like `isServer`, `isBrowser` and
  `canUseDOM` used as conditions.
- [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state)
  reports browser values in `useState`, `useReducer` and `useRef` initializers.

[`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
makes sure a `useSyncExternalStore` server snapshot does not read the browser.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

`hydration-proof test` reports each difference as HP1001, HP1002, HP1003 or a
form state difference ([HP1012](https://hydration.jscrate.dev/docs/issues/hp1012)), including the attribute
and style differences React stays silent about. Run in development mode for
exact source lines, or in both modes to see what production users get:

```bash
npx hydration-proof test --mode both
```

No [probe](https://hydration.jscrate.dev/docs/probes) factor flips a `typeof window` branch, so the cause
comes from the code. When a probe changes the value, the cause is more specific:
[storage](https://hydration.jscrate.dev/docs/causes/storage), [media queries](https://hydration.jscrate.dev/docs/causes/media-query) or
[theme](https://hydration.jscrate.dev/docs/causes/theme).

## Related

- [window is not defined](https://hydration.jscrate.dev/docs/errors/window-is-not-defined)
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [localStorage and sessionStorage in render](https://hydration.jscrate.dev/docs/causes/storage)
- [The no-window-render-branch rule](https://hydration.jscrate.dev/docs/rules/no-window-render-branch)
- [HP1002: attribute differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1002)

---

# Fix the Next.js localStorage hydration error

> A localStorage hydration error happens when render code reads localStorage or sessionStorage. Render a neutral value first, then read storage after hydration.

Source: https://hydration.jscrate.dev/docs/causes/storage
Last updated: 2026-09-18

A localStorage hydration error happens when a component reads `localStorage` or
`sessionStorage` while it renders. The server has no storage and renders the
default; the browser renders the stored value during hydration, so the two
differ. Render a neutral value first and read storage in `useEffect`, or
subscribe with a server snapshot.

## Symptoms

```text
Hydration failed because the server rendered text didn't match the client.
Text content does not match server-rendered HTML.
Warning: Text content did not match. Server: "Welcome back, guest" Client: "Welcome back, Sohail"
Warning: Prop `className` did not match. Server: "light" Client: "dark"
```

It only happens for visitors who have something stored, so it never shows in a
fresh browser and always shows for returning users.

hydration-proof reports text as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) and a stored
class or attribute as [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) or
[HP1002](https://hydration.jscrate.dev/docs/issues/hp1002), with the cause **localStorage / sessionStorage
read during render**. In the package's test suite it names the cause with 94%
confidence.

## Why a localStorage hydration error happens

Storage exists only in the browser. Code that reads it during render either
crashes on the server or, behind a `typeof window` check, renders the default
there:

```tsx title="welcome.tsx"
"use client";

// Next.js hydration error: local storage read during render.
export function Welcome() {
  const name =
    typeof window === "undefined"
      ? "guest"
      : (localStorage.getItem("name") ?? "guest");
  return <p>Welcome back, {name}</p>;
}
```

The check stops the crash but not the mismatch: the server renders "guest", the
first client render reads "Sohail". State initializers have the same problem,
because `useState(() => localStorage.getItem("theme"))` runs during the
hydration render too.

A text difference makes React discard the server HTML and render again. An
attribute difference is worse: React 19 keeps the server's `class="light"`
without a warning in production, so the page stays in the wrong state until
something re-renders it.

## How to fix it

### Render a neutral value, then read storage in useEffect

Render the default on both sides, and load the stored value after hydration:

```tsx title="welcome.tsx"
"use client";

import { useEffect, useState } from "react";

export function Welcome() {
  const [name, setName] = useState("guest");

  useEffect(() => {
    setName(localStorage.getItem("name") ?? "guest");
  }, []);

  return <p>Welcome back, {name}</p>;
}
```

### Subscribe with useSyncExternalStore: localStorage plus a server snapshot

`useSyncExternalStore` renders the server snapshot during server rendering and
hydration, then switches to the real value. It also re-renders when the value
changes:

```ts title="use-stored-name.ts"
import { useSyncExternalStore } from "react";

function subscribe(onChange: () => void) {
  window.addEventListener("storage", onChange);
  return () => window.removeEventListener("storage", onChange);
}

export function useStoredName() {
  return useSyncExternalStore(
    subscribe,
    () => localStorage.getItem("name") ?? "guest", // browser
    () => "guest" // server and hydration: never read storage here
  );
}
```

The `storage` event only fires for changes made in other tabs. If the same tab
writes the value, dispatch an event after writing so subscribers update.

### Fix a React custom localStorage hook hydration error

Most `useLocalStorage` hooks read storage in the `useState` initializer. That
works in a client-only app and breaks the moment the component is server
rendered:

```tsx title="use-local-storage.ts"
import { useEffect, useState } from "react";

export function useLocalStorage<T>(key: string, initialValue: T) {
  // Before: useState(() => JSON.parse(localStorage.getItem(key) ?? "null") ?? initialValue)
  const [value, setValue] = useState<T>(initialValue);

  useEffect(() => {
    const stored = localStorage.getItem(key);
    if (stored !== null) setValue(JSON.parse(stored) as T);
  }, [key]);

  const update = (next: T) => {
    setValue(next);
    localStorage.setItem(key, JSON.stringify(next));
  };

  return [value, update] as const;
}
```

Library hooks usually have a switch for this. In usehooks-ts, pass
`{ initializeWithValue: false }` to `useLocalStorage` for server-rendered
pages, as its documentation recommends. Persisted stores have the same
problem: see [Zustand's persist middleware](https://hydration.jscrate.dev/docs/guides/zustand-hydration-error).

### Store it in a cookie when the server needs it

If the first paint must already show the stored value (a theme, a currency, a
dismissed banner), keep it in a cookie. The server reads the cookie and
renders the right value, so there is nothing to fix up after hydration. The
[theme guide](https://hydration.jscrate.dev/docs/causes/theme) shows this for dark mode.

## Catch it with ESLint

[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
reports every read of `localStorage` or `sessionStorage` in render code,
including state initializers and reads behind a `typeof window` check.
[`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
reports storage reads inside a `getServerSnapshot`.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

hydration-proof tests a clean browser by default, which hides this bug the same
way a fresh browser does. Give a scenario the storage your returning users
have:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  scenarios: [
    { name: "default" },
    { name: "returning", localStorage: { name: "Sohail", theme: "dark" } },
  ],
});
```

The entries are written before any page script runs. Findings are HP1001, or
HP1002 and HP1004 for attributes. With `--probe`, hydration-proof reloads the
page without the scenario's `localStorage`, `sessionStorage` and
`storageState`; if the finding disappears, storage is the proven cause. See
[scenarios](https://hydration.jscrate.dev/docs/scenarios) and [probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe
```

## Related

- [Zustand persist and hydration](https://hydration.jscrate.dev/docs/guides/zustand-hydration-error)
- [Dark mode and theme mismatches](https://hydration.jscrate.dev/docs/causes/theme)
- [Browser-only APIs in render](https://hydration.jscrate.dev/docs/causes/browser-api)
- [The no-storage-in-initial-render rule](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
- [Missing getServerSnapshot](https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot)

---

# Fix the useMediaQuery Next.js hydration error

> A useMediaQuery Next.js hydration error happens when render code reads matchMedia or the window size. Use CSS media queries, or read the value after mount.

Source: https://hydration.jscrate.dev/docs/causes/media-query
Last updated: 2026-09-18

A useMediaQuery Next.js hydration error happens when a component reads
`matchMedia`, `innerWidth` or the screen size while it renders. The server has
no screen and renders a guess (usually desktop); a phone renders the mobile
branch during hydration, and the HTML differs. Let CSS media queries decide
layout, or read the query after mount.

## Symptoms

```text
Hydration failed because the server rendered text didn't match the client.
Warning: Text content did not match. Server: "Desktop layout" Client: "Mobile layout"
Warning: Prop `className` did not match. Server: "menu-desktop" Client: "menu-mobile"
Warning: Expected server HTML to contain a matching <nav> in <header>.
```

Desktop visitors see nothing wrong. Every phone and tablet hits the mismatch.

hydration-proof reports text as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001), class names as
[HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) and swapped elements as
[HP1007](https://hydration.jscrate.dev/docs/issues/hp1007), with the cause **Screen size or media query read
during render**. In the package's test suite it names the cause with 89%
confidence.

## Why the useMediaQuery Next.js hydration error happens

Most `useMediaQuery` hooks, and hand-written checks, evaluate the query while
the component renders:

```tsx title="menu.tsx"
"use client";

export function Menu() {
  // Before: false on the server, true on a phone during hydration
  const mobile =
    typeof window !== "undefined" &&
    window.matchMedia("(max-width: 600px)").matches;
  return mobile ? <MobileMenu /> : <DesktopMenu />;
}
```

The server cannot evaluate `(max-width: 600px)`, `innerWidth`, `screen.width`
or `(prefers-reduced-motion: reduce)`, so it picks a default. The first client
render evaluates the real query. For `prefers-color-scheme`, see the
[theme guide](https://hydration.jscrate.dev/docs/causes/theme): it has its own fixes.

## How to fix it

### Let CSS decide the layout

When the difference is only layout, render both versions and let a CSS media
query hide one. The server HTML and the client render are identical, and the
right version shows before any JavaScript runs:

```tsx title="menu.tsx"
export function Menu() {
  return (
    <>
      <MobileMenu className="md:hidden" />
      <DesktopMenu className="hidden md:block" />
    </>
  );
}
```

The same works with plain CSS (`@media (min-width: 768px)`). This is the only
fix with no flash on first paint.

### Use a media query hook with a server snapshot

When the component really must know the answer in JavaScript, subscribe with
`useSyncExternalStore`. It uses the server snapshot during server rendering and
hydration, then switches to the real value and keeps it updated:

```ts title="use-media-query.ts"
import { useCallback, useSyncExternalStore } from "react";

export function useMediaQuery(query: string, serverValue = false) {
  const subscribe = useCallback(
    (onChange: () => void) => {
      const list = window.matchMedia(query);
      list.addEventListener("change", onChange);
      return () => list.removeEventListener("change", onChange);
    },
    [query]
  );

  return useSyncExternalStore(
    subscribe,
    () => window.matchMedia(query).matches,
    () => serverValue
  );
}
```

Pick the server value your most common visitor gets, since everyone else sees
one render with it. Library hooks have an equivalent switch: usehooks-ts'
`useMediaQuery` takes `{ defaultValue, initializeWithValue: false }` for
server-rendered pages.

### Read the query after mount

A plain effect works too, and fits code that only needs the value once:

```tsx title="reduced-motion.tsx"
"use client";

import { useEffect, useState } from "react";

export function useReducedMotion() {
  const [reduced, setReduced] = useState(false);

  useEffect(() => {
    setReduced(window.matchMedia("(prefers-reduced-motion: reduce)").matches);
  }, []);

  return reduced;
}
```

[useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
explains the extra render and how to keep it from shifting the layout.

## Catch it with ESLint

[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) reports
`matchMedia` calls in render code, including state initializers and calls
behind a `typeof window` check. `innerWidth`, `screen` and `devicePixelRatio`
are reported by [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render),
and [`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
keeps `matchMedia` out of `getServerSnapshot`.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

hydration-proof tests a desktop-sized viewport unless a scenario sets another.
Add a mobile scenario, or a viewport axis to the matrix:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  matrix: {
    viewport: ["desktop", "mobile"],
  },
});
```

Findings are HP1001, HP1004 or HP1007, and the report names the viewport that
separates failing pages from passing ones. With `--probe`, hydration-proof
reloads the page with only the viewport swapped between desktop and mobile; if
the value follows it, the viewport is the proven cause. See
[probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe
```

## Related

- [Dark mode and theme mismatches](https://hydration.jscrate.dev/docs/causes/theme)
- [Browser-only APIs in render](https://hydration.jscrate.dev/docs/causes/browser-api)
- [The no-match-media-in-render rule](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render)
- [Testing viewports with the environment matrix](https://hydration.jscrate.dev/docs/environment-matrix)
- [HP1004: class name differs](https://hydration.jscrate.dev/docs/issues/hp1004)

---

# Fix the next-themes hydration error

> A next-themes hydration error comes from the class set on html before hydration or useTheme() in render. Suppress it on html; render theme UI after mount.

Source: https://hydration.jscrate.dev/docs/causes/theme
Last updated: 2026-09-18

A next-themes hydration error has two sources. next-themes sets the theme class
on `<html>` with a script before React hydrates, so React finds attributes it
did not render; and components that render from `useTheme()` get `undefined`
on the server. Add `suppressHydrationWarning` to `<html>` only, and render
theme-dependent UI after mount.

## Symptoms

Issue titles call it a next-themes hydration mismatch, a next-themes hydration
warning, "next-themes hydration failed" or a Next ThemeProvider hydration
error. A typical report reads "Using next-themes for dark mode generates
hydration failed error". The messages:

```text
Warning: Extra attributes from the server: class,style
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
Warning: Prop `className` did not match. Server: "theme-light" Client: "theme-dark"
Hydration failed because the server rendered HTML didn't match the client.
```

The first two come from `<html>`, where the pre-hydration script added
`class="dark"` and `style="color-scheme: dark"`. The last two come from a
component that renders a different class or icon once it knows the theme.

hydration-proof reports class differences as [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) and
other attributes (an SVG `fill`, a `data-theme`) as
[HP1002](https://hydration.jscrate.dev/docs/issues/hp1002), with the cause **Theme preference (dark/light
mode)**. It recognizes theme-like class names (`dark`, `light`, `theme-*`) and
`prefers-color-scheme` in the code; in the package's test suite it names the
cause with 99% confidence for a class and 91% for an SVG attribute.

## Why the next-themes hydration error happens

The server renders HTML before it knows anything about the visitor's color
scheme. There are two ways to fill that gap, and each fails in its own way:

1. **Set the class before React hydrates.** next-themes injects a small
   blocking script that reads the stored theme (or the system preference) and
   updates `<html>` before the page paints, so there is no flash. React then
   hydrates an `<html>` whose attributes differ from what it rendered.
2. **Decide in a component.** A toggle that shows a sun or a moon from
   `useTheme()` renders the server's guess first. The next-themes README says
   it directly: "Because we cannot know the `theme` on the server, many of the
   values returned from `useTheme` will be `undefined` until mounted on the
   client."

Hand-written dark mode has the same problem when it reads
`matchMedia("(prefers-color-scheme: dark)")` or `localStorage` during render.

## How to fix it

### Render the theme on the server from a cookie

The only fix with no suppression and no flash: store the choice in a cookie and
render it on the server. Both renders then agree from the start:

```tsx title="app/layout.tsx"
import { cookies } from "next/headers";

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const theme =
    (await cookies()).get("theme")?.value === "dark" ? "dark" : "light";
  return (
    <html lang="en" className={theme}>
      <body>{children}</body>
    </html>
  );
}
```

```tsx title="app/theme-toggle.tsx"
"use client";

export function ThemeToggle({ theme }: { theme: "light" | "dark" }) {
  const toggle = () => {
    const next = theme === "dark" ? "light" : "dark";
    document.cookie = `theme=${next}; path=/; max-age=31536000; samesite=lax`;
    document.documentElement.className = next;
  };
  return (
    <button onClick={toggle}>
      {theme === "dark" ? "Light mode" : "Dark mode"}
    </button>
  );
}
```

A "system" setting cannot be rendered on the server this way, because the
server does not know the operating system's preference. Style that case with a
CSS `prefers-color-scheme` media query instead of a class.

### suppressHydrationWarning: next-themes needs it on `<html>`

With next-themes, mark the one element its script changes:

```tsx title="app/layout.tsx"
import { ThemeProvider } from "next-themes";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class">{children}</ThemeProvider>
      </body>
    </html>
  );
}
```

From the [next-themes README](https://github.com/pacocoursey/next-themes): "If
you do not add suppressHydrationWarning to your `<html>` you will get warnings
because next-themes updates that element. This property only applies one level
deep, so it won't block hydration warnings on other elements." The default
`attribute` is `data-theme`; use `attribute="class"` for class-based dark mode
such as Tailwind's.

Do not move `suppressHydrationWarning` to `<body>` or a wrapper `<div>` to
silence component warnings. It covers only that element's own attributes and
text, and hides real bugs there. See
[when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

### Render theme-dependent UI after mount

For components that read `useTheme()`, the README recommends waiting for the
mount:

```tsx title="app/theme-switch.tsx"
"use client";

import { useEffect, useState } from "react";
import { useTheme } from "next-themes";

export function ThemeSwitch() {
  const [mounted, setMounted] = useState(false);
  const { resolvedTheme, setTheme } = useTheme();

  useEffect(() => {
    setMounted(true);
  }, []);

  // Same size as the real button, so nothing shifts when it appears.
  if (!mounted) return <span className="inline-block size-9" />;

  return (
    <button
      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
    >
      {resolvedTheme === "dark" ? "Light mode" : "Dark mode"}
    </button>
  );
}
```

When only the look differs, CSS avoids the extra render: render both icons and
hide one with a `dark:` variant (`dark:hidden` on the sun, `hidden dark:block`
on the moon). The class on `<html>` decides which one shows, before any
JavaScript runs.

### Fix a Next.js dark mode hydration error without next-themes

Hand-written dark mode usually reads the preference in render:

```tsx title="theme-preview.tsx"
"use client";

export function ThemePreview() {
  // Before: false on the server, true in a dark browser
  const dark =
    typeof window !== "undefined" &&
    window.matchMedia("(prefers-color-scheme: dark)").matches;
  return (
    <div className={dark ? "theme-dark" : "theme-light"}>Theme preview</div>
  );
}
```

Replace the read with CSS (`@media (prefers-color-scheme: dark)`), with the
cookie approach above, or with the same pattern next-themes uses: an inline
script that sets the class before hydration, and `suppressHydrationWarning` on
`<html>`:

```tsx title="app/layout.tsx"
const setTheme = `
  try {
    const stored = localStorage.getItem("theme");
    const dark = stored ? stored === "dark" : matchMedia("(prefers-color-scheme: dark)").matches;
    document.documentElement.classList.toggle("dark", dark);
  } catch {}
`;

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <script dangerouslySetInnerHTML={{ __html: setTheme }} />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

Components then style themselves with `dark:` classes or CSS variables, and
never read the theme during render.

## Catch it with ESLint

[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
accepts `suppressHydrationWarning` on `<html>` and `<body>` (its `allowOn`
option), and reports it where it does nothing or hides too much: on an element
with element children, on an element with only static content, and on a
component. It also checks Server Components, since the root layout is one.
[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) and
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
catch hand-written theme reads.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

Test both color schemes:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  matrix: {
    colorScheme: ["light", "dark"],
  },
});
```

Theme bugs show as HP1004 or HP1002. A suppressed `<html>` shows as
[HP6001](https://hydration.jscrate.dev/docs/issues/hp6001), an info finding that lists what the attribute
hid, so you can check it only covers the theme class. With `--probe`,
hydration-proof reloads the page with only the color scheme swapped between
light and dark; if the value follows it, the theme is the proven cause. See
[probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe
```

## Related

- [suppressHydrationWarning: when it is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [shadcn/ui and dark mode](https://hydration.jscrate.dev/docs/guides/shadcn-hydration-error)
- [localStorage in render](https://hydration.jscrate.dev/docs/causes/storage)
- [Intentional differences](https://hydration.jscrate.dev/docs/causes/suppressed)
- [Extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server)

---

# Fix server/client data mismatch hydration errors

> A server/client data mismatch hydration error means the client rendered different data than the server. Send the server's data along; don't refetch it.

Source: https://hydration.jscrate.dev/docs/causes/data
Last updated: 2026-09-18

A server/client data mismatch hydration error happens when the first client
render uses different data than the server did: the client fetched again and
got a newer answer, read a different cache, or evaluated a flag on its own.
Send the exact data the server rendered with to the client, and hydrate from
it before fetching anything new.

## Symptoms

```text
Hydration failed because the server rendered text didn't match the client.
Warning: Text content did not match. Server: "Visits: 41" Client: "Visits: 42"
Warning: Expected server HTML to contain a matching <li> in <ul>.
Warning: Did not expect server HTML to contain a <li> in <ul>.
```

React 19's own message names this cause: "External changing data without
sending a snapshot of it along with the HTML."

hydration-proof reports changed text as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001), and a
list that is longer or shorter on one side as
[HP1007](https://hydration.jscrate.dev/docs/issues/hp1007), [HP1008](https://hydration.jscrate.dev/docs/issues/hp1008) or
[HP1009](https://hydration.jscrate.dev/docs/issues/hp1009), with the cause **Server and client used different
data**. This is the hardest cause to read off the values (68% in the package's
test suite): a counter one higher on the client and a `fetch` near the element
are the clues. A probe gives the proof.

## Why a server/client data mismatch hydration error happens

The server renders with the data it had at that moment. If the client does not
receive that exact data, its first render works from something else:

- **A second fetch.** A Client Component fetches during render (with a
  suspense-enabled hook or a cache that was never filled on the client) and the
  data changed in between: a view counter, a stock level, a feed.
- **A cache that was not sent.** The server filled a query cache, but the client
  starts with an empty one and renders loading state or refetched data.
- **Decisions made twice.** A feature flag, an A/B test bucket or a
  personalization rule is evaluated on the server and again in the browser.
- **Environment values.** In Next.js, environment variables without the
  `NEXT_PUBLIC_` prefix are only available on the server, so a Client
  Component that renders `process.env.REGION` gets a value on the server and
  nothing in the browser.

## How to fix it

### Pass the server's data as props

In the App Router, fetch in a Server Component and pass the result to the
Client Component. React serializes the props into the page, so the client
renders the same data:

```tsx title="app/stats/page.tsx"
import { Visits } from "./visits";

export default async function Page() {
  const stats = await getStats();
  return <Visits initialCount={stats.count} />;
}
```

```tsx title="app/stats/visits.tsx"
"use client";

import { useState } from "react";

export function Visits({ initialCount }: { initialCount: number }) {
  // Before: const { count } = use(fetchStats()) fetched again on the client
  const [count] = useState(initialCount);
  return <p>Visits: {count}</p>;
}
```

Refresh the value after hydration (polling, a subscription, an effect) if it
must stay live. The first render uses the snapshot; later renders can use newer
data.

### Hydrate the query cache

With TanStack Query, prefetch on the server and send the cache along with
`dehydrate` and `HydrationBoundary`. The client's `useQuery` then starts with
the server's data instead of fetching:

```tsx title="app/posts/page.tsx"
import {
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from "@tanstack/react-query";
import { Posts } from "./posts";

export default async function PostsPage() {
  const queryClient = new QueryClient();
  await queryClient.prefetchQuery({ queryKey: ["posts"], queryFn: getPosts });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <Posts />
    </HydrationBoundary>
  );
}
```

Set a default `staleTime` above 0, as the
[TanStack Query SSR guide](https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr)
recommends, so the client does not refetch as soon as it hydrates. For a
single query, `initialData` from a server prop does the same job.

### Use the framework's loader data

React Router and Remix serialize loader data into the page. Read it with
`useLoaderData()` in the component instead of fetching again in an effect or
during render, and both sides render from the same snapshot.

### Decide flags once, on the server

Evaluate feature flags and experiment buckets on the server, and pass the
result down (a prop, a context value, a cookie the server set). The client
reads the decision; it never makes its own.

## Catch it with ESLint

No lint rule can tell whether two fetches return the same data, so there is no
rule for this cause. `hydration-proof test` finds it in the running app.

## Catch it in CI

`hydration-proof test` reports the differing text or elements. With `--probe`,
it reloads the page with nothing changed at all: if that identical reload
renders a different value, the page depends on server data, not on the clock,
the locale or anything else in the browser. See [probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe --repeat 3
```

`--repeat` loads each page several times and marks findings that come and go
as flaky, which data mismatches often are. To make the client's requests
predictable in a test, a scenario's `mocks` answer browser requests; requests
the server makes are not affected. See [scenarios](https://hydration.jscrate.dev/docs/scenarios).

## Related

- [HP1001: text differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1001)
- [Expected server HTML to contain a matching element](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching)
- [Server Action form state](https://hydration.jscrate.dev/docs/causes/form-state)
- [Hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)

---

# Fix the invalid HTML nesting hydration error

> An invalid HTML nesting hydration error happens when the browser repairs markup, like a div in a p, before React hydrates. Fix the nesting to stop it.

Source: https://hydration.jscrate.dev/docs/causes/invalid-html
Last updated: 2026-09-18

An invalid HTML nesting hydration error happens when the server sends markup
that HTML does not allow, such as a `<div>` inside a `<p>` or a link inside a
link. The browser's parser repairs it while reading the page, so the DOM no
longer has the structure React rendered. Fix the nesting so the parser has
nothing to rewrite.

## Symptoms

React names the elements, in development builds only:

```text
In HTML, <div> cannot be a descendant of <p>.
This will cause a hydration error.
In HTML, <tr> cannot be a child of <table>.
<a> cannot contain a nested <a>.
Warning: validateDOMNesting(...): <div> cannot appear as a descendant of <p>.
Hydration failed because the server rendered HTML didn't match the client.
```

Production builds show only the generic hydration failure, which is why this
cause is easy to miss there. The React-specific messages have their own pages:
[div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p)
and [validateDOMNesting](https://hydration.jscrate.dev/docs/errors/validatedomnesting).

hydration-proof reports it as [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001) (invalid nesting)
or [HP3002](https://hydration.jscrate.dev/docs/issues/hp3002) (an interactive element inside another), with
the cause **Invalid HTML nesting** and the line in the server HTML. It compares
the raw server HTML with what the browser's own parser built, so it names this
cause with 97% confidence.

## Why an invalid HTML nesting hydration error happens

React renders the tree exactly as you wrote it. The browser builds the DOM from
the server's HTML with the HTML parser, which follows the HTML rules and fixes
what breaks them:

```text
server HTML:  <p>Intro<div>Details</div></p>
browser DOM:  <p>Intro</p><div>Details</div><p></p>
```

When React hydrates, it expects a `<div>` inside the `<p>` and finds it next to
it instead. The common repairs:

| You render                                                         | The browser builds                                                  | Fix                                                      |
| ------------------------------------------------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------- |
| `<div>` (or `<ul>`, `<h2>`, `<table>`, another `<p>`) inside `<p>` | Closes the `<p>` before the block, and adds an empty `<p>` after it | Use `<span>` inside, or make the outer element a `<div>` |
| `<a>` inside `<a>`                                                 | Closes the outer link before the inner one                          | Move the inner link out                                  |
| `<button>` inside `<button>`, `<form>` inside `<form>`             | Closes the outer button; ignores the inner form tag                 | Make them siblings                                       |
| `<tr>` directly inside `<table>`                                   | Adds a `<tbody>` around the rows                                    | Render the `<tbody>` yourself                            |
| `<td>` directly inside `<tbody>` or `<table>`                      | Adds a `<tr>`                                                       | Wrap cells in `<tr>`                                     |

## How to fix it

### Use an inline element inside a paragraph

```tsx title="intro.tsx"
// Before: <p>Welcome<div className="details">Read more below.</div></p>
export function Intro() {
  return (
    <div>
      <p>Welcome</p>
      <div className="details">Read more below.</div>
    </div>
  );
}
```

Watch components that render a block element: `<p><Card /></p>` breaks if
`Card` returns a `<div>`. Markdown renderers and CMS rich text often wrap
content in `<p>`, so a component placed inside that content needs to render
inline elements.

### Take nested links and buttons apart

A card that is a link and also has a button inside is two interactive elements
in one. Make them siblings, and stretch the link over the card with CSS if the
whole card must be clickable:

```tsx title="card-link.tsx"
export function CardLink({
  href,
  onSave,
}: {
  href: string;
  onSave: () => void;
}) {
  return (
    <div className="card relative">
      <a href={href} className="after:absolute after:inset-0">
        <h3>Title</h3>
      </a>
      <button onClick={onSave} className="relative z-10">
        Save
      </button>
    </div>
  );
}
```

### Write the table elements the browser would add

```tsx title="rows.tsx"
export function Rows({ rows }: { rows: { id: string; name: string }[] }) {
  return (
    <table>
      {/* Before: <tr> directly inside <table> */}
      <tbody>
        {rows.map((row) => (
          <tr key={row.id}>
            <td>{row.name}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}
```

Stray whitespace between table tags is a text node the table cannot hold.
Keep `{" "}` and line-broken text out of `<table>`, `<tbody>` and `<tr>`.

## Catch it with ESLint

[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
reports every pattern in the table above when it is visible in one component,
through fragments, conditionals and `.map()` callbacks. It checks Server
Components too, because React hydrates the elements they render.

```bash
npm install -D eslint-plugin-hydration-proof
```

Nesting across components (`<p><Card /></p>` where `Card` renders a `<div>`)
is invisible to a linter.

## Catch it in CI

`hydration-proof test` finds nesting across components, in content from a CMS
and in HTML injected with `dangerouslySetInnerHTML`, because it compares the
real server HTML with the DOM the browser's parser built, using React's own
nesting rules. It reports HP3001 or HP3002 with the element and its line in the
server HTML. No probe is needed: the parser's repair is the proof. See
[how it works](https://hydration.jscrate.dev/docs/how-it-works).

```bash
npx hydration-proof test
```

## Related

- [div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p)
- [validateDOMNesting warnings](https://hydration.jscrate.dev/docs/errors/validatedomnesting)
- [HP3001: invalid HTML nesting](https://hydration.jscrate.dev/docs/issues/hp3001)
- [The no-invalid-interactive-nesting rule](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
- [Compared: eslint-plugin-validate-jsx-nesting](https://hydration.jscrate.dev/docs/compare/eslint-plugin-validate-jsx-nesting)

---

# Fix the styled-components hydration error

> A styled-components hydration error means the server and browser generated different class names. Turn on the compiler and add a style registry.

Source: https://hydration.jscrate.dev/docs/causes/css-in-js
Last updated: 2026-09-18

A styled-components hydration error happens when the server and the browser
generate different class names for the same component: `sc-abc123` in the
server HTML, `sc-xyz789` during hydration. Missing server setup or styled
components created in a different order cause it. Turn on the compiler plugin,
add a style registry, and create styled components at module level.

## Symptoms

```text
Warning: Prop `className` did not match. Server: "sc-bdVaJa kLmNop" Client: "sc-bwzfXH dEfGhI"
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

In React 19 production builds there is no error at all: React keeps the
server's classes, so the element shows the wrong styles or none. MUI and other
Emotion-based libraries show the same symptom with `css-` or `Mui*` class
names.

hydration-proof reports it as [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) with the cause
**CSS-in-JS class names differ**. It recognizes generated class names
(`sc-`, `css-`, `emotion-`, `jsx-`, `makeStyles-`) in the differing tokens; in
the package's test suite it names the cause with 90% confidence.

## Why a styled-components hydration error happens

A CSS-in-JS library turns each styled component into a generated class name.
The name has to come out the same on the server and in the browser, and three
things break that:

1. **No server rendering setup.** Without the compiler plugin, component ids
   depend on the order in which styled components are created. Anything that
   changes that order on one side changes every name after it.
2. **Components created conditionally.** A `styled()` call inside a component,
   or behind a `typeof window` check, runs a different number of times on each
   side.
3. **Styles never collected on the server.** Without a registry, the server
   HTML has class names but no matching styles, and the library generates the
   styles again in the browser.

The second case, in its smallest form:

```tsx title="title.tsx"
import styled from "styled-components";

// Before: an extra styled component on the server shifts every id after it
if (typeof window === "undefined") styled.h2``;

const Title = styled.h2`
  color: tomato;
`;
```

## How to fix it

### Turn on the styled-components compiler

Next.js compiles styled-components with SWC. The plugin gives every styled
component a stable id and display name instead of a counter:

```js title="next.config.js"
module.exports = {
  compiler: {
    styledComponents: true,
  },
};
```

### Add a style registry for the App Router

The registry collects the styles generated during a server render and inserts
them into the HTML with `useServerInsertedHTML`. This is the setup from the
[Next.js CSS-in-JS guide](https://nextjs.org/docs/app/guides/css-in-js) for
styled-components 6:

```tsx title="lib/registry.tsx"
"use client";

import React, { useState } from "react";
import { useServerInsertedHTML } from "next/navigation";
import { ServerStyleSheet, StyleSheetManager } from "styled-components";

export default function StyledComponentsRegistry({
  children,
}: {
  children: React.ReactNode;
}) {
  // Only create the stylesheet once, with lazy initial state.
  const [styledComponentsStyleSheet] = useState(() => new ServerStyleSheet());

  useServerInsertedHTML(() => {
    const styles = styledComponentsStyleSheet.getStyleElement();
    styledComponentsStyleSheet.instance.clearTag();
    return <>{styles}</>;
  });

  if (typeof window !== "undefined") return <>{children}</>;

  return (
    <StyleSheetManager sheet={styledComponentsStyleSheet.instance}>
      {children}
    </StyleSheetManager>
  );
}
```

```tsx title="app/layout.tsx"
import StyledComponentsRegistry from "./lib/registry";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <StyledComponentsRegistry>{children}</StyledComponentsRegistry>
      </body>
    </html>
  );
}
```

The `typeof window` branch in the registry is safe: it only changes which
wrapper collects styles, not what the page renders. The Pages Router uses
`ServerStyleSheet` in a custom `_document` instead; the
[with-styled-components example](https://github.com/vercel/next.js/tree/canary/examples/with-styled-components)
shows both.

### Create styled components at module level

Define every styled component once, at the top level of a module, and choose
between them with props:

```tsx title="title.tsx"
import styled from "styled-components";

const Title = styled.h2<{ $muted?: boolean }>`
  color: ${(props) => (props.$muted ? "gray" : "tomato")};
`;

export function Heading({ muted }: { muted?: boolean }) {
  return <Title $muted={muted}>Styled title</Title>;
}
```

### Fix the MUI Next.js hydration error

Material UI styles with Emotion, which needs its own cache setup for server
rendering. MUI ships it in `@mui/material-nextjs`:

```bash
npm install @mui/material-nextjs @emotion/cache
```

```tsx title="app/layout.tsx"
import { AppRouterCacheProvider } from "@mui/material-nextjs/v15-appRouter";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <AppRouterCacheProvider>{children}</AppRouterCacheProvider>
      </body>
    </html>
  );
}
```

The import path names the Next.js major version (`v15-appRouter`,
`v16-appRouter`); use the one that matches yours. The Pages Router uses
`AppCacheProvider` and `documentGetInitialProps` from the matching
`v15-pagesRouter` entry. See
[MUI's Next.js integration guide](https://mui.com/material-ui/integrations/nextjs/).

For other libraries, check the list of CSS-in-JS libraries with App Router
support in the Next.js guide above. Each needs its own registry or provider.

## Catch it with ESLint

There is no lint rule for this cause: whether class names match depends on
the build setup, not on one line of code. `hydration-proof test` finds it in
the running app.

## Catch it in CI

`hydration-proof test` reports each class difference as HP1004, including the
ones React 19 production builds never report. Run the production build in CI,
where users see the wrong styles, and the development build for exact source
lines:

```bash
npx hydration-proof test --mode both
```

No [probe](https://hydration.jscrate.dev/docs/probes) factor changes generated class names, so the cause
comes from the shape of the names and the styled component near the element.

## Related

- [Prop className did not match](https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match)
- [HP1004: class name differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1004)
- [Hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Dark mode and theme classes](https://hydration.jscrate.dev/docs/causes/theme)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)

---

# Fix a browser extension hydration error

> A browser extension hydration error comes from Grammarly, ColorZilla or a password manager editing the page before React hydrates. Confirm it, then ignore it.

Source: https://hydration.jscrate.dev/docs/causes/extension
Last updated: 2026-09-18

A browser extension hydration error is not a bug in your code. An extension
such as Grammarly, ColorZilla or a password manager adds attributes or elements
to the page after the server HTML arrives and before React hydrates, so React
finds markup it did not render. Confirm it in a clean browser profile, then
ignore it.

## Symptoms

The warning names an attribute you never wrote, usually on `<body>`,
`<html>` or a form field:

```text
Warning: Extra attributes from the server: cz-shortcut-listen
Warning: Extra attributes from the server: data-new-gr-c-s-check-loaded,data-gr-ext-installed
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

A Grammarly hydration error is the most common one, and React's own message
now says "It can also happen if the client has a browser extension installed
which messes with the HTML before React loaded." Seeing
`cz-shortcut-listen="true"`? Next.js is not the cause: ColorZilla adds it to
`<body>`.

| Attribute or element                                                                       | Added by                                                   |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `data-new-gr-c-s-check-loaded`, `data-gr-ext-installed`, `<grammarly-desktop-integration>` | Grammarly                                                  |
| `cz-shortcut-listen="true"`                                                                | ColorZilla                                                 |
| `data-lt-installed`                                                                        | LanguageTool                                               |
| `bis_skin_checked`                                                                         | Commonly traced to Bitdefender's browser extension         |
| Their own `data-*` attributes on forms and inputs                                          | Password managers such as LastPass, Dashlane and 1Password |
| `data-darkreader-*` and inline styles                                                      | Dark Reader                                                |
| `__gchrome_uniqueid` on inputs                                                             | Chrome and Edge on iPad, not an extension                  |

The `__gchrome_uniqueid` hydration warning comes from the browser itself: Chrome
and Edge on iPadOS add it to form fields
([vercel/next.js#77710](https://github.com/vercel/next.js/issues/77710)). It
behaves like an extension and has the same answer.

hydration-proof reports recognized extension changes as
[HP4002](https://hydration.jscrate.dev/docs/issues/hp4002), an info finding that does not fail the run
with the default `ci.failOn: 'error'`, with the cause **Browser extension**. Other changes made before hydration are
[HP4001](https://hydration.jscrate.dev/docs/issues/hp4001).

## Why a browser extension hydration error happens

Extensions run their content scripts as soon as the page starts loading, often
before your JavaScript. They mark `<body>` to say they are active, add
attributes to inputs they manage, or insert their own elements. React then
compares its first render with a DOM that someone else already changed.

React 19 handles part of this: unexpected tags in `<head>` and `<body>` are
skipped instead of failing hydration. Attributes on `<html>`, `<body>` and your
elements, and text an extension rewrites (a translator, a spell checker), still
differ. An extension that inserts a script before `<head>` can still break
hydration entirely
([react/react#24430](https://github.com/facebook/react/issues/24430)).

## How to fix it

There is nothing to fix in your code. Make sure it really is an extension, and
keep it out of your reports.

### Confirm it in a clean profile

1. Open the page in a private window with extensions disabled, or in a new
   browser profile.
2. Reload with the console open. If the warning is gone, an extension caused it.
3. Turn extensions back on one at a time to find which one, if you need to know.

If the warning stays in a clean profile, the attribute comes from your own
code or a script on the page. See
[third-party scripts](https://hydration.jscrate.dev/docs/causes/third-party-script).

### Silence the development warning on html and body only

If the warning gets in your way during development, `suppressHydrationWarning`
on `<body>` (or `<html>`) tells React to ignore differences in that element's
own attributes:

```tsx title="app/layout.tsx"
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body suppressHydrationWarning>{children}</body>
    </html>
  );
}
```

It works one level deep. It does not cover inputs, text or anything inside
`<body>`, so do not spread it through your components to chase extension
attributes: it would hide your own bugs there. See
[suppressHydrationWarning](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Catch it with ESLint

No lint rule can see an extension. The one related rule,
[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning),
accepts `suppressHydrationWarning` on `<html>` and `<body>` by default for this
reason, and reports it on other elements where it would hide more.

## Catch it in CI

`hydration-proof test` drives a clean browser, so extensions installed on your
machine never reach its results. When you simulate one on purpose (a scenario's
`initScripts` can change the page before hydration), the changes it recognizes
show as HP4002 info findings, and real bugs around them still fail the run.
If a known extension attribute keeps appearing in a report, ignore it by name:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    attributes: ["cz-shortcut-listen", /^data-gr-/],
  },
});
```

Ignored findings stay in the report, marked as ignored, and do not fail the
run. See [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Related

- [Extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server)
- [Scripts that change the page before hydration](https://hydration.jscrate.dev/docs/causes/third-party-script)
- [HP4002: a browser extension changed the page](https://hydration.jscrate.dev/docs/issues/hp4002)
- [When suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)

---

# Fix the next/script hydration error

> A next/script hydration error happens when a script edits the server HTML before React hydrates. Load it afterInteractive or lazyOnload instead.

Source: https://hydration.jscrate.dev/docs/causes/third-party-script
Last updated: 2026-09-18

A next/script hydration error happens when a script changes the server-rendered
DOM before React hydrates. A tag manager, an A/B testing snippet, a consent
banner or a `beforeInteractive` script adds attributes, rewrites text or
inserts elements, and React finds HTML it did not render. Load the script after
hydration, or let it change only elements outside React's tree.

## Symptoms

```text
Hydration failed because the server rendered text didn't match the client.
Warning: Text content did not match. Server: "Hello world" Client: "Hola mundo"
Warning: Extra attributes from the server: data-experiment
Minified React error #418; visit https://react.dev/errors/418
```

The error appears only when the script wins the race against hydration, so it
often comes and goes with network speed and cache state.

hydration-proof reports it as [HP4001](https://hydration.jscrate.dev/docs/issues/hp4001), "The page was
modified before React hydrated", with the cause **A script changed the page
before hydration** and the exact change:

```text
HP4001 The page was modified before React hydrated  (a script changed the page before hydration, 80%)
  #greeting
  server: "Hello world"
  client: "Hola mundo"
  → Load the script after hydration (for example next/script with strategy="afterInteractive" or "lazyOnload"), or make it change only elements outside React's tree.
```

## Why the next/script hydration error happens

React hydrates the DOM as it finds it, not the HTML the server sent. Any script
that runs between the browser parsing the page and React hydrating it can
change what React sees:

- scripts in `<head>` without `defer` or `async`, and inline scripts
- `next/script` with `strategy="beforeInteractive"`, which Next.js injects into
  the `<head>` of the server HTML and fetches before any Next.js code
- tag managers and experimentation tools that swap text or classes as early
  as they can, to avoid a flash
- personalization, translation and consent tools that edit the page on load

### next/script beforeInteractive hydration error

The Next.js docs say `beforeInteractive` scripts are "downloaded before any
Next.js module", and that their execution "does not block page hydration from
occurring". A script that touches the DOM can therefore run before hydration or
during it. Scripts with this strategy in the root layout causing hydration
errors were reported in
[vercel/next.js#51242](https://github.com/vercel/next.js/issues/51242), now
closed. Keep `beforeInteractive` for scripts that must run first and leave the
DOM alone, such as bot detectors and consent managers.

### next/script nonce CSP hydration warning

With a Content Security Policy that uses a nonce, you may see:

```text
Warning: Extra attributes from the server: nonce
```

Browsers hide the `nonce` attribute from the DOM after parsing, for security,
so the element React hydrates no longer shows the value the server rendered
([react/react#26028](https://github.com/facebook/react/issues/26028)). The
script still runs with its nonce. Do not work around the warning by exposing
the nonce to client code, which weakens the policy. Let Next.js apply the nonce
on the server as its
[CSP guide](https://nextjs.org/docs/app/guides/content-security-policy)
describes, and keep Next.js up to date: the report in
[vercel/next.js#77952](https://github.com/vercel/next.js/issues/77952) was
closed as a duplicate of #63749.

### Vercel Speed Insights hydration error

A Vercel Speed Insights hydration error with minified errors 418 and 423 was
reported in [vercel/next.js#59379](https://github.com/vercel/next.js/issues/59379)
against a Next.js 14 canary, and is closed. If you still see it, upgrade
`@vercel/speed-insights` and Next.js, then run hydration-proof: it shows
whether the page was changed before hydration (HP4001) or has an ordinary
mismatch with another cause.

## How to fix it

### Load the script after hydration

`afterInteractive` (the default) injects the script on the client after some
hydration has happened. `lazyOnload` waits for browser idle time:

```tsx title="app/layout.tsx"
import Script from "next/script";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Before: strategy="beforeInteractive" */}
        <Script
          src="https://example.com/experiments.js"
          strategy="afterInteractive"
        />
        <Script
          src="https://example.com/chat-widget.js"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}
```

Tag managers and analytics fit `afterInteractive`; chat widgets and social
embeds fit `lazyOnload`.

### Give the script its own element

If a script must run early, let it change only elements React does not render:
a container it creates itself and appends to `<body>`, or one your layout
renders empty and never updates. Changes outside React's roots cannot break
hydration, and hydration-proof reports them as info at most.

### Move experiments to the server

A/B tests that swap copy in the browser before hydration change React's DOM by
design. Decide the variant on the server (in middleware or the page) and render
it directly, so both sides agree. See
[server and client data](https://hydration.jscrate.dev/docs/causes/data).

### Mark inline theme scripts

An inline script that sets a class on `<html>` before paint (a theme script) is
fine if it changes only `<html>` and that element has
`suppressHydrationWarning`. The [theme guide](https://hydration.jscrate.dev/docs/causes/theme) shows the
pattern.

## Catch it with ESLint

No lint rule can see what an external script does at runtime, so there is no
rule for this cause. `hydration-proof test` catches it in the running page.

## Catch it in CI

hydration-proof compares the server HTML as the browser parsed it with the DOM
right before React hydrated, after undoing React's own streaming moves.
Whatever remains was changed by someone else: HP4001 for your scripts and
third-party tags, [HP4002](https://hydration.jscrate.dev/docs/issues/hp4002) for changes that look like a
browser extension. To test a tag before you ship it, add it to a scenario's
`initScripts`, which run before the page's own scripts. See
[how it works](https://hydration.jscrate.dev/docs/how-it-works).

```bash
npx hydration-proof test
```

## Related

- [Browser extensions that change the page](https://hydration.jscrate.dev/docs/causes/extension)
- [HP4001: the page was modified before React hydrated](https://hydration.jscrate.dev/docs/issues/hp4001)
- [Dark mode scripts and suppressHydrationWarning](https://hydration.jscrate.dev/docs/causes/theme)
- [Hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)

---

# Fix the Cloudflare Auto Minify hydration error

> A Cloudflare Auto Minify hydration error happens when a CDN rewrites server HTML on its way to the browser. Turn off HTML minification and email obfuscation.

Source: https://hydration.jscrate.dev/docs/causes/cdn
Last updated: 2026-09-18

A Cloudflare Auto Minify hydration error happens when a CDN or proxy rewrites
the server's HTML on its way to the browser. Minification drops the whitespace
between elements, email obfuscation replaces addresses, and injected scripts
change the page, so React hydrates HTML its server never produced. Turn HTML
rewriting off for server-rendered pages.

## Symptoms

The app works locally and on a preview deployment, and fails only behind the
CDN:

```text
Hydration failed because the server rendered text didn't match the client.
Text content does not match server-rendered HTML.
Minified React error #418; visit https://react.dev/errors/418
```

hydration-proof reports whitespace-only differences as
[HP1015](https://hydration.jscrate.dev/docs/issues/hp1015) and HTML changed between the origin and the
browser as [HP4003](https://hydration.jscrate.dev/docs/issues/hp4003), with the cause **HTML rewritten by a
CDN or proxy**. When only whitespace differs and the response carries a CDN
header (`cf-ray`, `x-amz-cf-id`, `x-served-by`, `x-cache`, `via`), it names the
cause with 88% confidence.

## Why a Cloudflare Auto Minify hydration error happens

React renders text and spaces as separate pieces: `Hello{" "}<strong>world</strong>`
needs the space between the text and the element. An HTML minifier removes
"unneeded" whitespace between tags, the browser parses the shorter HTML, and
React's first render no longer matches it. Minifiers that strip HTML comments
do more damage: React's server HTML uses comments to separate adjacent text
nodes and to mark Suspense boundaries.

CDN features that rewrite HTML:

| Feature                          | What it changes                                                           | Turn it off                                                                                                                                                                                                                                                            |
| -------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auto Minify (HTML)               | Removes whitespace and comments                                           | Cloudflare deprecated Auto Minify on August 5, 2024. A zone that still has it on can turn it off through the API, as Cloudflare's [Turn off Auto Minify](https://developers.cloudflare.com/speed/optimization/content/troubleshooting/disable-auto-minify/) page shows |
| Email Address Obfuscation        | Replaces visible email addresses with a link and adds a decode script     | Security, Settings, Client-side abuse, Email Address Obfuscation: Off. A configuration rule can turn it off for some paths only                                                                                                                                        |
| Rocket Loader                    | Defers all JavaScript until after rendering, rewriting the page's scripts | Speed, Settings, Content Optimization, Rocket Loader: Off. `data-cfasync="false"` before `src` excludes one script                                                                                                                                                     |
| Other proxies and edge functions | Minify, inject banners or analytics, rewrite links                        | Check the proxy's HTML settings                                                                                                                                                                                                                                        |

Cloudflare documents the email feature in
[Email Address Obfuscation](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/)
and the script feature in
[Rocket Loader](https://developers.cloudflare.com/speed/optimization/content/rocket-loader/).

## How to fix it

1. Turn off HTML minification at the CDN for server-rendered pages. Your
   framework's build already minifies JavaScript and CSS; the HTML does not
   need a second pass.
2. Turn off Email Address Obfuscation, or exclude your app's paths with a
   configuration rule. If you want to hide addresses from scrapers, do it in
   your own components.
3. Turn off Rocket Loader for the app. React and your framework load their own
   scripts in a specific order.
4. Test through the CDN again. The finding disappears once the HTML arrives
   unchanged.

Purge the CDN cache after changing the settings, or cached pages keep the
rewritten HTML.

## Fix an iOS format-detection hydration mismatch

Safari on iOS does its own rewriting: by default it detects strings that look
like phone numbers and turns them into links that call the number. When that
happens to server HTML before React hydrates, the DOM holds an `<a>` React did
not render. Turn the detection off with a meta tag:

```html title="index.html"
<meta name="format-detection" content="telephone=no" />
```

In the Next.js App Router, set it through the metadata API:

```tsx title="app/layout.tsx"
import type { Metadata } from "next";

export const metadata: Metadata = {
  formatDetection: {
    telephone: false,
    email: false,
    address: false,
  },
};
```

Next.js renders that as
`<meta name="format-detection" content="telephone=no, address=no, email=no" />`.
Render phone numbers you want linked as real `tel:` links yourself. The desktop
browsers hydration-proof drives may not do this detection, so check this one on
a real iPhone.

## Catch it with ESLint

A CDN setting is not code, so no lint rule can catch it.

## Catch it in CI

Run hydration-proof against the origin and against the CDN. A finding that
only appears through the CDN is the CDN:

```bash
npx hydration-proof test --url https://origin.example.com --route / --route /contact
npx hydration-proof test --url https://www.example.com --route / --route /contact
```

The CDN run reports HP1015 or HP4003, with the CDN header that pointed at the
cause in the reason. See [CI](https://hydration.jscrate.dev/docs/ci) for running this against a staging
deployment.

## Related

- [HP1015: whitespace differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1015)
- [HP4003: HTML was rewritten between the server and the browser](https://hydration.jscrate.dev/docs/issues/hp4003)
- [Errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [Scripts that change the page before hydration](https://hydration.jscrate.dev/docs/causes/third-party-script)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)

---

# Fix the React useId hydration error

> A React useId hydration error means an id differs between server and client: a counter, a random value, or useId in trees that differ. How to fix each.

Source: https://hydration.jscrate.dev/docs/causes/unstable-id
Last updated: 2026-09-18

A React useId hydration error means an element's id differs between the server
HTML and the first client render. The id came from a counter, a random value or
the clock, or `useId` ran in trees that differ. Use `useId` for every generated
id, render the same tree on both sides, and give each React root its own
`identifierPrefix`.

## Symptoms

React 18 says the prop `id` did not match, and prints the server and client
values:

```text
Warning: Prop `id` did not match. Server: "react-select-2-live-region" Client: "react-select-3-live-region"
Warning: Prop `htmlFor` did not match. Server: "field-5731" Client: "field-1"
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

React 19 reports attribute differences in development only. In production it
keeps the server's ids without a warning, so a `<label>` can point at nothing
and ARIA references (`aria-controls`, `aria-describedby`) break for screen
readers.

hydration-proof reports a differing id as [HP1002](https://hydration.jscrate.dev/docs/issues/hp1002) with
the cause **Generated id differs**, and recognizes React's own ids (`:r1:`,
`«r1»` or `_r_1_`, depending on the React version). It also reports ids used
twice on a page as [HP3003](https://hydration.jscrate.dev/docs/issues/hp3003), and several React roots that
generate the same ids as [HP3004](https://hydration.jscrate.dev/docs/issues/hp3004).

## Why a React useId hydration error happens

An id has to be computed the same way on the server and in the browser. These
do not qualify:

- **A module-level counter.** The server process keeps counting across every
  request (`field-5731`), while each browser tab starts at `field-1`.
- **Random values and the clock.** `Math.random()`, `crypto.randomUUID()`,
  `nanoid()`, lodash's `uniqueId` and `Date.now()` give a new value per render.
- **`useId` in trees that differ.** `useId` derives the id from the
  component's position in the tree, so it only matches when the server and the
  client render exactly the same tree above it. A component that renders
  something extra on one side (a `typeof window` branch, a client-only banner)
  shifts every id after it.
- **Several roots without a prefix.** Two React roots on one page both start
  their `useId` sequence from the same point, so they generate the same ids.

## How to fix it

### Use useId instead of counters and random ids

```tsx title="email-field.tsx"
import { useId } from "react";

// Before:
// let nextId = 0;
// const id = `email-${nextId++}`;

export function EmailField() {
  const id = useId();
  return (
    <>
      <label htmlFor={id}>Email</label>
      <input id={id} type="email" />
    </>
  );
}
```

For list items, combine `useId()` with a stable key from your data:
`` `${id}-${item.id}` ``. Never use `useId` for React `key` props.

### Give each React root its own identifierPrefix

When one page hydrates several independent React apps, give each root a
prefix, and use the same prefix on the server and the client:

```tsx title="server.tsx"
import { renderToPipeableStream } from "react-dom/server";

const { pipe } = renderToPipeableStream(<App />, {
  identifierPrefix: "checkout-",
});
```

```tsx title="client.tsx"
import { hydrateRoot } from "react-dom/client";

hydrateRoot(document.getElementById("checkout")!, <App />, {
  identifierPrefix: "checkout-",
});
```

With one app per page, no prefix is needed.

### useId hydration mismatch (App Router)

In the Next.js App Router, check what renders above the component whose id
differs:

1. Look for a Client Component above it that renders a different number of
   components on each side (`typeof window`, `useMediaQuery` without a server
   default, a mounted flag that adds siblings). Fix that component first; see
   [browser APIs in render](https://hydration.jscrate.dev/docs/causes/browser-api).
2. `useId` cannot be used in async Server Components. Call it in a Client
   Component or a synchronous component.
3. Keep React and Next.js on matching, current versions. Framework bugs have
   shifted ids before: [vercel/next.js#84029](https://github.com/vercel/next.js/issues/84029)
   reported different `useId` values on each side in some Next.js 15 releases,
   and was closed with a fix.

### Fix a Radix UI hydration error

Radix Primitives generate their ids on the server with React's `useId` on
React 18 and later (on older React versions they added ids only after
hydration). A Radix id hydration error today (`aria-controls` or `id` values
like `radix-_R_166itmdl5rlb_` on the server and `radix-_R_66itmdl5rlb_` in the
browser) nearly always means the component trees differ, as in the list above.
Version combinations matter too:
[radix-ui/primitives#3700](https://github.com/radix-ui/primitives/issues/3700)
reported this error with Next.js 15.5 and React 19.2, and downgrading Next.js
avoided it. Upgrade Radix, React and Next.js together. The
[shadcn/ui guide](https://hydration.jscrate.dev/docs/guides/shadcn-hydration-error) covers the components
built on Radix.

### Fix the react-select hydration error

react-select builds its ids from a module-level counter
(`react-select-2-live-region`) unless you pass `instanceId`. The server's
counter keeps growing across requests, so every react-select Next.js hydration
error has the same fix:

```tsx title="country-select.tsx"
"use client";

import { useId } from "react";
import Select from "react-select";

export function CountrySelect({
  options,
}: {
  options: { value: string; label: string }[];
}) {
  const instanceId = useId();
  return <Select instanceId={instanceId} options={options} />;
}
```

Other libraries with an id or prefix prop take the same approach: pass a value
from `useId`.

## Catch it with ESLint

[`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) reports random values, the
clock and module-level counters that end up in an `id`, `htmlFor`, an `aria-*`
reference or a prop ending in `Id`, and points you to `useId`.
[`no-global-render-counter`](https://hydration.jscrate.dev/docs/rules/no-global-render-counter) reports
module-level variables changed during render, the counters behind many id
bugs.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

`hydration-proof test` reports differing ids as HP1002 even in production
builds, where React says nothing, and checks the whole document for duplicate
ids (HP3003) and roots that share `useId` ids (HP3004). With `--probe`, a
random id changes when only the random seed changes, which proves the cause. An
id from a server-side counter changes on every request, so an identical reload
already renders it differently. See [probes](https://hydration.jscrate.dev/docs/probes).

```bash
npx hydration-proof test --probe
```

## Related

- [Random values in render](https://hydration.jscrate.dev/docs/causes/random)
- [HP3004: two React roots generate the same ids](https://hydration.jscrate.dev/docs/issues/hp3004)
- [The no-unstable-id rule](https://hydration.jscrate.dev/docs/rules/no-unstable-id)
- [Attributes that didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)
- [shadcn/ui hydration errors](https://hydration.jscrate.dev/docs/guides/shadcn-hydration-error)

---

# Fix Server Action form state hydration

> Server Action form state hydration breaks when the server renders a submitted form and the client hydrates without its state. Let the framework pass it on.

Source: https://hydration.jscrate.dev/docs/causes/form-state
Last updated: 2026-09-18

Server Action form state hydration breaks when the server renders a form with
the result of a submitted action (`useActionState` with a `permalink`,
submitted before JavaScript loaded) but the client hydrates without that
state. Fields and messages jump back to their initial values. Let the framework
pass the form state along, and render the form from the action state only.

## Symptoms

React says nothing. Form control values are properties, not text, and React
18 and 19 report no warning when a control's value or selected option changes
during hydration, not even in development. The user sees the message
they submitted disappear, or a field reset, right after the page becomes
interactive.

hydration-proof reports it as [HP1012](https://hydration.jscrate.dev/docs/issues/hp1012), a warning:

```text
HP1012 Form state differs between server and client  (server action form state, 90%)
  #newsletter-email
  attribute: value
  server: "ada@example.com"
  client: ""
  → The server rendered this form with the result of a submitted Server Action (useActionState with a permalink), but the client hydrated without that state. Let the framework pass the form state to hydrateRoot (Next.js does this), and render the form from the action state only.
```

It picks the cause **Server Action form state** when the difference sits inside
a form the server rendered with action state, which React marks in the server
HTML with a `<!--F!-->` comment before the `<form>`. The same code without that
marker is usually a value computed differently on each side: see
[browser APIs in render](https://hydration.jscrate.dev/docs/causes/browser-api).

## Why Server Action form state hydration breaks

`useActionState` supports progressive enhancement. If a visitor submits the
form before the JavaScript bundle loads, the browser posts it to the server,
the server runs the action and renders the page with the result. From the
React documentation of `useActionState`: "If `reducerAction` is a Server
Function and the form is submitted before the JavaScript bundle loads, the
browser will navigate to the specified permalink URL rather than the current
page's URL."

For hydration to match, the client must start from the same result. React
takes it through the `formState` option of `hydrateRoot`, which "must be the
same value as the `formState` passed to the server renderer". When it is
missing, `useActionState` returns `initialState` in the browser while the server
HTML shows the submitted state.

That happens when:

- a custom server or framework integration renders with form state but does not
  pass it to `hydrateRoot`;
- the permalink page renders a different form component, action or permalink
  than the page the form was on, so React cannot match the state to the form;
- the form copies the action result into local state or computes default
  values from something else, so the server and client disagree even with the
  right state.

## How to fix it

### Let the framework pass the form state

Next.js passes the form state for you. With a custom server, pass the value the
server rendered with to `hydrateRoot`, serialized into the page:

```tsx title="client.tsx"
import { hydrateRoot } from "react-dom/client";

// The same value the server passed to its renderer as `formState`,
// serialized into the page by your server.
const formState = JSON.parse(
  document.getElementById("form-state")?.textContent ?? "null"
);

hydrateRoot(document, <App />, { formState });
```

### Render the form from the action state only

Derive every value the form shows from the state `useActionState` returns, and
render the same form, action and permalink on the permalink page:

```tsx title="app/newsletter/signup.tsx"
"use client";

import { useActionState } from "react";
import { subscribe } from "./actions";

export function Signup() {
  // Before: const [email] = useState(() => readDraftFromStorage());
  const [state, formAction, pending] = useActionState(
    subscribe,
    { email: "", message: "" },
    "/newsletter"
  );

  return (
    <form action={formAction}>
      <input id="newsletter-email" name="email" defaultValue={state.email} />
      <button disabled={pending}>Subscribe</button>
      {state.message && <p>{state.message}</p>}
    </form>
  );
}
```

React's documentation adds a caveat for the permalink: "ensure the same form
component is rendered on the destination page (including the same
`reducerAction` and `permalink`) so React knows how to pass the state through."

### Keep default values identical on both sides

Outside Server Actions, HP1012 means a control's `defaultValue`,
`defaultChecked` or selected option was computed differently on each side. A
`<textarea>` or `<select>` whose default depends on storage or a browser API
changes silently during hydration. Compute defaults from data the server has,
and fill anything browser-specific in an effect.

## Catch it with ESLint

No lint rule can tell whether a framework passes the form state along.
[`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state) and
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
catch form defaults read from the browser.

## Catch it in CI

`hydration-proof test` compares every form control's value, checked and
selected state in the server HTML with what React rendered, including the
differences React never reports. To exercise a submission before hydration,
use [interactions](https://hydration.jscrate.dev/docs/interactions): they can type and click while the
page's scripts are held back.

```bash
npx hydration-proof test
```

## Related

- [HP1012: form state differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1012)
- [Server and client data that differ](https://hydration.jscrate.dev/docs/causes/data)
- [Browser APIs in render](https://hydration.jscrate.dev/docs/causes/browser-api)
- [Interactions and navigation](https://hydration.jscrate.dev/docs/interactions)
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes)

---

# Handle an intentional hydration mismatch

> An intentional hydration mismatch is a difference you accept, like a timestamp. Put suppressHydrationWarning on the smallest element and audit what it hides.

Source: https://hydration.jscrate.dev/docs/causes/suppressed
Last updated: 2026-09-18

An intentional hydration mismatch is a difference you accept: a timestamp the
server renders and the browser replaces, or a theme class a script sets before
hydration. Mark the one element that differs with `suppressHydrationWarning`,
keep it on the smallest element possible, and let hydration-proof list what
each suppression hides.

## Symptoms

Nothing in the console: that is what the attribute is for. hydration-proof
still sees the difference and reports it, so a suppression cannot quietly
cover a real bug:

| Code                          | Severity | Meaning                                                              |
| ----------------------------- | -------- | -------------------------------------------------------------------- |
| [HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) | info     | A difference hidden by `suppressHydrationWarning`, with both values  |
| [HP6002](https://hydration.jscrate.dev/docs/issues/hp6002) | error    | The attribute cannot hide this: the elements inside differ           |
| [HP6003](https://hydration.jscrate.dev/docs/issues/hp6003) | info     | Nothing on the element differs, so the attribute hides nothing today |

These findings get the cause **Intentional difference
(suppressHydrationWarning)**. When the hidden difference does not look
intentional (not a time, timezone, locale, random, theme or extension
difference), HP6001 is raised to a warning with the note "suppressHydrationWarning
hides a difference that does not look intentional", and the fix for the real
cause is shown first.

## What suppressHydrationWarning does

`suppressHydrationWarning` tells React to keep the server's text and
attributes for one element without reporting that they differ. The React
documentation is direct about its limits: "This only works one level deep, and
is intended to be an escape hatch. Don't overuse it. React will **not** attempt
to patch mismatched text content."

So the element keeps showing the server's value until something re-renders it,
and anything inside a child element is not covered at all.

## Which intentional hydration mismatch is safe?

| Difference                                                             | Suppress it?                                     |
| ---------------------------------------------------------------------- | ------------------------------------------------ |
| A live clock or "last updated" time that updates right after hydration | Yes, on the element that shows the time          |
| The theme class a pre-hydration script sets on `<html>`                | Yes, on `<html>` only                            |
| Attributes browser extensions add to `<body>`                          | Only if the development warning gets in your way |
| Data, ids, CSS-in-JS class names, invalid nesting                      | No: fix the cause                                |

When the difference should not exist, the cause pages have the fix: start with
[all causes of hydration errors](https://hydration.jscrate.dev/docs/causes).

## How to fix it

### Put it on the smallest element

The attribute covers the element's own text and attributes. On a wrapper, it
misses the text inside a child:

```tsx title="clock.tsx"
// Before: still a hydration error, the text is in the <span>
export function ClockBefore({ now }: { now: Date }) {
  return (
    <div suppressHydrationWarning>
      <span>{now.toLocaleTimeString("en-US", { timeZone: "UTC" })}</span>
    </div>
  );
}

// After: on the element whose text differs
export function Clock({ now }: { now: Date }) {
  return (
    <div>
      <span suppressHydrationWarning>
        {now.toLocaleTimeString("en-US", { timeZone: "UTC" })}
      </span>
    </div>
  );
}
```

It also does nothing on a component (`<Clock suppressHydrationWarning />`)
unless the component passes the prop to an HTML element.

### Fix structural differences instead

`suppressHydrationWarning` never covers elements that are added, removed or
replaced. If the server renders a `<p>` and the client a `<div>` inside the
marked element, React still fails hydration, and hydration-proof reports
HP6002. Render the same elements on both sides and let only text or attributes
differ.

### Remove it where nothing differs

HP6003 means the element's server and client output are identical. The
attribute is doing nothing today and will hide the next real mismatch on that
element. Remove it.

### Prefer rendering after mount

Even an intended difference can often be avoided: render a placeholder on the
server and the real value in an effect. The page then never shows a stale
server value. See [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
and [when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning).

## Catch it with ESLint

[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
reports `suppressHydrationWarning` on an element with element children (it
only covers one level), on an element whose content is static (nothing can
differ, with a suggestion to remove it) and on a component. `<html>` and
`<body>` are accepted by default. The `strict` preset reports every other use
too, so each suppression needs an `eslint-disable` comment that explains it.
The rule also checks Server Components, since root layouts are one.

```bash
npm install -D eslint-plugin-hydration-proof
```

## Catch it in CI

`hydration-proof test` lists every suppressed difference as HP6001 with the
server and client values, so a review can check that each one is the
intended timestamp or theme class and nothing else. HP6002 fails the run;
HP6001 and HP6003 are info unless the hidden difference looks like a bug.

```bash
npx hydration-proof test
```

To keep a difference out of hydration-proof's results without touching React,
use the `ignore` options or a `data-hydration-proof-ignore` attribute instead:
see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Related

- [suppressHydrationWarning: when it is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [HP6001: mismatch hidden by suppressHydrationWarning](https://hydration.jscrate.dev/docs/issues/hp6001)
- [The audit-suppress-hydration-warning rule](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
- [Dark mode and the class on html](https://hydration.jscrate.dev/docs/causes/theme)
- [Date and time values](https://hydration.jscrate.dev/docs/causes/time)

---

# CLI

> The hydration-proof CLI reference: every command (test, baseline, merge-reports, dev, ui, init, migrate, install, doctor), its flags and the exit codes.

Source: https://hydration.jscrate.dev/docs/cli
Last updated: 2026-09-18

The hydration-proof CLI has nine commands. `test`, the default, loads every
route of your app in a real browser and reports hydration problems. The others
record a baseline, merge CI shards, open a development overlay or a dashboard,
write a config, migrate an old one, download browsers and check your setup.

| Command | What it does |
| --- | --- |
| `test` | Test the app's routes for hydration problems (default) |
| `baseline` | Record the current findings; "test --new-only" then fails only on new ones |
| `merge-reports` | Combine the reports of parallel CI jobs |
| `dev` | Browse the app with a hydration overlay |
| `ui` | Open a local dashboard to run tests and read reports |
| `init` | Create hydration-proof.config.ts (and a CI workflow with --ci) |
| `migrate` | Update a config written for an older version |
| `install` | Download the browser (Chromium by default) |
| `doctor` | Check the environment and configuration |

## How to run the hydration-proof CLI

```text
hydration-proof <command> [options]
```

Run `hydration-proof <command> --help` for the options of a command.
Command-line options override the [config file](https://hydration.jscrate.dev/docs/configuration). Every
example on this page uses `npx`; the tabs show the pnpm, Yarn and Bun
equivalents.

## `test`

Tests your app's routes for hydration problems. By default it builds the app if
there is no build output yet, starts it on a free port, discovers the routes and
tests each one in Chromium.

```bash
npx hydration-proof test
npx hydration-proof test --url http://localhost:3000 --route / --route /pricing
npx hydration-proof test --mode both --probe
npx hydration-proof test --changed --shard 1/3
```

A few flags need more than the table says:

- `--url` tests an app that is already running: nothing is built or started.
- `--route` turns route discovery off; only the routes you name are tested.
  See [routes](https://hydration.jscrate.dev/docs/routes) for everything else that picks routes.
- `--mode` takes `production` (the default), `development` or `both`, and the
  short forms `prod` and `dev`. `both` marks issues found in only one mode.
- `--sitemap` reads `robots.txt` and `/sitemap.xml`. `--crawl` follows
  same-origin links to a depth of 2, at most 50 routes.
- `--changed` without a ref compares with the pull request's base branch, or
  `main`.
- `--reporter` defaults to `list,json,html`.

| Option | What it does |
| --- | --- |
| `-c, --config <file>` | Config file (default: hydration-proof.config.*) |
| `-u, --url <url>` | Test an app that is already running |
| `-r, --route <path>` | Test only this route (repeatable) |
| `--grep <regex>` | Only routes whose path matches |
| `-s, --scenario <name>` | Only this scenario (repeatable) |
| `--mode <mode>` | production (default), development, or both |
| `--build / --no-build` | Always rebuild / never build before testing |
| `--browser <name>` | chromium (default), firefox or webkit |
| `--channel <name>` | Use an installed browser, e.g. chrome |
| `--no-matrix` | Test the scenarios without the environment matrix |
| `--probe` | Prove causes by reloading pages with one thing changed |
| `--interactions` | Type, click and scroll while pages load; check nothing is lost |
| `--navigation` | Compare client-side navigation with direct loads (Next.js) |
| `--repeat <n>` | Load every page n times and report flaky findings |
| `--reporter <list>` | Comma-separated: list,json,html,junit,sarif,github,gitlab |
| `-o, --output <dir>` | Report directory (default: .hydration-proof/report) |
| `-w, --workers <n>` | Pages tested in parallel |
| `--timeout <ms>` | Per-page timeout |
| `--retries <n>` | Retries for pages that fail to load |
| `--fail-on <level>` | error (default), warning, info or never |
| `--shard <i/n>` | Run part i of n (for parallel CI jobs) |
| `--changed [ref]` | Only routes affected by files changed since ref (default: the pull request base or main) |
| `--new-only` | Fail only on findings that are not in the baseline |
| `--update-baseline` | Write the baseline from this run's findings |
| `--project <name>` | Only this monorepo project (repeatable) |
| `--crawl` | Also test same-origin links found on pages |
| `--sitemap` | Also test routes listed in /sitemap.xml |
| `--no-cache` | Discover routes again instead of using the cache |
| `--watch` | Keep the app running and test the routes each change affects |
| `--headed` | Show the browser |

## `baseline`

Tests the app and records every finding in the baseline file (`ci.baseline`,
by default `.hydration-proof/baseline.json`). Afterwards,
`hydration-proof test --new-only` fails only on findings that are not in it.

```bash
npx hydration-proof baseline
npx hydration-proof test --new-only
```

Entries keep the date they were first seen. Add `reason` and `expires`
(YYYY-MM-DD) to an entry by hand: they are kept when the baseline is written
again, and an expired entry fails the run. [Baselines and budgets](https://hydration.jscrate.dev/docs/baselines)
covers adopting hydration-proof on an app with known problems.

Takes the same options as `test`.

## `merge-reports`

Combines the reports of parallel CI jobs (`--shard`) into one. Each argument is
a report folder or a `report.json` file, and screenshots are copied next to the
merged report.

```bash
npx hydration-proof merge-reports shards/1 shards/2 shards/3 --output .hydration-proof/report
```

With `--config`, the config's CI policy (`failOn`, budgets, ignore rules)
decides the exit code. See [CI](https://hydration.jscrate.dev/docs/ci) for a sharded workflow.

| Option | What it does |
| --- | --- |
| `-o, --output <dir>` | Where the merged reports go (default: .hydration-proof/report) |
| `--reporter <list>` | Comma-separated reporters (default: list,json,html) |
| `-c, --config <file>` | Config for the CI policy (failOn, budgets, ignore rules) |
| `--fail-on <level>` | error (default), warning, info or never |

## `dev`

Opens your app in a browser window with a hydration overlay. It starts the
development server for you (or uses `--url`), and every page you open is
checked: findings appear in the overlay and in the terminal.

```bash
npx hydration-proof dev
npx hydration-proof dev --route /dashboard --mode production
```

From the overlay you can highlight the element, open the source file in your
editor and copy a report. The editor comes from `HYDRATION_PROOF_EDITOR`,
`VISUAL` or `EDITOR`, or the first of `cursor`, `code`, `windsurf`, `zed`,
`webstorm`, `idea` or `subl` found on `PATH`. See the
[dev overlay](https://hydration.jscrate.dev/docs/dev-overlay).

| Option | What it does |
| --- | --- |
| `-c, --config <file>` | Config file |
| `-u, --url <url>` | Use an app that is already running |
| `-r, --route <path>` | Page to open first (default: the first configured route, or /) |
| `-s, --scenario <name>` | Scenario to browse in (default: the first one) |
| `--mode <mode>` | development (default) or production |
| `--browser <name>` | chromium (default), firefox or webkit |
| `--channel <name>` | Use an installed browser, e.g. chrome |

## `ui`

Starts a local dashboard: run tests from the browser, follow their output and
read the latest report. It listens on `127.0.0.1` only, and the printed URL
contains an access token that every request needs.

```bash
npx hydration-proof ui --open
```

| Option | What it does |
| --- | --- |
| `-c, --config <file>` | Config file |
| `-p, --port <port>` | Port (default: a free port) |
| `--open` | Open the dashboard in the default browser |

## `init`

Creates `hydration-proof.config.ts` for your project and ignores the report
folder in git. With `--ci github` it also writes
`.github/workflows/hydration.yml`; with `--ci gitlab`, `.gitlab/hydration-proof.yml`.

```bash
npx hydration-proof init
npx hydration-proof init --ci github
```

The config it writes sets `reporters: ['list', 'json']`. Without that option,
the default is `list`, `json` and `html`. Existing files are only overwritten
with `--force`.

| Option | What it does |
| --- | --- |
| `--ci <provider>` | Also write a CI workflow: github (.github/workflows/hydration.yml) or gitlab (.gitlab/hydration-proof.yml) |
| `--force` | Overwrite existing files |

## `migrate`

Checks a config written for an older version and lists the options that were
renamed or replaced. It reads the config without validating it.

```bash
npx hydration-proof migrate
npx hydration-proof migrate --write
```

```text
2 changes for hydration-proof.config.ts
  server.start → server.command
    The start command is `server.command`.
  normalize.maskText → redact.patterns
    Text masking is now redaction (it applies to every report). Move the patterns to `redact: { patterns: [...] }`.
```

`--write` applies the renames that are safe and keeps the old file as
`<file>.backup`. A key is only renamed when it appears exactly once in the
file, so a `start` inside `projects` or a `"[data-start]"` selector is never
touched. Anything that needs a judgment call is listed as a change to make by
hand. The exit code is 0 when the config is current or the changes were
reported, and 2 when there is no config file or it has options this version
does not know.

| Option | What it does |
| --- | --- |
| `-c, --config <file>` | Config file |
| `--write` | Change the file (a copy is kept as <file>.backup) |

## `install`

Downloads the browsers hydration-proof drives, using the same Playwright version
it runs with. Chromium is the default.

```bash
npx hydration-proof install
npx hydration-proof install chromium firefox webkit
npx hydration-proof install --with-deps   # Linux CI: also system dependencies
```

Browsers go into Playwright's shared cache, so a project that already uses the
same Playwright version does not download them again.

| Option | What it does |
| --- | --- |
| `--with-deps` | Also install system dependencies (Linux CI) |

## `doctor`

Checks Node.js, Playwright, the browsers, the config file and framework
detection. Run it first when something does not start; the
[troubleshooting](https://hydration.jscrate.dev/docs/troubleshooting) page covers the common failures.

```bash
npx hydration-proof doctor
```

No options.

## Exit codes

| Code  | Meaning                                                                                                         |
| ----- | --------------------------------------------------------------------------------------------------------------- |
| `0`   | Every page passed                                                                                               |
| `1`   | The run failed: issues at or above `--fail-on`, too many warnings, a budget exceeded, or an expired ignore rule |
| `2`   | Invalid configuration or command-line usage                                                                     |
| `3`   | The app could not be built, started or reached                                                                  |
| `4`   | The browser is not installed or could not start                                                                 |
| `70`  | Internal error (please report it)                                                                               |
| `130` | Interrupted                                                                                                     |

`dev`, `ui` and `test --watch` exit with `0` when you stop them with Ctrl+C.
These values are stable: see [compatibility](https://hydration.jscrate.dev/docs/compatibility).

## Running it with pnpm, Yarn or Bun

The binary is installed into your project, so each package manager runs the
local copy:

| npm                        | pnpm                             | Yarn                        | Bun                         |
| -------------------------- | -------------------------------- | --------------------------- | --------------------------- |
| `npx hydration-proof test` | `pnpm exec hydration-proof test` | `yarn hydration-proof test` | `bunx hydration-proof test` |

## Related

- [Configuration](https://hydration.jscrate.dev/docs/configuration): every option the flags override
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci) with sharding and merged reports
- [Choose which routes are tested](https://hydration.jscrate.dev/docs/routes)
- [Exit codes and what stays stable](https://hydration.jscrate.dev/docs/compatibility)
- [Quick start](https://hydration.jscrate.dev/docs/quick-start)

---

# Configuration

> Every hydration-proof config option: the file, defineConfig, and the server, routes, scenarios, matrix, probes, ready, checks, ignore, CI and hooks settings.

Source: https://hydration.jscrate.dev/docs/configuration
Last updated: 2026-09-18

The hydration-proof config is optional: the framework, the build and start
commands and the routes are detected. When you need to change something, write
a TypeScript file that exports `defineConfig({ ... })`. Every option has a
default, and command-line flags override the file.

## The hydration-proof config file

hydration-proof reads the first of these files it finds in the directory it
runs in: `hydration-proof.config.{ts,mts,js,mjs,cjs,json}`.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    dynamic: { "/products/[id]": ["1", "42"] },
  },
});
```

- **TypeScript is loaded by Node.js itself**, with no extra tooling (it needs
  Node.js 22.18 or newer). Use plain types only: no `enum`, no `namespace` and
  no parameter properties. Relative imports need their file extension
  (`./routes.ts`).
- **`defineConfig`** returns the object unchanged. It is there for type
  checking and completion.
- **Unknown options are errors**, with a suggestion when the name looks like a
  typo ("is not a known option. Did you mean ...?").
- **`configVersion`** is optional and currently always `1`. Setting it lets a
  future version that changes the format migrate the file instead of guessing.
- **An older config** is updated with `hydration-proof migrate` (see the
  [CLI](https://hydration.jscrate.dev/docs/cli#migrate)).

For a JSON config, point `$schema` at the schema in the package to get
completion in your editor:

```json title="hydration-proof.config.json"
{
  "$schema": "./node_modules/hydration-proof/schema/config.json",
  "routes": { "exclude": ["/api/**", "/admin/**"] }
}
```

The same schema is published at `https://hydration.jscrate.dev/schema/config.json`.

## `server`

How the app is built and started, or the URL of one that is already running.
The adapter supplies the commands, so most apps leave this out. `{port}` in a
command is replaced with the chosen port, which is also passed as `PORT`. The
app, and everything it spawned, is stopped when the run ends.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  server: {
    build: "pnpm build",
    command: "pnpm start --port {port}",
    // Build only when there is no build output yet; "always" in CI
    buildWhen: "if-missing",
    env: { NEXT_PUBLIC_API_URL: "http://localhost:4000" },
    timeout: 180_000,
  },
});
```

To test an app you started yourself, set `url` (or pass `--url`): nothing is
built or started. `mode: "both"` tests the production build and the
development server (`devCommand`) in one run.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `command` | `string` | the adapter's start command | Command that starts the app. `{port}` is replaced with the chosen port. |
| `build` | `string \| false` | the adapter's build command | Command that builds the app for production. `false` never builds. |
| `buildWhen` | `"always" \| "if-missing" \| "never"` | `"if-missing"` | Build before testing: always, only when no build output exists, or never. |
| `url` | `string` | — | URL of an app that is already running. When set, nothing is started. |
| `port` | `number` | a free port | Port for the started app. |
| `cwd` | `string` | the config file's directory | Working directory for the commands. |
| `env` | `Record<string, string>` | — | Extra environment variables for the app. |
| `timeout` | `number` | 120000 | Milliseconds to wait for the app to answer. |
| `reuseExisting` | `boolean` | `true` outside CI | Use an app already listening on the URL instead of starting one. |
| `mode` | `BuildMode \| "both"` | `"production"` | Test the production build, the dev server, or both (and compare). |
| `devCommand` | `string` | the adapter's dev command | Development server command when both modes are tested. |

## `routes`

Which pages are tested. Without `paths`, routes are discovered from the
framework and the build output. Dynamic routes need example values, or they are
skipped. [Routes](https://hydration.jscrate.dev/docs/routes) explains every source, the glob syntax and the
route cache.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    discover: true,
    // Routes discovery cannot see: redirects, rewrites, anything behind a flag
    paths: ["/pricing?plan=team"],
    // One real value per dynamic segment, or the route is skipped
    dynamic: {
      "/blog/[slug]": ["hello-world"],
      "/products/[id]": ["1", "42"],
    },
    exclude: ["/api/**", "/admin/**"],
    sitemap: true,
  },
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `paths` | `(string \| RouteEntry)[]` | `["/"]` when discovery is off | Routes to test. Strings are paths. |
| `dynamic` | `Record<string, string[]>` | — | Example values for dynamic segments, e.g. `{ "/products/[id]": ["1", "42"] }`. |
| `include` | `string[]` | — | Glob patterns (`*`, `**`) a route must match. |
| `exclude` | `string[]` | — | Glob patterns of routes to skip. |
| `discover` | `boolean` | `true` when `paths` is empty | Find routes from the framework (Next.js app/ and pages/, plus build manifests). |
| `query` | `Record<string, string[]>` | — | Query-string variants per route pattern, e.g. `{ "/search": ["?q=shoes", "?q=&page=2"] }`. |
| `sitemap` | `boolean \| string` | — | Read routes from the sitemap: `true` for /sitemap.xml (and robots.txt), or a sitemap URL/path. |
| `crawl` | `boolean \| CrawlConfig` | — | Follow same-origin links found on tested pages. |
| `notFound` | `boolean` | `true` for Next.js | Also test a URL that does not exist, to check the not-found page hydrates. |
| `manifestExamples` | `number` | 3 | Most example values taken per dynamic route from build manifests. |

## `scenarios`

The browser environments every route is tested in. By default there is one
scenario, `default`, that uses this machine's locale and timezone and a light
color scheme, so a server started on the same machine renders with the same
values. Scenarios also carry cookies, storage and a `login` function for
signed-in pages; see [scenarios](https://hydration.jscrate.dev/docs/scenarios).

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  scenarios: [
    { name: "default" },
    { name: "dark-mobile", colorScheme: "dark", viewport: "mobile" },
    { name: "karachi", locale: "ur-PK", timezoneId: "Asia/Karachi" },
  ],
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Unique name, shown in reports and used by `--scenario`. |
| `locale` | `string` | this machine's locale | BCP 47 locale for the browser (also sets Accept-Language). |
| `timezoneId` | `string` | this machine's timezone | IANA timezone for the browser, e.g. `Asia/Karachi`. |
| `colorScheme` | `ColorScheme` | `"light"` | Emulated `prefers-color-scheme`: `"light"`, `"dark"` or `"no-preference"`. |
| `reducedMotion` | `"reduce" \| "no-preference"` | — | Emulated `prefers-reduced-motion`. |
| `viewport` | `ViewportOption` | — | Viewport size as `{ width, height }`, or a preset: `"mobile"` (390×844, touch), `"tablet"` (820×1180) or `"desktop"` (1280×800). |
| `userAgent` | `string` | — | User agent string for the browser context. |
| `storageState` | `string` | — | Playwright storage state file (cookies and localStorage), e.g. a logged-in user. |
| `cookies` | `CookieConfig[]` | — | Cookies set before every page load, e.g. a session cookie for a signed-in user. |
| `headers` | `Record<string, string>` | — | Extra request headers. |
| `localStorage` | `Record<string, string>` | — | `localStorage` entries set before page scripts run. |
| `sessionStorage` | `Record<string, string>` | — | `sessionStorage` entries set before page scripts run. |
| `initScripts` | `string[]` | — | Scripts run before page scripts (code strings). |
| `login` | `(context: LoginContext) => Promise<void>` | — | Sign in once before this scenario's pages are tested. The cookies and storage it leaves behind are used for every page. |
| `mocks` | `MockConfig[]` | — | Answers for browser requests (API fixtures). Server-side requests are not affected. |
| `include` | `string[]` | — | Only test routes matching these globs in this scenario. |
| `exclude` | `string[]` | — | Skip routes matching these globs in this scenario. |
| `query` | `Record<string, string>` | — | Query parameters added to every URL (e.g. `{ currency: 'EUR' }`). |
| `browser` | `BrowserName` | `browser.name` | Browser for this scenario. |
| `network` | `NetworkProfile` | — | Throttle the network: `"fast-3g"`, `"slow-3g"` or `{ downloadKbps, uploadKbps, latencyMs }`. Chromium throttles natively; Firefox and WebKit delay subresources instead. |
| `cpu` | `number` | — | Slow down JavaScript by this factor (Chromium only). |
| `cache` | `CacheState` | `cold` | `warm` loads the page once before testing it, like a returning visitor. |
| `clock` | `string \| number` | — | Fixed browser time (ISO string or epoch ms) for `Date.now()` / `new Date()`. A diagnostic option: the server keeps its real clock, so time-dependent output is still found. |
| `randomSeed` | `number` | — | Seed for `Math.random()` and `crypto.getRandomValues()` in the browser (diagnostic, like `clock`). |

## `matrix`

Tests every scenario in combinations of environments, so a problem that only
shows up in one locale, timezone, theme, screen size or browser is found.
Pairwise selection (the default) tests every pair of values at least once with
few combinations. The [environment matrix](https://hydration.jscrate.dev/docs/environment-matrix) guide has
the details and the limits of each browser.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  matrix: {
    locale: ["en-US", "de-DE", "ar-EG"],
    timezoneId: ["UTC", "Asia/Karachi", "America/Los_Angeles"],
    colorScheme: ["light", "dark"],
    viewport: ["desktop", "mobile"],
    // Custom axes: feature flags, tenants, currencies
    axes: {
      checkout: {
        new: { cookies: [{ name: "flag-checkout", value: "new" }] },
        old: {},
      },
    },
  },
});
```

The first value of every axis is the baseline and is always tested.
`--no-matrix` tests the scenarios as configured.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` | `string[]` | — | Locales to test, e.g. `['en-US', 'de-DE', 'ar-EG']`. |
| `timezoneId` | `string[]` | — | Timezones to test, e.g. `['UTC', 'Asia/Karachi', 'America/Los_Angeles']`. |
| `colorScheme` | `ColorScheme[]` | — | Color schemes to test, e.g. `['light', 'dark']`. |
| `reducedMotion` | `("reduce" \| "no-preference")[]` | — | Reduced-motion settings to test. |
| `viewport` | `ViewportOption[]` | — | Viewports to test: sizes or the presets `mobile`, `tablet`, `desktop`. |
| `browser` | `BrowserName[]` | — | Browsers to test: `chromium`, `firefox`, `webkit`. |
| `network` | `NetworkProfile[]` | — | Network profiles to test: `fast` (no throttling), `fast-3g`, `slow-3g` or custom. |
| `cpu` | `number[]` | — | CPU slowdown factors (Chromium only); `1` is no slowdown. |
| `cache` | `CacheState[]` | — | Cache states to test: `cold` and `warm`. |
| `axes` | `Record<string, Record<string, ScenarioVariant>>` | — | Custom axes: axis name → value name → scenario settings. `{ flags: { 'new-checkout': { cookies: [{ name: 'flag', value: 'on' }] }, 'old-checkout': {} } }` |
| `strategy` | `"pairwise" \| "full" \| "sample"` | — | `pairwise` (default) covers every pair of values, `full` every combination, `sample` a random subset. |
| `max` | `number` | 16 | Most environments per scenario. |
| `seed` | `number` | 1 | Seed for `sample`. |
| `scenarios` | `string[]` | all | Scenarios the matrix applies to. |

## `probes`

`probes: true` (or `--probe`) proves the cause of value mismatches. Pages with
text or attribute differences are loaded again with one thing changed at a
time: the clock, the random seed, the locale, the timezone, the theme, the
viewport or storage. Each probed page costs up to 9 extra page loads, so probes
are off by default. See [probes](https://hydration.jscrate.dev/docs/probes).

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  probes: { factors: ["time", "random"], maxPages: 5 },
  // Load every page 3 times and mark findings seen in only some runs as flaky
  repeat: 3,
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `factors` | `ProbeFactor[]` | all that apply | What to vary. |
| `maxPages` | `number` | 5 | Most pages probed per run. |

## `ready`

When a page counts as settled before the final snapshot. hydration-proof never
waits for "network idle": it waits for a quiet period without DOM changes or
React commits. For pages with animations, polling or live data that never go
quiet, set a `selector` or a `function`, or lower `quietMs`.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ready: {
    quietMs: 400,
    selector: "[data-page-ready]",
    // A page function, as a string, that must return a truthy value
    function: "() => window.__APP_READY__ === true",
  },
});
```

A route can override these with its own `ready` (see [routes](https://hydration.jscrate.dev/docs/routes)).

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `quietMs` | `number` | 400 | Quiet time (ms) without DOM changes or React commits before the page counts as settled. |
| `timeout` | `number` | 30000 | Maximum time (ms) per page. |
| `hydrationTimeout` | `number` | 15000 | Maximum time (ms) for hydration to finish once React is loaded. |
| `selector` | `string` | — | A selector that must exist before the final snapshot. |
| `function` | `string` | — | Page function source that must return truthy before the final snapshot. |

## `checks`

Turns individual checks on or off. Everything that compares the server HTML
with the hydrated page is on by default. The interaction and navigation checks
load each page several extra times, so they are off until you enable them; see
[interactions and navigation](https://hydration.jscrate.dev/docs/interactions), which also covers the
top-level `interactions` option for custom Playwright steps.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  checks: {
    // Also flag suppressHydrationWarning that hides nothing
    suppressedWarnings: "strict",
    interactions: true,
    navigation: { from: "/", maxRoutes: 10 },
  },
});
```

| Check                | Finds                                                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reactErrors`        | Errors and warnings React reports (HP2xxx)                                                                                                          |
| `domDiff`            | DOM differences React produced while hydrating, in the root and in every Suspense boundary (HP1xxx), and `<head>` values hydration changed (HP1014) |
| `propsAudit`         | Attributes and text that differ from what React renders on the client, including the ones React never reports, and events handled twice (HP5006)    |
| `invalidHtml`        | Markup the browser repairs, duplicate ids and useId collisions between React roots (HP3xxx)                                                         |
| `externalChanges`    | Changes made by other scripts before hydration (HP4xxx)                                                                                             |
| `suppressedWarnings` | Differences hidden by `suppressHydrationWarning` (`"info"`), plus unused suppression (`"strict"`)                                                   |

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `reactErrors` | `boolean` | true | Collect React hydration errors and warnings. |
| `domDiff` | `boolean` | true | Compare the DOM before and after hydration. |
| `propsAudit` | `boolean` | true | Compare attributes and text with what React renders on the client. |
| `invalidHtml` | `boolean` | true | Check the server HTML for markup the browser has to repair. |
| `externalChanges` | `boolean` | true | Detect changes made by other scripts before hydration. |
| `suppressedWarnings` | `"off" \| "info" \| "strict"` | `"info"` | How to treat suppressHydrationWarning: report suppressed differences as info, or also flag unused suppression. |
| `interactions` | `boolean` | false | Type, click, focus and scroll while the page loads and check nothing is lost. |
| `navigation` | `boolean \| NavigationConfig` | false | Compare client-side navigation to each route with loading it directly (Next.js). |

## `ignore`

Findings to leave out. Ignored findings stay in the report, marked as ignored,
and do not fail the run. An `issues` rule needs a `reason`, and a rule past its
`expires` date fails the run, so a temporary exception cannot become permanent.
[Ignoring findings](https://hydration.jscrate.dev/docs/ignoring) covers when to use each kind.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    // Third-party markup that is expected to differ
    selectors: ["#ad-slot", "[data-chat-widget]"],
    attributes: [/^data-gtm-/],
    issues: [
      {
        code: "HP4001",
        route: "/checkout",
        reason: "The payment iframe rewrites its container. Ticket ACME-431.",
        expires: "2026-12-31",
      },
    ],
  },
});
```

`[data-hydration-proof-ignore]` is always in `selectors`, so you can also mark
an element in your markup.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `selectors` | `string[]` | — | Elements whose subtree is not compared. `[data-hydration-proof-ignore]` is always included. |
| `attributes` | `(string \| RegExp)[]` | — | Attribute names (or patterns) that are never compared. |
| `textPatterns` | `RegExp[]` | — | Text differences are ignored when both values are equal after removing these patterns. |
| `issues` | `IgnoreRule[]` | — | Ignore specific findings. |

## `ci`

When the run fails: the lowest failing severity, a warning limit, a baseline of
accepted findings, budgets and a history file for trends.
[Baselines and budgets](https://hydration.jscrate.dev/docs/baselines) explains how to adopt hydration-proof
on an app that already has findings.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ci: {
    failOn: "warning",
    maxWarnings: 10,
    newIssuesOnly: true,
    budget: {
      warning: 5,
      codes: { HP1004: 3 },
      routes: { "/legacy/**": { error: 2 } },
    },
    history: true,
  },
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `failOn` | `Severity \| "never"` | `"error"` | Lowest severity that makes the run fail. |
| `maxWarnings` | `number` | — | Fail when more warnings than this are found. |
| `baseline` | `string` | `.hydration-proof/baseline.json` | Baseline file of accepted issues. |
| `newIssuesOnly` | `boolean` | — | Only fail on issues that are not in the baseline. |
| `budget` | `BudgetConfig` | — | Hydration error budget: how many findings of a severity (in total, per route glob or per code) are allowed before the run fails. |
| `history` | `boolean \| string` | — | Append a line per run to a history file for trends: `true` for `.hydration-proof/history.ndjson`, or a path. |

## `hooks`

Code that runs around the test run, after the app is up. `setup` runs once per
build mode, before any page is tested and before the scenario logins, and may
return a teardown function. Teardown functions always run, even when testing
fails. An error in `setup` stops the run. There are only these two hooks; sign-in
belongs in a scenario's `login`.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  hooks: {
    // Seed data or create users. May return a teardown function.
    setup: async ({ baseUrl }) => {
      await fetch(`${baseUrl}/api/test/seed`, { method: "POST" });
      return async () => {
        await fetch(`${baseUrl}/api/test/reset`, { method: "POST" });
      };
    },
  },
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `setup` | `(context: HookContext) => Promise<void \| (() => Promise<void> \| void)> \| void \| (() => Promise<void> \| void)` | — | Runs once after the app is up and before any page is tested (seed a database, create users). May return a teardown function. |
| `teardown` | `(context: HookContext) => Promise<void> \| void` | — | Runs once after all pages are tested. |

## `owners`

Who owns a finding. Owners come from route globs in the config and from the
CODEOWNERS entries of the source files, and they are shown in every report and
can be filtered in the HTML report.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  owners: {
    routes: { "/checkout/**": ["@acme/payments"] },
    codeowners: true,
  },
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `routes` | `Record<string, string \| string[]>` | — | Route glob → owners, e.g. `{ '/checkout/**': ['@acme/payments'] }`. |
| `codeowners` | `boolean \| string` | — | Owners of source files from CODEOWNERS: `true` (default) looks in .github/, docs/ and the repository root; or a path. |

## Other options

The table lists every top-level option, including the ones above:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `$schema` | `string` | — | JSON Schema for editor completion in a JSON config, e.g. `./node_modules/hydration-proof/schema/config.json`. |
| `configVersion` | `1` | — | Config format version. |
| `adapter` | `"auto" \| "next" \| "react-router" \| "remix" \| "astro" \| "vite" \| "node" \| "none" \| (string & {}) \| Adapter` | `"auto"` | Framework adapter. `"auto"` detects it from `package.json` and config files; or name one: `"next"`, `"react-router"`, `"remix"`, `"astro"`, `"vite"`, `"node"`, `"none"`, a plugin adapter, or an adapter from `defineAdapter()`. |
| `plugins` | `HydrationProofPlugin[]` | — | Plugins: adapters, normalizers, cause detectors, reporters and route providers. |
| `server` | `ServerConfig` | — | How the app is built and started, or the URL of one already running. See [server](https://hydration.jscrate.dev/docs/configuration#server). |
| `routes` | `RoutesConfig` | — | Which pages are tested: discovered, listed, from the sitemap or crawled. See [routes](https://hydration.jscrate.dev/docs/routes). |
| `scenarios` | `ScenarioConfig[]` | one scenario named `default`, using this machine's locale and timezone and a light color scheme | Environments every route is tested in: locale, timezone, theme, viewport, cookies, signed-in state. See [scenarios](https://hydration.jscrate.dev/docs/scenarios). |
| `ready` | `ReadyConfig` | — | When a page counts as settled before the final snapshot. See [ReadyConfig](https://hydration.jscrate.dev/docs/configuration#ready). |
| `browser` | `BrowserConfig` | `{ name: "chromium", headless: true }` | Which browser runs the pages. |
| `workers` | `number` | half the CPU cores, at most 4 | Pages tested in parallel. |
| `retries` | `number` | 0 (1 on CI) | Retries for pages that failed to load. |
| `checks` | `ChecksConfig` | — | Turn individual checks on or off. See [checks](https://hydration.jscrate.dev/docs/configuration#checks). |
| `ignore` | `IgnoreConfig` | — | Selectors, attributes, text patterns and findings to leave out. See [ignoring findings](https://hydration.jscrate.dev/docs/ignoring). |
| `reporters` | `ReporterName[]` | `["list", "json", "html"]`, plus `github` inside GitHub Actions | Output formats: `list`, `json`, `html`, `junit`, `sarif`, `github`, `gitlab`. See [reports](https://hydration.jscrate.dev/docs/reports). |
| `outputDir` | `string` | `.hydration-proof/report` | Where reports are written. |
| `screenshots` | `"failures" \| "all" \| "off"` | `"failures"` when the `html` reporter is on, otherwise `"off"` | Screenshots for the HTML report: of failing pages (`"failures"`), of every page (`"all"`), or none (`"off"`). |
| `ci` | `CiConfig` | — | When the run fails: severity, baselines, budgets and history. See [baselines and budgets](https://hydration.jscrate.dev/docs/baselines). |
| `hooks` | `HooksConfig` | — | Code that runs once before the first page (`setup`) and after the last (`teardown`). |
| `cache` | `boolean` | true | Cache discovered routes between runs (keyed by build). |
| `matrix` | `MatrixConfig` | — | Test every scenario in combinations of environments. |
| `probes` | `boolean \| ProbesConfig` | false | Prove causes: pages with value mismatches are loaded again with one thing changed (clock, random seed, locale, timezone, theme, viewport, storage). |
| `repeat` | `number` | 1 | Load every page this many times and report flaky issues. |
| `interactions` | `InteractionConfig[]` | — | Custom interactions to run on routes (before or after hydration). |
| `owners` | `OwnersConfig` | — | Who owns findings: route owners and CODEOWNERS. |
| `redact` | `boolean \| RedactConfig` | true | Remove secrets and personal data from reports. |
| `projects` | `(string \| ProjectConfig)[]` | — | Monorepo: test these projects (each has its own config) in one run. |
| `sourceOrigins` | `string[]` | — | Extra origins scripts and source maps may be fetched from, for apps that serve assets from a CDN. The app's own origin is always allowed. |

### `adapter` and `plugins`

`adapter` is `"auto"` by default: it is chosen from `package.json` and the
framework's config files. Name one to override it, or pass your own from
`defineAdapter()`. Plugins add normalizers, cause detectors, route providers,
reporters and adapters. See [adapters](https://hydration.jscrate.dev/docs/adapters) and
[plugins](https://hydration.jscrate.dev/docs/plugins).

### `browser`

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `BrowserName` | `"chromium"` | `chromium`, `firefox` or `webkit`. |
| `channel` | `string` | — | Installed browser channel, e.g. `chrome` or `msedge`. |
| `headless` | `boolean` | `true` (`--headed` turns it off) | Run the browser without a window. |

### `redact`

Redaction is on by default: emails, tokens, card numbers and secret URL
parameters are removed from every report. Add patterns, black out elements in
screenshots, or set `redact: false` to keep everything. See
[security](https://hydration.jscrate.dev/docs/security).

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `builtIn` | `boolean` | true | Remove emails, tokens, card numbers and secret URL parameters. |
| `patterns` | `RegExp[]` | — | More text to remove from reports. |
| `selectors` | `string[]` | — | Elements to black out in screenshots. |

### `projects`

A config at the root of a monorepo can list the apps to test. Each app keeps its
own config, and the run writes one combined report. See
[monorepos](https://hydration.jscrate.dev/docs/monorepos).

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  projects: ["apps/web", { path: "apps/admin", name: "admin" }],
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `path` (required) | `string` | — | Folder of the project (with its own hydration-proof config). |
| `name` | `string` | the folder name | Name shown in reports. |
| `config` | `string` | found automatically | Config file inside the folder. |

### `sourceOrigins`

To report a `file:line`, hydration-proof downloads the page's scripts and their
source maps, but only from the app's own origin. If your app serves its bundles
from a CDN, allow that origin too:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  sourceOrigins: ["https://cdn.example.com"],
});
```

Findings are still reported when a source map is skipped, only without a
source location.

## Related

- [The CLI](https://hydration.jscrate.dev/docs/cli): flags that override these options
- [Test every route](https://hydration.jscrate.dev/docs/routes): discovery, dynamic values and globs
- [Scenarios and signed-in pages](https://hydration.jscrate.dev/docs/scenarios)
- [Ignore known findings](https://hydration.jscrate.dev/docs/ignoring) with a reason and an expiry date
- [Run it in CI](https://hydration.jscrate.dev/docs/ci)

---

# Routes

> How to test every route for hydration errors: route discovery per framework, example values for dynamic routes, sitemaps, crawling, globs and the route cache.

Source: https://hydration.jscrate.dev/docs/routes
Last updated: 2026-09-18

To test every route for hydration errors, hydration-proof combines the routes it
discovers from your framework and build output with the paths, dynamic values,
sitemap entries and crawled links you configure. Every page in the report
records where its route came from. A dynamic route needs example values, or it
is skipped with a note.

## Where routes come from

| Source       | Meaning                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `config`     | `routes.paths`, `routes.dynamic` or `--route`                                                  |
| `discovered` | Found by the framework adapter, for example in `app/` or `pages/`                              |
| `manifest`   | Example values of a dynamic route, read from the Next.js build output (including i18n locales) |
| `sitemap`    | Listed in a sitemap                                                                            |
| `crawl`      | Linked from a tested page                                                                      |
| `not-found`  | The not-found probe                                                                            |

`include`, `exclude` and `--grep` apply to routes from every source.

### Discovery for each framework

Discovery is on when you do not list `paths`. The [adapter](https://hydration.jscrate.dev/docs/adapters)
decides where routes come from:

| Adapter                | Routes                                                                                                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `next`                 | `app/` and `pages/`, plus the pages the build pre-rendered. Route groups, parallel routes and private folders are handled; API routes are skipped by the default `exclude` |
| `react-router`         | `react-router routes --json`                                                                                                                                               |
| `remix`                | `remix routes --json`                                                                                                                                                      |
| `astro`                | `src/pages`                                                                                                                                                                |
| `vite`, `node`, `none` | From the config: list them in `routes.paths`                                                                                                                               |

## List routes yourself

`paths` adds routes discovery cannot know about: redirects, rewrites, pages
behind a flag, or every route of a framework without discovery. An entry is a
path string, with an optional query, or an object with more options:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    paths: [
      "/",
      "/pricing?plan=team",
      // A page that is meant to answer 404
      { path: "/404-page", expectStatus: [404], ready: { selector: "#app" } },
      // A page that is meant to redirect
      { path: "/account", expectRedirect: "/login" },
      // Only in one scenario
      { path: "/admin", scenarios: ["admin"] },
    ],
  },
});
```

- `expectStatus` lists HTTP statuses that are not errors for the route.
- `expectRedirect` is the path the route should end on. Without it, a page that
  ends on another path is reported as [HP9010](https://hydration.jscrate.dev/docs/issues/hp9010).
- `ready` overrides the [`ready` options](https://hydration.jscrate.dev/docs/configuration#ready) for this
  route, for example a page that never goes quiet.
- `scenarios` limits the route to some [scenarios](https://hydration.jscrate.dev/docs/scenarios).

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `path` (required) | `string` | — | Path, e.g. `/pricing` or `/products/42?tab=reviews`. |
| `expectRedirect` | `string` | — | The final URL (path) the route must redirect to. Other redirects are reported. |
| `pattern` | `string` | the path without query | Route pattern used for grouping and fingerprints. |
| `expectStatus` | `number[]` | — | HTTP statuses that are not errors for this route (e.g. `[404]`). |
| `scenarios` | `string[]` | — | Only test in these scenarios. |
| `ready` | `ReadyConfig` | — | Per-route readiness overrides. |
| `navigateFrom` | `string` | `checks.navigation.from` | Page the navigation check starts from for this route. |

## Dynamic routes

A route like `/products/[id]` has nothing to render until it has a value. Give
it example values in `dynamic`:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    dynamic: {
      "/products/[id]": ["1", "42"],
      // Several parameters: separate the values with "/";
      // a catch-all takes the rest
      "/[lang]/docs/[...slug]": ["en/getting-started/install"],
    },
  },
});
```

One syntax works for every framework: `[id]`, `[...slug]` (catch-all) and
`[[lang]]` (optional). React Router's `:id`, `*` and `:lang?`, and Astro's
`[id]` and `[...slug]`, are converted, so `routes.dynamic` looks the same
everywhere.

For Next.js, pages the build pre-rendered with `generateStaticParams` or
`getStaticPaths` are tested without any config: up to `manifestExamples` values
(3 by default) are taken per dynamic route from the build output. Dynamic
routes that end up with no values are skipped, and the run lists them in a note.

## Query-string variants

When a page renders differently for a query string, test each variant:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    query: { "/search": ["?q=shoes", "?q=&page=2"] },
  },
});
```

## Routes from the sitemap

`sitemap: true` (or `--sitemap`) also tests the routes in your sitemap. It reads
the `Sitemap:` lines of `robots.txt` and `/sitemap.xml`; you can also give a
sitemap URL or path. Sitemap indexes are followed, and absolute URLs are moved to
the tested app, so a sitemap that names `https://example.com` still works
locally.

## Crawl links from tested pages

`crawl: true` (or `--crawl`) also tests same-origin links found on the tested
pages, to a depth of 2 and at most 50 routes. Pass `{ depth, limit }` to change
that. Crawled links are grouped under the most specific known route pattern, and
crawling never leaves the app's origin.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `depth` | `number` | 2 | Link depth from the start routes. |
| `limit` | `number` | 50 | Maximum number of crawled routes. |

## The not-found page

For Next.js, `notFound` is on: hydration-proof also loads
`/hydration-proof-not-found` and checks that your not-found page hydrates. That
URL must answer with a 404. Set `notFound: false` to skip it.

## Include and exclude routes with globs

`include` and `exclude` take globs, matched against the route's path:

- `*` matches one path segment.
- `**` matches any number of segments, and `/blog/**` also matches `/blog`.
- `exclude` defaults to `["/api/**"]`. Setting it replaces that default, so
  keep `/api/**` in your list.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    include: ["/", "/blog/**", "/products/*"],
    exclude: ["/api/**", "/admin/**"],
  },
});
```

Scenarios have their own `include` and `exclude`, for pages only one identity
can open.

## Choose routes on the command line

```bash
# Only these routes; discovery, the sitemap and the not-found probe are off
npx hydration-proof test --route / --route /pricing

# Only routes whose path matches a regular expression
npx hydration-proof test --grep "^/blog"

# Also the sitemap, and links found on tested pages
npx hydration-proof test --sitemap --crawl

# Only the routes the files changed since main can affect
npx hydration-proof test --changed main
```

`--grep` applies to routes from every source. `--changed` reads an import graph
of your sources; see [CI](https://hydration.jscrate.dev/docs/ci) for how it picks routes.

## The route cache

Discovered routes are cached in `.hydration-proof/cache/routes.json`. The cache
key covers the Next.js build id and the modification times of the route
folders, so a new build or a changed route folder invalidates it. Sitemap and
crawled routes are never cached.

If a new page is missing, run with `--no-cache`, or set `cache: false` in the
config to always discover again:

```bash
npx hydration-proof test --no-cache
```

## How to test every route for hydration errors in a Next.js app

This config, from the package's examples, is what most Next.js apps end up
with after the first run: discovery, one real value per dynamic segment, and
the routes that are not pages.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    discover: true,
    // Routes discovery cannot see: redirects, rewrites, anything behind a flag
    paths: ["/pricing?plan=team"],
    // One real value per dynamic segment, or the route is skipped
    dynamic: {
      "/blog/[slug]": ["hello-world"],
      "/products/[id]": ["1", "42"],
    },
    exclude: ["/api/**", "/admin/**"],
  },
});
```

## All route options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `paths` | `(string \| RouteEntry)[]` | `["/"]` when discovery is off | Routes to test. Strings are paths. |
| `dynamic` | `Record<string, string[]>` | — | Example values for dynamic segments, e.g. `{ "/products/[id]": ["1", "42"] }`. |
| `include` | `string[]` | — | Glob patterns (`*`, `**`) a route must match. |
| `exclude` | `string[]` | — | Glob patterns of routes to skip. |
| `discover` | `boolean` | `true` when `paths` is empty | Find routes from the framework (Next.js app/ and pages/, plus build manifests). |
| `query` | `Record<string, string[]>` | — | Query-string variants per route pattern, e.g. `{ "/search": ["?q=shoes", "?q=&page=2"] }`. |
| `sitemap` | `boolean \| string` | — | Read routes from the sitemap: `true` for /sitemap.xml (and robots.txt), or a sitemap URL/path. |
| `crawl` | `boolean \| CrawlConfig` | — | Follow same-origin links found on tested pages. |
| `notFound` | `boolean` | `true` for Next.js | Also test a URL that does not exist, to check the not-found page hydrates. |
| `manifestExamples` | `number` | 3 | Most example values taken per dynamic route from build manifests. |

## Related

- [Scenarios and signed-in pages](https://hydration.jscrate.dev/docs/scenarios)
- [Frameworks and adapters](https://hydration.jscrate.dev/docs/adapters): how each one discovers routes
- [Configuration reference](https://hydration.jscrate.dev/docs/configuration)
- [Split the routes across CI jobs](https://hydration.jscrate.dev/docs/ci)
- [HP9010: a page ended on an unexpected URL](https://hydration.jscrate.dev/docs/issues/hp9010)

---

# Scenarios and sign-in

> Test signed-in pages for hydration errors with scenarios: locale, timezone, theme and viewport presets, session cookies, storage state, a login and API mocks.

Source: https://hydration.jscrate.dev/docs/scenarios
Last updated: 2026-09-18

To test signed-in pages for hydration errors, give each identity its own
scenario. A scenario is a browser environment (locale, timezone, color scheme,
viewport, cookies, storage) that every route it covers is tested in. A `login`
runs once per scenario, and the cookies and storage it leaves behind are reused
for every page.

## What a scenario is

Without a `scenarios` option, there is one scenario named `default`. It uses
this machine's locale and timezone and a light color scheme, so a server started
on the same machine renders with the same values.

List scenarios to test the environments your users have:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  scenarios: [
    { name: "default" },
    { name: "dark-mobile", colorScheme: "dark", viewport: "mobile" },
    { name: "karachi", locale: "ur-PK", timezoneId: "Asia/Karachi" },
  ],
});
```

Each scenario name is shown in reports. `--scenario <name>` tests only that
scenario, and the flag can be repeated:

```bash
npx hydration-proof test --scenario dark-mobile
```

## Locale, timezone, theme and viewport

| Option          | Values                                                                                                         |
| --------------- | -------------------------------------------------------------------------------------------------------------- |
| `locale`        | A BCP 47 locale such as `"de-DE"`. It also sets the `Accept-Language` header                                   |
| `timezoneId`    | An IANA timezone such as `"Asia/Karachi"`                                                                      |
| `colorScheme`   | `"light"` (default), `"dark"` or `"no-preference"`                                                             |
| `reducedMotion` | `"reduce"` or `"no-preference"`                                                                                |
| `viewport`      | `{ width, height }`, or a preset: `"mobile"` (390×844, touch), `"tablet"` (820×1180) or `"desktop"` (1280×800) |

To test many combinations without writing each one, use the
[environment matrix](https://hydration.jscrate.dev/docs/environment-matrix): it expands every scenario into
combinations of locales, timezones, themes, viewports and browsers.

## Test signed-in pages for hydration errors

Hydration problems hide behind logins: a dashboard that renders a date, an admin
table that reads `localStorage`. There are three ways to sign a scenario in,
cheapest first:

1. **`cookies`:** when the app accepts a session value you can mint for tests.
   There is no browser work, so it costs nothing.
2. **`storageState`:** a file Playwright wrote with
   `context.storageState({ path })`. Use it when you already have a Playwright
   login.
3. **`login`:** a real sign-in through the form. It runs once per scenario, not
   once per page, and whatever cookies and storage it leaves behind are reused.

An `authorization` entry in `headers` works too.

This config tests public, customer and admin pages in one run:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    dynamic: { "/account/orders/[id]": ["1001"] },
  },

  scenarios: [
    // Everything that is not behind a login
    { name: "guest", exclude: ["/account/**", "/admin/**"] },

    // A real sign-in, once, then reused for every page of this scenario
    {
      name: "customer",
      include: ["/account/**"],
      login: async ({ page, baseUrl }) => {
        await page.goto(`${baseUrl}/login`);
        await page.fill("#email", process.env.TEST_USER_EMAIL ?? "");
        await page.fill("#password", process.env.TEST_USER_PASSWORD ?? "");
        await page.click("button[type=submit]");
        await page.waitForURL("**/account");
      },
    },

    // A session the test environment hands out: no browser work at all
    {
      name: "admin",
      include: ["/admin/**"],
      cookies: [{ name: "session", value: process.env.ADMIN_SESSION ?? "" }],
    },
  ],
});
```

Run it with the credentials in the environment:

```sh
TEST_USER_EMAIL=… TEST_USER_PASSWORD=… ADMIN_SESSION=… npx hydration-proof test
```

### How the login runs

- `login` receives `{ page, baseUrl }`: a Playwright page in a browser context
  with the scenario's settings, and the URL of the tested app.
- It runs once per run, after the app is up and after `hooks.setup`.
- A login that throws stops the run with exit code `2` and the error message.
- Cookies without a `domain` apply to the tested app.
- Keep credentials in environment variables, not in the config file, which gets
  committed.

### When a signed-in page ends on the login page

If a page that should be signed in ends on another URL, it gets an
[HP9010](https://hydration.jscrate.dev/docs/issues/hp9010) warning. That usually means the sign-in did not
work: the login did not wait for the page after submitting
(`page.waitForURL`), the session cookie belongs to another domain, or the
cookie or storage state has expired. Run with `--headed --workers 1` to watch
it. If a route is meant to redirect, set `expectRedirect` on it (see
[routes](https://hydration.jscrate.dev/docs/routes)).

## Split public, customer and admin pages

`include` and `exclude` decide which routes a scenario covers, with the same
globs as `routes` (`*` is one segment, `**` any number). A route that no
scenario matches is not tested, so keep one scenario as the default for public
pages, as `guest` is above.

## Mock browser requests

`mocks` answer requests the browser makes with fixed data, so pages that show
changing numbers render the same on every run:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  scenarios: [
    {
      name: "admin",
      cookies: [{ name: "session", value: process.env.ADMIN_SESSION ?? "" }],
      // Admin pages often show data that changes between requests; pin it
      mocks: [{ url: "**/api/metrics", body: { signups: 12, revenue: 3400 } }],
    },
  ],
});
```

`url` is a glob or a RegExp, and object bodies are sent as JSON. Only browser
requests are answered: requests your server makes while rendering are not
affected. Mocks turn the browser's HTTP cache off.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `url` (required) | `string \| RegExp` | — | URL glob (`**` and `*`) or RegExp of browser requests to answer. |
| `method` | `string` | — | Only answer requests with this HTTP method. |
| `status` | `number` | `200` | Response status. |
| `headers` | `Record<string, string>` | — | Response headers. |
| `body` | `unknown` | — | Response body; objects are sent as JSON. |

## Seed data before the pages load

To create users or seed a database, use `hooks.setup` in the
[config](https://hydration.jscrate.dev/docs/configuration#hooks). It runs once per build mode, after the app
is up and before the scenario logins, and may return a teardown function. Sign-in
itself belongs in a scenario's `login`: there is no global setup hook.

## Fixed clock and random values

`clock` fixes the browser time for `Date.now()` and `new Date()`, and
`randomSeed` seeds `Math.random()` and `crypto.getRandomValues()` in the
browser. Both are diagnostic: they make the client values repeatable between
runs, but the server keeps its real clock, so time-dependent and random output
is still found. To prove that the clock or randomness causes a finding, use
[probes](https://hydration.jscrate.dev/docs/probes).

## More scenario options

- `headers`: extra request headers
- `localStorage` and `sessionStorage`: entries written before any page script
  runs
- `initScripts`: code run before page scripts
- `query`: query parameters added to every URL, such as `{ currency: "EUR" }`
- `browser`: `"chromium"`, `"firefox"` or `"webkit"` for this scenario
- `network`: `"fast-3g"`, `"slow-3g"` or a custom profile
- `cpu`: slow JavaScript down by a factor (Chromium only)
- `cache`: `"warm"` loads each page once before testing it, like a returning
  visitor (the default is `"cold"`)

## All scenario options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Unique name, shown in reports and used by `--scenario`. |
| `locale` | `string` | this machine's locale | BCP 47 locale for the browser (also sets Accept-Language). |
| `timezoneId` | `string` | this machine's timezone | IANA timezone for the browser, e.g. `Asia/Karachi`. |
| `colorScheme` | `ColorScheme` | `"light"` | Emulated `prefers-color-scheme`: `"light"`, `"dark"` or `"no-preference"`. |
| `reducedMotion` | `"reduce" \| "no-preference"` | — | Emulated `prefers-reduced-motion`. |
| `viewport` | `ViewportOption` | — | Viewport size as `{ width, height }`, or a preset: `"mobile"` (390×844, touch), `"tablet"` (820×1180) or `"desktop"` (1280×800). |
| `userAgent` | `string` | — | User agent string for the browser context. |
| `storageState` | `string` | — | Playwright storage state file (cookies and localStorage), e.g. a logged-in user. |
| `cookies` | `CookieConfig[]` | — | Cookies set before every page load, e.g. a session cookie for a signed-in user. |
| `headers` | `Record<string, string>` | — | Extra request headers. |
| `localStorage` | `Record<string, string>` | — | `localStorage` entries set before page scripts run. |
| `sessionStorage` | `Record<string, string>` | — | `sessionStorage` entries set before page scripts run. |
| `initScripts` | `string[]` | — | Scripts run before page scripts (code strings). |
| `login` | `(context: LoginContext) => Promise<void>` | — | Sign in once before this scenario's pages are tested. The cookies and storage it leaves behind are used for every page. |
| `mocks` | `MockConfig[]` | — | Answers for browser requests (API fixtures). Server-side requests are not affected. |
| `include` | `string[]` | — | Only test routes matching these globs in this scenario. |
| `exclude` | `string[]` | — | Skip routes matching these globs in this scenario. |
| `query` | `Record<string, string>` | — | Query parameters added to every URL (e.g. `{ currency: 'EUR' }`). |
| `browser` | `BrowserName` | `browser.name` | Browser for this scenario. |
| `network` | `NetworkProfile` | — | Throttle the network: `"fast-3g"`, `"slow-3g"` or `{ downloadKbps, uploadKbps, latencyMs }`. Chromium throttles natively; Firefox and WebKit delay subresources instead. |
| `cpu` | `number` | — | Slow down JavaScript by this factor (Chromium only). |
| `cache` | `CacheState` | `cold` | `warm` loads the page once before testing it, like a returning visitor. |
| `clock` | `string \| number` | — | Fixed browser time (ISO string or epoch ms) for `Date.now()` / `new Date()`. A diagnostic option: the server keeps its real clock, so time-dependent output is still found. |
| `randomSeed` | `number` | — | Seed for `Math.random()` and `crypto.getRandomValues()` in the browser (diagnostic, like `clock`). |

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Cookie name. |
| `value` (required) | `string` | — | Cookie value. |
| `domain` | `string` | the tested origin | Cookie domain. |
| `path` | `string` | `"/"` | Cookie path. |
| `httpOnly` | `boolean` | — | Hide the cookie from page scripts. |
| `secure` | `boolean` | — | Send the cookie over HTTPS only. |
| `sameSite` | `"Strict" \| "Lax" \| "None"` | — | The `SameSite` attribute. |

## Related

- [Test locales and timezones with the environment matrix](https://hydration.jscrate.dev/docs/environment-matrix)
- [Prove what causes a mismatch](https://hydration.jscrate.dev/docs/probes)
- [Choose which routes are tested](https://hydration.jscrate.dev/docs/routes)
- [Keep secrets out of reports](https://hydration.jscrate.dev/docs/security)
- [Configuration reference](https://hydration.jscrate.dev/docs/configuration)

---

# Test locales and timezones for hydration errors

> Use the matrix option to test locales and timezones for hydration errors, plus themes, viewports and browsers, in a small set of pairwise runs.

Source: https://hydration.jscrate.dev/docs/environment-matrix
Last updated: 2026-09-18

To test locales and timezones for hydration errors, list the values in the
`matrix` option. hydration-proof runs each scenario in combinations of them,
and of themes, viewports, browsers, network and CPU speeds, then says which
value a finding depends on. Pairwise selection keeps the run small: every pair
of values is tested at least once.

## Why test more than one environment?

Most hydration bugs are environment bugs: a date formatted in the browser's
[timezone](https://hydration.jscrate.dev/docs/causes/timezone) or [locale](https://hydration.jscrate.dev/docs/causes/locale), a
[theme](https://hydration.jscrate.dev/docs/causes/theme) read from `prefers-color-scheme`, or a layout that
[branches on screen size](https://hydration.jscrate.dev/docs/causes/media-query). The server renders one
version and the visitor's browser another.

Without a matrix, hydration-proof tests one scenario named `default`. It uses
this machine's locale and timezone and a light color scheme, so a server
started on the same machine renders with the same settings. That is the one
combination where these bugs never show up.

## How to test locales and timezones for hydration errors

Add a `matrix` to the config. Pick values that differ in ways your code cares
about:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  matrix: {
    // A right-to-left locale, and timezones on both sides of UTC.
    locale: ["en-US", "de-DE", "ar-EG"],
    timezoneId: ["UTC", "Asia/Karachi", "America/Los_Angeles"],
    colorScheme: ["light", "dark"],
    viewport: ["desktop", "mobile"],
    browser: ["chromium", "firefox", "webkit"],
    // A returning visitor: scripts arrive in a different order.
    cache: ["cold", "warm"],
    // Chromium only; other browsers skip it with a note.
    cpu: [1, 4],

    // Anything the tool cannot guess. Each value is scenario settings.
    axes: {
      flags: {
        "new-checkout": { cookies: [{ name: "flag_checkout", value: "new" }] },
        "old-checkout": {},
      },
      currency: {
        eur: { localStorage: { currency: "EUR" } },
        jpy: { localStorage: { currency: "JPY" } },
      },
    },

    strategy: "pairwise",
    max: 16,
  },
});
```

Then run the tests as usual:

```bash
npx hydration-proof test
```

This config has 1,728 combinations. Pairwise testing covers every pair of
values with about a dozen of them (11 here), because pairs of values are what
usually breaks.

## Which axes can you vary?

| Axis            | Values                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `locale`        | Locales such as `'de-DE'`. Also sets `Accept-Language`                                           |
| `timezoneId`    | IANA timezones such as `'Asia/Karachi'`                                                          |
| `colorScheme`   | `'light'`, `'dark'`, `'no-preference'`                                                           |
| `reducedMotion` | `'reduce'`, `'no-preference'`                                                                    |
| `viewport`      | `'mobile'`, `'tablet'`, `'desktop'`, or `{ width, height }`                                      |
| `browser`       | `'chromium'`, `'firefox'`, `'webkit'`                                                            |
| `network`       | `'fast'` (no throttling), `'fast-3g'`, `'slow-3g'`, or `{ downloadKbps, uploadKbps, latencyMs }` |
| `cpu`           | Slowdown factors such as `[1, 4]`, where `1` is no slowdown (Chromium only)                      |
| `cache`         | `'cold'`, and `'warm'`, which loads the page once before testing it                              |
| `axes`          | Custom axes: axis name, then value name, then scenario settings                                  |

`cache: ['cold', 'warm']` is a cheap axis worth adding: a warm cache changes
the order scripts arrive in, which changes when hydration starts.

### Custom axes

Use `axes` for anything the tool cannot know: feature flags, tenants, a
currency cookie, an A/B bucket. Each value applies scenario settings:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `cookies` | `CookieConfig[]` | — | Cookies this axis value sets. |
| `headers` | `Record<string, string>` | — | Request headers this axis value sets. |
| `localStorage` | `Record<string, string>` | — | `localStorage` entries this axis value sets. |
| `sessionStorage` | `Record<string, string>` | — | `sessionStorage` entries this axis value sets. |
| `initScripts` | `string[]` | — | Scripts this axis value runs before page scripts. |
| `query` | `Record<string, string>` | — | Query parameters this axis value adds to every URL. |

## Choose a strategy

| `strategy`             | What it tests                                                                     |
| ---------------------- | --------------------------------------------------------------------------------- |
| `'pairwise'` (default) | Every pair of values at least once                                                |
| `'full'`               | Every combination. A matrix larger than `max` falls back to pairwise, with a note |
| `'sample'`             | A random subset of `max` environments, chosen from `seed` (default `1`)           |

`max` (default `16`) is the most environments per scenario. If pairwise needs
more than that, the first `max` are tested and a note tells you to raise it for
full pair coverage.

The first value of every axis is the baseline, and the combination of all
baselines is always tested when the browsers can run it. Put the value most of
your users have first.

`matrix.scenarios` limits the matrix to some scenarios; the others run as
configured. The login of a scenario runs once and is shared by all of its
environments (see [scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios)).

## Which combinations are skipped?

Some combinations cannot run. They are left out with a note instead of failing
the run:

- CPU slowdown needs Chromium.
- Firefox and WebKit have no network throttling. There, every request except
  the document is delayed by the latency instead, and a warm cache cannot be
  combined with a throttled network.
- Firefox has no mobile emulation, so `'mobile'` only sets the viewport size
  and touch.
- Mocks turn the HTTP cache off, so `'warm'` only repeats the visit.

## Read the results

Each environment is a scenario named after the values it varies, such as
`guest (de-DE, Asia/Karachi, firefox)`. Axes with a single value are left out
of the name, and custom axes appear as `name=value` (`flags=new-checkout`).
`--scenario guest` selects every environment of `guest`.

When a finding appears in some environments of a route and not in others, the
report names the values that separate them. The terminal lists these at the
end of the run:

```text
  Only in some environments
    HP1001 /checkout #total  Only found with locale de-DE.
```

With `--mode both`, the build is an axis too: "Only found with the production
build." The HTML report shows the other environments of the same route next to
each finding. To go from "only in de-DE" to a proven cause, add
[probes](https://hydration.jscrate.dev/docs/probes).

## Turn the matrix off with --no-matrix

A full matrix is slower than you want for a quick local check. `--no-matrix`
tests the scenarios as configured:

```bash
npx hydration-proof test --no-matrix
```

## Find flaky findings with --repeat

A finding in one environment out of twelve is usually a real bug that needs
that environment, not flakiness. `--repeat` tells the two apart: it loads every
page several times.

```bash
npx hydration-proof test --repeat 3
```

Findings that appear in only some runs are marked flaky ("Seen in 2 of 3 runs
of this page.") and still count, because an intermittent mismatch is a real
bug. Each page gets a flakiness score: the share of runs whose findings differ
from the most common result. The same option is `repeat: 3` in the config.

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` | `string[]` | — | Locales to test, e.g. `['en-US', 'de-DE', 'ar-EG']`. |
| `timezoneId` | `string[]` | — | Timezones to test, e.g. `['UTC', 'Asia/Karachi', 'America/Los_Angeles']`. |
| `colorScheme` | `ColorScheme[]` | — | Color schemes to test, e.g. `['light', 'dark']`. |
| `reducedMotion` | `("reduce" \| "no-preference")[]` | — | Reduced-motion settings to test. |
| `viewport` | `ViewportOption[]` | — | Viewports to test: sizes or the presets `mobile`, `tablet`, `desktop`. |
| `browser` | `BrowserName[]` | — | Browsers to test: `chromium`, `firefox`, `webkit`. |
| `network` | `NetworkProfile[]` | — | Network profiles to test: `fast` (no throttling), `fast-3g`, `slow-3g` or custom. |
| `cpu` | `number[]` | — | CPU slowdown factors (Chromium only); `1` is no slowdown. |
| `cache` | `CacheState[]` | — | Cache states to test: `cold` and `warm`. |
| `axes` | `Record<string, Record<string, ScenarioVariant>>` | — | Custom axes: axis name → value name → scenario settings. `{ flags: { 'new-checkout': { cookies: [{ name: 'flag', value: 'on' }] }, 'old-checkout': {} } }` |
| `strategy` | `"pairwise" \| "full" \| "sample"` | — | `pairwise` (default) covers every pair of values, `full` every combination, `sample` a random subset. |
| `max` | `number` | 16 | Most environments per scenario. |
| `seed` | `number` | 1 | Seed for `sample`. |
| `scenarios` | `string[]` | all | Scenarios the matrix applies to. |

## Related

- [Scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios): the environments the matrix expands
- [Prove which factor causes a finding](https://hydration.jscrate.dev/docs/probes)
- [Timezone hydration mismatches](https://hydration.jscrate.dev/docs/causes/timezone)
- [Locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale)
- [The `matrix` option](https://hydration.jscrate.dev/docs/configuration#matrix) in the configuration reference

---

# Prove the cause of a hydration mismatch

> Run hydration-proof with --probe to prove the cause of a hydration mismatch: each page is reloaded with one thing changed, such as the clock or the locale.

Source: https://hydration.jscrate.dev/docs/probes
Last updated: 2026-09-18

Probes prove the cause of a hydration mismatch instead of guessing it. With
`--probe`, hydration-proof reloads each page that has a value mismatch with the
browser clock and random values fixed, then once per factor with exactly one
thing changed. If the client value changes, or the finding disappears, when
only that factor changes, the factor is the cause.

## Turn probes on

```bash
npx hydration-proof test --probe
```

Or in the config, with `probes: true`, or with options:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  probes: { factors: ["time", "random"], maxPages: 5 },
});
```

Probes are off by default because they cost extra page loads (see
[below](#what-do-probes-cost)).

## How to prove the cause of a hydration mismatch

Every finding already has a likely cause: an informed guess, with a confidence,
made from the values that differ, the code around the source line, the
scenario and the stage where the difference started. A probe turns the guess
into a test:

1. The page is loaded with the browser clock and `Math.random()` fixed.
2. It is loaded again, identically. This is the control.
3. It is loaded once more for each factor, with only that factor changed.
4. hydration-proof compares the finding across the loads.

| Factor     | What changes                                                                                    | Proves                                                 |
| ---------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `time`     | The browser clock moves by 3 days, 7 hours, 11 minutes and 13 seconds                           | [Time-dependent value](https://hydration.jscrate.dev/docs/causes/time)              |
| `random`   | A different seed for `Math.random()` and `crypto.getRandomValues()`                             | [Random value](https://hydration.jscrate.dev/docs/causes/random)                    |
| `locale`   | The browser locale becomes the server's (or another one)                                        | [Locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale)     |
| `timezone` | The browser timezone becomes the server's (or another one)                                      | [Timezone difference](https://hydration.jscrate.dev/docs/causes/timezone)           |
| `theme`    | Light ↔ dark                                                                                    | [Theme preference](https://hydration.jscrate.dev/docs/causes/theme)                 |
| `viewport` | Desktop ↔ mobile                                                                                | [Screen size or media query](https://hydration.jscrate.dev/docs/causes/media-query) |
| `storage`  | No `localStorage`, `sessionStorage` or `storageState` from the scenario (only when it has them) | [Browser storage](https://hydration.jscrate.dev/docs/causes/storage)                |

The clock moves by an odd amount so that every field of a date changes at once:
the day, the hour, the minute and the second.

## Proven or likely?

A finding whose client value changes, or that disappears, when only one factor
changes has that cause **proven**. The terminal shows `proven` where it
otherwise shows a percentage, and the run ends with a summary of what the
probes found:

```text
    HP1001 Text differs between server and client  (timezone difference, proven)
      #last-login  in LastLogin
      server: "Signed in at 5:00 AM"
      client: "Signed in at 10:00 AM"

  Probes
    HP1001 /dashboard #last-login  proven: timezone difference
```

The finding's evidence says what changed, for example that the client rendered
one value instead of another when only the browser timezone changed. Its list
of fixes starts with the fixes for the proven cause.

When several factors change the finding, the most specific one names the
cause, and the evidence lists the others. Factors that changed nothing are
listed too, and a likely cause that a probe ruled out loses confidence.

## What if an identical reload renders differently?

Then the value does not come from the browser. The clock and random values were
fixed, so it comes from the server or an API that answers differently each
time. The finding's cause becomes
[server and client used different data](https://hydration.jscrate.dev/docs/causes/data), and the other
factors are marked inconclusive, since a page that changes on its own cannot
prove anything else.

## What do probes cost?

Only value mismatches are probed: text, attribute, style, class and
`dangerouslySetInnerHTML` differences, plus form state
([HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) to [HP1006](https://hydration.jscrate.dev/docs/issues/hp1006),
[HP1012](https://hydration.jscrate.dev/docs/issues/hp1012) and [HP1013](https://hydration.jscrate.dev/docs/issues/hp1013)). Ignored,
suppressed and info findings are skipped.

- Each probed page costs up to 9 extra page loads: the fixed load, the control,
  and one per factor.
- `maxPages` (default `5`) caps the pages probed per run. Pages with the most
  errors go first, and a note says how many were left out.
- The run ends with a note of how many extra loads the probes took.

Narrow `factors` when you only suspect one or two causes.

## Probes never hide a finding

The server is never changed. Fixing the browser clock only makes the loads
comparable with each other; the server keeps its real clock, so a
time-dependent value is still found. The same goes for a scenario's `clock`
and `randomSeed` options: they make client values repeatable between runs, and
hide nothing (see [scenarios](https://hydration.jscrate.dev/docs/scenarios)).

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `factors` | `ProbeFactor[]` | all that apply | What to vary. |
| `maxPages` | `number` | 5 | Most pages probed per run. |

## Related

- [How hydration-proof works](https://hydration.jscrate.dev/docs/how-it-works): stages, comparisons and causes
- [All causes of hydration errors](https://hydration.jscrate.dev/docs/causes) and their fixes
- [Environment matrix](https://hydration.jscrate.dev/docs/environment-matrix): find the locale or browser a bug needs
- [Fix date and time hydration errors](https://hydration.jscrate.dev/docs/causes/time)
- [HP1001: text differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1001)

---

# Test interactions and navigation

> Find lost clicks before hydration, input that React resets, lost focus and scroll, and pages that differ after client-side navigation, on every route.

Source: https://hydration.jscrate.dev/docs/interactions
Last updated: 2026-09-18

hydration-proof finds lost clicks before hydration by loading each page with
its scripts held back, like a user on a slow connection, and acting on it: it
types, clicks, focuses and scrolls, then checks that nothing was lost once
React took over. Navigation checks compare a route reached through the app's
router with the same route loaded directly.

## Why interactions before hydration matter

The server HTML shows buttons and fields long before React attaches its event
handlers. In that window the page looks ready, but a click does nothing, and
text typed into a field can be wiped when React hydrates it. On a fast
development machine the window is too short to notice; on a slow phone it is
not.

These checks are off by default because each one costs extra page loads.

## Check interactions while the page loads

```bash
npx hydration-proof test --interactions
```

Or set `checks.interactions` in the config:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  checks: { interactions: true },
});
```

For each page, with the page's scripts held back, hydration-proof:

1. types into the first text field, checks the first checkbox, selects text
   and scrolls, then lets the page hydrate and checks that the text and the
   checkbox ([HP5002](https://hydration.jscrate.dev/docs/issues/hp5002)), the focus and the selection
   ([HP5003](https://hydration.jscrate.dev/docs/issues/hp5003)) and the scroll position
   ([HP5007](https://hydration.jscrate.dev/docs/issues/hp5007)) survived;
2. clicks the first button outside forms and links, and compares the result
   with the same click after hydration. A click that only works after
   hydration is reported as lost ([HP5001](https://hydration.jscrate.dev/docs/issues/hp5001)), a warning:
   the page looks ready before it is.

Pages without fields, buttons or scrollable content are skipped. Each checked
page costs about six extra page loads.

## How to fix lost clicks before hydration

Pick the fix that matches the finding:

- **Lost click (HP5001).** Keep controls disabled, or show them as loading,
  until the page is interactive. Or make them work without JavaScript: links,
  and forms with Server Actions. Shipping less JavaScript for the first view
  helps too, and Suspense boundaries hydrate in order of interaction.
- **Input reset (HP5002).** Use uncontrolled inputs (`defaultValue`,
  `defaultChecked`), or read the current DOM value when the component mounts,
  so text typed before hydration is kept. Also fix any hydration mismatch
  around the form: a re-rendered branch creates new, empty inputs.
- **Focus lost (HP5003).** Do not re-create the focused element during
  hydration (fix mismatches around it), and do not move focus in effects that
  run on load.
- **Scroll reset (HP5007).** Do not change the scroll position during
  hydration (`scrollTo` in effects, `focus()` on load); let the browser
  restore it.

A button that stays disabled until its component has hydrated renders the same
HTML on the server and in the first client render, so it causes no mismatch:

```tsx title="buy-button.tsx"
"use client";

import { useEffect, useState } from "react";

export function BuyButton({ onBuy }: { onBuy: () => void }) {
  const [hydrated, setHydrated] = useState(false);

  // Effects only run in the browser, after hydration.
  useEffect(() => setHydrated(true), []);

  return (
    <button type="button" disabled={!hydrated} onClick={onBuy}>
      Buy
    </button>
  );
}
```

## Interaction issue codes

| Code | Title | Severity |
| --- | --- | --- |
| [HP5001](https://hydration.jscrate.dev/docs/issues/hp5001) | An interaction before hydration was lost | Warning |
| [HP5002](https://hydration.jscrate.dev/docs/issues/hp5002) | User input was reset during hydration | Error |
| [HP5003](https://hydration.jscrate.dev/docs/issues/hp5003) | Focus was lost during hydration | Warning |
| [HP5004](https://hydration.jscrate.dev/docs/issues/hp5004) | The page differs after client-side navigation | Warning |
| [HP5005](https://hydration.jscrate.dev/docs/issues/hp5005) | Client-side navigation failed | Error |
| [HP5006](https://hydration.jscrate.dev/docs/issues/hp5006) | An element handles the same event twice | Warning |
| [HP5007](https://hydration.jscrate.dev/docs/issues/hp5007) | Scroll position was reset during hydration | Warning |
| [HP5008](https://hydration.jscrate.dev/docs/issues/hp5008) | A custom interaction failed | Error |

## Write custom interactions

The built-in check only touches the first field and the first button. For the
flows that matter, write the steps yourself with Playwright:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  interactions: [
    {
      route: "/checkout",
      name: "continue to payment",
      steps: async ({ page }) => {
        await page.getByLabel("Email").fill("test@example.com");
        await page.getByRole("button", { name: "Continue" }).click();
        await page.getByText("Payment").waitFor();
      },
    },
    {
      route: "/search",
      name: "type before the page is ready",
      when: "before-hydration",
      steps: async ({ page }) => {
        await page.fill("#query", "shoes");
      },
    },
  ],
});
```

- `route` is a glob, matched against the path and the route pattern.
- `when: 'after-hydration'` (the default) runs once the page is interactive;
  `'before-hydration'` runs while the page's scripts are still held back.
- `steps` receives `{ page, baseUrl, url }`, with a Playwright page.
- `scenarios` limits the interaction to some scenarios.

Custom interactions run on every test run, without `--interactions`, on the
pages that hydrated. An interaction that throws, or that causes an uncaught
error on the page, is reported as [HP5008](https://hydration.jscrate.dev/docs/issues/hp5008). Run with
`--headed` to watch where it fails.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `route` (required) | `string` | — | Route glob the interaction runs on, e.g. `/checkout` or `/products/**`. |
| `name` | `string` | — | Shown in reports. |
| `when` | `"before-hydration" \| "after-hydration"` | — | `after-hydration` (default): run once the page is interactive. `before-hydration`: run while the page's scripts are still held back, like a user on a slow connection. |
| `scenarios` | `string[]` | — | Only in these scenarios. |
| `steps` (required) | `(context: InteractionContext) => Promise<void>` | — | The interaction, written with Playwright: receives `{ page, baseUrl, url }`. A thrown error is reported as HP5008. |

## Check client-side navigation

A route can render one thing when you load its URL and another when you reach
it through a link. The navigation check finds that:

```bash
npx hydration-proof test --navigation
```

It opens a page, navigates to each route with the app's router (`router.push`
in the Next.js App Router and Pages Router) and compares the result with
loading the route directly. Both loads use the same fixed browser clock and
random seed, and numbers are ignored in the comparison.

- Content that differs after navigation is reported as
  [HP5004](https://hydration.jscrate.dev/docs/issues/hp5004), a warning. Routes that render parallel routes
  (`@slot` folders), or that an intercepting route can replace, are reported
  as info, since the difference is usually intended.
- An error thrown during navigation, a failed RSC request, or a URL that never
  changes is reported as [HP5005](https://hydration.jscrate.dev/docs/issues/hp5005).
- Navigations the framework turns into a full page load (for example to
  another root layout) are noted in the page's timeline, not reported.

The check needs an adapter with a client router, which today means
[Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs). With another framework it is skipped with a
note. Each checked route costs two page loads, or three with `prefetch`.

Configure it with `checks.navigation`:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  checks: {
    navigation: { from: "/", prefetch: true, maxRoutes: 20 },
  },
});
```

A route can name its own starting page with `navigateFrom` in
[`routes.paths`](https://hydration.jscrate.dev/docs/configuration#routes), for example to test a modal that
an intercepting route shows.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` | `/` (another tested route when the target is `/`) | Page to navigate from. |
| `prefetch` | `boolean` | true | Also navigate after the router prefetched the route. |
| `maxRoutes` | `number` | 20 | Most routes checked per scenario. |

## Events handled twice (HP5006)

[HP5006](https://hydration.jscrate.dev/docs/issues/hp5006) is found on every run, without extra flags: a
script or an inline `on*` attribute handles an event on an element that React
also handles, so one click can run the action twice. Handle the event in one
place: remove the inline attribute or the script that adds the listener, or
remove the React handler.

## Related

- [HP5001: an interaction before hydration was lost](https://hydration.jscrate.dev/docs/issues/hp5001)
- [The `checks` options](https://hydration.jscrate.dev/docs/configuration#checks)
- [Hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [Use hydration-proof with Playwright](https://hydration.jscrate.dev/docs/playwright)

---

# Ignore known hydration mismatches

> Ignore known hydration mismatches without hiding new ones: skip elements and attributes, mask text, or accept one finding with a reason and an expiry date.

Source: https://hydration.jscrate.dev/docs/ignoring
Last updated: 2026-09-18

To ignore known hydration mismatches, add them to the `ignore` option: skip an
element's subtree, never compare an attribute, mask a text pattern, or accept
one finding with a reason and an expiry date. Ignored findings stay in the
report, marked as ignored with the reason, and do not fail the run.

## When to ignore known hydration mismatches

Ignoring is for markup that is meant to differ between the server and the
browser: an ad slot, analytics attributes, a third-party chat widget. A
difference in your own components is a bug, and the [causes](https://hydration.jscrate.dev/docs/causes)
pages show how to fix each one.

Prefer the narrowest tool, and write down why. For an app that already has many
findings, record a [baseline](https://hydration.jscrate.dev/docs/baselines) instead: it accepts today's
findings in one step and still fails on new ones.

| You want to                                               | Use                                                   |
| --------------------------------------------------------- | ----------------------------------------------------- |
| Skip an element in your own markup                        | The `data-hydration-proof-ignore` attribute           |
| Skip third-party markup you cannot edit                   | `ignore.selectors`                                    |
| Never compare an attribute, such as `data-gtm-*`          | `ignore.attributes`                                   |
| Ignore text that differs only in one part, such as a time | `ignore.textPatterns`                                 |
| Accept one known finding for a while                      | An `ignore.issues` rule with a `reason` and `expires` |
| Accept every current finding while you fix them           | A [baseline](https://hydration.jscrate.dev/docs/baselines)                         |
| Keep a value that differs on purpose, in the app itself   | `suppressHydrationWarning` (reported as info)         |

## Mark an element with data-hydration-proof-ignore

The subtree of any element with this attribute is not compared:

```tsx title="ad-slot.tsx"
export function AdSlot() {
  // The ad script fills this element before React hydrates.
  return <div id="ad-slot" data-hydration-proof-ignore />;
}
```

`[data-hydration-proof-ignore]` is always part of `ignore.selectors`, so
nothing else needs configuring.

## Ignore selectors, attributes and text patterns

For markup you cannot edit, list it in the config:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    // Third-party markup that is expected to differ.
    selectors: ["#ad-slot", "[data-chat-widget]"],
    // Attribute names, or patterns.
    attributes: [/^data-gtm-/],
    // "Updated 10:41" and "Updated 10:42" count as equal.
    textPatterns: [/\d{2}:\d{2}/],
  },
});
```

- `selectors`: elements whose subtree is not compared.
- `attributes`: attribute names (strings) or patterns (`RegExp`) that are
  never compared.
- `textPatterns`: a text difference is ignored when both values are equal after
  removing these patterns.

## Ignore one finding with a reason

An `ignore.issues` rule accepts specific findings. It matches on any
combination of `code`, `route` (a glob), `fingerprint` and `selector`, and every
field you give must match. `reason` is required and is shown in reports:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    issues: [
      {
        code: "HP4001",
        route: "/checkout",
        reason: "The payment iframe rewrites its container. Ticket ACME-431.",
        expires: "2026-12-31",
      },
    ],
  },
});
```

- `code`: an issue code, such as `HP1004`.
- `route`: a route glob, matched against the path and the route pattern.
- `fingerprint`: the exact fingerprint of one finding, from `report.json`.
- `selector`: a CSS selector prefix the finding must point at.
- `expires`: an ISO date after which the rule stops applying.

A fingerprint stays the same across runs as long as the problem does: the same
code, route pattern, element and attribute. It never depends on values that
change per request, so a rule written against it keeps matching.

> **An expired rule fails the run**
>
> After its `expires` date, a rule that still matches a finding fails the run
> with "Ignore rule "…" expired on 2026-12-31." That way a temporary exception
> cannot quietly become permanent: fix the finding, or extend the date on
> purpose.

## How suppressHydrationWarning differs from ignoring

`suppressHydrationWarning` changes your app: React keeps the server's text or
attribute on that element and does not report the difference. `ignore` changes
nothing in the app, only what hydration-proof reports.

hydration-proof still sees what `suppressHydrationWarning` hides, and audits it:

| Code                          | Severity | Finding                                                                                      |
| ----------------------------- | -------- | -------------------------------------------------------------------------------------------- |
| [HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) | info     | A mismatch hidden by `suppressHydrationWarning`                                              |
| [HP6002](https://hydration.jscrate.dev/docs/issues/hp6002) | error    | A structural difference it cannot hide: it only covers the element's own text and attributes |
| [HP6003](https://hydration.jscrate.dev/docs/issues/hp6003) | info     | `suppressHydrationWarning` on an element with nothing to suppress                            |

`checks.suppressedWarnings` sets how much of this you see: `'info'` (the
default) lists the differences it hides, `'strict'` also flags unused
suppression, and `'off'` hides both. See
[when suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning),
and the ESLint rule
[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
to catch misuse in your editor.

## Where ignored findings show up

Each report format handles ignored findings its own way:

- The terminal summary counts them as "Ignored issues".
- The HTML report hides them until you tick "Show ignored", then shows each
  one with the rule and the reason.
- SARIF includes them with an external suppression, so code scanning does not
  open alerts for them.
- JUnit lists them, but they never fail a test case. The GitLab Code Quality
  report leaves them out.

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `selectors` | `string[]` | — | Elements whose subtree is not compared. `[data-hydration-proof-ignore]` is always included. |
| `attributes` | `(string \| RegExp)[]` | — | Attribute names (or patterns) that are never compared. |
| `textPatterns` | `RegExp[]` | — | Text differences are ignored when both values are equal after removing these patterns. |
| `issues` | `IgnoreRule[]` | — | Ignore specific findings. |

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `code` | `string` | — | Issue code, e.g. `HP1004`. |
| `route` | `string` | — | Route glob. |
| `fingerprint` | `string` | — | Exact issue fingerprint from a report. |
| `selector` | `string` | — | CSS selector prefix the issue must point at. |
| `reason` (required) | `string` | — | Why this is ignored. Shown in reports. |
| `expires` | `string` | — | ISO date after which the rule stops applying (and CI fails). |

## Related

- [Baselines and budgets](https://hydration.jscrate.dev/docs/baselines) for existing findings
- [When suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [The `ignore` option](https://hydration.jscrate.dev/docs/configuration#ignore)
- [Reports](https://hydration.jscrate.dev/docs/reports): where fingerprints and ignored findings appear
- [Scripts that change the page before hydration](https://hydration.jscrate.dev/docs/causes/third-party-script)

---

# Reports: terminal, HTML, JSON, JUnit, SARIF

> Each hydration error report (SARIF, JUnit, JSON, HTML, GitHub, GitLab) that hydration-proof writes: what it contains, where it goes and how CI reads it.

Source: https://hydration.jscrate.dev/docs/reports
Last updated: 2026-09-18

hydration-proof writes each hydration error report (SARIF, JUnit, JSON, HTML,
GitHub annotations, GitLab Code Quality) from the same findings, into
`.hydration-proof/report/`. Choose them with `--reporter` or the `reporters`
option. Every format carries the stable issue codes and fingerprints, so CI
tools recognize the same problem from one run to the next.

## Which hydration error report: SARIF, JUnit or JSON?

| Reporter | Writes                           | Use it for                                                |
| -------- | -------------------------------- | --------------------------------------------------------- |
| `list`   | The terminal                     | Reading results as the run goes                           |
| `json`   | `report.json`                    | Scripts, merging shards, the [Node API](https://hydration.jscrate.dev/docs/node-api)   |
| `html`   | `report.html` and `screenshots/` | Debugging a finding                                       |
| `junit`  | `junit.xml`                      | Test results in any CI system                             |
| `sarif`  | `report.sarif`                   | GitHub code scanning and other static-analysis dashboards |
| `github` | Nothing: workflow commands       | Annotations and the job summary on GitHub Actions         |
| `gitlab` | `gl-code-quality.json`           | The Code Quality widget in GitLab merge requests          |

```bash
npx hydration-proof test --reporter list,html,json,junit,sarif
```

When `reporters` is not set, the default is `list`, `json` and `html`. On GitHub
Actions (`GITHUB_ACTIONS=true`), `github` is added automatically unless you pass
`--reporter`. `hydration-proof init` writes `reporters: ['list', 'json']` into
the config it creates. Reports go to `.hydration-proof/report/`; change it with
`outputDir` or `--output`. [Running in CI](https://hydration.jscrate.dev/docs/ci) has the reporter set for
each CI system.

## Terminal (list)

One line per page while testing. Failing pages show their most important
findings with the element, the server and client values, the likely cause, the
source location and the first fix. A summary follows:

```text
  ✖ /dashboard 1.1s  1 error
    HP1001 Text differs between server and client  (timezone difference, 95%)
      #last-login  in LastLogin
      server: "Signed in at 5:00 AM"
      client: "Signed in at 10:00 AM"
      app/dashboard/LastLogin.tsx:14:10
      → Pass an explicit timeZone to the formatter (the same on both sides), or format the date after mount.
```

## JSON (json)

`report.json` contains everything: run information, a summary, every page and
every issue. It is what the other tools build on.

- **Schema.** The format is described by
  `node_modules/hydration-proof/schema/report.json` (its `$id` is
  `https://hydration.jscrate.dev/schema/report.json`). Within
  `schemaVersion: 1` it only changes in compatible ways: fields are added,
  never removed.
- **Fingerprints.** Every issue has a `fingerprint` that stays the same across
  runs as long as the problem is the same: the same code, route pattern,
  element and attribute. Ignore rules and baselines use it.
  `fingerprintVersion` says how the fingerprints were computed.
- **CI data.** Findings carry their owners (`owners`), whether the baseline
  knows them (`baseline`, `new`) and, in a monorepo, their `project`. The run
  records the git commit and branch. With `ci.history`, `history` holds the
  previous runs.
- **Pages.** Each page records where its route came from (`source`: `config`,
  `discovered`, `manifest`, `sitemap`, `crawl` or `not-found`) and, when the
  tool started the app, the error and warning lines the server printed while
  the page loaded (`serverLogs`).
- **Redaction.** Values removed by [redaction](https://hydration.jscrate.dev/docs/security) are counted in
  `summary.redacted`.

## HTML (html)

`report.html` is a single file you can open locally or keep as a CI artifact.
Its Content Security Policy starts with `default-src 'none'`, and the page makes
no network requests. Screenshots are image files in `screenshots/` next to it,
so keep the folder together.

It shows:

- a summary and filters: page status, severity, cause, kind, scenario, owner,
  text search and ignored findings;
- per page, the findings with server and client values side by side
  (differences highlighted), the element on each side, the component, the
  source code, evidence and fixes, and the server log lines;
- screenshots of the hydrated page and of the server HTML without scripts,
  with the affected elements outlined;
- a timeline of the page: scripts and RSC requests loading, React loading,
  hydration commits for the root and each Suspense boundary, React errors,
  scripts changing the DOM, streamed content and the navigation check;
- the other environments of a route for [matrix](https://hydration.jscrate.dev/docs/environment-matrix)
  runs, what each [probe](https://hydration.jscrate.dev/docs/probes) changed, and flaky findings for
  repeated runs;
- with `ci.history`, the errors and warnings of the last 30 runs.

`screenshots` sets which pages get screenshots: `'failures'` (the default with
the HTML reporter), `'all'` or `'off'`. Deep links such as
`report.html#page=…&issue=…` open one finding.

## JUnit XML (junit)

`junit.xml` works with any CI system that reads JUnit results, including
GitLab, CircleCI, Jenkins, Azure Pipelines and Buildkite.

- One `<testsuite>` per scenario, or per scenario and build mode with
  `--mode both`.
- One `<testcase>` per page. The `classname` is
  `hydration-proof.<scenario>[.<mode>]` and the `name` is the page path with
  its query string. A path tested twice in one suite gets ` (2)`, ` (3)` and so
  on, so every pair is unique. `time` is the page's test time in seconds.
- A failed page has a `<failure>`. Its `type` is the first issue code, its
  `message` lists the error codes, and its body lists each error with the
  element, both values, the likely cause, the source location, the first fix
  and the documentation link.
- A page that could not be tested has an `<error>` whose `type` is the outcome.
- A page with only warnings or info findings passes. Its findings go to
  `<system-out>`, with the URL, the outcome and any ignored findings. Server
  log lines go to `<system-err>`.

Test cases follow the page status and ignore `--fail-on` and `ci.maxWarnings`.
With `--fail-on warning` the job fails while pages with only warnings still
pass in JUnit. The exit code always applies the policy.

Values are quoted with escapes such as `\n` and `\u0000`, so invisible
differences stay visible.

## SARIF (sarif)

`report.sarif` is a [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/)
log for GitHub code scanning and other static-analysis dashboards.

- Every issue code is a rule. Its `id` is the code (`HP1001`) and its `name` is
  the PascalCase issue name (`TextMismatch`), with the description, the fix
  and a documentation link. The default level follows the severity: `error`,
  `warning`, or `note` for info.
- Each finding is one result, with the source file and line, the route
  pattern, scenario and build mode as a logical location, and the fingerprint
  in `partialFingerprints["hydrationProof/v1"]`, so code scanning recognizes
  an alert across runs.
- Ignored findings are included with an `external` suppression, so no alert
  opens for them.
- `invocations[0].executionSuccessful` is `false` only when the tool itself
  could not run (exit codes 2, 3, 4 and 70).

To upload it to GitHub code scanning, give the job the `security-events: write`
permission and use `github/codeql-action/upload-sarif`:

```yaml title=".github/workflows/hydration.yml"
permissions:
  contents: read
  security-events: write

steps:
  # checkout, setup-node, npm ci, install
  - run: npx hydration-proof test --reporter list,html,json,github,sarif
  - uses: github/codeql-action/upload-sarif@v3
    if: ${{ !cancelled() && hashFiles('.hydration-proof/report/report.sarif') != '' }}
    with:
      sarif_file: .hydration-proof/report/report.sarif
      category: hydration-proof
```

Code scanning is on for public repositories; private ones need GitHub Advanced
Security. Pull requests from forks get a read-only token, so the upload step
fails there.

## GitHub Actions (github)

The `github` reporter prints workflow commands and writes no file.

- **Annotations.** Each problem becomes an `::error`, `::warning` or `::notice`
  annotation, with the page, scenario, element, both values (up to 200
  characters each), the likely cause and its confidence, the first fix and the
  documentation link. When the source location is known, it is attached to
  that file and line, so it shows in the pull request's changed files. The same
  fingerprint in several scenarios, modes or URLs of one route becomes one
  annotation.
- **Limits.** GitHub shows at most 10 annotations of each level per step. The
  most important come first, and a final notice says how many were left out.
- **Job summary.** A Markdown summary with a pass or fail headline, totals, the
  pages with problems and a section per problem. GitHub rejects summaries over
  1 MiB, so long ones are shortened, with a note, to stay under that size.

## GitLab Code Quality (gitlab)

`gl-code-quality.json` is a Code Quality report that GitLab shows in merge
requests. It has one entry per finding that is not ignored:

| Finding                                | GitLab `severity` |
| -------------------------------------- | ----------------- |
| Error with a confidence of 0.9 or more | `critical`        |
| Any other error                        | `major`           |
| Warning                                | `minor`           |
| Info                                   | `info`            |

`check_name` is the issue code, and `fingerprint` is unique within the file and
stable across runs. Declare the file, and the JUnit file, as reports:

```yaml title=".gitlab-ci.yml"
artifacts:
  when: always
  paths:
    - .hydration-proof/report
  reports:
    codequality: .hydration-proof/report/gl-code-quality.json
    junit: .hydration-proof/report/junit.xml
```

## File paths in CI formats

Paths are relative to the repository root: the closest directory above the app
that contains `.git`, or `GITHUB_WORKSPACE` for GitHub annotations and
`CI_PROJECT_DIR` for GitLab. A source file in another workspace package of a
monorepo is still linked. A finding with no source location, or one outside
the repository, is attached to line 1 of the config file (or of `package.json`)
in SARIF and GitLab, and the message names the real source.

## Source locations

Findings point at the code that rendered the element when that can be proven:

- **Development builds** (`--mode development`): the exact file and line where
  the element was created.
- **Production builds with browser source maps**: the component that rendered
  the element, found in the loaded scripts and mapped back through the source
  maps. In Next.js, turn them on:

```ts title="next.config.ts"
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  productionBrowserSourceMaps: true,
};

export default nextConfig;
```

Otherwise the finding says why there is no location, in
`sourceUnavailableReason`: for example, the scripts have no source maps, or
only framework code could be mapped (elements rendered by Server Components
have no client code).

## Related

- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci) with these reporters
- [Baselines and budgets](https://hydration.jscrate.dev/docs/baselines): the `new` and `baseline` fields
- [Read and merge reports from Node](https://hydration.jscrate.dev/docs/node-api)
- [Security and redaction](https://hydration.jscrate.dev/docs/security)
- [All issue codes](https://hydration.jscrate.dev/docs/issues)

---

# Detect hydration errors in CI

> Detect hydration errors in CI with GitHub Actions, GitLab CI or CircleCI: complete workflows, SARIF upload, browser caching, sharding and --changed.

Source: https://hydration.jscrate.dev/docs/ci
Last updated: 2026-09-18

To detect hydration errors in CI, install the browser and run
`npx hydration-proof test`. It exits with a non-zero code when it finds a
problem, so it works in any CI system. Add the reporters your CI understands,
or let `npx hydration-proof init --ci github` (or `--ci gitlab`) write the
workflow for you.

## How to detect hydration errors in CI

1. Install your dependencies, then the browser with its system dependencies:
   `npx hydration-proof install --with-deps`.
2. Run `npx hydration-proof test` with the reporters your CI system reads.
3. Keep `.hydration-proof/report` as an artifact, so you can open the HTML
   report when a run fails.

### Which reporters does each CI use?

| CI system                                             | Reporters                     |
| ----------------------------------------------------- | ----------------------------- |
| GitHub Actions                                        | `list,html,json,github,sarif` |
| GitLab CI                                             | `list,html,json,junit,gitlab` |
| CircleCI, Jenkins, Azure Pipelines, Buildkite, others | `list,html,json,junit`        |

On GitHub Actions the `github` reporter is added automatically unless you pass
`--reporter`. [Reports](https://hydration.jscrate.dev/docs/reports) explains what each format contains.

## GitHub Actions

You do not need a separate hydration-proof GitHub Action: the CLI runs as an
ordinary step. Generate the workflow:

```bash
npx hydration-proof init --ci github
```

It writes `.github/workflows/hydration.yml` for your package manager (npm,
pnpm, Yarn or Bun), and runs on pull requests and on pushes to `main`. Or write
it yourself:

```yaml title=".github/workflows/hydration.yml"
name: Hydration
on: [pull_request]

permissions:
  contents: read
  security-events: write # upload-sarif

jobs:
  hydration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx hydration-proof install --with-deps
      - run: npx hydration-proof test --reporter list,html,json,github,sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: ${{ !cancelled() && hashFiles('.hydration-proof/report/report.sarif') != '' }}
        with:
          sarif_file: .hydration-proof/report/report.sarif
          category: hydration-proof
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: hydration-report
          path: .hydration-proof/report
```

Problems appear as annotations on the changed files and in the job summary.
The SARIF upload also adds them to the repository's code scanning alerts. Code
scanning must be available (public repositories, or GitHub Advanced Security),
and pull requests from forks cannot upload. Without it, leave out `sarif`, the
`security-events` permission and the upload step.

## GitLab CI

```bash
npx hydration-proof init --ci gitlab
```

This writes `.gitlab/hydration-proof.yml`. Include it from your pipeline:

```yaml title=".gitlab-ci.yml"
include:
  - local: .gitlab/hydration-proof.yml
```

The job looks like this:

```yaml title=".gitlab/hydration-proof.yml"
hydration:
  image: node:24
  script:
    - npm ci
    - npx hydration-proof install --with-deps
    - npx hydration-proof test --reporter list,html,json,junit,gitlab
  artifacts:
    when: always
    paths:
      - .hydration-proof/report
    reports:
      codequality: .hydration-proof/report/gl-code-quality.json
      junit: .hydration-proof/report/junit.xml
```

The merge request shows failing pages in the test summary and the problems in
the Code Quality widget. The generated file also sets `GIT_DEPTH: 0`, so
`--changed` can compare with the target branch.

## CircleCI

```yaml title=".circleci/config.yml"
version: 2.1

jobs:
  hydration:
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - run: npm ci
      - run: npx hydration-proof install --with-deps
      - run: npx hydration-proof test --reporter list,html,json,junit
      - store_test_results:
          path: .hydration-proof/report/junit.xml
      - store_artifacts:
          path: .hydration-proof/report
          destination: hydration-report

workflows:
  hydration:
    jobs:
      - hydration
```

`store_test_results` shows each tested page as a test in the Tests tab.
`store_artifacts` keeps the HTML report, which you open from the Artifacts tab.

## Other CI systems

Run with `--reporter list,html,json,junit`, publish
`.hydration-proof/report/junit.xml` as test results, and keep
`.hydration-proof/report` as an artifact. JUnit test cases follow the page
status, and the exit code applies `--fail-on`.

## Cache the browsers

Downloading the browser is the slowest step. Playwright keeps browsers in
`~/.cache/ms-playwright` on Linux; cache that folder and skip the install on a
hit:

```yaml title=".github/workflows/hydration.yml"
- name: Browser cache
  id: browsers
  uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
- if: steps.browsers.outputs.cache-hit != 'true'
  run: npx hydration-proof install --with-deps chromium
```

If your project already uses Playwright 1.63 or newer, hydration-proof uses the
same browsers, so an existing cache step covers both (see
[Playwright](https://hydration.jscrate.dev/docs/playwright)).

## Split the run across jobs

`--shard i/n` tests one part of the pages. The split depends only on the route
and the scenario, so the parts never overlap and together cover every page. A
final job merges the shard reports and applies the CI policy once, over every
finding:

```yaml title=".github/workflows/hydration.yml"
name: Hydration (sharded)
on: [pull_request]

permissions:
  contents: read
  security-events: write

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx hydration-proof install --with-deps chromium
      # The merge job decides the outcome, not each shard.
      - run: npx hydration-proof test --shard ${{ matrix.shard }}/4 --fail-on never --reporter json
      - uses: actions/upload-artifact@v4
        with:
          name: shard-${{ matrix.shard }}
          path: .hydration-proof/report

  report:
    needs: test
    if: ${{ !cancelled() }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - uses: actions/download-artifact@v4
        with:
          pattern: shard-*
          path: shards
      - run: npx hydration-proof merge-reports shards/shard-* --output .hydration-proof/report --reporter list,html,json,github,sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: ${{ !cancelled() && hashFiles('.hydration-proof/report/report.sarif') != '' }}
        with:
          sarif_file: .hydration-proof/report/report.sarif
          category: hydration-proof
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: hydration-report
          path: .hydration-proof/report
```

`merge-reports` applies the CI policy from the config (`failOn`, budgets and
ignore rules) to the merged findings, so a budget covers the whole run rather
than each shard. Each job builds and starts the app itself. To build once, build in
an earlier job, pass the build output as an artifact, and keep
`buildWhen: 'if-missing'`.

If you upload SARIF from each shard instead, give each upload its own
`category`, or each one replaces the previous shard's results.

## Test only what changed

On pull requests, `--changed` tests only the routes the changed files can
affect. hydration-proof follows the imports of your source files (including
`@/` path aliases and workspace packages) from the changed files to the route
files, their layouts and `_app`. Changes to `package.json`, lockfiles,
`next.config`, `tsconfig`, `middleware` or environment files test every route.

```yaml title=".github/workflows/hydration.yml"
- uses: actions/checkout@v4
  with:
    fetch-depth: 0 # the base branch must be available
# ...
- run: npx hydration-proof test --changed
```

Without a value, `--changed` compares with the pull request's base branch
(from `GITHUB_BASE_REF` or `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`), or with the
repository's default branch, usually `main`. Give a ref to choose another:
`--changed origin/develop`. Run the full suite on the main branch as well:
`--changed` cannot see changes in data or on the server.

## Decide what fails the build

`--fail-on` sets the lowest severity that fails the run: `error` (the default),
`warning`, `info` or `never`. The same setting is `ci.failOn` in the config.

```bash
npx hydration-proof test --fail-on warning
```

An app that already has findings should not start with a red pipeline. Record
a baseline and fail only on new findings, or allow a number of findings with a
budget: see [baselines and budgets](https://hydration.jscrate.dev/docs/baselines).

## What changes when CI=true

When the `CI` environment variable is set (to anything but an empty string,
`0` or `false`):

- every page that fails to load is retried once (`retries` defaults to `1`);
- a server that is already running is never reused (`server.reuseExisting`
  defaults to `false`), so the run always tests the app it started.

## More tips

- Test the production build: build in an earlier step and keep the default
  `buildWhen: 'if-missing'`, or pass `--build` to force a fresh build.
- Reports and screenshots show what the tested pages show. Treat the report
  artifact like other test output with user data; secrets and personal data
  are redacted by default (see [security](https://hydration.jscrate.dev/docs/security)).
- Keep sign-in credentials in CI secrets and read them in a scenario's `login`
  (see [scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios)).

## Related

- [Baselines, budgets and owners](https://hydration.jscrate.dev/docs/baselines) for apps with existing problems
- [Every report format](https://hydration.jscrate.dev/docs/reports): JUnit, SARIF, GitHub and GitLab
- [Test several apps of a monorepo](https://hydration.jscrate.dev/docs/monorepos)
- [CLI flags and exit codes](https://hydration.jscrate.dev/docs/cli)
- [Security and redaction](https://hydration.jscrate.dev/docs/security)

---

# Baselines, budgets and owners

> Adopt hydration-proof on an app with existing problems: a hydration error baseline and budget let CI fail only on new findings, with owners and trends.

Source: https://hydration.jscrate.dev/docs/baselines
Last updated: 2026-09-18

A hydration error baseline and budget let you adopt hydration-proof on an app
that already has problems. The baseline records today's findings, so CI fails
only on new ones. A budget allows a number of findings per severity, route or
issue code. Owners say who fixes each finding, and the history shows whether
the numbers go down.

## Record a baseline

Run the tests once and record every finding:

```bash
npx hydration-proof baseline   # records the current findings
```

Commit the file it writes:

```sh
git add .hydration-proof/baseline.json
```

Then fail CI only on findings that are not in it:

```bash
npx hydration-proof test --new-only
```

The same setting in the config is `ci.newIssuesOnly: true`. Findings in the
baseline are reported as known ("in baseline") and do not fail the run; new
findings are marked "new" and do. The terminal summary counts both.

`baseline` takes the same options as `test`. The file lives at
`.hydration-proof/baseline.json`; change the path with `ci.baseline`.

## How baseline entries match

Entries match by fingerprint: the issue code, the route pattern, the element
and the attribute. So an entry keeps matching when the page changes elsewhere,
and a new problem on the same page is still new.

Each entry records the route, the issue, the likely cause, the scenarios it
was seen in, and the dates it was first and last seen:

```json title=".hydration-proof/baseline.json"
{
  "$schema": "../node_modules/hydration-proof/schema/baseline.json",
  "version": 1,
  "tool": "hydration-proof",
  "updatedAt": "2026-09-18T09:12:44.120Z",
  "fingerprintVersion": 1,
  "entries": [
    {
      "fingerprint": "3f9c2a7d41e0b865",
      "code": "HP1004",
      "title": "Class name differs between server and client",
      "route": "/settings",
      "scenarios": ["default"],
      "firstSeen": "2026-09-18",
      "lastSeen": "2026-09-18",
      "selector": "#theme",
      "attribute": "class",
      "cause": "theme",
      "expires": "2026-12-31",
      "reason": "The theme toggle rewrite is tracked in ACME-512."
    }
  ]
}
```

## Add a reason and an expiry date

Add `reason` and `expires` (`YYYY-MM-DD`) to an entry by hand. The reason is
shown in reports. After the expiry date the finding fails the run again, with a
message such as "The baseline entry for HP1004 on /settings (#theme) expired on
2026-12-31.", so accepted problems do not stay forever.

## Update the baseline

After fixing problems, record again:

```bash
npx hydration-proof baseline
# or, as part of a normal run:
npx hydration-proof test --update-baseline
```

Fixed entries are removed. The fields you wrote by hand and the `firstSeen`
dates are kept.

If a release has to change how fingerprints are computed, the report's
`fingerprintVersion` goes up. Until you record again, entries with an older
version are matched by code, route and selector instead, so the pipeline does
not turn red overnight.

## Budgets

A budget allows a number of findings instead of failing on the first one:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ci: {
    budget: {
      error: 3,
      warning: 20,
      routes: { "/checkout/**": { error: 0, warning: 0 } },
      codes: { HP1004: 2 },
    },
  },
});
```

- `error`, `warning`, `info`: the most findings of that severity in the run.
  A budget for a severity replaces the "any finding fails" rule for that
  severity.
- `routes`: limits per severity for the routes matching each glob.
- `codes`: limits per issue code, such as `{ HP1004: 3 }`.

When a limit is exceeded, the run fails with a message like "4 errors exceed
the budget of 3." Lower the numbers as problems are fixed, so the count can only
go down.

## failOn and maxWarnings

`ci.failOn` is the lowest severity that fails the run: `'error'` (the default),
`'warning'`, `'info'` or `'never'`. `--fail-on` sets it for one run.
`ci.maxWarnings` fails the run when there are more warnings than this, even
when warnings do not fail it on their own.

Pin these explicitly if the outcome matters to you: an issue code's default
severity can be raised or lowered in a minor release (see
[compatibility](https://hydration.jscrate.dev/docs/compatibility)).

## Combine a hydration error baseline and budget

A CI policy for an app that already has findings: green from day one, a
ratchet that stops the numbers from growing, and a checkout flow that must stay
clean.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ci: {
    failOn: "error",
    // Only findings that are not in the baseline fail.
    newIssuesOnly: true,
    baseline: ".hydration-proof/baseline.json",
    // The ratchet: the numbers may only go down.
    budget: {
      error: 0,
      warning: 12,
      routes: { "/checkout/**": { error: 0, warning: 0 } },
      codes: { HP1004: 3 },
    },
    history: true,
  },

  // Who gets pinged, from CODEOWNERS unless the route says otherwise.
  owners: {
    routes: { "/checkout/**": ["@acme/payments"] },
    codeowners: true,
  },
});
```

[Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci) has the workflows to run it in.

## Owners

Findings show who owns them. Route owners come from `owners.routes`; for other
findings, the CODEOWNERS entry of the finding's source file is used.
hydration-proof looks for `.github/CODEOWNERS`, `CODEOWNERS`,
`docs/CODEOWNERS` and `.gitlab/CODEOWNERS`, or the path you give in
`owners.codeowners`. Set it to `false` to turn the lookup off.

The terminal prints the owners under each finding, `report.json` has them in
`owners`, and the HTML report can be filtered by owner.

## Trends

`ci.history: true` appends one line per run to `.hydration-proof/history.ndjson`
(or to the path you give). Each line holds the date, the commit and branch, the
duration, the number of pages and failed pages, and the findings by severity
and by issue code. Ignored findings are not counted.

The HTML report shows the errors and warnings of the last 30 runs. Keep the
file between CI runs, for example with `actions/cache` or by committing it on
the main branch; otherwise the trend starts over every run.

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `failOn` | `Severity \| "never"` | `"error"` | Lowest severity that makes the run fail. |
| `maxWarnings` | `number` | — | Fail when more warnings than this are found. |
| `baseline` | `string` | `.hydration-proof/baseline.json` | Baseline file of accepted issues. |
| `newIssuesOnly` | `boolean` | — | Only fail on issues that are not in the baseline. |
| `budget` | `BudgetConfig` | — | Hydration error budget: how many findings of a severity (in total, per route glob or per code) are allowed before the run fails. |
| `history` | `boolean \| string` | — | Append a line per run to a history file for trends: `true` for `.hydration-proof/history.ndjson`, or a path. |

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `routes` | `Record<string, BudgetLimits>` | — | Limits for the findings of routes matching each glob. |
| `codes` | `Record<string, number>` | — | Limits per issue code, e.g. `{ HP1004: 3 }`. |
| `error` | `number` | — | Inherited from BudgetLimits. |
| `warning` | `number` | — | Inherited from BudgetLimits. |
| `info` | `number` | — | Inherited from BudgetLimits. |

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `routes` | `Record<string, string \| string[]>` | — | Route glob → owners, e.g. `{ '/checkout/**': ['@acme/payments'] }`. |
| `codeowners` | `boolean \| string` | — | Owners of source files from CODEOWNERS: `true` (default) looks in .github/, docs/ and the repository root; or a path. |

## Related

- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci): workflows, sharding and `--changed`
- [Ignore known hydration mismatches](https://hydration.jscrate.dev/docs/ignoring) one at a time
- [Reports](https://hydration.jscrate.dev/docs/reports): the `new`, `baseline` and `owners` fields
- [The `ci` option](https://hydration.jscrate.dev/docs/configuration#ci) in the configuration reference
- [What is stable between releases](https://hydration.jscrate.dev/docs/compatibility)

---

# Dev overlay, watch mode and dashboard

> hydration-proof dev opens your app with a hydration error overlay: every page you open is checked, with the element, both values, the cause and source line.

Source: https://hydration.jscrate.dev/docs/dev-overlay
Last updated: 2026-09-18

`hydration-proof dev` opens your app in a browser with a hydration error
overlay. Every page you open is checked the way `hydration-proof test` checks
it, and the findings appear in a panel in the corner of the page and in the
terminal: the element, the server and client values, the likely cause, the
fix and the source line.

## Open the overlay

```bash
npx hydration-proof dev
```

It starts the development server for you and opens a browser window. By
default it uses the development build (`--mode development`), which gives
exact source lines. Useful options:

- `--url http://localhost:3000` uses an app that is already running.
- `--route /pricing` opens that page first.
- `--scenario dark-mobile` browses in one of your [scenarios](https://hydration.jscrate.dev/docs/scenarios).
- `--mode production` checks the production build instead.
- `--browser firefox` or `--channel chrome` picks the browser.

## What the hydration error overlay shows

A badge in the corner shows the state of the current page: checking, no
problems, or the number of errors and warnings. The panel opens by itself when
the page has an error. For each finding it shows the code, the element, the
component, the likely cause with its confidence (or "proven"), both values and
the first fix, with these actions:

- **Highlight** scrolls to the element and outlines it.
- **Open file:line** opens the source in your editor.
- **Copy** puts a Markdown summary of the finding on the clipboard, ready for
  an issue or a pull request. **Copy report** does the same for every finding
  on the page.
- **Docs** opens the page for the issue code.
- **Re-run** reloads the page and checks it again.

The overlay is injected by the test browser. Your app is not changed, nothing
is added to its bundle, and the checks ignore the overlay. It renders in a
shadow root, so its styles and your app's styles stay apart.

Client-side navigations keep the result of the last loaded page. Reload to
check the page you navigated to.

## Open files in your editor

**Open file:line** uses the editor named in `HYDRATION_PROOF_EDITOR`, `VISUAL`
or `EDITOR`, in that order, such as `code`, `cursor`, `zed`, `webstorm`, `subl`
or `nvim`:

```sh
export HYDRATION_PROOF_EDITOR=cursor
```

Without one, it uses the first of `cursor`, `code`, `windsurf`, `codium`,
`zed`, `webstorm`, `idea` and `subl` found on your `PATH`. Only files inside
the project are opened.

## How it differs from the Next.js dev overlay

Unlike an overlay that shows the hydration errors React itself logs, the
hydration-proof overlay runs the same checks as `hydration-proof test`:

- It compares the server HTML with the hydrated DOM, so it also finds markup
  the browser repaired and changes that other scripts or extensions made
  before hydration.
- With `--mode production`, it finds the attribute differences React does not
  report in production builds.
- Each finding gets a likely cause and a fix for that cause.
- It works with every framework hydration-proof supports, not only Next.js.

The two work side by side. See
[hydration-proof and the Next.js dev overlay](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay)
for a full comparison.

> **Next.js allowedDevOrigins**
>
> hydration-proof opens the Next.js dev server on `localhost`, because Next.js
> blocks development resources for other hosts. If you test a dev server through
> another host name, add it to `allowedDevOrigins` in `next.config`.

## Watch mode: test --watch

Watch mode re-runs the tests while you work, with no browser window to click
through:

```bash
npx hydration-proof test --watch
```

It starts the development server once, tests every route, then waits for
changes. After each change, only the routes the changed files can affect are
tested, the same way [`--changed`](https://hydration.jscrate.dev/docs/ci#test-only-what-changed) chooses
them. Changes to `package.json`, configs or environment files test every
route. Add `--mode production` to test the production server instead; it is
not rebuilt on changes. Stop it with Ctrl+C.

## Dashboard: hydration-proof ui

```bash
npx hydration-proof ui --open
```

A local page to start test runs (all routes or some, with probes, interaction
or navigation checks), follow their output live and read the latest HTML
report. `--port` picks the port (a free one by default), and `--open` opens it
in your default browser.

The dashboard listens on `127.0.0.1` only, and the printed URL contains a
random access token that every request needs. It refuses requests for other
host names and cross-site requests. Stop it with Ctrl+C.

## Options

| Option | What it does |
| --- | --- |
| `-c, --config <file>` | Config file |
| `-u, --url <url>` | Use an app that is already running |
| `-r, --route <path>` | Page to open first (default: the first configured route, or /) |
| `-s, --scenario <name>` | Scenario to browse in (default: the first one) |
| `--mode <mode>` | development (default) or production |
| `--browser <name>` | chromium (default), firefox or webkit |
| `--channel <name>` | Use an installed browser, e.g. chrome |

| Option | What it does |
| --- | --- |
| `-c, --config <file>` | Config file |
| `-p, --port <port>` | Port (default: a free port) |
| `--open` | Open the dashboard in the default browser |

## Related

- [hydration-proof and the Next.js dev overlay](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay)
- [How to debug hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Every command and flag of the CLI](https://hydration.jscrate.dev/docs/cli)
- [Hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Prove the cause of a finding with probes](https://hydration.jscrate.dev/docs/probes)

---

# Use hydration-proof with Playwright

> Find every Playwright hydration error your e2e suite misses: hydration-proof drives Playwright, waits for React to hydrate and reuses your browsers and login.

Source: https://hydration.jscrate.dev/docs/playwright
Last updated: 2026-09-18

A Playwright hydration error test needs more than `page.goto()` and a console
listener. hydration-proof is built on Playwright: it waits for React to finish
hydrating, compares the server HTML with the hydrated DOM, and reports the
differences React never logs. Run it next to your e2e suite, and reuse that
suite's browsers, login and server.

## Built on Playwright

hydration-proof drives Chromium, Firefox and WebKit through `playwright-core`
1.63 or newer, its only runtime dependency. `playwright-core` downloads nothing
when you install it, and at run time hydration-proof prefers your project's own
copy when it is new enough:

- The browsers you already have in `~/.cache/ms-playwright` are used as they
  are. Nothing is downloaded twice.
- `npx hydration-proof install` is only needed when the project has no
  Playwright browsers at all.

## Why does a Playwright hydration error go unnoticed?

A common way to catch hydration errors in Playwright tests is a console
listener:

```ts title="e2e/home.spec.ts"
import { expect, test } from "@playwright/test";

test("home page has no hydration errors", async ({ page }) => {
  const errors: string[] = [];
  page.on("console", (message) => {
    if (message.type() === "error") errors.push(message.text());
  });

  await page.goto("/");
  expect(errors).toEqual([]);
});
```

It misses most problems and explains none of them. Playwright hydration issues
slip through for four reasons:

1. **Production builds say almost nothing.** At best the console shows a
   minified error code such as `Minified React error #418`, with no element
   and no values, and nothing at all for attribute mismatches.
2. **React 19 keeps wrong attributes silently.** In production, a mismatched
   `className`, `style` or `data-*` attribute is never reported and never
   fixed.
3. **React recovers.** When the text or structure differs, React 19 throws the
   server HTML away and renders the page again on the client. The page works,
   so assertions about its content still pass, while users get a slower page
   and lose state.
4. **The server HTML looks ready too early.** Buttons and fields are visible
   before React attaches its handlers, so a test that clicks as soon as an
   element appears can act before hydration, or wait for the wrong thing.

hydration-proof checks for all of this directly. It compares each stage of the
page, from the server HTML to the hydrated DOM, and audits every attribute
against the props React renders on the client. See
[how it works](https://hydration.jscrate.dev/docs/how-it-works).

## How to make Playwright wait for hydration

Waiting for hydration is the hard part. The page's load event does not mean
React has hydrated, and a visible element proves nothing, because the server
HTML rendered it.

hydration-proof connects to React through `__REACT_DEVTOOLS_GLOBAL_HOOK__`,
the hook React looks for when it loads, in development and production builds.
It provides the hook, or wraps an existing one so React DevTools and Fast
Refresh keep working, and React then reports every renderer and every commit
to it. So hydration-proof knows when the root and each Suspense boundary have
hydrated.

After hydration, it waits until the page is quiet. It never waits for
"network idle". The `ready` option sets the rules:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ready: {
    // Wait for the same thing the e2e suite waits for.
    selector: "[data-app-ready]",
    // No DOM changes or React commits for this long.
    quietMs: 400,
    // Hydration must finish within this time once React has loaded.
    hydrationTimeout: 15_000,
    // The most time one page may take.
    timeout: 30_000,
  },
});
```

`ready.function` is a page function, written as a string, that must return a
truthy value before the final snapshot. A route can have its own `ready`
settings in `routes.paths`.

A page whose hydration does not finish in time is reported as
[HP9001](https://hydration.jscrate.dev/docs/issues/hp9001). A page that never becomes quiet (animations,
polling, live data) is reported as [HP9009](https://hydration.jscrate.dev/docs/issues/hp9009): set
`ready.selector` or `ready.function`, or lower `ready.quietMs`.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `quietMs` | `number` | 400 | Quiet time (ms) without DOM changes or React commits before the page counts as settled. |
| `timeout` | `number` | 30000 | Maximum time (ms) per page. |
| `hydrationTimeout` | `number` | 15000 | Maximum time (ms) for hydration to finish once React is loaded. |
| `selector` | `string` | — | A selector that must exist before the final snapshot. |
| `function` | `string` | — | Page function source that must return truthy before the final snapshot. |

## Use it with an existing Playwright setup

Three things from your Playwright setup are worth reusing:

1. **The browsers.** Nothing to do: see [above](#built-on-playwright).
2. **The login.** If your Playwright global setup signs in and saves
   `storageState` (for example to `playwright/.auth/user.json`), point a
   scenario's `storageState` at the same file. The login then runs once, in
   whichever suite runs first.
3. **The server.** If Playwright's `webServer` already starts the app, leave
   `server` out of the hydration-proof config and pass the URL.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  // The app is already running: CI starts it, or Playwright's webServer does.
  server: {
    url: process.env.BASE_URL ?? "http://localhost:3000",
    reuseExisting: true,
  },

  routes: { discover: true },

  scenarios: [
    {
      name: "signed-in",
      // The file Playwright's global setup already wrote.
      storageState: "playwright/.auth/user.json",
    },
  ],

  ready: {
    selector: "[data-app-ready]",
    quietMs: 200,
    timeout: 15_000,
  },
});
```

Or skip the config and pass the URL on the command line:

```bash
npx hydration-proof test --url http://localhost:3000
```

For signed-in pages with a `login` function instead of a saved state, see
[scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios).

## Run it next to your tests, not inside them

> **Do not run hydration-proof inside a Playwright test**
>
> hydration-proof launches and drives its own browser contexts, takes six DOM
> snapshots per page and needs each page loaded without interference. Nested in
> a Playwright worker, it fights your tests for the same browser and slows both
> down.

Run it as its own command, next to the e2e suite. When a script needs to do
something around the run, such as start a server, seed a database or publish
the report, call `run()` from Node:

```ts title="run-from-node.ts"
import { run } from "hydration-proof";

const { exitCode, report } = await run({
  overrides: { url: "http://localhost:3000", reporters: ["json"] },
  write: (text) => process.stdout.write(text),
});

// The report is the same object the JSON reporter writes.
for (const issue of report.issues) {
  if (issue.severity !== "error") continue;
  console.log(
    `${issue.route.pattern} ${issue.code} ${issue.source?.file ?? "(no source)"}`
  );
}

process.exit(exitCode);
```

The [Node API](https://hydration.jscrate.dev/docs/node-api) covers `run()` and its options.

## Related

- [How hydration-proof works](https://hydration.jscrate.dev/docs/how-it-works): the stages it compares
- [The Node API](https://hydration.jscrate.dev/docs/node-api) for scripts around a run
- [Scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios)
- [Lost clicks and input before hydration](https://hydration.jscrate.dev/docs/interactions)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)

---

# Node API

> The hydration-proof Node API: run tests from a script with run(), read and merge reports, define configs, plugins and adapters, and use the stable exit codes.

Source: https://hydration.jscrate.dev/docs/node-api
Last updated: 2026-09-18

The hydration-proof Node API runs the same test as the CLI from your own
script. `run()` resolves with the report and the exit code and never calls
`process.exit`, so you can start a server, seed data or publish the report
around it. Everything on this page is exported from the `hydration-proof`
package.

## Run a test with run()

```ts title="run-from-node.ts"
import { run } from "hydration-proof";

const { exitCode, report } = await run({
  overrides: { url: "http://localhost:3000", reporters: ["json"] },
  write: (text) => process.stdout.write(text),
});

// The report is the same object the JSON reporter writes.
for (const issue of report.issues) {
  if (issue.severity !== "error") continue;
  console.log(
    `${issue.route.pattern} ${issue.code} ${issue.source?.file ?? "(no source)"} — ${issue.cause?.title ?? "unknown cause"}`
  );
}

process.exit(exitCode);
```

`run()` reads the config the way the CLI does, from `cwd` or the file you name
in `config`. `overrides` are the same overrides the command line applies, such
as `url`, `routes`, `reporters`, `failOn`, `probes` or `shard`. `write`
receives the progress and the terminal report (standard output by default),
and `reporters` adds your own reporters to the configured ones.

```ts
function run(options?: RunOptions): Promise<RunResult>
```

Runs a test the way `hydration-proof test` does and resolves with the report and exit code. It never calls `process.exit`.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `cwd` | `string` | `process.cwd()` | Directory the config is looked up from. |
| `config` | `string` | — | Config file path; found automatically when omitted. |
| `overrides` | `CliOverrides` | — | The same overrides the command line applies, e.g. `{ url, routes, reporters, failOn }`. |
| `write` | `(text: string) => void` | — | Where progress and the terminal report are written. |
| `reporters` | `Reporter[]` | — | Extra reporters (in addition to the configured ones). |
| `signal` | `AbortSignal` | — | Abort the run (the app and browser are shut down). |

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `report` (required) | `Report` | — | The full report, the same object `report.json` holds. |
| `exitCode` (required) | `ExitCode` | — | The exit code the CLI would use. See `ExitCode`. |
| `failures` (required) | `string[]` | — | Human-readable reasons the run failed. |
| `files` (required) | `string[]` | — | Report files that were written. |
| `notes` (required) | `string[]` | — | Informational notes printed at the end of the run. |
| `outputDir` (required) | `string` | — | Where the reports were written. |

To stop a run early, pass an `AbortSignal`. When it aborts, the app and the
browser are shut down:

```ts title="run-with-timeout.ts"
import { run } from "hydration-proof";

// Stop the run, the app and the browser after ten minutes.
await run({ signal: AbortSignal.timeout(10 * 60_000) });
```

## Handle errors with RunError

Problems found on pages never throw: they are in the report, and `exitCode`
says whether the policy failed. `run()` throws a `RunError` for failures that
stop a run before any page is tested, such as an invalid config, a failing
`setup` hook or login, a browser that cannot launch, or an app that cannot be
started. Its `exitCode` is the one the CLI would use:

```ts title="hydration.ts"
import { run, RunError } from "hydration-proof";

try {
  const result = await run();
  process.exitCode = result.exitCode;
} catch (error) {
  if (!(error instanceof RunError)) throw error;
  console.error(error.message);
  process.exitCode = error.exitCode;
}
```

```ts
class RunError extends Error {
  override name: string;
  readonly exitCode: ExitCode;
  readonly details: string | undefined;
  constructor(message: string, exitCode: ExitCode, details?: string);
}
```

Thrown by `run()` for failures that stop a run before any page is tested, with the exit code the CLI would use.

## Exit codes

`ExitCode` names the codes the CLI exits with. They are stable:

| Name          | Code  | Meaning                                                        |
| ------------- | ----- | -------------------------------------------------------------- |
| `Ok`          | `0`   | Every page passed the policy                                   |
| `Failed`      | `1`   | Findings, a budget or an expired ignore rule failed the policy |
| `Usage`       | `2`   | Invalid configuration or command-line usage                    |
| `Server`      | `3`   | The app could not be built, started or reached                 |
| `Browser`     | `4`   | The browser is missing or failed to launch                     |
| `Internal`    | `70`  | A bug in hydration-proof                                       |
| `Interrupted` | `130` | Interrupted (Ctrl+C)                                           |

```ts
const ExitCode: {
  /** Every page passed the policy. */
  readonly Ok: 0;
  /** Issues, budget or expired ignore rules failed the policy. */
  readonly Failed: 1;
  /** Invalid configuration or command-line usage. */
  readonly Usage: 2;
  /** The app could not be built, started or reached. */
  readonly Server: 3;
  /** The browser is missing or failed to launch. */
  readonly Browser: 4;
  /** A bug in hydration-proof. */
  readonly Internal: 70;
  /** Interrupted (Ctrl+C). */
  readonly Interrupted: 130;
}
```

Exit codes. They are stable: `0` ok, `1` failed, `2` usage or config error, `3` server, `4` browser, `70` internal error. An interrupted run exits `130`.

## Read and merge reports

`readReport()` reads `report.json` from a report folder or a file path.
`mergeReports()` combines the reports of sharded or per-project runs into one
report, removing duplicates. The CLI's
[`merge-reports`](https://hydration.jscrate.dev/docs/ci#split-the-run-across-jobs) command wraps it, and
also applies the CI policy and runs the reporters.

```ts title="merge.ts"
import { writeFileSync } from "node:fs";
import { mergeReports, readReport } from "hydration-proof";

const report = mergeReports(
  ["shards/shard-1", "shards/shard-2"].map((dir) => readReport(dir))
);

writeFileSync("merged-report.json", JSON.stringify(report, null, 2));
console.log(`${report.summary.failed} pages failed`);
```

```ts
function mergeReports(inputs: readonly MergeInput[]): Report
```

Combines the reports of sharded or per-project runs into one, removing duplicates. The CLI's `merge-reports` command wraps it.

```ts
function readReport(path: string): MergeInput
```

Read `report.json` from a folder or a file path.

## Configs, plugins and adapters

`defineConfig()`, `definePlugin()` and `defineAdapter()` give the config file,
a plugin and an adapter type checking and completion. `ADAPTERS` lists the
built-in adapters in detection order, most specific first. See
[plugins](https://hydration.jscrate.dev/docs/plugins) for normalizers, cause detectors, route providers and
reporters, and [adapters](https://hydration.jscrate.dev/docs/adapters) for frameworks hydration-proof does
not know.

```ts
function defineConfig(config: HydrationProofConfig): HydrationProofConfig
```

Identity helper that gives `hydration-proof.config.ts` type checking and completion.

```ts
function definePlugin(plugin: HydrationProofPlugin): HydrationProofPlugin
```

Identity helper with type checking for plugins.

```ts
function defineAdapter(definition: AdapterDefinition): Adapter
```

Create an adapter for a framework hydration-proof does not know.

## Issue codes and documentation links

`ISSUES` maps every issue code to its name, title, default severity and
description. `docsUrl()` returns the documentation page of a code:

```ts title="list-codes.ts"
import { docsUrl, ISSUES } from "hydration-proof";

for (const [code, issue] of ISSUES) {
  console.log(`${code} ${issue.severity} ${issue.title} ${docsUrl(code)}`);
}
```

```ts
const ISSUES: ReadonlyMap<IssueCode, IssueDefinition>
```

Every issue code with its name, title, default severity and description. The [issue code reference](https://hydration.jscrate.dev/docs/issues) is generated from it.

```ts
function docsUrl(code: IssueCode): string
```

The documentation URL for an issue code, e.g. `https://hydration.jscrate.dev/docs/issues/hp1001`.

## Schemas and versions

`configJsonSchema()` returns the JSON Schema of the config file, the same one
published at `/schema/config.json` and shipped as
`node_modules/hydration-proof/schema/config.json`. `VERSION` is the installed
version. `REPORT_SCHEMA_VERSION` is the `schemaVersion` written into
`report.json`, `1`, and it changes only in a major release.

```ts
function configJsonSchema(): JsonSchema
```

The JSON Schema of the config file, the same one published at `/schema/config.json`.

```ts
const VERSION: string
```

The installed version of hydration-proof.

```ts
const REPORT_SCHEMA_VERSION = 1
```

The `schemaVersion` written into `report.json`. It changes only in a major release.

## What is stable in the hydration-proof Node API

From 1.0 on, the stable parts follow semver: they change only in a major
release, with a migration path.

- **Stable:** `run()`, `defineConfig`, `definePlugin`, `defineAdapter`,
  `mergeReports`, `ISSUES` and the types they use; the exit codes; and
  `report.json` with `schemaVersion: 1`, where fields are added but never
  removed or repurposed.
- **Not stable:** anything the package does not export; the HTML report's
  markup and embedded data; the wording of messages, the set of `evidence`
  entries and confidence scores; and which cause a finding is given. Treat a
  cause as an explanation for a person, not something to assert on.

A code's default severity can change in a minor release. If your script
depends on what fails, set `failOn` or a budget explicitly. The
[compatibility](https://hydration.jscrate.dev/docs/compatibility) page has the full list.

## Related

- [The CLI](https://hydration.jscrate.dev/docs/cli): the same run from the command line
- [Write a plugin](https://hydration.jscrate.dev/docs/plugins): reporters, detectors and route providers
- [Adapters](https://hydration.jscrate.dev/docs/adapters) for other frameworks
- [The report format](https://hydration.jscrate.dev/docs/reports)
- [Compatibility and stability](https://hydration.jscrate.dev/docs/compatibility)

---

# Monorepos

> Run hydration tests in a monorepo with one command: list each app under projects, keep a config per app, pick one with --project and get one combined report.

Source: https://hydration.jscrate.dev/docs/monorepos
Last updated: 2026-09-18

To run hydration tests in a monorepo, put a hydration-proof config at the
repository root that lists your apps under `projects`. Each app keeps its own
config, with its own server, routes, scenarios and CI policy.
`npx hydration-proof test` then tests every app, one after another, and writes
one combined report.

## How to run hydration tests in a monorepo

A repository with three apps looks like this:

```text
repo/
  hydration-proof.config.ts             lists the projects
  apps/web/hydration-proof.config.ts
  apps/admin/hydration-proof.config.ts
  apps/docs/config/hydration-proof.ts
```

1. Give every app a config of its own. Running `npx hydration-proof init` in
   an app's folder writes one from that app's `package.json` and route folders.
2. List the apps in a config at the repository root:

   ```ts title="hydration-proof.config.ts"
   import { defineConfig } from "hydration-proof";

   export default defineConfig({
     projects: [
       // A path is enough when the folder has a hydration-proof config.
       "apps/web",
       // A name makes --project admin and the report grouping read better.
       { path: "apps/admin", name: "admin" },
       // Or point at a config that is not in the default place.
       { path: "apps/docs", name: "docs", config: "config/hydration-proof.ts" },
     ],
   });
   ```

3. Run the tests from the root:

   ```bash
   npx hydration-proof test
   ```

Why not one config with every route? Because the apps have different servers.
hydration-proof starts an app (building it first when there is no build yet),
tests it, stops it, and only then moves on to the next one.

## Each project

Each entry in `projects` is a folder path, or an object:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `path` (required) | `string` | — | Folder of the project (with its own hydration-proof config). |
| `name` | `string` | the folder name | Name shown in reports. |
| `config` | `string` | found automatically | Config file inside the folder. |

Project names must be unique. When two folders have the same name (say
`apps/web` and `packages/web`), set `name` on one of them.

## Configure each app on its own

A project config is an ordinary config. Everything about how an app is tested
comes from it: the server, routes, scenarios, ignore rules, the baseline and
the CI policy.

```ts title="apps/admin/hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  server: {
    command: "pnpm start --port {port}",
    build: "pnpm build",
    port: 3002,
  },
  routes: { discover: true, dynamic: { "/users/[id]": ["1"] } },
  scenarios: [
    {
      name: "admin",
      cookies: [{ name: "session", value: process.env.ADMIN_SESSION ?? "" }],
    },
  ],
  // The legacy app may keep a shrinking number of warnings.
  ci: { budget: { error: 0, warning: 8 } },
});
```

A per-project `ci.budget` lets the app that is already clean stay at zero while
a legacy app works its numbers down. See
[baselines and budgets](https://hydration.jscrate.dev/docs/baselines) for the other ways to adopt the tool
on an app that already has findings.

The root config decides where the combined report goes and in which formats
(`outputDir`, `reporters`). Command-line flags such as `--mode both` or
`--fail-on warning` apply to every project.

### Does each app need its own port?

Only if you set one. Without `server.port`, every app gets a free port and
there is nothing to do.

If a config sets `server.port`, give every app a different one. Outside CI,
hydration-proof reuses an app that already answers on a configured port
(`server.reuseExisting`), so two apps on the same port can end up testing the
same server.

## Test one app with --project

```bash
npx hydration-proof test --project admin
npx hydration-proof test --project admin --project docs
```

`--project` takes a project's name or its path, and can be repeated. An unknown
name stops the run with exit code `2` and lists the projects that exist.

## Read the combined report

The root writes one report for all apps, in the formats its `reporters` list.
Findings are grouped by project, so a finding is never ambiguous about which
app it came from. Screenshots are copied next to the combined report, and each
app also keeps its own report in its own output folder.

The run fails when any project fails. If an app cannot be built or started, the
other apps are still tested, and the run exits with that app's code (`3`), which
takes precedence over findings (`1`). [Exit codes](https://hydration.jscrate.dev/docs/cli) lists them all.

To combine reports yourself, for example from one CI job per app, use
`hydration-proof merge-reports` or `mergeReports()` from the
[Node API](https://hydration.jscrate.dev/docs/node-api).

## Owners from CODEOWNERS

Findings show who owns them. hydration-proof looks for `CODEOWNERS` at the
repository root (the nearest folder with `.git`): `.github/CODEOWNERS`,
`CODEOWNERS`, `docs/CODEOWNERS` or `.gitlab/CODEOWNERS`. Every app finds the
same file, so findings are attributed to the right team without any
configuration. Route owners (`owners.routes`) go in each app's config.

## Test only what a pull request changed

```bash
npx hydration-proof test --changed
```

`--changed` follows the import graph from the files a pull request touches to
the routes that render them, across package boundaries. In a monorepo that is
the difference between testing three apps and testing four pages. By default it
compares with the pull request's base branch, or `main`.

A shared package that every app imports still selects every route that uses
it. That is correct: a change there can break all of them.

## Related

- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci): workflows, sharding and annotations
- [Baselines and budgets](https://hydration.jscrate.dev/docs/baselines) for apps with existing findings
- [Configuration reference](https://hydration.jscrate.dev/docs/configuration)
- [CLI commands and flags](https://hydration.jscrate.dev/docs/cli)
- [Adapters](https://hydration.jscrate.dev/docs/adapters): how each app is built and started

---

# Adapters

> hydration-proof adapters build, start and find the routes of Next.js, React Router, Remix, Astro and Vite SSR apps, or write your own with defineAdapter.

Source: https://hydration.jscrate.dev/docs/adapters
Last updated: 2026-09-18

hydration-proof adapters tell the CLI how to build and start your app, where
its routes are, and which markup the framework adds that is not page content.
With the default `adapter: "auto"`, the adapter is chosen from `package.json`
and your config files. Set it yourself when detection is wrong, or write one
for a framework it does not know.

## Which hydration-proof adapters are built in?

| Adapter        | Detected by                                                      | Build / start / dev                                                                                                   | Routes                                                 | Client navigation                           |
| -------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------- |
| `next`         | `next` dependency or `next.config.*`                             | `next build` (or your `build` script when it runs `next build`) / `next start --port {port}` / `next dev`             | `app/` and `pages/`, plus pages the build pre-rendered | `router.push` (App Router and Pages Router) |
| `react-router` | `@react-router/dev` or `react-router.config.*`                   | `react-router build` / `react-router-serve ./build/server/index.js` / `react-router dev`                              | `react-router routes --json`                           | `window.__reactRouterDataRouter.navigate`   |
| `remix`        | `@remix-run/dev`                                                 | `remix vite:build` / `remix-serve ./build/server/index.js` / `remix vite:dev` (the classic compiler is supported too) | `remix routes --json`                                  | `window.__remixRouter.navigate`             |
| `astro`        | `astro` or `astro.config.*`                                      | `astro build` / `node ./dist/server/entry.mjs` with `@astrojs/node`, otherwise `astro preview` / `astro dev`          | `src/pages`                                            | —                                           |
| `vite`         | `vite` and `react-dom`, plus `server.js` or `src/entry-server.*` | the `build`, `start` (or `serve`, `preview`) and `dev` scripts                                                        | from the config                                        | —                                           |
| `node`         | `react-dom` and a `start` script                                 | the `build`, `start` and `dev` scripts                                                                                | from the config                                        | —                                           |
| `none`         | the fallback                                                     | `server.command` / `server.build`                                                                                     | from the config                                        | —                                           |

With `adapter: "auto"`, adapters from [plugins](https://hydration.jscrate.dev/docs/plugins) are tried first,
then the built-in ones in the order of the table. The first match wins, and
`none` is used when nothing matches.

Each adapter also knows the file that means a build exists, such as
`.next/BUILD_ID` for Next.js. By default the app is built only when that file
is missing (`server.buildWhen: "if-missing"`); `--build` forces a fresh build.

### What else an adapter handles

- **Framework markup.** Markup the framework adds is left out of every
  comparison: the Next.js route announcer, dev overlay and RSC payload scripts,
  the React Router and Remix context scripts, Astro's island loader and dev
  toolbar, and Vite's client and React Refresh scripts.
- **The development server host.** The `next` adapter opens `next dev` on
  `localhost`, because Next.js blocks development resources for other hosts.
- **The not-found page.** The `next`, `react-router`, `remix` and `astro`
  adapters also load `/hydration-proof-not-found` and check that the not-found
  page hydrates. It must answer 404. Turn this off with `routes.notFound: false`.
- **Client navigation.** Adapters with a router in the last column support
  [navigation checks](https://hydration.jscrate.dev/docs/interactions), which compare a client-side
  navigation to each route with loading it directly.

Dynamic routes use one syntax for every framework: `[id]`, `[...slug]`
(catch-all) and `[[lang]]` (optional). React Router's `:id`, `*` and `:lang?`
are converted, so `routes.dynamic` looks the same everywhere:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: { dynamic: { "/products/[id]": ["1", "42"] } },
});
```

## Choose an adapter

Set `adapter` when detection picks the wrong framework, or to skip detection
altogether:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({ adapter: "react-router" });
```

| Value                                                                | Meaning                                                           |
| -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `"auto"`                                                             | Detect from `package.json` and config files (the default)         |
| `"next"`, `"react-router"`, `"remix"`, `"astro"`, `"vite"`, `"node"` | That built-in adapter                                             |
| `"none"`                                                             | No framework: `server.command` and `routes` come from your config |
| a plugin adapter's name                                              | An adapter a plugin provides                                      |
| `defineAdapter({ … })`                                               | An adapter object from your config                                |

An unknown name stops the run with exit code `2` and lists the adapters that
exist. To see what was detected, and how many routes it found, run:

```bash
npx hydration-proof doctor
```

Every adapter can be overridden: `server.command`, `server.build`,
`server.devCommand` and `routes` in your config always win.

## Custom React servers

For Express, Fastify, `node:http` or any other server that renders React, use
the `node` adapter (or `none`) with your own commands:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  adapter: "node",
  server: {
    build: "npm run build",
    command: "node server.js", // listens on process.env.PORT
    devCommand: "node --watch server.js",
  },
  routes: { paths: ["/", "/pricing", "/products/1"] },
});
```

`{port}` in a command is replaced with the port hydration-proof chose, and the
same port is in the `PORT` environment variable. A custom start command only
gets a build step when you configure `server.build`.

Streaming servers are supported. With `renderToPipeableStream` or
`renderToReadableStream`, Suspense boundaries that hydrate later are compared
on their own. [Custom React servers](https://hydration.jscrate.dev/docs/frameworks/custom-server) covers the
setup in detail.

## Astro islands

Each `<astro-island>` hydrates as its own React root, so findings are reported
per island. Astro changes island attributes (`ssr`, `props`, `client` and
others) while it loads them; these are never compared. Pages without any React
are normal in an Astro site and are not reported.

Islands that call `useId` need an `identifierPrefix`, or two roots generate the
same ids. Astro's React integration sets one per island; without it
hydration-proof reports [HP3004](https://hydration.jscrate.dev/docs/issues/hp3004). See
[Astro hydration errors](https://hydration.jscrate.dev/docs/frameworks/astro).

## Write an adapter with defineAdapter

For a framework hydration-proof does not know, create an adapter with
`defineAdapter`, directly in the config or in a plugin:

```ts
function defineAdapter(definition: AdapterDefinition): Adapter
```

Create an adapter for a framework hydration-proof does not know.

```ts title="hydration-proof.config.ts"
import { existsSync } from "node:fs";
import { join } from "node:path";
import { defineAdapter, defineConfig } from "hydration-proof";

const waku = defineAdapter({
  name: "waku",
  detect: (rootDir) => existsSync(join(rootDir, "waku.config.ts")),
  commands: () => ({
    build: "waku build",
    start: "waku start --port {port}",
    dev: "waku dev --port {port}",
    buildOutput: "dist/index.js",
  }),
  discoverRoutes: () => [
    {
      pattern: "/",
      dynamic: false,
      router: "app",
      file: "src/pages/index.tsx",
    },
  ],
  normalizers: [
    {
      name: "waku-data",
      match: (node) =>
        node.k === 1 &&
        node.tag === "script" &&
        node.attrs.some(([name]) => name === "data-waku")
          ? "drop"
          : undefined,
    },
  ],
  navigation: {
    navigate: `(url) => { window.__WAKU_ROUTER__?.push(url); return Boolean(window.__WAKU_ROUTER__); }`,
  },
  notFound: true,
});

export default defineConfig({ adapter: waku });
```

| Field                                         | Description                                                                                                                                |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                                        | Shown in reports. `adapter: "<name>"` selects an adapter a plugin provides                                                                 |
| `detect(rootDir)`                             | Used by `adapter: "auto"`; plugin adapters are tried before the built-in ones. Without it, the adapter is never detected                   |
| `commands({ rootDir, packageManager })`       | `build`, `start`, `dev`, `buildOutput` (a file that exists after a build) and `env`. `{port}` is replaced, and `PORT` is set               |
| `discoverRoutes({ rootDir, packageManager })` | Routes with `pattern`, `dynamic`, `router`, `file` (relative to the project) and optionally `wrappers` (layout files, used by `--changed`) |
| `normalizers`                                 | Markup to ignore: return `"drop"` to remove a node, `"opaque"` to keep an element but not compare its content                              |
| `ignoreAttributes`, `elementAttributes`       | Attributes never compared, everywhere or only on some elements (`{ "astro-island": ["ssr"] }`)                                             |
| `devHost`                                     | Host for the development server (Next.js needs `localhost`)                                                                                |
| `navigation`                                  | Page function sources that start a client navigation (`navigate`) and a prefetch (`prefetch`). Return `false` when the router is missing   |
| `notFound`                                    | Also load a URL that does not exist and check the not-found page                                                                           |
| `pagesWithoutReact`                           | Pages without React are normal (islands architectures) and are not reported                                                                |

The options that are not functions, with their types:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` | — | Adapter name, used by `adapter: '<name>'` and shown in reports. |
| `normalizers` | `NormalizerRule[]` | — | Rules that drop or blank framework markup before DOM stages are compared. |
| `ignoreAttributes` | `(string \| RegExp)[]` | — | Attributes the framework adds or changes on its own; never compared. |
| `elementAttributes` | `Record<string, (string \| RegExp)[]>` | — | Attributes the framework changes on its wrapper elements, by tag name. |
| `devHost` | `string` | — | Host to use for the dev server, for frameworks that block other origins (Next.js uses `localhost`). |
| `navigation` | `AdapterNavigation` | — | Page-function sources that start (`navigate`) and prefetch (`prefetch`) a client-side navigation, for navigation checks. |
| `notFound` | `boolean` | — | Also test a URL that does not exist. |
| `pagesWithoutReact` | `boolean` | — | Pages without React are normal (islands architectures). |

The adapter API is part of the stable public API: see
[compatibility](https://hydration.jscrate.dev/docs/compatibility). To share an adapter between apps, put it
in a [plugin's](https://hydration.jscrate.dev/docs/plugins) `adapters` list.

## Related

- [Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs) and the `next` adapter
- [React Router](https://hydration.jscrate.dev/docs/frameworks/react-router) and
  [Remix](https://hydration.jscrate.dev/docs/frameworks/remix) apps
- [Vite SSR apps](https://hydration.jscrate.dev/docs/frameworks/vite-ssr)
- [Routes](https://hydration.jscrate.dev/docs/routes): discovery, dynamic values, sitemaps and crawling
- [Plugins](https://hydration.jscrate.dev/docs/plugins): normalizers, detectors, routes and reporters

---

# Plugins

> hydration-proof plugins teach the tool about your app: markup to ignore, causes it cannot guess, routes from a CMS, custom reporters and adapters.

Source: https://hydration.jscrate.dev/docs/plugins
Last updated: 2026-09-18

hydration-proof plugins add knowledge the tool cannot have on its own: markup
that is meant to differ, the reason a finding happened, routes only a running
system knows, and where results should go. A plugin is a plain object made with
`definePlugin`, so it can live next to your config or be published as a package
your apps share.

## What can hydration-proof plugins do?

Two kinds of knowledge are out of the tool's reach:

1. **Markup that is meant to differ.** A support-chat widget, an analytics
   attribute, a CDN that rewrites HTML. Left alone, these are reported on every
   page, which trains people to ignore the report.
2. **Why a finding happened.** [Probes](https://hydration.jscrate.dev/docs/probes) can prove time and random
   values, but the tool cannot know that `data-region` comes from a geo header
   on your server.

A plugin supplies both, plus route providers, reporters and
[adapters](https://hydration.jscrate.dev/docs/adapters):

```ts
function definePlugin(plugin: HydrationProofPlugin): HydrationProofPlugin
```

Identity helper with type checking for plugins.

| Field                 | Called with                                                                                                          | Returns                                                               |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `normalizers[].match` | a serialized DOM node (`k` 1 element, 3 text, 8 comment; elements have `tag`, `attrs` and `children`) and its parent | `"drop"`, `"opaque"` or `undefined`                                   |
| `ignoreAttributes`    | (a list, not a function)                                                                                             | Attribute names or patterns that are never compared                   |
| `detectors[].detect`  | the finding (read only) and `{ source, scenario }`                                                                   | `{ id, title, confidence, reason?, fixes?, docsUrl? }` or `undefined` |
| `routes[].routes`     | `{ rootDir, baseUrl }` (the app is running)                                                                          | paths or route objects                                                |
| `reporters[]`         | `onBegin(context)`, `onPage(page, issues, context)`, `onEnd(report, context)`                                        | `onEnd` may return the files it wrote                                 |
| `adapters[]`          | see [adapters](https://hydration.jscrate.dev/docs/adapters#write-an-adapter-with-defineadapter)                                                   |                                                                       |

Plugins run in the order they are listed, and plugin names must be unique.

## A complete plugin

This plugin, for a made-up company called Acme, uses every kind of extension:

```ts title="hydration-proof.config.ts"
import { defineConfig, definePlugin } from "hydration-proof";

const acme = definePlugin({
  name: "acme",

  normalizers: [
    // The support widget injects itself after load: never compare it.
    {
      name: "support-chat",
      match: (node) =>
        node.k === 1 && node.tag === "acme-chat" ? "drop" : undefined,
    },
    // The experiment script's body changes per request, but the tag has to be
    // in the right place, so keep the element and ignore its contents.
    {
      name: "experiment-script",
      match: (node) =>
        node.k === 1 &&
        node.tag === "script" &&
        node.attrs.some(
          ([name, value]) => name === "data-acme" && value === "experiments"
        )
          ? "opaque"
          : undefined,
    },
  ],
  // Analytics writes these in an effect; they are never a mismatch.
  ignoreAttributes: [/^data-track-/],

  detectors: [
    {
      name: "geo-header",
      detect: (issue) =>
        issue.selector?.includes("[data-region]") &&
        issue.server !== issue.client
          ? {
              id: "geo-header",
              title: "Region resolved from a header on the server",
              confidence: 0.9,
              reason:
                "The server reads x-acme-region; the browser falls back to the default region.",
              fixes: [
                "Pass the region from the server as a prop instead of resolving it again on the client.",
              ],
              docsUrl: "https://wiki.acme.test/geo",
            }
          : undefined,
    },
  ],

  routes: [
    {
      name: "cms",
      // The app is already running, so ask it which pages exist.
      routes: async ({ baseUrl }) => {
        const response = await fetch(`${baseUrl}/api/pages`);
        if (!response.ok) {
          throw new Error(`The CMS route list failed: ${response.status}`);
        }
        const pages = (await response.json()) as { path: string }[];
        return pages.map((page) => page.path);
      },
    },
  ],

  reporters: [
    {
      name: "slack",
      onEnd: async (report) => {
        if (report.summary.failed === 0 || !process.env.SLACK_WEBHOOK) return;
        await fetch(process.env.SLACK_WEBHOOK, {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({
            text: `${report.summary.failed} pages have hydration problems on ${report.run.branch ?? "unknown"}`,
          }),
        });
      },
    },
  ],
});

export default defineConfig({ plugins: [acme] });
```

## Normalizers: drop or opaque

A normalizer decides, node by node, what is left out of the comparison between
the server HTML and the hydrated DOM. It receives a serialized node: `k` is `1`
for an element, `3` for text and `8` for a comment, and elements have `tag`,
`attrs` (a list of `[name, value]` pairs) and `children`.

| Return      | Effect                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `"drop"`    | Removes the node, as if it were not there                                                        |
| `"opaque"`  | Keeps the element in the tree, so its position is still compared, but never compares its content |
| `undefined` | Leaves the node alone                                                                            |

`"opaque"` is the right answer for framework script tags and anything whose
presence matters but whose body does not.

A normalizer is finer than `ignore.selectors`, which drops a whole subtree.
For one-off exceptions, [ignoring findings](https://hydration.jscrate.dev/docs/ignoring) with a selector or
an ignore rule is simpler; reach for a normalizer when the same markup shows up
across apps.

## Detectors: explain a finding

A detector runs on each finding and may return a cause. The cause with the
highest confidence wins, with one exception: a cause **proven** by a
differential probe is always kept. A plugin cannot overrule evidence.

Keep `confidence` honest, on a scale from 0 to 1:

- below about 0.5 for a guess,
- 0.8 or more only when the evidence is specific.

The number decides which explanation the reader sees first. `reason` is shown
as evidence, and `fixes` are shown before the generic suggestions.

The second argument has the `source` around the element (`file`, `line`,
`content`) when it was found, and the `scenario`'s `locale`, `timezoneId` and
`colorScheme`.

A detector that throws is recorded as evidence on the finding, not as a
failure of the run. A broken plugin degrades the report instead of breaking
the pipeline.

## Route providers: routes from anywhere

Some routes are only known to a running system: pages from a CMS, tenants from
a database, a list behind an internal endpoint. A route provider runs with the
app already started, so it can ask the app.

It returns paths (`"/pricing"`) or route objects, the same shapes as
`routes.paths` in the [configuration](https://hydration.jscrate.dev/docs/configuration). Routes it adds have
`source: "plugin"` in the report. A provider that fails adds a note, and the run
continues with the routes it does have.

## Reporters: send results somewhere

A reporter has up to three hooks:

| Hook                            | Runs                                                           |
| ------------------------------- | -------------------------------------------------------------- |
| `onBegin(context)`              | Before the first page                                          |
| `onPage(page, issues, context)` | After each page, with its findings                             |
| `onEnd(report, context)`        | Once, with the finished report, the exit code and the failures |

Post to Slack, write a custom format, push a metric. When `onEnd` returns the
files it wrote, they are listed with the built-in [reports](https://hydration.jscrate.dev/docs/reports).

## Related

- [Adapters](https://hydration.jscrate.dev/docs/adapters) for frameworks hydration-proof does not know
- [Ignore known hydration mismatches](https://hydration.jscrate.dev/docs/ignoring) without a plugin
- [How hydration-proof detects mismatches](https://hydration.jscrate.dev/docs/how-it-works)
- [Probes](https://hydration.jscrate.dev/docs/probes): the causes a plugin cannot overrule
- [Node API](https://hydration.jscrate.dev/docs/node-api): `run()` with extra reporters

---

# Security

> hydration-proof security: no telemetry, requests only to the app under test, redacted reports, a locked-down local dashboard and one runtime dependency.

Source: https://hydration.jscrate.dev/docs/security
Last updated: 2026-09-18

hydration-proof security starts from one fact: the tool runs your app in a
browser and reads everything it renders, including pages behind a login. It
uploads none of it. There is no telemetry, every request goes to the app you
are testing, and reports are redacted before they are written.

## Report a hydration-proof security issue

Report vulnerabilities privately through
[GitHub security advisories](https://github.com/re-sohail/hydration-proof/security/advisories/new),
not in public issues. Include the version, the command you ran and, if you can,
a fixture or app that shows the problem. You get a first reply within a week.
Security fixes are released for the latest minor version.

## No telemetry

Nothing about your app, your run or your machine is uploaded. There is no
analytics, no crash reporting, no version check and no "anonymous usage data",
neither on install nor at run time. The package has no `postinstall` or other
lifecycle script, so nothing runs until you run a command yourself.

## What the network sees

Every request comes from a command you started, and all of them go to the app
you are testing:

| What                                                            | Where it goes                                                                                             |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| The pages under test, and everything they load                  | The URL from `server.url` or `--url`, or the app hydration-proof started                                  |
| Readiness checks while the server starts                        | The same URL                                                                                              |
| Sitemap and crawl requests                                      | The same origin. Crawling never leaves it; a `routes.sitemap` URL you configure yourself is used as given |
| Scripts and source maps, to turn a stack frame into `file:line` | The app's origin, plus any origin in `sourceOrigins`                                                      |

Two commands reach further, and only when you run them:

- `hydration-proof install` downloads browsers through Playwright's own
  installer and its hosts. `PLAYWRIGHT_DOWNLOAD_HOST` and the other Playwright
  environment variables work as usual, so you can use an internal mirror.
- The build and server commands from your config run as you wrote them, with
  your environment. They can do anything.

### Why source maps are origin-restricted

To name the file and line a finding comes from, hydration-proof downloads the
page's scripts and their source maps. Those requests go only to the app's own
origin. A script or `sourceMappingURL` that points anywhere else is skipped,
and the run ends with a note that lists the origins it refused:

```text
Source maps were not fetched from https://cdn.example.com (only the app's own
origin is used). Add sourceOrigins to the config to allow them.
```

This matters because a page can name any URL in a `sourceMappingURL` comment.
Without the restriction, testing a page you do not control could make your CI
runner fetch from a host of that page's choosing, from inside your network. If
your app serves its bundles from a CDN, allow that one origin:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  sourceOrigins: ["https://cdn.example.com"],
});
```

Findings are still reported when a map is skipped, only without a source
location. The restriction costs you file names, never detection.

## What ends up in a report

A report is built from the app's own output, so it can contain page text,
attribute values, URLs with their query strings, server log lines and
screenshots. Treat a report like any other test artifact of the app it came
from, and think before you attach one to a public pull request.

### Redaction is on by default

Before anything is written or printed, known secrets and personal data are
replaced. The built-in rules cover:

- email addresses
- JWTs and `Bearer` tokens
- API keys: `sk_`, `pk_` and `rk_` keys, GitHub (`ghp_`, `github_pat_`), GitLab
  (`glpat-`), Slack (`xox…`), AWS (`AKIA…`) and Google (`AIza…`)
- PEM private key blocks
- secret URL parameters (`token`, `api_key`, `password`, `session`, `code`,
  `signature` and others), whose values become `[redacted]`
- payment card numbers. A match must pass the Luhn checksum **and** have a
  prefix and length a card network issues, so order ids and millisecond
  timestamps are left alone.

Fingerprints are computed first, so redaction never changes which findings are
grouped together or matched against a [baseline](https://hydration.jscrate.dev/docs/baselines). The summary
of a run says how many values were replaced and under which label, so you can
see the rules firing.

Add your own patterns, and black out elements in screenshots:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  redact: {
    patterns: [/CUST-\d{6}/],
    selectors: [".account-number", "[data-private]"],
  },
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `builtIn` | `boolean` | true | Remove emails, tokens, card numbers and secret URL parameters. |
| `patterns` | `RegExp[]` | — | More text to remove from reports. |
| `selectors` | `string[]` | — | Elements to black out in screenshots. |

`selectors` only masks screenshots; it does not change report text.
`redact: false` turns redaction off entirely, for example for local runs.
`screenshots: "off"` is the blunt instrument for pages whose pictures should
not exist at all.

### Keep credentials out of the config

Never write credentials into `hydration-proof.config.ts`. Sign in with a
scenario's `login`, reading the credentials from `process.env`, or with a
Playwright `storageState` file. A token can go in a header:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  scenarios: [
    {
      name: "admin",
      headers: { authorization: `Bearer ${process.env.TEST_TOKEN}` },
    },
  ],
});
```

Seed test data in `hooks.setup`, which runs after the app is up and before any
page is tested, and read its secrets from the environment as well.
`hydration-proof init` adds the report folder to `.gitignore`; add your
`storageState` file too. [Signed-in pages](https://hydration.jscrate.dev/docs/scenarios) covers each way to
sign in.

## Is the HTML report safe to open?

`report.html` is a single file you open from disk. The report data sits in a
`<script type="application/json">` element with `<`, `>`, `&` and the line
separators escaped, and the viewer only writes it into the page with
`textContent`. Page content from the app under test cannot become markup or
script in the report.

The document also carries a `Content-Security-Policy` meta tag with
`default-src 'none'`, which stops the report from loading or sending anything
at all.

## The dashboard and the dev overlay

`hydration-proof ui` starts a small local server, meant for your own machine.
It is built so that a web page you happen to have open cannot drive it:

- it listens on `127.0.0.1` only, never on `0.0.0.0`
- every request needs a random 144-bit token, generated per run and printed as
  part of the URL; it is compared with `timingSafeEqual`
- requests whose `Host` is not `127.0.0.1:<port>` or `localhost:<port>` are
  refused, so a DNS name that resolves to your loopback address cannot reach it
- `POST /api/*` needs the token in an `x-hydration-proof-token` header, which a
  cross-site form cannot set, and a request with an `Origin` header from
  anywhere else is refused
- report files are served from one token-prefixed path, from inside the output
  folder only, and only with known media types
- bodies are capped, and responses carry `no-store` and `nosniff`

Do not forward the port or share the URL. The token in it is the only thing
protecting the dashboard, and running tests from it means running your
configured build and server commands.

`hydration-proof dev` opens a normal browser window with the
[overlay](https://hydration.jscrate.dev/docs/dev-overlay) injected by an init script. The overlay lives in
its own shadow root, so the app's CSS cannot reach it and its CSS cannot reach
the app. Every node it adds carries `data-hydration-proof-internal`, so the
tool's own markup is never compared as if it were the app's. Nothing is written
into your source tree, and nothing ships in your production bundle.

## Supply chain

- **One runtime dependency:** `playwright-core`, which itself has none.
  Everything else is Node.js built-ins or code in the repository.
- **No lifecycle scripts:** the package is published as ESM without install
  scripts, so installing it cannot execute anything.
- **Nothing loaded at run time:** the browser runtime is inlined into `dist` at
  build time, so nothing is read from disk or the network to inject it. This is
  also what makes Yarn Plug'n'Play work.
- **Provenance:** releases are published from CI with npm trusted publishing
  (OIDC), so no long-lived npm token exists to leak. Every published version
  has a provenance attestation you can check with `npm audit signatures`.

## Running it against untrusted pages

Testing a URL you do not control means loading that page in a browser on your
machine or runner. The browser is Playwright's, sandboxed as usual. Each run
gets a fresh context, and the source-map restriction keeps a hostile page from
steering requests.

It is still worth running it in a container with no access to your internal
network, the way you would treat any other untrusted URL.

## Related

- [Scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios): test signed-in pages without
  committing credentials
- [Reports](https://hydration.jscrate.dev/docs/reports): what each output format contains
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)
- [Configuration reference](https://hydration.jscrate.dev/docs/configuration)
- [Troubleshooting](https://hydration.jscrate.dev/docs/troubleshooting)

---

# Troubleshooting

> hydration-proof troubleshooting: fix a missing browser, an app that won't start, skipped routes, failed logins, pages that never settle, missing source lines.

Source: https://hydration.jscrate.dev/docs/troubleshooting
Last updated: 2026-09-18

hydration-proof troubleshooting starts with `npx hydration-proof doctor`, which
checks Node.js, Playwright, the browsers, the config file and framework
detection in one go. The answers below cover the problems people hit most,
grouped by where they show up: installing and starting, signing in, routes,
findings, source locations and speed.

## Start hydration-proof troubleshooting with doctor

```bash
npx hydration-proof doctor
```

It prints one line per check, marked as passed, a warning or a failure:

| Check                     | What it tells you                                                                       |
| ------------------------- | --------------------------------------------------------------------------------------- |
| Node.js                   | The running version; 22.18 or newer is required                                         |
| Package manager, CI       | What was detected; CI changes defaults such as retries                                  |
| Playwright                | The `playwright-core` version in use and where it came from                             |
| chromium, firefox, webkit | Whether each browser is installed, with the command that installs it                    |
| Config                    | The config file it found, or the command that creates one                               |
| Framework                 | The [adapter](https://hydration.jscrate.dev/docs/adapters) that was detected, or "not detected (set server.command)" |
| Routes                    | How many static and dynamic routes the adapter discovered                               |

`doctor` exits with `0` when nothing failed and `2` when something did. A
missing Firefox or WebKit is only a warning; a missing Chromium is a failure.

## Installing and starting the app

### Why does it say "chromium is not installed"?

The browser for the Playwright version hydration-proof uses has not been
downloaded yet, and the run stops with exit code `4`. Install it:

```bash
npx hydration-proof install
npx hydration-proof install --with-deps   # on Linux CI, with system libraries
npx hydration-proof install firefox webkit
```

### Why does it say "Nothing answers at …"?

The app could not be built, started or reached, and the run exits with code
`3`. Check these in order:

1. **Run `server.command` on its own.** `{port}` in the command is replaced
   with the port hydration-proof chose, and the same port is in the `PORT`
   environment variable. A server that ignores both listens somewhere else.
2. **Give slow builds more time.** `server.timeout` is how long to wait for the
   app to answer, 120000 ms by default.
3. **With `--url`, start the app first.** Nothing is built or started when you
   pass a URL.

When a build or start command fails, the run prints the command and the end of
its output.

### What if hydration-proof does not know how to start the app?

No adapter matched, so there is no start command. Set `server.command` (and
`server.build`) in `hydration-proof.config.ts`, or pass `--url` to test an app
you started yourself. [Adapters](https://hydration.jscrate.dev/docs/adapters#custom-react-servers) shows a
config for a custom server.

### Why does Next.js development mode not load?

hydration-proof opens the development server on `localhost`, because Next.js
blocks development resources for other hosts. If you test a development server
through another host name, add that host to `allowedDevOrigins` in
`next.config`.

### Why does my TypeScript config fail to load?

Node.js loads `hydration-proof.config.ts` directly, without a compiler. Use
plain types (no `enum` or `namespace`), include the file extension in relative
imports (`./routes.ts`), or rename the file to `.mjs`.

## Signing in

### Why do signed-in pages end on the login page (HP9010)?

The scenario's `login` did not leave a working session, so the page redirected
and got an [HP9010](https://hydration.jscrate.dev/docs/issues/hp9010) warning.

1. Run with `--headed --workers 1` to watch the login.
2. Check that `login` waits for the page after signing in, for example with
   `page.waitForURL`.
3. Check that the session cookie is not limited to another domain.

If the route is supposed to redirect, set `expectRedirect` on it. See
[scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios).

### What does "The login of scenario … failed" or "The setup hook failed" mean?

The scenario's `login` function, or the `hooks.setup` function, threw an
error; its message follows. Both run after the app is up, with the same
`baseUrl` the pages use. Either failure stops the run with exit code `2`.

## Routes

### Why are some dynamic routes skipped?

A dynamic route is only tested with example values: from `routes.dynamic`, or
from pages the build pre-rendered. A route without values is skipped, with a
note that lists it. Add values, or list the URLs in a sitemap and turn on
`routes.sitemap`:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: { dynamic: { "/products/[id]": ["1", "42"] } },
});
```

### Why is a new page missing from the run?

Discovered routes are cached until the build or a route folder changes. Run
with `--no-cache` if a change was missed:

```bash
npx hydration-proof test --no-cache
```

## Findings

### How do I keep a difference that is intentional?

Mark the element with `data-hydration-proof-ignore`, add a selector to
`ignore.selectors`, or add an `ignore.issues` rule with a reason. For values
that differ on purpose, such as a live clock, render them after mount or put
`suppressHydrationWarning` on that element; hydration-proof then lists them as
info. [Ignoring findings](https://hydration.jscrate.dev/docs/ignoring) covers each option.

### What if a page keeps changing and never settles (HP9009)?

Pages with animations, polling or live data may never be quiet for the 400 ms
hydration-proof waits by default, and get an [HP9009](https://hydration.jscrate.dev/docs/issues/hp9009)
warning. Tell it what "ready" means for the page instead:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ready: {
    selector: "#app-ready", // an element that exists once the page is ready
    quietMs: 200, // or wait less time without changes
  },
});
```

`ready.function` takes a page function (as a string) that must return a truthy
value. A route object can have its own `ready` options.

### Why is a cause "not proven"?

[Probes](https://hydration.jscrate.dev/docs/probes) prove a cause when a finding changes with exactly one
factor. When the page renders differently on identical reloads, the value comes
from the server or an API, for example a counter or the current time on the
server, which the browser cannot control. Send the data the server rendered
with to the client.

### Why do navigation checks report differences?

Client navigation keeps state that a direct load does not have: module
variables, context in layouts, parallel route slots. If the difference is
intended (a modal from an intercepting route, a slot that keeps its page), add
an ignore rule for the route with `code: "HP5004"`. To start from another page,
set `checks.navigation.from`, or `navigateFrom` on the route.

### What is a lost click?

A server-rendered button is visible before React can handle its clicks, and a
click in that window does nothing ([HP5001](https://hydration.jscrate.dev/docs/issues/hp5001)). Show the
control as disabled or loading until the page is interactive, or make it work
without JavaScript. If that is acceptable for your app, ignore HP5001.

## Source locations

### Why is there no source location in production?

The issue's `sourceUnavailableReason` says why. Enable browser source maps
(`productionBrowserSourceMaps: true` in Next.js) to get the component, or run
with `--mode development` for the exact line. Elements rendered by Server
Components have no client code to point at.

### Why are source maps from my CDN not used?

Scripts and source maps are only fetched from the app's own origin, and the run
ends with a note that names the origin it refused. Add the CDN to
`sourceOrigins`. [Security](https://hydration.jscrate.dev/docs/security) explains why the restriction
exists.

### Why are component names single letters?

Production builds minify component names. Run with `--mode development` to see
the real names:

```bash
npx hydration-proof test --mode development
```

## Speed

### How do I make the matrix faster?

Every environment loads every route. Keep the default `strategy: "pairwise"`,
lower `matrix.max`, limit the matrix to some scenarios with
`matrix.scenarios`, or run quick local checks with `--no-matrix`. In CI, split
the pages across jobs with `--shard`. See the
[environment matrix](https://hydration.jscrate.dev/docs/environment-matrix).

### Why is network throttling different in Firefox and WebKit?

Only Chromium can throttle the network. In Firefox and WebKit, every request
except the page itself is delayed by the latency instead, which turns the HTTP
cache off. CPU slowdown is Chromium only.

## Related

- [CLI commands, flags and exit codes](https://hydration.jscrate.dev/docs/cli)
- [Configuration reference](https://hydration.jscrate.dev/docs/configuration)
- [Compatibility](https://hydration.jscrate.dev/docs/compatibility): supported Node.js, React and framework
  versions
- [Scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios)
- [Ignore known hydration mismatches](https://hydration.jscrate.dev/docs/ignoring)

---

# Compatibility and stability

> hydration-proof compatibility: supported Node.js, React, Next.js, framework, browser and package manager versions, what is stable, and how deprecation works.

Source: https://hydration.jscrate.dev/docs/compatibility
Last updated: 2026-09-18

hydration-proof compatibility covers two things: the versions of Node.js,
React, frameworks, browsers and package managers it is tested with, and the
parts of the tool you can build on. Everything listed as stable follows
[semver](https://semver.org/): it changes only in a major release, with a
migration path.

## The hydration-proof compatibility table

|                      | Supported                                                                                                                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Node.js**          | 22.18 and later, the first version that imports `.ts` directly. Tested on 22.18, 24 and 26, on Linux, macOS and Windows                                                                     |
| **React**            | 18.3 and 19.x, in development **and** production builds. React 18.0–18.2 are not tested; they hydrate differently enough that findings may be less precise                                  |
| **Next.js**          | 15.5 and 16.x, App Router and Pages Router, webpack and Turbopack. The App Router always uses Next.js's own bundled React, so the installed React version only matters for the Pages Router |
| **React Router**     | Framework mode (`@react-router/dev`); the fixtures run version 8.4                                                                                                                          |
| **Other frameworks** | Remix v2, Astro with React islands, Vite SSR, and custom Node.js servers                                                                                                                    |
| **Browsers**         | Chromium, Firefox and WebKit through Playwright. CPU slowdown and native network throttling are Chromium only                                                                               |
| **Playwright**       | `playwright-core` 1.63 and later. Your own copy is used when it is new enough, so browsers are never downloaded twice                                                                       |
| **Package managers** | npm, pnpm, Yarn Classic, Yarn Berry (including Plug'n'Play) and Bun                                                                                                                         |
| **ESLint plugin**    | ESLint 9 and 10, flat config only                                                                                                                                                           |

Each package manager is tested by installing the packed tarball into a fresh
app and running the CLI against it. A version leaving this table is a major
release; adding one is not.

[Adapters](https://hydration.jscrate.dev/docs/adapters) explains how each framework is built, started and
read.

## How the table is checked

Two workflows in the repository back the table with evidence:

- **`compat.yml`** runs the whole fixture suite again against other Next.js
  versions (16.3, 16.2 and 15.5), and against React 18.3 and 19.0 to 19.3 for
  the Pages Router and custom SSR.
- **`real-world.yml`** runs the packed CLI against pinned open-source Next.js
  apps that nobody on the project wrote: Next.js's own `blog-starter`,
  `with-styled-components` and `app-dir-i18n-routing` examples, pinned to a
  release tag. It runs without a config file, the way a first run on a real app
  does, and with `--fail-on warning`: the apps are expected to be clean, so any
  finding above info is a false positive to investigate.

A tool that only works on its own fixtures is not a tool, which is why the
second workflow matters most.

## What is stable

| Surface                    | Stable part                                                                                                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CLI**                    | The commands, their flags and the exit codes. New flags are added; existing ones keep their meaning                                                                        |
| **Config**                 | Every documented option and `configVersion: 1`. Removing or renaming one needs a major release, and `hydration-proof migrate` keeps working for at least one major version |
| **Report**                 | `report.json` with `schemaVersion: 1`, described by `schema/report.json`. Fields are added, never removed or repurposed                                                    |
| **Issue codes**            | An `HPxxxx` code keeps its meaning forever and is never reused for something else                                                                                          |
| **Fingerprints**           | Stable for a given `fingerprintVersion`, so baselines and ignore rules keep matching                                                                                       |
| **Node API**               | `run()`, `defineConfig`, `definePlugin`, `defineAdapter`, `mergeReports`, `ISSUES` and the types they use                                                                  |
| **Plugin and adapter API** | The fields documented for [plugins](https://hydration.jscrate.dev/docs/plugins) and [adapters](https://hydration.jscrate.dev/docs/adapters)                                                                                          |
| **Reporter output**        | The JUnit, SARIF and GitLab shapes, as their own schemas define them                                                                                                       |

The [issue codes](https://hydration.jscrate.dev/docs/issues) and [CLI](https://hydration.jscrate.dev/docs/cli) pages list the stable
values.

## What is not stable

These are internals. They change in minor releases, and nothing outside the
package should depend on them:

- everything the public exports do not re-export, including the capture
  stages, the mutation log, the rewind and the diff
- the browser runtime and its protocol, which is rebuilt and inlined on every
  release (both sides always ship together)
- the HTML report's markup and its embedded data
- the exact wording of messages, the set of `evidence` entries, and confidence
  scores
- **which** cause a finding is given, and whether it has a cause at all.
  Diagnosis improves over releases, so treat a cause as an explanation for a
  human, not as something to assert on

`severity` is in between: a code's severity can be lowered or raised in a
minor release when experience shows it was wrong. Pin the behavior you care
about with `ci.failOn` and `ci.budget` rather than relying on the defaults.
[Baselines and budgets](https://hydration.jscrate.dev/docs/baselines) shows how.

## Fingerprints and baselines

A fingerprint identifies a finding across runs, so a baseline recorded today
still matches tomorrow. It is built from the issue code, the route pattern, the
scenario and the element's position. It never uses values that change per
request, or anything redaction rewrites: fingerprints are computed first.

If a fix has to change how fingerprints are computed, `fingerprintVersion` in
the report is raised, the release notes say so, and `hydration-proof baseline`
rewrites your baseline. Old baselines keep working until you record them again:
entries with an older `fingerprintVersion` are matched by code, route and
selector instead.

## How deprecation works

When something stable has to go:

1. It keeps working, and using it prints a note that names the replacement.
2. `hydration-proof migrate` rewrites it where a rewrite is possible.
3. It is removed in the next major release at the earliest.

Config options are the common case, and `migrate` covers them. Nothing is ever
removed in a patch release.

## Upgrading

List what the new version renamed or replaced, then apply the safe renames:

```bash
npx hydration-proof migrate
npx hydration-proof migrate --write
```

`--write` keeps the old file as `<file>.backup`. Changes that need a judgment
call are listed for you to make by hand.

Between minor versions, expect new findings: better detection is the point. If
a release reports something you have decided to live with,
[an ignore rule](https://hydration.jscrate.dev/docs/ignoring) with a reason and an expiry date is the honest
way to park it. `ci.newIssuesOnly` (`--new-only`) lets you adopt a release
without a red pipeline on day one.

## Related

- [Release notes](https://hydration.jscrate.dev/docs/releases)
- [Node API](https://hydration.jscrate.dev/docs/node-api): the stable programmatic surface
- [Reports](https://hydration.jscrate.dev/docs/reports): the `report.json` schema and other formats
- [Troubleshooting](https://hydration.jscrate.dev/docs/troubleshooting)
- [Quick start](https://hydration.jscrate.dev/docs/quick-start)

---

# ESLint plugin

> eslint-plugin-hydration-proof adds an ESLint rule for hydration mismatch causes of each kind to React and Next.js: 15 flat-config rules, three presets.

Source: https://hydration.jscrate.dev/docs/eslint
Last updated: 2026-09-18

`eslint-plugin-hydration-proof` gives you an ESLint rule for hydration
mismatch causes of each kind, 15 in all: the clock, random values,
browser-only globals, storage, media queries, locale and time zone
formatting, unstable ids, environment branches, invalid HTML nesting and
misused `suppressHydrationWarning`. They report the code while you type,
before it reaches a browser.

Every report says why the code breaks hydration and what to do instead. Some
rules offer [suggestions](#every-eslint-rule-for-hydration-mismatch-patterns)
(an explicit locale, an explicit time zone, removing an unused attribute);
nothing is fixed automatically, because each fix changes what your app
renders.

## Install the ESLint plugin

```bash
npm install eslint-plugin-hydration-proof --save-dev
```

It requires ESLint 9 or 10 (flat config) and Node.js 22.18 or newer, works
with npm, pnpm, Yarn and Bun, and has no dependencies of its own.

The plugin does not parse TypeScript itself. For `.ts` and `.tsx` files,
install a TypeScript parser: `@typescript-eslint/parser`, or the
`typescript-eslint` package, which includes it:

```bash
npm install -D typescript-eslint
```

### ESLint 9 and 10, flat config only

The presets are flat config objects, and there is no legacy `.eslintrc`
version. A project that still uses `.eslintrc` needs to move to
`eslint.config.js` first; ESLint's
[migration guide](https://eslint.org/docs/latest/use/configure/migration-guide)
covers it.

## Set up a preset

Add one preset to `eslint.config.mjs` (or `eslint.config.js`).

### React apps: recommended

```js title="eslint.config.mjs"
import hydrationProof from "eslint-plugin-hydration-proof";

export default [
  // ...your other configs
  hydrationProof.configs.recommended,
];
```

### Next.js App Router: next

Next.js needs no separate ESLint plugin. Next.js hydration works as in any
React app, except that Server Components render once, on the server, and
never hydrate. The `next` preset skips them (see
[Server Components](#server-components)):

```js title="eslint.config.mjs"
import hydrationProof from "eslint-plugin-hydration-proof";

export default [
  // ...your other configs
  hydrationProof.configs.next,
];
```

### Every rule as an error: strict

`strict` turns every rule into an error and requires a reason for every
`suppressHydrationWarning`. It does not set `serverComponents`, so in a
Next.js App Router project add the setting yourself:

```js title="eslint.config.mjs"
import hydrationProof from "eslint-plugin-hydration-proof";

export default [
  hydrationProof.configs.strict,
  // Next.js App Router only: skip Server Components, as the next preset does.
  { settings: { "hydration-proof": { serverComponents: "next-app" } } },
];
```

### With typescript-eslint

`eslint.config.ts`, with typescript-eslint and the rules limited to component
files:

```ts title="eslint.config.ts"
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";
import hydrationProof from "eslint-plugin-hydration-proof";

export default defineConfig([
  tseslint.configs.recommended,
  {
    files: ["**/*.{jsx,tsx}"],
    extends: [hydrationProof.configs.next],
  },
]);
```

A config that already uses `tseslint.config(...)` takes the same `extends`
entry.

The presets apply to `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts` and
`.cts` files and enable JSX parsing
(`languageOptions.parserOptions.ecmaFeatures.jsx`). TypeScript files need a
TypeScript parser, for example from typescript-eslint. ESLint loads
`eslint.config.ts` with [`jiti`](https://www.npmjs.com/package/jiti), or
natively with `--flag unstable_native_nodejs_ts_config`.

### Pick rules yourself

Register the plugin and turn rules on by name:

```js title="eslint.config.mjs"
import hydrationProof from "eslint-plugin-hydration-proof";

export default [
  {
    plugins: { "hydration-proof": hydrationProof },
    rules: {
      "hydration-proof/no-date-in-render": "error",
      "hydration-proof/no-locale-without-explicit-locale": [
        "warn",
        { defaultLocale: "en-GB" },
      ],
    },
  },
];
```

Without a preset, nothing sets `files` or JSX parsing for you: ESLint then
lints only `.js`, `.mjs` and `.cjs` files. Add a `files` pattern for `.jsx`
and `.tsx`, and turn on `languageOptions.parserOptions.ecmaFeatures.jsx` (or
use the TypeScript parser).

## Presets

| Preset        | What it enables                                                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recommended` | Every rule. Definite mismatches are errors; likely ones (locale, time zone, initial state, list order) are warnings.                                                                              |
| `next`        | `recommended` plus `settings['hydration-proof'].serverComponents: 'next-app'`.                                                                                                                    |
| `strict`      | Every rule as an error, and [`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning) with `reportAll: true`, so every `suppressHydrationWarning` needs a justification. |

## Every ESLint rule for hydration mismatch patterns

| Rule | What it reports | recommended | strict |
| --- | --- | --- | --- |
| [no-date-in-render](https://hydration.jscrate.dev/docs/rules/no-date-in-render) | Disallow reading the current time while a component renders | Error | Error |
| [no-random-in-render](https://hydration.jscrate.dev/docs/rules/no-random-in-render) | Disallow random values while a component renders | Error | Error |
| [no-browser-global-in-render](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render) | Disallow reading browser-only globals such as window and document while a component renders | Error | Error |
| [no-storage-in-initial-render](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render) | Disallow reading localStorage or sessionStorage while a component renders, including state initializers | Error | Error |
| [no-match-media-in-render](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) | Disallow evaluating media queries with matchMedia while a component renders | Error | Error |
| [no-locale-without-explicit-locale](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale) | Require an explicit locale for locale-sensitive formatting during render | Warning | Error |
| [no-timezone-without-explicit-timezone](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone) | Require an explicit timeZone when dates are formatted or split into parts during render | Warning | Error |
| [no-unstable-id](https://hydration.jscrate.dev/docs/rules/no-unstable-id) | Disallow ids built from random values, the clock or module-level counters | Error | Error |
| [no-global-render-counter](https://hydration.jscrate.dev/docs/rules/no-global-render-counter) | Disallow changing module-level variables while a component renders | Error | Error |
| [no-window-render-branch](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) | Disallow rendering different output depending on whether the code runs on the server or in the browser | Error | Error |
| [no-invalid-interactive-nesting](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting) | Disallow HTML nesting that the browser repairs while parsing, such as <div> in <p> or <a> in <a> | Error | Error |
| [audit-suppress-hydration-warning](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning) | Report suppressHydrationWarning where it has no effect or hides more than intended | Error | Error |
| [no-client-only-initial-state](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state) | Disallow initial state and refs computed from browser-only values | Warning | Error |
| [require-stable-server-snapshot](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot) | Require useSyncExternalStore to have a getServerSnapshot that returns the same value on the server and during hydration | Error | Error |
| [require-deterministic-list-order](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order) | Require list ordering during render to be the same on the server and in the browser | Warning | Error |

Four rules offer suggestions:
[`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale),
[`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone),
[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
and
[`require-deterministic-list-order`](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order).
[All rules](https://hydration.jscrate.dev/docs/rules) groups them by what they catch.

## What counts as render

The rules look at code that runs while React renders a component, because
that code runs twice: once on the server and once in the browser during
hydration.

- **Components:** functions with a PascalCase name (`function Card()`,
  `const Card = () => ...`, `Card.Header = function ...`), functions wrapped
  in `memo()`/`forwardRef()` (also `React.memo`, `React.forwardRef`),
  default-exported functions that return JSX, and the `render()` method,
  constructor and instance fields of class components.
- **Hooks:** functions named `useSomething`.
- **Also render:** `useMemo` callbacks, lazy initializers of `useState` and
  `useReducer`, initial values of `useRef`, immediately invoked functions,
  and callbacks of array methods called during render (`map`, `flatMap`,
  `filter`, `reduce`, `forEach`, `some`, `every`, `find`, `findIndex`,
  `sort`, `toSorted`, ...).
- **Not render:** `useEffect`, `useLayoutEffect` and `useInsertionEffect`
  callbacks, `useCallback` bodies, event handlers, other nested functions
  (including render props), other class methods, and module-level code.

Globals are resolved with scope analysis: a parameter or local variable called
`window`, `document`, `Date` or `Math` is not the global.

## Server Components

Server Components render once, on the server. Their values are sent to the
browser as data and are not computed again, so the clock or `Math.random()` in
a Server Component cannot cause a mismatch.

Tell the plugin how to recognize them with a shared setting:

```js title="eslint.config.mjs"
export default [
  {
    settings: {
      "hydration-proof": {
        serverComponents: "next-app", // default: 'none'
      },
    },
  },
];
```

| Value                                   | Files treated as Server Components                                                                                     |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `'none'` (default)                      | none                                                                                                                   |
| `'next-app'` (set by the `next` preset) | files under an `app/` directory (any depth: `app/`, `src/app/`, `apps/web/app/`) that do not start with `'use client'` |

Files that start with `'use server'` are always skipped. `pages/` and every
other directory are always checked.

Two rules keep checking Server Components:
[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
and
[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning).
React still hydrates the HTML elements a Server Component renders, so invalid
nesting breaks hydration there too, and the root layout is where
`<html suppressHydrationWarning>` lives.

A file under `app/` without `'use client'` becomes a Client Component when a
client file imports it. The plugin cannot see the import graph; add
`'use client'` to shared client components, or lint them with
`serverComponents: 'none'` in a separate config block.

## Shared settings

Both settings live under `settings['hydration-proof']` and apply to every
rule:

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| `serverComponents` | `ServerComponentsMode` | — | How Server Components are recognised. - `'none'` (default): every file is a client file. - `'next-app'`: files under an `app/` directory without a `'use client'` directive are Server Components and are skipped. |
| `environmentFlags` | `string[]` | — | Extra identifiers treated as "running in the browser/server" flags by no-window-render-branch. |

`serverComponents` defaults to `'none'`. `environmentFlags` defaults to `[]`:
its names are added to the flags
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) already
knows (`isServer`, `isBrowser`, `isClient`, `canUseDOM`, `isSSR`,
`IS_BROWSER`, ...).

```js title="eslint.config.mjs"
import hydrationProof from "eslint-plugin-hydration-proof";

export default [
  hydrationProof.configs.recommended,
  {
    settings: {
      "hydration-proof": {
        serverComponents: "next-app",
        environmentFlags: ["__SERVER__", "isNode"],
      },
    },
  },
];
```

## One report per problem

The rules share one analysis, so a construct is reported by exactly one rule:

- A random value, a clock read or a counter that ends up in an id is reported
  by `no-unstable-id`, not by `no-random-in-render`, `no-date-in-render` or
  `no-global-render-counter`.
- A `typeof window` check is reported by `no-window-render-branch`; the
  browser reads it guards are not reported again by
  `no-browser-global-in-render`. When the check guards `localStorage` or
  `matchMedia`, only the storage or media query rule reports.
- In `useState`, `useReducer`, `useRef` and class state initializers, browser
  reads and environment checks belong to `no-client-only-initial-state`
  (storage and `matchMedia` still to their own rules).
- Random values and `localeCompare` inside `sort` comparators, and lodash's
  `shuffle`/`sampleSize`, belong to `require-deterministic-list-order`.
- Browser reads, the clock and random values inside `getServerSnapshot`
  belong to `require-stable-server-snapshot`.

Two combinations are reported by two rules on purpose, because they need two
fixes: `date.toLocaleDateString()` lacks both a locale
(`no-locale-without-explicit-locale`) and a time zone
(`no-timezone-without-explicit-timezone`), and `new Date().getHours()` reads
the clock (`no-date-in-render`) and the local time zone
(`no-timezone-without-explicit-timezone`). The reports are at different
positions.

## How it relates to hydration-proof test

ESLint hydration checks read your source code; `hydration-proof test` loads
the running app in real browsers. The plugin and the
[`hydration-proof` CLI](https://hydration.jscrate.dev/docs/cli) work together:

|          | ESLint plugin                               | `hydration-proof test`                                                                                                                                                       |
| -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runs     | in the editor and in CI, on source code     | in CI, against the running app in real browsers                                                                                                                              |
| Finds    | patterns that are known to cause mismatches | mismatches that actually happen, including ones no linter can see: data, CSS-in-JS, browser extensions, CDN rewrites, nesting across components, silent attribute mismatches |
| Explains | the pattern and the fix                     | the element, the server and client values, the component, the line, and the likely cause                                                                                     |

Use the plugin to stop common mistakes before they are committed, and
`hydration-proof test` to prove the pages hydrate; the
[quick start](https://hydration.jscrate.dev/docs/quick-start) sets it up in three commands. The likely
causes the CLI reports map directly to the rules:

| ESLint rule                                                                                                                                                                                                            | Hydration mismatch it prevents                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render)                                                                                                                                                                   | [Time-dependent value](https://hydration.jscrate.dev/docs/causes/time)                                      |
| [`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone)                                                                                                                           | [Timezone difference](https://hydration.jscrate.dev/docs/causes/timezone)                                   |
| [`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale)                                                                                                                                   | [Locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale)                             |
| [`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render)                                                                                                                                                               | [Random value](https://hydration.jscrate.dev/docs/causes/random)                                            |
| [`require-deterministic-list-order`](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order)                                                                                                                                     | [Random value](https://hydration.jscrate.dev/docs/causes/random) or [locale](https://hydration.jscrate.dev/docs/causes/locale) in a sort |
| [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render), [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch), [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state) | [Browser-only API used during render](https://hydration.jscrate.dev/docs/causes/browser-api)                |
| [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)                                                                                                                                             | [localStorage or sessionStorage read during render](https://hydration.jscrate.dev/docs/causes/storage)      |
| [`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render)                                                                                                                                                     | [Screen size or media query read during render](https://hydration.jscrate.dev/docs/causes/media-query)      |
| [`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)                                                                                                                                         | Browser values, storage or the clock in `getServerSnapshot`                    |
| [`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id), [`no-global-render-counter`](https://hydration.jscrate.dev/docs/rules/no-global-render-counter)                                                                                                     | [Generated id differs](https://hydration.jscrate.dev/docs/causes/unstable-id)                               |
| [`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)                                                                                                                                         | [Invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html)                              |
| [`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)                                                                                                                                     | [Intentional difference (suppressHydrationWarning)](https://hydration.jscrate.dev/docs/causes/suppressed)   |

[Different data on the server and the client](https://hydration.jscrate.dev/docs/causes/data), CSS-in-JS
class names, browser extensions, third-party scripts and CDN rewrites have no
rule: only `hydration-proof test` sees them.

## Overlap with eslint-plugin-react-hooks

The `purity` rule of eslint-plugin-react-hooks (part of the React Compiler
rules) flags known impure calls such as `Date.now()` and `Math.random()`
during render. It overlaps with
[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) and
[`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render); with both plugins
enabled you get two reports for those calls. Keep both, or turn one off.
[eslint-plugin-react-hooks compared](https://hydration.jscrate.dev/docs/compare/eslint-plugin-react-hooks)
goes through the differences.

## Limitations

- The plugin reads one file at a time. Values passed through props, context
  or other modules, and nesting across components, are not visible;
  `hydration-proof test` finds those.
- Only the listed hooks, methods and imports are recognized. A custom
  `useLocalStorage` hook is analyzed where it is defined (it is a hook), not
  where it is called.
- Render props and other callbacks passed to child components are not treated
  as render code.

## Related

- [All ESLint rules, grouped by what they catch](https://hydration.jscrate.dev/docs/rules)
- [Quick start with `hydration-proof test`](https://hydration.jscrate.dev/docs/quick-start)
- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes) and their fixes
- [Hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)

---

# ESLint rules

> All 15 ESLint rules for React hydration in eslint-plugin-hydration-proof, grouped by the mismatch they catch, with their severity in each preset.

Source: https://hydration.jscrate.dev/docs/rules
Last updated: 2026-09-18

These are the ESLint rules for React hydration in
`eslint-plugin-hydration-proof`: 15 rules, each for one way the server render
and the browser's first render can differ. Every rule is on in all three
presets; the presets change only the severity and whether Server Components
are checked. [Install the plugin](https://hydration.jscrate.dev/docs/eslint) to use them.

## All ESLint rules for React hydration

| Rule | What it reports | recommended | strict |
| --- | --- | --- | --- |
| [no-date-in-render](https://hydration.jscrate.dev/docs/rules/no-date-in-render) | Disallow reading the current time while a component renders | Error | Error |
| [no-random-in-render](https://hydration.jscrate.dev/docs/rules/no-random-in-render) | Disallow random values while a component renders | Error | Error |
| [no-browser-global-in-render](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render) | Disallow reading browser-only globals such as window and document while a component renders | Error | Error |
| [no-storage-in-initial-render](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render) | Disallow reading localStorage or sessionStorage while a component renders, including state initializers | Error | Error |
| [no-match-media-in-render](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) | Disallow evaluating media queries with matchMedia while a component renders | Error | Error |
| [no-locale-without-explicit-locale](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale) | Require an explicit locale for locale-sensitive formatting during render | Warning | Error |
| [no-timezone-without-explicit-timezone](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone) | Require an explicit timeZone when dates are formatted or split into parts during render | Warning | Error |
| [no-unstable-id](https://hydration.jscrate.dev/docs/rules/no-unstable-id) | Disallow ids built from random values, the clock or module-level counters | Error | Error |
| [no-global-render-counter](https://hydration.jscrate.dev/docs/rules/no-global-render-counter) | Disallow changing module-level variables while a component renders | Error | Error |
| [no-window-render-branch](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) | Disallow rendering different output depending on whether the code runs on the server or in the browser | Error | Error |
| [no-invalid-interactive-nesting](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting) | Disallow HTML nesting that the browser repairs while parsing, such as <div> in <p> or <a> in <a> | Error | Error |
| [audit-suppress-hydration-warning](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning) | Report suppressHydrationWarning where it has no effect or hides more than intended | Error | Error |
| [no-client-only-initial-state](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state) | Disallow initial state and refs computed from browser-only values | Warning | Error |
| [require-stable-server-snapshot](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot) | Require useSyncExternalStore to have a getServerSnapshot that returns the same value on the server and during hydration | Error | Error |
| [require-deterministic-list-order](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order) | Require list ordering during render to be the same on the server and in the browser | Warning | Error |

Each rule page shows what it reports, why it breaks hydration, code the rule
reports and code it accepts, its options and its exact messages.

## What each group of rules catches

### Time and random values

[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) reports `Date.now()`,
`new Date()`, `performance.now()` and `Temporal.Now` in render code.
[`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render) reports
`Math.random()`, `crypto.randomUUID()`, uuid, nanoid and lodash's random
helpers. Both values change between the server render and hydration; see
[time](https://hydration.jscrate.dev/docs/causes/time) and [random values](https://hydration.jscrate.dev/docs/causes/random).

### Browser-only values

The server has no `window`, storage or screen, so anything read from them
renders differently on each side:

- [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render):
  `window`, `document`, `navigator`, `location`, `innerWidth` and the other
  browser globals
- [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render):
  `localStorage` and `sessionStorage`, including state initializers
- [`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render):
  `matchMedia()` media queries
- [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch):
  `typeof window` checks and `isServer`-style flags that change the output
- [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state):
  browser values in the initial value of `useState`, `useReducer`, `useRef`
  and class state

The matching fix guides are [browser-only APIs](https://hydration.jscrate.dev/docs/causes/browser-api),
[storage](https://hydration.jscrate.dev/docs/causes/storage) and
[media queries](https://hydration.jscrate.dev/docs/causes/media-query).

### Locale, time zone and list order

- [`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale):
  `toLocaleString()`, `localeCompare()` and `Intl.*` without a locale
- [`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone):
  date formatting without `timeZone`, and local-time getters such as
  `getHours()`
- [`require-deterministic-list-order`](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order):
  random or locale-dependent sorting, boolean comparators and `shuffle`

These are warnings in `recommended`, because the output only differs when the
server and the visitor use a different [locale](https://hydration.jscrate.dev/docs/causes/locale) or
[time zone](https://hydration.jscrate.dev/docs/causes/timezone).

### Ids and counters

[`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) reports random, time-based or
counter ids where `useId()` belongs.
[`no-global-render-counter`](https://hydration.jscrate.dev/docs/rules/no-global-render-counter) reports
module-level variables changed during render, which keep counting on the
server across requests. See [generated ids that differ](https://hydration.jscrate.dev/docs/causes/unstable-id).

### Markup

[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
reports `<div>` in `<p>`, `<a>` in `<a>`, `<button>` in `<button>` and table
rows outside `<tbody>`: nesting the browser repairs before React hydrates
([invalid HTML](https://hydration.jscrate.dev/docs/causes/invalid-html)).
[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
reports `suppressHydrationWarning` that does nothing or covers too much
([suppressed differences](https://hydration.jscrate.dev/docs/causes/suppressed)). Both also check Server
Components: React hydrates the elements a Server Component renders, and the
root layout, where `<html suppressHydrationWarning>` lives, is one.

### useSyncExternalStore

[`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
reports `useSyncExternalStore` without a `getServerSnapshot`, and a
`getServerSnapshot` that reads the browser, the clock or random values. It is
the rule behind the fix several other rules recommend.

## Presets

| Preset        | Severity                                                                                         | Server Components                                     |
| ------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| `recommended` | Definite mismatches are errors; locale, time zone, initial state and list order are warnings.    | Checked (the setting defaults to `'none'`)            |
| `next`        | Same as `recommended`.                                                                           | Files under `app/` without `'use client'` are skipped |
| `strict`      | Every rule is an error, and every `suppressHydrationWarning` needs a reason (`reportAll: true`). | Checked unless you add the setting                    |

[Set up a preset](https://hydration.jscrate.dev/docs/eslint#set-up-a-preset) shows the config for each,
and [one report per problem](https://hydration.jscrate.dev/docs/eslint#one-report-per-problem) explains
which rule reports a construct when two could.

## Related

- [ESLint plugin: install and configure](https://hydration.jscrate.dev/docs/eslint)
- [What counts as render](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render)
- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes)
- [eslint-plugin-react-hooks compared](https://hydration.jscrate.dev/docs/compare/eslint-plugin-react-hooks)
- [Test the running app with hydration-proof](https://hydration.jscrate.dev/docs/quick-start)

---

# no-date-in-render

> Calling Date.now() in render, new Date() or performance.now() gives the server and the browser different times. This rule reports it and shows the fix.

Source: https://hydration.jscrate.dev/docs/rules/no-date-in-render
Last updated: 2026-09-18

Calling Date.now() in render makes the output depend on the moment the
component runs: the server renders at one time, the browser hydrates at
another, and the text no longer matches. `no-date-in-render` reports
`Date.now()`, `new Date()`, `performance.now()` and `Temporal.Now` in render
code, and tells you where to read the time instead.

| | |
| --- | --- |
| Rule | `hydration-proof/no-date-in-render` |
| What it reports | Disallow reading the current time while a component renders |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

These calls in [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render):

- `Date.now()`
- `new Date()` and `Date()` without arguments
- `performance.now()`
- `Temporal.Now.*()`

It also finds them through `window.`, `self.` and `globalThis.`, and ignores
local variables that happen to be called `Date` or `performance`. Dates built
from explicit values (`new Date(post.publishedAt)`) are fine.

## Why Date.now() in render breaks hydration

The server renders the component at one moment, and the browser renders it
again when it hydrates, a few hundred milliseconds (or, with a cached page,
days) later:

```text
server HTML:   <p>Rendered at 1767225600000</p>
client render: <p>Rendered at 1767225600412</p>
```

React finds different text, reports a hydration error and, in React 19, throws
the server HTML away and renders the page again on the client.
[Date and time hydration errors](https://hydration.jscrate.dev/docs/causes/time) covers every fix in
detail.

## Incorrect

```jsx
function Footer() {
  return <p>© {new Date().getFullYear()}</p>;
}

function Countdown({ endsAt }) {
  const left = endsAt - Date.now();
  return <span>{Math.round(left / 1000)}s</span>;
}

function Timer() {
  const [start] = useState(() => performance.now());
  return <Elapsed since={start} />;
}
```

## Correct

Pass the time from a Server Component, so both renders use the same value.
With the `next` preset, this file is a Server Component and is not checked:

```jsx title="app/sale/page.jsx" filename="app/sale/page.jsx" preset="next"
export default async function Page() {
  return <Countdown endsAt={deadline} now={Date.now()} />;
}
```

Or render a placeholder and read the clock after hydration:

```jsx
function Countdown({ endsAt }) {
  const [now, setNow] = useState(null);
  useEffect(() => {
    setNow(Date.now());
    const id = setInterval(() => setNow(Date.now()), 1000);
    return () => clearInterval(id);
  }, []);
  if (now === null) return <span>–</span>;
  return <span>{Math.round((endsAt - now) / 1000)}s</span>;
}

// Explicit dates are deterministic.
export function Published({ at }) {
  return <time dateTime={at}>{new Date(at).toISOString().slice(0, 10)}</time>;
}
```

Reading the clock in event handlers, effects and `useCallback` callbacks is
fine: they run after hydration.

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- `<source>` reads the clock during render. The server renders one time and the browser another while hydrating, so the output does not match. Pass the time from the server (props or data), or read it in useEffect after hydration.

## When not to use it

When the component is never server-rendered (a client-only app, or a
component loaded with [`next/dynamic` and `ssr: false`](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false)),
or when the output is wrapped in an element with `suppressHydrationWarning` on
purpose (for example a live clock).

## Related

- [`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) reports the clock when the
  value ends up in an `id` (or `htmlFor`, `aria-*`, `name`). Those calls are
  not reported by this rule.
- [`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone)
  reports `new Date().getHours()` for the time zone; this rule reports the
  `new Date()` in it. They are different problems.
- [`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
  reports the clock inside `getServerSnapshot`.
- [eslint-plugin-react-hooks](https://hydration.jscrate.dev/docs/compare/eslint-plugin-react-hooks): its
  `purity` rule (part of the React Compiler rules) also flags known impure
  calls such as `Date.now()` during render, because they make renders
  unpredictable. This rule explains the hydration consequence, skips Server
  Components, covers `performance.now()` and `Temporal.Now`, and hands ids to
  `no-unstable-id`. With both enabled you see two reports for the same call;
  turn one off if you prefer a single report.
- [Text content does not match server-rendered HTML](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html),
  the error this rule prevents

---

# no-random-in-render

> Math.random() in render, crypto.randomUUID(), uuid and nanoid return a new value on each render, so hydration fails. This rule reports them in React code.

Source: https://hydration.jscrate.dev/docs/rules/no-random-in-render
Last updated: 2026-09-18

Math.random() in render returns one value on the server and another when the
browser hydrates, so the HTML and the first client render disagree.
`no-random-in-render` reports `Math.random()`, `crypto.randomUUID()`, uuid,
nanoid and lodash's random helpers in render code, and points you to a value
the server creates or `useId()`.

| | |
| --- | --- |
| Rule | `hydration-proof/no-random-in-render` |
| What it reports | Disallow random values while a component renders |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

These calls in [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render):

- `Math.random()`
- `crypto.randomUUID()` and `crypto.getRandomValues()` (the global,
  `window.crypto`, or `node:crypto`'s `randomUUID`, `randomBytes`,
  `randomInt`)
- `v1`, `v4`, `v6` and `v7` imported from `uuid` (named or namespace imports;
  `v3` and `v5` are deterministic and allowed)
- `nanoid()` from `nanoid` (and `nanoid/non-secure`), and functions created at
  module level with `customAlphabet()` or `customRandom()`
- `uniqueId`, `random` and `sample` from `lodash`, `lodash-es`,
  `lodash/<name>` or `lodash.<name>`

Only imports are matched, so a local function called `nanoid` is not
reported.

## Why Math.random() in render breaks hydration

Every render produces a new value, and the hydration render is a new render:

```text
server HTML:   <div class="card card-0.7281">
client render: <div class="card card-0.1942">
```

Text differences are reported by React and make it render the page again.
Attribute differences (`className`, `style`, `data-*`) are worse: React 19
keeps the server value **without reporting it** in production, so the page
silently runs with the wrong attribute. See
[attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)
for that case.

## Incorrect

```jsx
import { v4 as uuid } from "uuid";
import { sample } from "lodash";

function Tip({ tips }) {
  return <p>{sample(tips)}</p>;
}

function Card() {
  const [seed] = useState(() => Math.random());
  return <div data-seed={seed} />;
}

function Upload() {
  const key = uuid();
  return <Dropzone key={key} />;
}
```

## Correct

Pick on the server and pass the result down. With the `next` preset, this
file is a Server Component and is not checked:

```jsx title="app/tips/page.jsx" filename="app/tips/page.jsx" preset="next"
export default async function Page() {
  const tips = await getTips();
  return <Tip tip={tips[Math.floor(Math.random() * tips.length)]} />;
}
```

Or render something stable first and randomize after hydration:

```jsx
function Tip({ tips }) {
  const [tip, setTip] = useState(tips[0]);
  useEffect(
    () => setTip(tips[Math.floor(Math.random() * tips.length)]),
    [tips]
  );
  return <p>{tip}</p>;
}

// Event handlers run after hydration.
function Upload() {
  const onDrop = (files) => save(files, crypto.randomUUID());
  return <Dropzone onDrop={onDrop} />;
}
```

For ids, use `useId()` (see [`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id)).

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- `<source>` returns a different value on the server and during hydration, so the rendered output does not match. Create the value on the server and pass it down, use useId() for ids, or generate it in useEffect after hydration.

## When not to use it

When the component is never server-rendered, or when the random value is only
used for something that never reaches the DOM and never changes what is
rendered.

## Related

- [`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) reports random values that
  end up in ids. Those calls are not reported by this rule.
- [`require-deterministic-list-order`](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order)
  reports random sort comparators and lodash's `shuffle`/`sampleSize`. Those
  are not reported by this rule.
- [eslint-plugin-react-hooks](https://hydration.jscrate.dev/docs/compare/eslint-plugin-react-hooks): its
  `purity` rule (part of the React Compiler rules) also flags known impure
  calls such as `Math.random()` during render. This rule explains the
  hydration consequence, skips Server Components, and also covers `crypto`,
  uuid, nanoid and lodash helpers. With both enabled you see two reports for
  `Math.random()`; turn one off if you prefer a single report.
- [Random values and hydration](https://hydration.jscrate.dev/docs/causes/random): every fix for this
  cause

---

# no-browser-global-in-render

> Reading window in render: React runs that code on the server too, where window, document and navigator do not exist. This rule reports those reads.

Source: https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render
Last updated: 2026-09-18

Reading window in render: React runs that code on the server as well, where
`window`, `document` and `navigator` do not exist, so the server either
crashes or renders something other than the browser.
`no-browser-global-in-render` reports reads of browser-only globals in render
code; read them after hydration instead.

| | |
| --- | --- |
| Rule | `hydration-proof/no-browser-global-in-render` |
| What it reports | Disallow reading browser-only globals such as window and document while a component renders |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

Reads in [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render) of `window`,
`self`, `document`, `navigator`, `location`, `history`, `screen`,
`innerWidth`, `innerHeight`, `outerWidth`, `outerHeight`, `devicePixelRatio`,
`visualViewport`, `scrollX`, `scrollY`, `pageXOffset` and `pageYOffset`,
directly or through `window.`, `self.` or `globalThis.`
(`globalThis.window.innerWidth`). Any other property read through `window` or
`self` (`window.__STATE__`) is reported too.

The rule uses scope analysis: a prop, parameter or local variable called
`window` or `location` is not the global and is not reported. Globals that
exist on the server as well (`Date`, `Math`, `Intl`, `crypto`, `performance`)
are left to the rules for them.

Not reported here, because a more specific rule does:

- `typeof window` and reads behind a `typeof window` / `isBrowser` check:
  [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) reports the
  check.
- `localStorage` and `sessionStorage`:
  [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render).
- `matchMedia`: [`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render).
- Initial values of `useState`, `useReducer`, `useRef` and class state:
  [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state).

## Why you can't read window in render (React SSR)

On the server these globals do not exist, so the code either throws
(`ReferenceError: window is not defined`, see
[window is not defined](https://hydration.jscrate.dev/docs/errors/window-is-not-defined)) or, behind a
check, renders something other than the browser does:

```text
server HTML:   <aside class="sidebar">        (no window: server rendering failed and fell back, or used a default)
client render: <aside class="sidebar wide">   (window.innerWidth is 1440)
```

## Incorrect

```jsx
function Sidebar() {
  const wide = window.innerWidth > 1024;
  return <aside className={wide ? "sidebar wide" : "sidebar"} />;
}

function Language() {
  return <p>{navigator.language}</p>;
}

function useCurrentPath() {
  return location.pathname;
}
```

## Correct

```jsx
// Read browser values after hydration.
function Sidebar() {
  const [wide, setWide] = useState(false);
  useEffect(() => {
    const update = () => setWide(window.innerWidth > 1024);
    update();
    window.addEventListener("resize", update);
    return () => window.removeEventListener("resize", update);
  }, []);
  return <aside className={wide ? "sidebar wide" : "sidebar"} />;
}

// Or subscribe with a server snapshot.
function useOnline() {
  return useSyncExternalStore(
    subscribe,
    () => navigator.onLine,
    () => true
  );
}

// Use the framework's router instead of location.
function useCurrentPath() {
  return usePathname();
}
```

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- `<read>` is read during render, but it does not exist when the server renders. The server output and the first browser render disagree (or the server crashes). Read it in useEffect after hydration, or use useSyncExternalStore with a getServerSnapshot.

## When not to use it

In components that only render in the browser (for example loaded with
`next/dynamic` and `ssr: false`, or rendered inside a
[client-only boundary](https://hydration.jscrate.dev/docs/guides/client-only-component)). Consider an
`eslint-disable` comment on those files rather than turning the rule off
everywhere.

## Related

- [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch): the
  `typeof window` checks that guard these reads
- [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state):
  browser values in initial state
- [`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot):
  browser reads inside `getServerSnapshot`
- [Browser-only APIs used during render](https://hydration.jscrate.dev/docs/causes/browser-api): the cause
  and its fixes

---

# no-storage-in-initial-render

> Reading localStorage in useState or anywhere in render makes the server render the default and the browser the stored value. This rule reports it.

Source: https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render
Last updated: 2026-09-18

Reading localStorage in useState, or anywhere else in render, gives the two
renders different values: the server has no storage and renders the default,
while the browser renders the stored value during hydration.
`no-storage-in-initial-render` reports every `localStorage` and
`sessionStorage` read in render code, including state initializers.

| | |
| --- | --- |
| Rule | `hydration-proof/no-storage-in-initial-render` |
| What it reports | Disallow reading localStorage or sessionStorage while a component renders, including state initializers |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

Any read of `localStorage` or `sessionStorage` (bare, or through `window.`,
`self.`, `globalThis.`) in [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render),
including the initial values of `useState`, `useReducer`, `useRef` and class
component state. Reads behind a `typeof window !== 'undefined'` check are
reported too: the check keeps the server from crashing, but the two renders
still differ. `typeof localStorage` on its own is an environment check and
belongs to [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch).

## Why localStorage in useState breaks hydration

The server has no storage, so it renders the default. The browser renders the
stored value during hydration:

```text
server HTML:   <html class="light">   (no stored theme)
client render: <html class="dark">    (localStorage.theme === 'dark')
```

React 19 keeps the server's `class="light"` without a warning in production,
so the page stays in the wrong theme until something re-renders it. A text
difference makes React discard the server HTML and render again.

## Incorrect

```jsx
function ThemeToggle() {
  const [theme, setTheme] = useState(
    () => localStorage.getItem("theme") ?? "light"
  );
  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      {theme}
    </button>
  );
}

function Draft() {
  const saved =
    typeof window !== "undefined" ? sessionStorage.getItem("draft") : "";
  return <textarea defaultValue={saved} />;
}
```

## Correct

```jsx
// Start from the default, then load the stored value.
function ThemeToggle() {
  const [theme, setTheme] = useState("light");
  useEffect(() => {
    setTheme(localStorage.getItem("theme") ?? "light");
  }, []);
  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      {theme}
    </button>
  );
}

// Or subscribe to storage with a server snapshot.
function useStoredTheme() {
  return useSyncExternalStore(
    subscribeToStorage,
    () => localStorage.getItem("theme") ?? "light",
    () => "light"
  );
}
```

For a theme that must be right before the first paint, store it in a cookie
and read it on the server, or set the class with an inline script before
React loads and put `suppressHydrationWarning` on `<html>`.
[Theme hydration mismatches](https://hydration.jscrate.dev/docs/causes/theme) walks through both.

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- `<read>` is read during render. Storage only exists in the browser, so the server renders without the stored value and hydration sees a different result. Render the default first and read storage in useEffect, or use useSyncExternalStore with a getServerSnapshot.
- The initial value of `<hook>` reads `<read>`. Storage only exists in the browser, so the server renders the default while the browser starts from the stored value and hydration does not match. Start from the default and load the stored value in useEffect.

## When not to use it

In components that are never server-rendered.

## Related

- [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state)
  covers other browser values in initial state.
- [`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
  reports storage reads inside `getServerSnapshot`.
- [localStorage and sessionStorage read during render](https://hydration.jscrate.dev/docs/causes/storage):
  the cause and its fixes
- [Zustand persist hydration errors](https://hydration.jscrate.dev/docs/guides/zustand-hydration-error),
  the same problem inside a store

---

# no-match-media-in-render

> A matchMedia SSR mismatch happens when a component evaluates a media query in render. This rule reports matchMedia() calls and shows the fixes.

Source: https://hydration.jscrate.dev/docs/rules/no-match-media-in-render
Last updated: 2026-09-18

A matchMedia SSR mismatch happens when a component evaluates a media query
while it renders: the server has no screen and no user preferences, so it
renders one branch, and the browser renders another while hydrating.
`no-match-media-in-render` reports `matchMedia()` in render code, including
state initializers and code behind a `typeof window` check.

| | |
| --- | --- |
| Rule | `hydration-proof/no-match-media-in-render` |
| What it reports | Disallow evaluating media queries with matchMedia while a component renders |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

`matchMedia(...)`, `window.matchMedia(...)`, `self.matchMedia(...)` and
`globalThis.matchMedia(...)` calls (and references to `matchMedia` that are
not a `typeof` check) in [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render),
including state initializers and code behind a `typeof window` check.

## Why matchMedia SSR output differs from the browser

The server has no screen and no user preferences. Code that guards the call
renders a fallback on the server and the real answer in the browser:

```text
server HTML:   <nav class="menu-desktop">   (no matchMedia: assumes desktop)
client render: <nav class="menu-mobile">    (matchMedia('(max-width: 600px)').matches)
```

## Incorrect

```jsx
function Menu() {
  const mobile =
    typeof window !== "undefined" &&
    window.matchMedia("(max-width: 600px)").matches;
  return mobile ? <MobileMenu /> : <DesktopMenu />;
}

function useReducedMotion() {
  const [reduced] = useState(
    () => matchMedia("(prefers-reduced-motion: reduce)").matches
  );
  return reduced;
}
```

## Correct

```jsx
// Let CSS decide when possible: both menus are in the HTML.
function Menu() {
  return (
    <>
      <MobileMenu className="only-mobile" />
      <DesktopMenu className="only-desktop" />
    </>
  );
}

// Or subscribe with a server snapshot.
function useMediaQuery(query) {
  return useSyncExternalStore(
    (onChange) => {
      const list = window.matchMedia(query);
      list.addEventListener("change", onChange);
      return () => list.removeEventListener("change", onChange);
    },
    () => window.matchMedia(query).matches,
    () => false
  );
}
```

`useSyncExternalStore` renders the server snapshot during hydration and then
switches to the real value, so hydration matches.

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- `<read>` evaluates a media query during render. The server has no screen or user preferences, so it renders a different branch than the browser does while hydrating. Render a neutral default and evaluate the query in useEffect or useSyncExternalStore (with getServerSnapshot), or use a CSS media query.

## When not to use it

In components that are never server-rendered.

## Related

- [`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
  makes sure `getServerSnapshot` does not call `matchMedia`.
- [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) reports
  `typeof window.matchMedia` checks.
- [Screen size and media queries read during render](https://hydration.jscrate.dev/docs/causes/media-query):
  the cause and its fixes
- [Theme hydration mismatches](https://hydration.jscrate.dev/docs/causes/theme), where
  `prefers-color-scheme` is the media query

---

# no-locale-without-explicit-locale

> Calling toLocaleString without a locale formats with the runtime's default, which differs on the server and in the browser. This rule reports it.

Source: https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale
Last updated: 2026-09-18

Calling toLocaleString without a locale formats the value with the default
locale of whichever runtime renders it: often `en-US` on the server, the
visitor's language in the browser. The text then differs during hydration.
`no-locale-without-explicit-locale` reports locale-sensitive formatting in
render code that has no explicit locale.

| | |
| --- | --- |
| Rule | `hydration-proof/no-locale-without-explicit-locale` |
| What it reports | Require an explicit locale for locale-sensitive formatting during render |
| recommended / next | Warning |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | Yes |
| Options | defaultLocale |

## What it reports

In [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render), when the locale argument
is missing, `undefined`, `void 0` or `[]`:

- `value.toLocaleString()`, `value.toLocaleDateString()`,
  `value.toLocaleTimeString()`
- `a.localeCompare(b)` (the locale is the second argument)
- `Intl.NumberFormat`, `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat`,
  `Intl.PluralRules`, `Intl.Collator`, `Intl.ListFormat` and
  `Intl.DisplayNames`, with or without `new`
- `Intl.X().resolvedOptions().locale`, which reads the runtime's default
  locale

A variable as the locale (`toLocaleString(locale)`) is accepted: the rule
cannot know its value, and passing the locale from the server is the fix.

The suggestion inserts the locale from the `defaultLocale` option (`'en-US'`
by default). It is offered as a suggestion, not a fix, because the right
locale is a product decision.

## Why toLocaleString without locale breaks hydration

Without a locale, formatting uses the default locale of the JavaScript
runtime. Servers usually run with `en-US` (or whatever the container sets);
browsers use the visitor's language:

```text
server HTML:   <p>Total: 1,234.5</p>   (en-US)
client render: <p>Total: 1.234,5</p>   (de-DE)
```

React reports the text mismatch and renders the page again on the client.
[Locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale) covers the fixes,
including where to get the visitor's locale on the server.

## Incorrect

```jsx
function Price({ amount }) {
  return <p>Total: {amount.toLocaleString()}</p>;
}

function Percent({ value }) {
  const format = new Intl.NumberFormat(undefined, { style: "percent" });
  return <span>{format.format(value)}</span>;
}

function Match({ a, b }) {
  return <p>{a.localeCompare(b) === 0 ? "same" : "different"}</p>;
}
```

## Correct

```jsx
function Price({ amount, locale }) {
  // The locale comes from the request (cookie, URL or Accept-Language) and is passed down.
  return <p>Total: {amount.toLocaleString(locale)}</p>;
}

function Percent({ value }) {
  const format = new Intl.NumberFormat("en-US", { style: "percent" });
  return <span>{format.format(value)}</span>;
}

function Match({ a, b }) {
  return <p>{a.localeCompare(b, "en") === 0 ? "same" : "different"}</p>;
}
```

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultLocale` | `string` | `'en-US'` | Locale inserted by the suggestion. |

```js title="eslint.config.mjs"
{
  rules: {
    'hydration-proof/no-locale-without-explicit-locale': ['warn', { defaultLocale: 'en-GB' }],
  },
}
```

- `defaultLocale` (string, default `'en-US'`): the locale the suggestion
  inserts.

## Messages

What ESLint prints for this rule, word for word:

- `<call>` uses the default locale of whichever runtime renders it. The server's locale and the visitor's browser locale usually differ, so the text does not match during hydration. Pass an explicit locale that is the same on the server and in the browser.
- `<call>` reads the runtime's default locale, which differs between the server and the browser. Pass the locale from the server instead.
- Use the '<locale>' locale.

## When not to use it

When every server and every visitor uses the same locale (an internal tool
with a fixed locale, for example), or when the app sets the runtime's default
locale explicitly on both sides.

## Related

- [`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone):
  `date.toLocaleDateString()` without arguments is missing both a locale and a
  time zone. Each rule reports its own half, at a different position, so the
  two reports are two separate fixes.
- [`require-deterministic-list-order`](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order)
  reports `localeCompare` inside `sort` comparators (the list order changes),
  so this rule does not.
- [Text content does not match server-rendered HTML](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html),
  the error a locale difference produces
- [Locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale): the cause and its fixes

---

# no-timezone-without-explicit-timezone

> Without the Intl.DateTimeFormat timeZone option, dates format in the server's zone and then in the browser's, so hydration fails. This rule reports it.

Source: https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone
Last updated: 2026-09-18

Without the Intl.DateTimeFormat timeZone option, a date is formatted in the
time zone of whichever runtime renders it: UTC on most servers, the visitor's
zone in the browser. `no-timezone-without-explicit-timezone` reports date
formatting without an explicit `timeZone`, and local-time getters such as
`getHours()`, in render code.

| | |
| --- | --- |
| Rule | `hydration-proof/no-timezone-without-explicit-timezone` |
| What it reports | Require an explicit timeZone when dates are formatted or split into parts during render |
| recommended / next | Warning |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | Yes |
| Options | defaultTimeZone |

## What it reports

In [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render):

- `toLocaleDateString()` and `toLocaleTimeString()` without a `timeZone`
  option.
- `new Intl.DateTimeFormat()` / `Intl.DateTimeFormat()` without a `timeZone`
  option.
- `toLocaleString()` without a `timeZone` option when the value is clearly a
  date: the receiver is `new Date(...)` (or a variable initialized with it in
  the same function), or the options contain date or time fields
  (`dateStyle`, `timeStyle`, `year`, `month`, `day`, `hour`, `minute`, ...).
- `getHours()`, `getMinutes()`, `getDate()`, `getDay()`, `getMonth()`,
  `getFullYear()`, `getTimezoneOffset()`, `toDateString()`, `toTimeString()`
  and `toString()` on `new Date(...)` or a variable initialized with it in the
  same function.
- `Intl.DateTimeFormat().resolvedOptions().timeZone`, which reads the
  runtime's time zone.

When the options are not an object literal
(`toLocaleDateString('en-US', options)`), the rule cannot see them and does
not report.

Suggestions (never automatic fixes):

- add `timeZone: 'UTC'` (or the `defaultTimeZone` option) to the options
  object, or add an options object when there is none;
- replace `getHours()` and the other local getters with their UTC versions
  (`getUTCHours()`), when `defaultTimeZone` is `'UTC'`.

## Why the Intl.DateTimeFormat timeZone option matters

Dates are formatted in the time zone of the runtime. Servers usually run in
UTC, browsers in the visitor's zone:

```text
server HTML:   <p>Signed in at 5:00 AM</p>    (UTC)
client render: <p>Signed in at 10:00 AM</p>   (Asia/Karachi)
```

Hydration fails whenever the two zones give a different result, which for
times is almost always, and for dates near midnight.
[Timezone hydration mismatches](https://hydration.jscrate.dev/docs/causes/timezone) explains how to pick
the zone both sides use.

## Incorrect

```jsx
function LastLogin({ at }) {
  return <p>Signed in at {new Date(at).toLocaleTimeString("en-US")}</p>;
}

function Posted({ at }) {
  const date = new Date(at);
  return (
    <p>
      {date.getDate()}/{date.getMonth() + 1}
    </p>
  );
}

function Schedule({ at }) {
  const format = new Intl.DateTimeFormat("en-US", {
    dateStyle: "medium",
    timeStyle: "short",
  });
  return <p>{format.format(at)}</p>;
}
```

## Correct

```jsx
function LastLogin({ at, timeZone }) {
  // The user's zone, stored in their profile or a cookie and passed from the server.
  return (
    <p>Signed in at {new Date(at).toLocaleTimeString("en-US", { timeZone })}</p>
  );
}

function Posted({ at }) {
  const date = new Date(at);
  return (
    <p>
      {date.getUTCDate()}/{date.getUTCMonth() + 1}
    </p>
  );
}

function Schedule({ at }) {
  const format = new Intl.DateTimeFormat("en-US", {
    timeZone: "UTC",
    dateStyle: "medium",
    timeStyle: "short",
  });
  return <p>{format.format(at)}</p>;
}
```

If the visitor's own zone is required and the server cannot know it, render
the date after hydration (in `useEffect`) or put `suppressHydrationWarning` on
the element that shows it.

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultTimeZone` | `string` | `'UTC'` | Time zone inserted by the suggestion. |

```js title="eslint.config.mjs"
{
  rules: {
    'hydration-proof/no-timezone-without-explicit-timezone': ['warn', { defaultTimeZone: 'Europe/Berlin' }],
  },
}
```

- `defaultTimeZone` (string, default `'UTC'`): the zone the suggestion
  inserts. The UTC getter suggestion is only offered when this is `'UTC'`.

## Messages

What ESLint prints for this rule, word for word:

- `<call>` formats the date in the time zone of whichever runtime renders it. Servers usually run in UTC and browsers in the visitor's zone, so the text does not match during hydration. Pass an explicit `timeZone` option.
- `<call>` reads the date in the runtime's local time zone, which differs between the server and the browser. Use the UTC methods, or format with an explicit `timeZone`.
- `<call>` reads the runtime's time zone, which differs between the server and the browser. Pass the time zone from the server, or read it after hydration.
- Add timeZone: '<timeZone>'.
- Use <method>() (UTC).

## When not to use it

When the servers and all visitors share one time zone, or the runtime's
default zone is set explicitly on both sides.

## Related

- [`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale):
  `date.toLocaleDateString()` without arguments is missing a locale and a time
  zone. Both rules report it: this one on the method name, that one on the
  whole call. They are two separate fixes.
- [`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render): `new Date().getHours()`
  reads the current time (that rule) and splits it in the local zone (this
  rule).
- [HP1001: text differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1001), how
  `hydration-proof test` reports a timezone difference
- [Timezone hydration mismatches](https://hydration.jscrate.dev/docs/causes/timezone): the cause and its
  fixes

---

# no-unstable-id

> Use useId instead of a random id, timestamp or counter: those differ between the server render and hydration. This rule reports every unstable id.

Source: https://hydration.jscrate.dev/docs/rules/no-unstable-id
Last updated: 2026-09-18

Use useId instead of a random id, a timestamp or a module-level counter: those
values differ between the server render and hydration, so `id`, `htmlFor` and
`aria-*` references stop matching. `no-unstable-id` reports every value that
changes between renders and ends up in an id, at the call that makes it
unstable.

| | |
| --- | --- |
| Rule | `hydration-proof/no-unstable-id` |
| What it reports | Disallow ids built from random values, the clock or module-level counters |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

Values that change between renders and end up in an id:

- **Sources:** everything [`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render)
  and [`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) recognize
  (`Math.random()`, `crypto.randomUUID()`, uuid, nanoid, lodash's `uniqueId`,
  `Date.now()`, `new Date()`, ...), and module-level `let`/`var` counters
  changed during render (`nextId++`).
- **Id attributes:** `id`, `htmlFor`, `for`, `aria-labelledby`,
  `aria-describedby`, `aria-controls`, `aria-owns`, `aria-activedescendant`,
  `aria-details`, `aria-errormessage`, `list` and `popoverTarget` on any
  element; `name` on `input`, `select`, `textarea`, `button`, `fieldset` and
  `output`; and props ending in `Id` on components (`labelId`, `triggerId`).
- **Id state:** `useState` and `useRef` whose variable is named like an id
  (`id`, `inputId`, `idRef`).

The value is followed through local variables, `useState`, `useRef` and
`useMemo` initializers, template literals, class fields (`this.id`) and
module-level constants. The report is on the call (or counter update) that
makes the value unstable.

## Why use useId instead of a random id

The id rendered on the server is not the id rendered during hydration:

```text
server HTML:   <label for="field-0.4211">Email</label><input id="field-0.4211">
client render: <label for="field-0.8390">Email</label><input id="field-0.8390">
```

React keeps the server's attributes without a warning in production, so the
page works until another render updates some attributes but not others.
Labels then point at nothing and screen readers lose the connection. A
module-level counter is worse: the server keeps counting across requests
(`field-5731`) while every browser starts at `field-1`.

`useId()` produces the same id on the server and during hydration, because it
is derived from the component's position in the tree.

## Incorrect

```jsx
import { nanoid } from "nanoid";

let nextId = 0;

function EmailField() {
  const id = `email-${nextId++}`;
  return (
    <>
      <label htmlFor={id}>Email</label>
      <input id={id} type="email" />
    </>
  );
}

function Tooltip({ children }) {
  const [tooltipId] = useState(() => nanoid());
  return <span aria-describedby={tooltipId}>{children}</span>;
}
```

## Correct

```jsx
function EmailField() {
  const id = useId();
  return (
    <>
      <label htmlFor={id}>Email</label>
      <input id={id} type="email" />
    </>
  );
}

function Tooltip({ children }) {
  const tooltipId = useId();
  return <span aria-describedby={tooltipId}>{children}</span>;
}
```

For list items, combine `useId()` with a stable key from your data:
`` `${id}-${item.id}` ``.

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- `<source>` makes `<sink>` differ between the server render and hydration, so the id and every reference to it (labels, ARIA attributes) do not match. Use React useId() to create ids.

## When not to use it

In components that are never server-rendered. Otherwise there is no reason to
turn it off: `useId()` exists in React 18 and 19.

## Related

This rule takes precedence over
[`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render),
[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render),
[`no-global-render-counter`](https://hydration.jscrate.dev/docs/rules/no-global-render-counter) and
[`require-deterministic-list-order`](https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order):
a value reported here is not reported by them.

- [Generated ids that differ](https://hydration.jscrate.dev/docs/causes/unstable-id): the cause and its
  fixes
- [Attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match),
  the warning an unstable id produces

---

# no-global-render-counter

> A module-level counter (SSR id, item number, render count) changed during render never matches the value in the browser. This rule reports the write.

Source: https://hydration.jscrate.dev/docs/rules/no-global-render-counter
Last updated: 2026-09-18

Changing a module-level variable during render makes the two renders
disagree: the server keeps the value across every request, while each browser
tab starts from the initial value. Anything built on a module-level counter
(SSR id values, item numbers, render counts) drifts.
`no-global-render-counter` reports writes to module-level `let` and `var`
variables in render code.

| | |
| --- | --- |
| Rule | `hydration-proof/no-global-render-counter` |
| What it reports | Disallow changing module-level variables while a component renders |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | allow |

## What it reports

Writes (`++`, `--`, `=`, `+=`, `??=`, destructuring assignments) to a
module-level `let` or `var` from
[render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render). Writes at module level, in
effects and in event handlers are fine, and so is mutating an object
(`cache.set(...)`): only reassigning the variable is reported.

A counter that ends up in an id (`` `field-${nextId++}` ``) is reported by
[`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) instead, with a message that
points to `useId()`.

## Why a module-level counter, SSR id or render count drifts

A module is loaded once per server process and once per browser tab. On the
server the variable keeps its value across every request and every user; in
the browser it starts from the initial value:

```text
server HTML (request 1,000): <p>Item #3001</p>
client render:               <p>Item #1</p>
```

React Strict Mode and concurrent rendering also render components more than
once, so the value drifts even in the browser.

## Incorrect

```jsx
let renderCount = 0;

function Item({ name }) {
  renderCount += 1;
  return (
    <p>
      Item #{renderCount}: {name}
    </p>
  );
}

let lastUser;

function useUser(user) {
  lastUser = user;
  return lastUser;
}
```

## Correct

```jsx
function List({ items }) {
  return items.map((item, index) => (
    <p key={item.id}>
      Item #{index + 1}: {item.name}
    </p>
  ));
}

function useUser(user) {
  const lastUser = useRef(user);
  useEffect(() => {
    lastUser.current = user;
  }, [user]);
  return user;
}
```

Use `useId()` for ids and `useRef` for values that should survive re-renders
of one component.

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `allow` | `string[]` | — | Module-level variable names that may be written during render (for example a deliberate cache). |

```js title="eslint.config.mjs"
{
  rules: {
    'hydration-proof/no-global-render-counter': ['error', { allow: ['cache'] }],
  },
}
```

- `allow` (string array, default `[]`): module-level variables that may be
  written during render, for example a deliberate memoization cache whose
  value is the same on both sides.

## Messages

What ESLint prints for this rule, word for word:

- Module-level `<name>` is changed during render. The server keeps its value across every request while the browser starts from the initial value, so anything derived from it does not match during hydration (and React may render twice in development). Keep the value in state or a ref, or use useId() for ids.

## When not to use it

When the module is only ever evaluated in the browser.

## Related

- [`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) reports counters that are used
  for ids. Those writes are not reported by this rule.
- [Generated ids that differ](https://hydration.jscrate.dev/docs/causes/unstable-id): why counters break
  ids, and the fix
- [Text content does not match server-rendered HTML](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html),
  the error a drifting count produces

---

# no-window-render-branch

> The typeof window !== 'undefined' hydration mismatch: the check is false on the server and true in the browser. This rule reports render branches on it.

Source: https://hydration.jscrate.dev/docs/rules/no-window-render-branch
Last updated: 2026-09-18

A `typeof window !== 'undefined'` hydration mismatch happens because the check
is false on the server and true in the browser, so a component that branches
on it renders different output on each side. `no-window-render-branch`
reports environment checks and flags such as `isServer` that change what a
component renders.

| | |
| --- | --- |
| Rule | `hydration-proof/no-window-render-branch` |
| What it reports | Disallow rendering different output depending on whether the code runs on the server or in the browser |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

In [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render):

- `typeof X` compared with a string (`typeof window !== 'undefined'`,
  `'undefined' == typeof document`, `typeof window.matchMedia === 'function'`),
  where `X` is a browser-only global such as `window`, `document`,
  `navigator`, `localStorage`, `sessionStorage`, `matchMedia`,
  `IntersectionObserver` or `requestAnimationFrame`.
- `'window' in globalThis` and similar `in` checks on the global object.
- `globalThis.window` / `globalThis.document` used as a condition.
- Environment flags used as the condition of `if`, `? :`, `&&`, `||` or `??`:
  `isServer`, `isBrowser`, `isClient`, `canUseDOM`, `canUseDom`, `isSSR`,
  `IS_BROWSER`, `IS_SERVER`, `IS_CLIENT` (imports, module-level constants or
  globals, also as properties such as `ExecutionEnvironment.canUseDOM`),
  `process.browser` and `import.meta.env.SSR`.

Local variables and props are not flags: `const isClient = useIsClient()` is
the recommended pattern and is not reported. A local assigned from a check
(`const isClient = typeof window !== 'undefined'`) is reported once, at the
check.

Not reported here:

- checks in effects, event handlers and other code that runs after hydration;
- checks in the initial value of `useState`, `useReducer`, `useRef` or class
  state: [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state)
  reports those;
- checks that guard a `localStorage`/`sessionStorage` read or a `matchMedia`
  call: [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
  and [`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) report
  the read.

Browser reads behind a reported check
(`typeof window !== 'undefined' ? window.innerWidth : 0`) are not reported
again by [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render).

## Why the typeof window !== 'undefined' hydration mismatch happens

The check is `false` on the server and `true` during hydration, so the two
renders take different branches:

```text
server HTML:   <div class="chart-placeholder"></div>
client render: <canvas class="chart"></canvas>
```

React reports the mismatch and renders the whole page again on the client,
which defeats server rendering.

## Incorrect

```jsx
function Chart({ data }) {
  if (typeof window === "undefined")
    return <div className="chart-placeholder" />;
  return <Canvas data={data} />;
}

function Greeting() {
  const isBrowser = typeof window !== "undefined";
  return (
    <p>{isBrowser ? `Hello from ${window.location.hostname}` : "Hello"}</p>
  );
}
```

## Correct

```jsx
function useIsClient() {
  return useSyncExternalStore(
    () => () => {},
    () => true,
    () => false
  );
}

function Chart({ data }) {
  const isClient = useIsClient();
  if (!isClient) return <div className="chart-placeholder" />;
  return <Canvas data={data} />;
}

function Greeting() {
  const [host, setHost] = useState(null);
  useEffect(() => setHost(window.location.hostname), []);
  return <p>{host ? `Hello from ${host}` : "Hello"}</p>;
}
```

Both render the server's output during hydration and switch after it. With
Next.js, [`next/dynamic` with `ssr: false`](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false)
is another way to render a component only in the browser.

## Options

This rule has no options. Add your own flag names with the
[shared setting](https://hydration.jscrate.dev/docs/eslint#shared-settings) `environmentFlags`:

```js title="eslint.config.mjs"
{
  settings: { 'hydration-proof': { environmentFlags: ['__SERVER__', 'isNode'] } },
}
```

## Messages

What ESLint prints for this rule, word for word:

- `<check>` makes the render output depend on where the code runs. The server takes one branch and the browser the other while hydrating, so the HTML does not match. Render the same output first and switch after mount (useEffect and state), or use useSyncExternalStore with a getServerSnapshot.

## When not to use it

In code that is never server-rendered.

## Related

- [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render):
  browser reads outside a check
- [`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot)
  reports checks inside `getServerSnapshot`.
- [Browser-only APIs used during render](https://hydration.jscrate.dev/docs/causes/browser-api): the cause
  and its fixes
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component): the patterns
  that replace the check
- [Hydration failed because the server rendered HTML didn't match the client](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)

---

# no-invalid-interactive-nesting

> When you nest a button inside button, React markup gets repaired by the browser before hydration. This rule reports that, a div in a p and table rows.

Source: https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting
Last updated: 2026-09-18

When you nest a button inside button, React renders the tree as written, but
the browser's HTML parser repairs the invalid nesting when it reads the
server HTML, so the DOM React hydrates is not the one it rendered.
`no-invalid-interactive-nesting` reports `<button>` in `<button>`, `<a>` in
`<a>`, `<div>` in `<p>`, table rows outside `<tbody>` and similar nesting.

| | |
| --- | --- |
| Rule | `hydration-proof/no-invalid-interactive-nesting` |
| What it reports | Disallow HTML nesting that the browser repairs while parsing, such as <div> in <p> or <a> in <a> |
| recommended / next | Error |
| strict | Error |
| Server Components | Checked |
| Suggestions | No |
| Options | none |

## What it reports

Nesting in JSX that is visible in one component (through fragments, `&&`,
`? :`, arrays and `.map()` callbacks, but not through other components):

- `<a>` in `<a>`, `<button>` in `<button>`, `<form>` in `<form>`, `<label>`
  in `<label>`, at any depth;
- interactive content inside `<a>` or `<button>`: `a`, `button`, `select`,
  `textarea`, `label`, `details`, `iframe`, `embed`, `input` (unless
  `type="hidden"`; a dynamic `type` is not reported) and `audio`/`video` with
  `controls`;
- elements that close an open `<p>` inside a `<p>`: `div`, `p`, `ul`, `ol`,
  `li`, `dl`, `dd`, `dt`, `table`, `h1`–`h6`, `section`, `article`, `header`,
  `footer`, `nav`, `aside`, `main`, `form`, `pre`, `blockquote`, `hr`,
  `figure`, `figcaption`, `fieldset`, `address`, `details`, `summary`,
  `dialog`, `hgroup`, `menu`, `search` and a few legacy tags. As in the HTML
  parser, the search stops at `button`, `table`, `td`, `th`, `caption`,
  `object` and `template`;
- `<tr>` as a direct child of `<table>` (the browser adds `<tbody>`), and
  `<td>`/`<th>` as a direct child of `<table>`, `<tbody>`, `<thead>` or
  `<tfoot>` (the browser adds `<tr>`).

The report is on the inner element. Elements inside `<svg>` and `<math>` are
skipped, and so is `<li>` outside a list: a component boundary may put it in
the right place.

Unlike most rules, this rule also checks
[Server Components](https://hydration.jscrate.dev/docs/eslint#server-components): React hydrates the
elements a Server Component renders, so invalid nesting there breaks
hydration too.

## What happens to a button inside button: React vs the HTML parser

React renders the tree as written, but the browser builds the DOM from the
server's HTML with the HTML parser, which repairs invalid nesting:

```text
server HTML:  <p>Intro<div>Details</div></p>
browser DOM:  <p>Intro</p><div>Details</div><p></p>
```

When React hydrates, the DOM no longer has the structure it rendered. React
reports the problem and renders the page again on the client:

```text
In HTML, <div> cannot be a descendant of <p>.
This will cause a hydration error.
```

[div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p)
explains that message. `hydration-proof test` reports the same problem as
[HP3001](https://hydration.jscrate.dev/docs/issues/hp3001) (invalid nesting) or
[HP3002](https://hydration.jscrate.dev/docs/issues/hp3002) (nested interactive elements), with the line in
the server HTML.

## Incorrect

```jsx
function Intro() {
  return (
    <p>
      Welcome
      <div className="details">Read more below.</div>
    </p>
  );
}

function CardLink({ href, onSave }) {
  return (
    <a href={href}>
      <h3>Title</h3>
      <button onClick={onSave}>Save</button>
    </a>
  );
}

function Rows({ rows }) {
  return (
    <table>
      {rows.map((row) => (
        <tr key={row.id}>
          <td>{row.name}</td>
        </tr>
      ))}
    </table>
  );
}
```

The rule checks Server Components too, so the same mistake in an App Router
page is reported with the `next` preset:

```jsx title="app/pricing/page.jsx" filename="app/pricing/page.jsx" preset="next"
export default function Page() {
  return (
    <button type="button">
      Compare plans
      <button type="button">Details</button>
    </button>
  );
}
```

## Correct

```jsx
function Intro() {
  return (
    <div>
      <p>Welcome</p>
      <div className="details">Read more below.</div>
    </div>
  );
}

function CardLink({ href, onSave }) {
  return (
    <div className="card">
      <a href={href}>
        <h3>Title</h3>
      </a>
      <button onClick={onSave}>Save</button>
    </div>
  );
}

function Rows({ rows }) {
  return (
    <table>
      <tbody>
        {rows.map((row) => (
          <tr key={row.id}>
            <td>{row.name}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}
```

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- `<<child>>` cannot be inside another `<<parent>>`. The browser repairs this HTML while parsing the server response, so the page no longer has the tree React rendered and hydration fails. Make them siblings or use a different element.
- Interactive `<<child>>` cannot be inside `<<parent>>`. The HTML is invalid, React reports it as a hydration error, and browsers handle clicks on it inconsistently. Move it outside the `<<parent>>`.
- `<<child>>` cannot be inside `<p>`. The browser closes the `<p>` before the `<<child>>` while parsing the server HTML, so the DOM no longer matches what React rendered and hydration fails. Use a `<div>` instead of the `<p>`, or a `<span>` instead of the `<<child>>`.
- `<tr>` cannot be a direct child of `<table>`. The browser inserts a `<tbody>` while parsing the server HTML, so the DOM no longer matches what React rendered. Wrap the rows in `<tbody>`, `<thead>` or `<tfoot>`.
- `<<child>>` must be inside a `<tr>`. The browser inserts a `<tr>` while parsing the server HTML, so the DOM no longer matches what React rendered. Wrap the cells in `<tr>`.

## When not to use it

When the HTML is never parsed by a browser before React takes over (pure
client rendering). Even then the markup is invalid, so keeping the rule is
recommended.

## Related

Nesting that crosses component boundaries (`<p><Card /></p>` where `Card`
renders a `<div>`) cannot be seen by a linter. `hydration-proof test` finds it
in the real server HTML.

- [Invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html): the cause and its fixes
- [validateDOMNesting warnings](https://hydration.jscrate.dev/docs/errors/validatedomnesting), React's
  development warning for the same nesting
- [eslint-plugin-validate-jsx-nesting compared](https://hydration.jscrate.dev/docs/compare/eslint-plugin-validate-jsx-nesting)
- [HP3002: nested interactive elements](https://hydration.jscrate.dev/docs/issues/hp3002)

---

# audit-suppress-hydration-warning

> A suppressHydrationWarning ESLint rule: it reports the attribute where it does nothing or hides more than intended, and in strict mode every use.

Source: https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning
Last updated: 2026-09-18

`audit-suppress-hydration-warning` is the suppressHydrationWarning ESLint
check: it reports the attribute where it does nothing or hides more than you
meant, on an element with child elements, on static content, or on a
component. With the `strict` preset it reports every use, so each one needs a
comment that explains it.

| | |
| --- | --- |
| Rule | `hydration-proof/audit-suppress-hydration-warning` |
| What it reports | Report suppressHydrationWarning where it has no effect or hides more than intended |
| recommended / next | Error |
| strict | Error |
| Server Components | Checked |
| Suggestions | Yes |
| Options | allowOn, reportAll |

## What the suppressHydrationWarning ESLint rule reports

`suppressHydrationWarning` (not `={false}`) on:

- **an HTML element with element children** (`tooDeep`). The attribute only
  covers the element's own attributes and its direct text, one level deep. A
  mismatch inside a child is still an error.
- **an HTML element whose attributes and text are all static** (`unused`).
  Nothing can differ, so the attribute only hides future mistakes. `key`,
  `ref` and event handlers are ignored when deciding. A suggestion removes the
  attribute.
- **a component** (`onComponent`), such as `<Clock suppressHydrationWarning />`.
  It has no effect unless the component passes the prop to an HTML element.
- with `reportAll: true` (the `strict` preset), **every other use**
  (`audit`), so each suppression needs an `eslint-disable` comment that
  explains it.

`<html>` and `<body>` are accepted by default (option `allowOn`): theme
scripts and browser extensions change their attributes before React hydrates,
which is the use case the attribute exists for.

Unlike most rules, this rule also checks
[Server Components](https://hydration.jscrate.dev/docs/eslint#server-components): the root layout, where
`<html suppressHydrationWarning>` usually lives, is one.

## Why

`suppressHydrationWarning` tells React to keep the server's text and
attributes for one element without reporting a difference. Used in the wrong
place it either does nothing (the error still happens) or hides a real bug:

```jsx
<div suppressHydrationWarning>
  <span>{new Date().toLocaleTimeString()}</span>{" "}
  {/* still a hydration error: the text is in the span */}
</div>
```

`hydration-proof test` lists every difference hidden by the attribute as
HP6xxx info ([HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) to [HP6003](https://hydration.jscrate.dev/docs/issues/hp6003)),
so you can check what each one suppresses.
[When suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
covers the cases where the attribute is the right tool.

## Incorrect

```jsx
function Clock() {
  return (
    <div suppressHydrationWarning>
      <span>{new Date().toLocaleTimeString("en-US", { timeZone: "UTC" })}</span>
    </div>
  );
}

function Title() {
  return <h1 suppressHydrationWarning>Dashboard</h1>;
}

function Page() {
  return <RelativeTime suppressHydrationWarning />;
}
```

With `reportAll: true`, as in the `strict` preset, a use that is not obviously
wrong is reported too, until it has a comment that explains it:

```jsx options='{"reportAll":true}'
function Clock({ now }) {
  return (
    <span suppressHydrationWarning>
      {now.toLocaleTimeString("en-US", { timeZone: "UTC" })}
    </span>
  );
}
```

## Correct

```jsx
function Clock({ now }) {
  return (
    <div>
      <span suppressHydrationWarning>
        {now.toLocaleTimeString("en-US", { timeZone: "UTC" })}
      </span>
    </div>
  );
}

function Title() {
  return <h1>Dashboard</h1>;
}

export function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>{children}</body>
    </html>
  );
}
```

With `reportAll: true`, a use with an `eslint-disable` comment that gives the
reason:

```jsx options='{"reportAll":true}'
function Clock({ now }) {
  return (
    <div>
      {/* eslint-disable-next-line hydration-proof/audit-suppress-hydration-warning -- a live clock; the server time is replaced after hydration */}
      <span suppressHydrationWarning>
        {now.toLocaleTimeString("en-US", { timeZone: "UTC" })}
      </span>
    </div>
  );
}
```

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `allowOn` | `string[]` | `['html', 'body']`: theme and extension scripts change their attributes before React hydrates | Elements where any use is accepted. |
| `reportAll` | `boolean` | `false` | Report every other use too, so each one must be justified in a disable comment. |

```js title="eslint.config.mjs"
{
  rules: {
    'hydration-proof/audit-suppress-hydration-warning': ['error', { allowOn: ['html', 'body', 'ThemeProvider'], reportAll: false }],
  },
}
```

- `allowOn` (string array, default `['html', 'body']`): element or component
  names where any use is accepted. Set it to `[]` to check `<html>` and
  `<body>` as well.
- `reportAll` (boolean, default `false`): also report uses that are not
  obviously wrong. The `strict` preset turns this on.

## Messages

What ESLint prints for this rule, word for word:

- `suppressHydrationWarning` on `<<tag>>` only covers its own attributes and text, not the elements inside it: a mismatch in a child is still an error. Put it on the element whose content differs.
- `suppressHydrationWarning` on `<<tag>>` has nothing to suppress: its attributes and text are static. Remove it so that real mismatches added later are not hidden.
- `suppressHydrationWarning` on `<<tag>>` does nothing unless the component passes it to an HTML element. Put it on the element that renders the differing content, or make sure `<tag>` forwards it.
- `suppressHydrationWarning` hides hydration mismatches on `<<tag>>`. Render the same value on the server and in the browser instead, or explain why it is needed in an eslint-disable comment.
- Remove suppressHydrationWarning.

## When not to use it

When a design system passes `suppressHydrationWarning` through many wrapper
components on purpose: add those components to `allowOn` instead of turning
the rule off.

## Related

- [`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) and
  [`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone):
  fixing the cause is usually better than suppressing it.
- [Intentional differences (suppressHydrationWarning)](https://hydration.jscrate.dev/docs/causes/suppressed),
  as `hydration-proof test` reports them
- [Theme hydration mismatches](https://hydration.jscrate.dev/docs/causes/theme), the case `<html>` is
  allowed for
- [Extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server),
  what browser extensions cause on `<html>` and `<body>`

---

# no-client-only-initial-state

> A useState initial value (window.innerWidth, navigator, a typeof window check) differs on the server and in the browser. This rule reports it in React.

Source: https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state
Last updated: 2026-09-18

A useState initial value (`window.innerWidth`, `navigator.share`, a
`typeof window` check) is computed on the server and again during hydration,
so the two sides start from different state and render different HTML.
`no-client-only-initial-state` reports browser-only reads and environment
checks in the initial values of `useState`, `useReducer`, `useRef` and class
state.

| | |
| --- | --- |
| Rule | `hydration-proof/no-client-only-initial-state` |
| What it reports | Disallow initial state and refs computed from browser-only values |
| recommended / next | Warning |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

Browser-only reads (`window`, `document`, `navigator`, `location`, `history`,
`screen`, `innerWidth`, `devicePixelRatio`, ... : the list of
[`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render)) in:

- the initial value of `useState` (value or lazy initializer),
- the initial argument and the init function of `useReducer`,
- the initial value of `useRef`,
- class component state: a `state = { ... }` field or `this.state = { ... }`
  in the constructor.

An initializer that reads nothing from the browser but branches on the
environment (`useState(typeof window !== 'undefined')`,
`useState(isBrowser ? 'live' : 'static')`) is reported once, at the check.

`localStorage`/`sessionStorage` and `matchMedia` in initializers are left to
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render) and
[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render), including a
`typeof window` check that guards them.

## Why a useState initial value (window, navigator) breaks hydration

State initializers run during the first render, on the server and again
during hydration. A guard keeps the server from crashing, but the two sides
still start from different state:

```text
server HTML:   <nav class="menu-desktop">   (useState(() => typeof window === 'undefined' ? 1024 : window.innerWidth) → 1024)
client render: <nav class="menu-mobile">    (the same initializer → 390)
```

React keeps the server's HTML only when the first client render produces the
same output. [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
explains the pattern the fixes below use.

## Incorrect

```jsx
function Menu() {
  const [width] = useState(() =>
    typeof window === "undefined" ? 1024 : window.innerWidth
  );
  return width < 600 ? <MobileMenu /> : <DesktopMenu />;
}

function ShareButton() {
  const [canShare] = useState(
    typeof navigator !== "undefined" && "share" in navigator
  );
  return canShare ? <button>Share</button> : null;
}

class Page extends React.Component {
  state = { path: window.location.pathname };
  render() {
    return <p>{this.state.path}</p>;
  }
}
```

## Correct

```jsx
function Menu() {
  const [width, setWidth] = useState(1024);
  useEffect(() => {
    const update = () => setWidth(window.innerWidth);
    update();
    window.addEventListener("resize", update);
    return () => window.removeEventListener("resize", update);
  }, []);
  return width < 600 ? <MobileMenu /> : <DesktopMenu />;
}

function ShareButton() {
  const [canShare, setCanShare] = useState(false);
  useEffect(() => setCanShare("share" in navigator), []);
  return canShare ? <button>Share</button> : null;
}

class Page extends React.Component {
  state = { path: this.props.initialPath };
  componentDidMount() {
    this.setState({ path: window.location.pathname });
  }
  render() {
    return <p>{this.state.path}</p>;
  }
}
```

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- The initial value of `<hook>` reads `<read>`, which only exists in the browser. The server renders with a fallback and the browser with the real value, so hydration does not match. Initialize with the value the server can render and update it in useEffect.
- The initial value of `<hook>` depends on `<check>`, so the server and the browser start from different state and hydration does not match. Initialize with the value the server can render and update it in useEffect.

## When not to use it

In components that are never server-rendered. The rule is a warning in
`recommended` because a component can be client-only by design (for example
behind [`next/dynamic` with `ssr: false`](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false)).

## Related

- [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render)
  reports browser reads elsewhere in render.
- [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) reports
  environment checks elsewhere in render.
- [Browser-only APIs used during render](https://hydration.jscrate.dev/docs/causes/browser-api): the cause
  and its fixes
- [Screen size and media queries read during render](https://hydration.jscrate.dev/docs/causes/media-query),
  the usual reason to read `window.innerWidth`

---

# require-stable-server-snapshot

> useSyncExternalStore needs a getServerSnapshot that returns the same value on the server and during hydration. This rule reports a missing or unstable one.

Source: https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot
Last updated: 2026-09-18

`useSyncExternalStore` needs a getServerSnapshot, its third argument, to
render on the server and to hydrate, and that function must return the same
value in both places. `require-stable-server-snapshot` reports a missing
`getServerSnapshot`, and one that reads the browser, the clock or random
values.

| | |
| --- | --- |
| Rule | `hydration-proof/require-stable-server-snapshot` |
| What it reports | Require useSyncExternalStore to have a getServerSnapshot that returns the same value on the server and during hydration |
| recommended / next | Error |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | No |
| Options | none |

## What it reports

- `useSyncExternalStore(subscribe, getSnapshot)` without a third argument (or
  with `undefined`), including `React.useSyncExternalStore` and the
  `use-sync-external-store/shim` export.
- Inside `getServerSnapshot` (an inline function, or a function declared in
  the same file and passed by name): any read of a browser-only global,
  `localStorage`/`sessionStorage`, `matchMedia`, the clock (`Date.now()`,
  `new Date()`, ...), random values (`Math.random()`, ...) and environment
  checks (`typeof window`).

Functions nested inside `getServerSnapshot` and functions imported from other
files are not inspected.

## Why getServerSnapshot must be stable

During server rendering React calls `getServerSnapshot`; without it,
rendering the component on the server fails and React renders it again in the
browser ([Missing getServerSnapshot](https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot)
is that error). During hydration React calls `getServerSnapshot` again, in the
browser, and expects the value the server used. Only after hydration does it
switch to `getSnapshot`:

```text
server:     getServerSnapshot() → typeof window === 'undefined' → 'light'
hydration:  getServerSnapshot() → typeof window === 'undefined' → 'dark'   (mismatch)
```

So `getServerSnapshot` must be a pure function of data both sides have.

## Incorrect

```jsx
function useOnline() {
  return useSyncExternalStore(subscribe, () => navigator.onLine);
}

function useTheme() {
  return useSyncExternalStore(
    subscribeToStorage,
    () => localStorage.getItem("theme"),
    () => localStorage.getItem("theme") ?? "light"
  );
}

const getWidth = () => window.innerWidth;

function useWidth() {
  return useSyncExternalStore(subscribeToResize, getWidth, getWidth);
}
```

## Correct

```jsx
function useOnline() {
  return useSyncExternalStore(
    subscribe,
    () => navigator.onLine,
    () => true
  );
}

function useTheme(serverTheme) {
  return useSyncExternalStore(
    subscribeToStorage,
    () => localStorage.getItem("theme") ?? serverTheme,
    () => serverTheme // read from a cookie on the server and passed as a prop
  );
}

const getWidth = () => window.innerWidth;
const getServerWidth = () => 1024;

function useWidth() {
  return useSyncExternalStore(subscribeToResize, getWidth, getServerWidth);
}
```

## Options

This rule has no options.

## Messages

What ESLint prints for this rule, word for word:

- `useSyncExternalStore` has no getServerSnapshot. React needs it to render on the server and to hydrate: without it the server render errors and the component is rendered again in the browser. Pass a third argument that returns the value the server renders.
- getServerSnapshot reads `<read>`. It must return the same value on the server and while hydrating, so it cannot depend on the browser, the clock or randomness. Return a constant or data passed from the server.

## When not to use it

When the store is only used in components that are never server-rendered.

## Related

- [`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state),
  [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render)
  and [`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render)
  recommend `useSyncExternalStore` with a server snapshot as a fix.
- [Missing getServerSnapshot](https://hydration.jscrate.dev/docs/errors/missing-getserversnapshot): the
  React error, decoded
- [localStorage and sessionStorage read during render](https://hydration.jscrate.dev/docs/causes/storage),
  the most common store behind `useSyncExternalStore`

---

# require-deterministic-list-order

> A localeCompare sort hydration mismatch, a random comparator or a shuffle orders a list differently on the server and in the browser. This rule reports it.

Source: https://hydration.jscrate.dev/docs/rules/require-deterministic-list-order
Last updated: 2026-09-18

A localeCompare sort hydration mismatch happens when a list is sorted during
render with the runtime's default locale: the server and the browser put the
items in a different order. `require-deterministic-list-order` reports that,
random comparators, comparators that return a boolean, and lodash's
`shuffle` and `sampleSize` in render code.

| | |
| --- | --- |
| Rule | `hydration-proof/require-deterministic-list-order` |
| What it reports | Require list ordering during render to be the same on the server and in the browser |
| recommended / next | Warning |
| strict | Error |
| Server Components | Skipped with the next preset |
| Suggestions | Yes |
| Options | defaultLocale |

## What it reports

In [render code](https://hydration.jscrate.dev/docs/eslint#what-counts-as-render):

- `sort`/`toSorted` comparators that use random values
  (`() => Math.random() - 0.5`);
- `localeCompare` without an explicit locale inside a `sort`/`toSorted`
  comparator. A suggestion adds the `defaultLocale` option (`'en-US'` by
  default);
- comparators that return a boolean (`(a, b) => a > b`). When both sides are
  simple values, a suggestion rewrites the comparator to return `1`, `-1` or
  `0`;
- lodash's `shuffle` and `sampleSize` (from `lodash`, `lodash-es`,
  `lodash/<name>` or `lodash.<name>`).

`sort()` without a comparator is fine: the default order compares strings by
UTF-16 code units, which is the same everywhere.

## Why a localeCompare sort hydration mismatch happens

The server and the browser must render list items in the same order:

- random comparators and shuffle helpers give a different order on each
  render;
- `localeCompare` without a locale sorts with the runtime's default locale
  (`'ä'` sorts differently in German and Swedish);
- a comparator must return a negative number, zero or a positive number. A
  boolean is `1` or `0`, never negative, and each JavaScript engine (V8 on the
  server, JavaScriptCore in Safari) handles that inconsistency differently.

```text
server HTML:   <li>Anna</li><li>Émile</li><li>Zoë</li>
client render: <li>Anna</li><li>Zoë</li><li>Émile</li>
```

## Incorrect

```jsx
import { shuffle } from "lodash";

function Featured({ products }) {
  return shuffle(products).map((product) => (
    <Product key={product.id} {...product} />
  ));
}

function Names({ names }) {
  return names
    .toSorted((a, b) => a.localeCompare(b))
    .map((name) => <li key={name}>{name}</li>);
}

function Scores({ scores }) {
  return [...scores]
    .sort((a, b) => a.points < b.points)
    .map((s) => <li key={s.id}>{s.points}</li>);
}
```

## Correct

```jsx
function Featured({ products, seed }) {
  // Shuffled on the server (or with a seed from the server), passed as a prop.
  return products.map((product) => <Product key={product.id} {...product} />);
}

function Names({ names, locale }) {
  return names
    .toSorted((a, b) => a.localeCompare(b, locale))
    .map((name) => <li key={name}>{name}</li>);
}

function Scores({ scores }) {
  return [...scores]
    .sort((a, b) => b.points - a.points)
    .map((s) => <li key={s.id}>{s.points}</li>);
}
```

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultLocale` | `string` | `'en-US'` | Locale inserted by the `localeCompare` suggestion. |

```js title="eslint.config.mjs"
{
  rules: {
    'hydration-proof/require-deterministic-list-order': ['warn', { defaultLocale: 'de-DE' }],
  },
}
```

- `defaultLocale` (string, default `'en-US'`): the locale the `localeCompare`
  suggestion inserts.

## Messages

What ESLint prints for this rule, word for word:

- Sorting with `<source>` shuffles the list differently on the server and while hydrating, so the items render in a different order. Shuffle on the server and pass the result down, or shuffle after mount.
- `<helper>()` picks a random order during render, which differs between the server and hydration. Shuffle on the server and pass the result down, or shuffle after mount.
- `<call>` sorts by the runtime's default locale, which differs between the server and the browser, so the list order does not match during hydration. Pass an explicit locale.
- This comparator returns a boolean. Comparators must return a negative number, zero or a positive number; with a boolean the order depends on the JavaScript engine, so the server and the browser can order items differently. Return a number instead.
- Use the '<locale>' locale.
- Return 1, -1 or 0.

## When not to use it

When lists are only rendered in the browser.

## Related

- [`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render) and
  [`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale)
  leave calls inside sort comparators, and `shuffle`/`sampleSize`, to this
  rule.
- [Locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale): the locale half of the
  problem
- [Random values and hydration](https://hydration.jscrate.dev/docs/causes/random): the shuffle half

---

# Next.js dev overlay vs hydration-proof

> The Next.js dev overlay hydration error view shows one mismatch on the page you have open. hydration-proof tests every route, in CI and in production builds.

Source: https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay
Last updated: 2026-09-18

The Next.js dev overlay hydration error view shows a mismatch on the page you have open, while `next dev` runs. hydration-proof loads every route of development and production builds, in CI, and reports each mismatch with a stable code and a likely cause. Use the overlay while you write code and hydration-proof before you merge.

## At a glance

|                                             | Next.js dev overlay                                        | hydration-proof                                                             |
| ------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| Runs                                        | In `next dev`, in your browser                             | In the terminal and CI, in Playwright browsers                              |
| Pages                                       | The one you open                                           | Every discovered route, plus sitemap or crawled pages                       |
| Builds                                      | Development                                                | Production (default), development, or both                                  |
| Attribute mismatches in React 19 production | Not applicable: development only                           | Reported                                                                    |
| Output                                      | The error, a code frame and a `+ Client` / `- Server` diff | Issue code, element, both values, component, source line, likely cause, fix |
| Fails a build                               | No                                                         | Yes, with exit code `1`                                                     |
| Setup                                       | Built into Next.js                                         | `npm install -D hydration-proof`                                            |
| Frameworks                                  | Next.js                                                    | Next.js, React Router, Remix, Astro, Vite SSR, custom servers               |

## What the Next.js dev overlay hydration error view does well

- **It is already there.** Every Next.js app has it; there is nothing to install or configure.
- **It shows the source.** Since Next.js 15, hydration errors "display the source code of the error with suggestions on how to address the issue" ([Next.js 15](https://nextjs.org/blog/next-15)).
- **It labels the diff.** Next.js 16.2 added a hydration diff indicator: the overlay "clearly labels which content came from the server and which from the client" with a `+ Client` / `- Server` legend ([Next.js 16.2](https://nextjs.org/blog/next-16-2)).
- **It is immediate.** The error appears as you browse, next to the code you just changed.

For a mismatch on the page in front of you, that is often all you need.

## Where hydration-proof differs

- **Every route, not the one you opened.** A mismatch in a page you did not visit, or in a scenario you did not try (another timezone, dark mode, a phone), never reaches the overlay. hydration-proof discovers routes from `app/`, `pages/` and the build output and tests each one in every [scenario](https://hydration.jscrate.dev/docs/scenarios) you configure.
- **Production builds.** The overlay is a development tool. hydration-proof tests the production build by default, and `--mode both` tests both and marks findings that appear in only one.
- **Mismatches React does not report.** React 19 production builds never report attribute mismatches. hydration-proof compares every attribute with the props React renders on the client, so a wrong `className`, `style` or `href` is found anyway.
- **Changes outside React.** Browser extensions, scripts that edit the page before hydration, and CDN rewrites are reported under their own codes ([HP4001](https://hydration.jscrate.dev/docs/issues/hp4001) to [HP4003](https://hydration.jscrate.dev/docs/issues/hp4003)).
- **Stable codes and causes.** Each finding has an [issue code](https://hydration.jscrate.dev/docs/issues) that never changes meaning, and a likely cause with a confidence score. `--probe` proves the cause by changing one factor at a time.
- **CI.** It exits with code `1` when it finds a problem, writes JSON, JUnit, SARIF and HTML reports, and supports baselines so you can adopt it without a red pipeline ([CI](https://hydration.jscrate.dev/docs/ci)).

## Use both

They cover different moments. Keep the overlay for the page you are working on, and run hydration-proof on every pull request:

```bash
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test --mode both
```

hydration-proof also has its own [development overlay](https://hydration.jscrate.dev/docs/dev-overlay), `npx hydration-proof dev`. It works next to Next.js's, shows the findings of each page you open with the cause and the fix, and adds nothing to your app's bundle.

## Sources

As of September 2026:

- [Next.js 15 release notes](https://nextjs.org/blog/next-15), "Hydration error improvements"
- [Next.js 16.2 release notes](https://nextjs.org/blog/next-16-2), "Hydration Diff Indicator"
- [Next.js: Text content does not match server-rendered HTML](https://nextjs.org/docs/messages/react-hydration-error)
- [hydration-proof: how it works](https://hydration.jscrate.dev/docs/how-it-works)

## Related

- [Next.js hydration errors](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [How hydration-proof compares with other tools](https://hydration.jscrate.dev/docs/comparison)
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)
- [react-hydration-overlay compared](https://hydration.jscrate.dev/docs/compare/react-hydration-overlay)

---

# hydration-proof vs react-hydration-overlay

> A react-hydration-overlay alternative that adds no code to your app: test every route in CI and production builds, with the element, values and cause.

Source: https://hydration.jscrate.dev/docs/compare/react-hydration-overlay
Last updated: 2026-09-18

If you are looking for a react-hydration-overlay alternative, hydration-proof covers the same need, the server and client HTML side by side, without code in your app. Builder.io's overlay wraps your app and shows a diff on the page when hydration fails. hydration-proof tests every route in a real browser, locally or in CI, in development and production builds.

## At a glance

|               | Builder.io's overlay                              | hydration-proof                                                        |
| ------------- | ------------------------------------------------- | ---------------------------------------------------------------------- |
| How it runs   | A component and a build plugin in your app        | A CLI that drives Playwright browsers; nothing in your app             |
| When          | While you browse, in development                  | In the terminal and CI; an optional overlay while you browse           |
| Pages         | The one you open                                  | Every discovered route                                                 |
| Builds        | Development (not intended for production)         | Production (default), development, or both                             |
| Shows         | The server and client HTML of the page, as a diff | The element, both values, component, source line, likely cause and fix |
| Frameworks    | Next.js (plugin), webpack                         | Next.js, React Router, Remix, Astro, Vite SSR, custom servers          |
| Status        | Beta, version 0.3.0                               | Stable, version 1.0                                                    |
| Fails a build | No                                                | Yes, with exit code `1`                                                |

## What Builder.io's overlay does well

[Builder.io's hydration overlay](https://github.com/BuilderIO/hydration-overlay) is a small, focused tool:

- **A whole-page diff.** An injected script captures the server HTML before hydration. When a hydration error happens, the overlay compares it with the client HTML and shows the difference on top of the page.
- **Simple setup for Next.js.** Wrap the app in `HydrationOverlay` and add `withHydrationOverlay` to `next.config.js`; `appRootSelector` points it at `main` for the App Router. A webpack plugin covers other setups.
- **Visual and immediate.** You see the diff where the error happened, without leaving the browser.

It has about 8,000 weekly downloads on npm.

## Where hydration-proof differs

- **Nothing added to your app.** The overlay is a dependency, a wrapper component and a build plugin, and its README says it "is not intended for production use". hydration-proof injects its runtime into the test browser only; your code and bundle do not change.
- **Every route, in CI.** The overlay reports the page you open. hydration-proof discovers routes and tests all of them, in every [scenario](https://hydration.jscrate.dev/docs/scenarios) you configure, and fails the build when it finds a problem.
- **Production builds and silent mismatches.** The overlay is for development builds, and React 19 production builds do not report attribute mismatches at all. hydration-proof tests production builds by default and compares every attribute with what React renders on the client, so it finds those too.
- **Where the difference started.** The overlay's README notes that because React re-renders the whole app after a hydration failure, its diff can show false positives, and that React's changes to inline `style` formatting (an added `;`, different whitespace) can look like differences. hydration-proof gives every node an identity across its snapshots and compares attributes with the props React renders, so it reports the element where a difference started ([how it works](https://hydration.jscrate.dev/docs/how-it-works)).
- **A cause, not only a diff.** Each finding has a [stable issue code](https://hydration.jscrate.dev/docs/issues), the component and source line, and a [likely cause](https://hydration.jscrate.dev/docs/causes) with a confidence score.
- **Frameworks beyond Next.js.** The overlay's README lists Remix and Vite SSR support as still needed. hydration-proof detects React Router, Remix, Astro and Vite SSR apps, and works with any server through `--url`.

## Switching to a react-hydration-overlay alternative

1. Remove the `HydrationOverlay` wrapper and the `withHydrationOverlay` plugin from `next.config.js`, then uninstall the package.
2. Install hydration-proof and run it once:

   ```bash
   npm install -D hydration-proof
   npx hydration-proof install
   npx hydration-proof test
   ```

3. For the same browse-and-see workflow, run `npx hydration-proof dev`. It opens the app with a hydration overlay that shows each page's findings, highlights the element and opens the source line in your editor ([dev overlay](https://hydration.jscrate.dev/docs/dev-overlay)).

## Sources

As of September 2026:

- [BuilderIO/hydration-overlay on GitHub](https://github.com/BuilderIO/hydration-overlay): README, setup, beta status and known false positives; about 530 stars
- [The package on npm](https://www.npmjs.com/package/@builder.io/react-hydration-overlay): version 0.3.0, published October 2024; 7,963 downloads in the week of September 10–16, 2026
- [hydration-proof: how it works](https://hydration.jscrate.dev/docs/how-it-works)

## Related

- [Next.js dev overlay compared](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay)
- [The hydration-proof dev overlay](https://hydration.jscrate.dev/docs/dev-overlay)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [All comparisons](https://hydration.jscrate.dev/docs/comparison)
- [Quick start](https://hydration.jscrate.dev/docs/quick-start)

---

# Sentry vs hydration-proof

> A Sentry hydration error issue shows what broke for real users after deploy. hydration-proof finds mismatches before deploy. How the two fit together.

Source: https://hydration.jscrate.dev/docs/compare/sentry-hydration-errors
Last updated: 2026-09-18

A Sentry hydration error issue tells you that hydration failed for real users in production, and with Session Replay attached it shows a diff of the page before and after hydration. hydration-proof finds mismatches before you deploy, by testing every route in a browser in CI. One observes, the other prevents, and they work well together.

## At a glance

|                                  | Sentry                                                             | hydration-proof                                           |
| -------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- |
| When                             | After deploy, in your users' browsers                              | Before deploy: locally and in CI                          |
| What it sees                     | Errors React reports on the pages people visit                     | Every tested route, in the scenarios you configure        |
| The diff                         | With Session Replay: HTML diff, tree compare and image comparisons | Server and client values of each differing element        |
| Real-world conditions            | Yes: real extensions, CDNs, data and devices                       | Simulated: locales, timezones, themes, viewports, storage |
| Mismatches React does not report | No error is raised to capture                                      | Reported (attribute mismatches in React 19 production)    |
| In your app                      | The Sentry SDK and, for the diff, Session Replay                   | Nothing                                                   |
| Cause                            | You infer it from the diff                                         | A likely cause, which `--probe` can prove                 |

## What the Sentry hydration error view does well

- **Real users, real conditions.** Sentry sees the extensions, CDN behavior, data and devices your users actually have, which no test environment fully reproduces.
- **A diff from production.** When a hydration error event has a replay, the issue page offers diff tools: an image slider, side-by-side images, a tree compare of added, removed and changed DOM nodes, and an HTML diff ([Sentry docs](https://docs.sentry.io/product/issues/issue-details/replay-issues/hydration-error/)).
- **Two ways in.** Hydration errors reach the issue stream as regular error events, or are detected inside a replay and turned into an issue.
- **Privacy by default.** Personal data on the page is masked or blocked before the replay is sent.

Sentry introduced the replay diff in January 2024; it needs Session Replay and a browser JavaScript SDK version 7.90.0 or later ([changelog](https://sentry.io/changelog/2024-1-5-diff-hydration-errors-with-replay)).

## Where hydration-proof differs

- **Before users see it.** A hydration error in Sentry has already happened to someone. hydration-proof fails the pull request instead ([CI](https://hydration.jscrate.dev/docs/ci)).
- **Every route, not only visited ones.** Sentry sees the pages people open, and replays only for sessions that were recorded. hydration-proof tests every discovered route in each configured [scenario](https://hydration.jscrate.dev/docs/scenarios).
- **Mismatches React does not report.** Sentry's hydration issues come from error events, or from errors detected in a replay. React 19 production builds do not report attribute mismatches at all, so no error is raised for a monitor to capture. hydration-proof compares every attribute with what React renders on the client.
- **Development builds too.** Sentry's docs note that "sometimes the diff Sentry shows doesn't contain any visible changes", a limitation of debugging React in production mode. hydration-proof can test the development build next to the production build (`--mode both`) to get React's full messages and exact source lines.
- **A cause.** Each finding comes with a likely cause and a fix, and [probes](https://hydration.jscrate.dev/docs/probes) prove the cause by changing one factor at a time.
- **Nothing in your bundle.** hydration-proof's runtime exists only in the test browser.

## Use both

They answer different questions: "will this deploy hydrate?" and "did it hydrate for our users?".

1. Run hydration-proof in CI, so known mismatches never ship:

   ```bash
   npx hydration-proof test --mode both
   ```

2. Keep Sentry in production for what tests cannot reproduce: a new browser extension, a CDN setting someone changed, data you never tested with.
3. When Sentry reports a hydration error on a route, add a [scenario](https://hydration.jscrate.dev/docs/scenarios) that reproduces its conditions (the locale, the timezone, the stored state), so hydration-proof catches it from then on.

## Sources

As of September 2026:

- [Sentry: Hydration Error](https://docs.sentry.io/product/issues/issue-details/replay-issues/hydration-error/), how hydration errors are detected, the diff tools and their limitations
- [Sentry changelog: Diff Hydration Errors with Replay](https://sentry.io/changelog/2024-1-5-diff-hydration-errors-with-replay), January 5, 2024, SDK 7.90.0 requirement
- [hydration-proof: how it works](https://hydration.jscrate.dev/docs/how-it-works)

## Related

- [Hydration errors only in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)
- [Scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios)
- [All comparisons](https://hydration.jscrate.dev/docs/comparison)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)

---

# eslint-plugin-react-hooks vs hydration-proof

> The eslint-plugin-react-hooks purity rule flags Date.now() and Math.random() in render. What it catches, what hydration needs beyond it, and how to run both.

Source: https://hydration.jscrate.dev/docs/compare/eslint-plugin-react-hooks
Last updated: 2026-09-18

The eslint-plugin-react-hooks purity rule reports calls to known impure functions, such as `Date.now()` and `Math.random()`, while a component renders. It protects re-renders and memoization. eslint-plugin-hydration-proof targets hydration: 15 rules for values that differ between the server and the browser, including code the purity rule accepts. The two overlap on the clock and random values, and run fine together.

## At a glance

|                                     | The purity rule                                                                   | eslint-plugin-hydration-proof                                                        |
| ----------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Goal                                | Components and hooks are pure, so re-renders and memoization are safe             | The server render and the hydration render produce the same output                   |
| Comes with                          | The `recommended` preset of eslint-plugin-react-hooks 7, and `eslint-config-next` | Its own `recommended`, `next` and `strict` presets                                   |
| Clock and random values             | `Date.now()`, `Math.random()`, `performance.now()` in 7.1.1                       | Those, plus `new Date()`, `crypto.randomUUID()`, uuid, nanoid, lodash and more       |
| Lazy `useState` initializers        | Accepted                                                                          | Reported: the initializer runs on the server and again during hydration              |
| Locale and timezone formatting      | Not checked                                                                       | `toLocaleString()`, `Intl.*` and date getters without an explicit locale or timezone |
| Browser APIs, storage, `matchMedia` | Not checked                                                                       | Reported in render and initial state                                                 |
| Invalid HTML nesting                | Not checked                                                                       | `<div>` in `<p>`, `<a>` in `<a>`, table structure                                    |
| `suppressHydrationWarning`          | Not checked                                                                       | Audited                                                                              |
| Server Components                   | No special handling                                                               | Skipped by the `next` preset, where the clock cannot cause a mismatch                |
| Message                             | Why the call is impure                                                            | What the server and the browser render, and the fix                                  |

## What the eslint-plugin-react-hooks purity rule does well

`react-hooks/purity` is one of the React Compiler's rules, now shipped in eslint-plugin-react-hooks. React's docs say it "validates that components/hooks are pure by checking that they do not call known-impure functions" ([purity](https://react.dev/reference/eslint-plugin-react-hooks/lints/purity)). It reports:

```text
Error: Cannot call impure function during render

`Date.now` is an impure function. Calling an impure function can produce unstable results that update unpredictably when the component happens to re-render.
```

- **It is on by default.** `purity` is in the `recommended` preset of eslint-plugin-react-hooks 7, and `eslint-config-next` includes that preset, so Next.js apps that use it already run the rule.
- **It sees data flow.** It runs the compiler's analysis, not a pattern match.
- **It covers more than hydration.** Impure renders break memoization and the React Compiler, not only server rendering. Its docs name hydration mismatches as one of the bugs impurity causes.

The React Compiler's lint rules used to live in a separate package, `eslint-plugin-react-compiler`. React's [Compiler 1.0 announcement](https://react.dev/blog/2025/10/07/react-compiler-1) says to remove it and use `eslint-plugin-react-hooks@latest` instead.

## Where hydration-proof differs

**Pure is not the same as hydration-safe.** Purity asks whether a render gives the same result every time it runs in one place. Hydration asks whether the server and the browser give the same result. The purity docs show this as the valid way to create an id:

```tsx title="components/item.tsx"
import { useState } from "react";

function Item() {
  // Stable across re-renders, so react-hooks/purity accepts it.
  // The server and the browser each run the initializer once, and get
  // different UUIDs: the hydration render does not match the server HTML.
  const [id] = useState(() => crypto.randomUUID());
  return <div id={id}>Content</div>;
}
```

eslint-plugin-hydration-proof reports it ([`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id)), because lazy initializers run during the first render on both sides. The same goes for `useState(() => Date.now())`, which the purity docs use for a clock: fine for re-renders, a guaranteed mismatch during hydration.

**More causes than the clock.** Many hydration mismatches never call an impure function:

- [`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale) and [`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone): formatting that depends on the machine;
- [`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render), [`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render), [`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) and [`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch): code that sees the browser;
- [`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting): HTML the browser repairs;
- [`require-stable-server-snapshot`](https://hydration.jscrate.dev/docs/rules/require-stable-server-snapshot) and [`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning).

**`new Date()`.** In eslint-plugin-react-hooks 7.1.1, the compiler marks `Date.now`, `Math.random` and `performance.now` as impure. A [reported gap](https://github.com/facebook/react/issues/37553) was that `new Date().getTime()` and `new Date().getFullYear()` were not flagged; the fix, which treats `new Date()` without arguments as impure, was merged on September 15, 2026 and is not in a stable release yet. [`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) reports `new Date()`, `Date()` and `Temporal.Now` today.

**Server Components.** With the `next` preset, eslint-plugin-hydration-proof skips Server Components, where reading the clock cannot cause a mismatch because the browser receives the result, not the code.

## Use both

Keep the purity rule for what it protects, and add eslint-plugin-hydration-proof for hydration:

```js title="eslint.config.mjs"
import { defineConfig } from "eslint/config";
import nextVitals from "eslint-config-next/core-web-vitals";
import hydrationProof from "eslint-plugin-hydration-proof";

export default defineConfig([...nextVitals, hydrationProof.configs.next]);
```

A `Date.now()` or `Math.random()` in render is then reported twice, once by each plugin, with different reasons. Keep both reports, or turn one of the overlapping rules off. The [ESLint plugin guide](https://hydration.jscrate.dev/docs/eslint) covers presets and settings.

```bash
npm install -D eslint-plugin-hydration-proof
```

A linter reads one file at a time. Values passed through props or context, nesting across components, CSS-in-JS and anything that happens outside your code need `hydration-proof test`, which checks the running app.

## Sources

As of September 2026:

- [react.dev: purity](https://react.dev/reference/eslint-plugin-react-hooks/lints/purity) and [eslint-plugin-react-hooks](https://react.dev/reference/eslint-plugin-react-hooks), the rule and the `recommended` preset
- [eslint-plugin-react-hooks 7.1.1 on npm](https://www.npmjs.com/package/eslint-plugin-react-hooks), the message text and the impure functions in its source
- [facebook/react#37553](https://github.com/facebook/react/issues/37553) and [facebook/react#37576](https://github.com/facebook/react/pull/37576), `new Date()` in the purity rule
- [Next.js: ESLint plugin](https://nextjs.org/docs/app/api-reference/config/eslint), `eslint-config-next` includes the `recommended` rules of eslint-plugin-react-hooks
- [React Compiler 1.0](https://react.dev/blog/2025/10/07/react-compiler-1), `eslint-plugin-react-compiler` replaced by eslint-plugin-react-hooks

## Related

- [All eslint-plugin-hydration-proof rules](https://hydration.jscrate.dev/docs/rules)
- [Getting started with the ESLint plugin](https://hydration.jscrate.dev/docs/eslint)
- [Date and time hydration errors](https://hydration.jscrate.dev/docs/causes/time)
- [Random values and hydration](https://hydration.jscrate.dev/docs/causes/random)
- [eslint-plugin-validate-jsx-nesting compared](https://hydration.jscrate.dev/docs/compare/eslint-plugin-validate-jsx-nesting)

---

# eslint-plugin-validate-jsx-nesting vs hydration-proof

> The ESLint no-invalid-jsx-nesting rule checks direct parent and child tags. What it catches, what it misses, and how hydration-proof's nesting rule differs.

Source: https://hydration.jscrate.dev/docs/compare/eslint-plugin-validate-jsx-nesting
Last updated: 2026-09-18

The ESLint no-invalid-jsx-nesting rule, from eslint-plugin-validate-jsx-nesting, reports HTML nesting the browser would repair, such as a `<p>` inside a `<p>`, when the child tag is written directly inside the parent. hydration-proof's `no-invalid-interactive-nesting` looks through fragments, conditions and lists and at any depth, and explains the hydration error each case causes.

## At a glance

|                                                                         | `no-invalid-jsx-nesting`                                        | `no-invalid-interactive-nesting`                                 |
| ----------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
| Checks                                                                  | A tag and its direct parent tag                                 | A tag and every enclosing tag in the same component              |
| Through fragments, `&&`, `? :`, arrays, `.map()`                        | No                                                              | Yes                                                              |
| `<div>` inside `<span>` inside `<p>`                                    | Not reported                                                    | Reported                                                         |
| `<a>` in `<a>`, `<button>` in `<button>`, `<form>` in `<form>`          | Direct children                                                 | At any depth                                                     |
| Interactive content in `<a>` or `<button>`                              | Not checked                                                     | `input`, `select`, `textarea`, `label`, `iframe` and more        |
| Table structure                                                         | `<tr>` outside a table section, `<td>` outside `<tr>`, and more | `<tr>` directly in `<table>`, `<td>` directly in a table section |
| Headings in headings, `<li>` in `<li>`, `<select>` and `<head>` content | Checked                                                         | Not checked                                                      |
| Across components                                                       | No                                                              | No; `hydration-proof test` finds those                           |
| Server Components                                                       | Checked                                                         | Checked, even with the `next` preset                             |
| Message                                                                 | `Invalid HTML nesting: <div> can not be child of <p>`           | What the parser does and how hydration fails                     |
| Latest release                                                          | 0.1.1, April 2023                                               | 1.0                                                              |

eslint-plugin-react, the other common React linter, has no rule for DOM nesting.

## What ESLint no-invalid-jsx-nesting does well

The plugin has one rule and does it simply:

- **A broad list of content rules.** It uses the validate-html-nesting library, which knows the only valid children of `<table>`, `<tr>`, `<select>`, `<head>` and `<colgroup>`, elements such as `<textarea>` and `<option>` that take no element children, and pairs like a heading in a heading or `<li>` in `<li>`. Some of these are outside what hydration-proof's rule checks.
- **Framework agnostic.** It works on any JSX, not only React.
- **Small.** Its only dependency is validate-html-nesting.

It has about 42,000 weekly downloads on npm.

## Where hydration-proof differs

**It looks past the direct parent.** `no-invalid-jsx-nesting` compares a tag with its parent only when both are HTML tags written next to each other. These all break hydration and are not reported by it:

```tsx title="components/intro.tsx"
export function Intro({
  items,
  showMore,
}: {
  items: string[];
  showMore: boolean;
}) {
  return (
    <p>
      Welcome.
      {/* Inside a condition: the parent of <div> is not the <p> tag. */}
      {showMore && <div>Read more below.</div>}
      {/* One level deeper: the browser still closes the <p>. */}
      <span>
        <ul>
          {items.map((item) => (
            <li key={item}>{item}</li>
          ))}
        </ul>
      </span>
    </p>
  );
}
```

`no-invalid-interactive-nesting` follows fragments, `&&`, `? :`, arrays and `.map()` callbacks, and walks every enclosing tag in the component, stopping where the HTML parser would. It reports both cases above.

**It covers interactive content.** A `<button>`, `<input>` or `<select>` inside a link, or a link inside a button, is reported with the reason. See [HP3002](https://hydration.jscrate.dev/docs/issues/hp3002) for what the CLI reports.

**It explains the hydration error.** Each message says what the browser does with the markup and how that breaks hydration, for example that the browser closes the `<p>` before the `<div>`, so the DOM no longer matches what React rendered.

**It is part of a hydration rule set.** The same plugin has 14 more rules for the clock, random values, locale, timezone, storage and browser APIs ([all rules](https://hydration.jscrate.dev/docs/rules)).

Neither linter sees nesting across components: `<p><Card /></p>` where `Card` renders a `<div>`. `hydration-proof test` checks the real server HTML with React's own nesting rules and reports it as [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001), with the line in the server HTML.

## Use both

They overlap on the common cases, like a `<div>` written directly inside a `<p>`, which then gets two reports. Each also catches something the other does not, so running both is reasonable:

```js title="eslint.config.js"
import hydrationProof from "eslint-plugin-hydration-proof";
import validateJsxNesting from "eslint-plugin-validate-jsx-nesting";

export default [
  hydrationProof.configs.recommended,
  {
    plugins: { "validate-jsx-nesting": validateJsxNesting },
    rules: { "validate-jsx-nesting/no-invalid-jsx-nesting": "error" },
  },
];
```

```bash
npm install -D eslint-plugin-hydration-proof eslint-plugin-validate-jsx-nesting
```

## Sources

As of September 2026:

- [The plugin's repository on GitHub](https://github.com/MananTank/eslint-plugin-validate-jsx-nesting), README and rule source (version 0.1.1)
- [The package on npm](https://www.npmjs.com/package/eslint-plugin-validate-jsx-nesting): 41,962 downloads in the week of September 10–16, 2026; last published April 23, 2023
- [eslint-plugin-react rules](https://github.com/jsx-eslint/eslint-plugin-react#list-of-supported-rules), no DOM nesting rule
- [`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)

## Related

- [no-invalid-interactive-nesting](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
- [div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p)
- [Invalid HTML nesting and hydration](https://hydration.jscrate.dev/docs/causes/invalid-html)
- [validateDOMNesting warnings](https://hydration.jscrate.dev/docs/errors/validatedomnesting)
- [eslint-plugin-react-hooks purity compared](https://hydration.jscrate.dev/docs/compare/eslint-plugin-react-hooks)

---

# Issue codes

> The hydration-proof issue codes: what each HP code means, its default severity, how to fix it and how to ignore it, from HP1001 text mismatches to HP9010.

Source: https://hydration.jscrate.dev/docs/issues
Last updated: 2026-09-18

Every finding carries one of the hydration-proof issue codes: `HP1001` for text
that differs between server and client, `HP3001` for invalid HTML nesting, and
so on. A code never changes meaning, so you can use it in ignore rules,
baselines and budgets. Each code below links to a page with its causes and
fixes.

## How to read a code

The first digit is the group. Each code also has a kebab-case name
(`text-mismatch`) that is as stable as the code itself.

| Codes  | Group                          | What went wrong                                                             |
| ------ | ------------------------------ | --------------------------------------------------------------------------- |
| HP1xxx | DOM mismatches                 | The server HTML and the first client render differ                          |
| HP2xxx | Problems React reported        | React logged an error or warning no DOM finding explains, or a script threw |
| HP3xxx | Markup the browser repaired    | The HTML parser rewrote invalid markup, or ids collide                      |
| HP4xxx | Changes made outside React     | A script, extension, CDN or proxy changed the page                          |
| HP5xxx | Interaction during hydration   | Input, clicks, focus, scroll or navigation broke while the page hydrated    |
| HP6xxx | suppressHydrationWarning audit | What `suppressHydrationWarning` hides, or fails to hide                     |
| HP9xxx | Test run problems              | The page could not be tested properly                                       |

The code shows up everywhere a finding does: the terminal, `report.json`, the
HTML report, the SARIF rule id, the JUnit failure type and the GitLab
`check_name`. See [report formats](https://hydration.jscrate.dev/docs/reports) for each one.

## Severity and --fail-on

Every code has a default severity. It decides whether the run fails:

| Severity  | Terminal                                  | Fails the run                                |
| --------- | ----------------------------------------- | -------------------------------------------- |
| `error`   | Listed, the page is marked failed         | By default                                   |
| `warning` | Listed, the page is marked with a warning | With `--fail-on warning` or `--fail-on info` |
| `info`    | Not listed; in the JSON and HTML reports  | Only with `--fail-on info`                   |

`--fail-on never` (or `ci.failOn: 'never'`) never fails the run, and
`ci.maxWarnings` fails it when there are more warnings than you allow. A
finding's severity is usually its code's default; a few are raised or lowered.
For example, a difference hidden by `suppressHydrationWarning` that does not
look intentional is a warning instead of info. Budgets per severity, route or
code are covered in [baselines and budgets](https://hydration.jscrate.dev/docs/baselines).

## Ignore a code

Ignored findings stay in the report, marked as ignored, and do not fail the
run. A rule needs a reason, and an expiry date keeps a temporary exception from
becoming permanent: once it passes, the finding fails the run again.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    issues: [
      {
        code: "HP1004",
        route: "/legacy/**",
        reason: "Old theme system",
        expires: "2026-12-31",
      },
    ],
  },
});
```

A rule can match a `code`, a `route` glob, a `selector` or a `fingerprint`.
[Ignoring findings](https://hydration.jscrate.dev/docs/ignoring) covers selectors, attributes and text
patterns as well.

## Fingerprints

Every finding also has a fingerprint. It stays the same across runs as long as
the problem is the same: same code, route pattern, element and attribute.
Ignore rules and baselines match on it, and the SARIF report passes it to code
scanning, so an alert is recognized from one run to the next.

## DOM mismatches

The server HTML and the first client render differ: text, attributes, inline
styles, class names, elements, whitespace, form state or the document head. It
also covers the branches React threw away and rendered again on the client.

| Code | Title | Severity |
| --- | --- | --- |
| [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) | Text differs between server and client | Error |
| [HP1002](https://hydration.jscrate.dev/docs/issues/hp1002) | Attribute differs between server and client | Error |
| [HP1003](https://hydration.jscrate.dev/docs/issues/hp1003) | Inline style differs between server and client | Error |
| [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) | Class name differs between server and client | Error |
| [HP1005](https://hydration.jscrate.dev/docs/issues/hp1005) | Attribute only present in the server HTML | Warning |
| [HP1006](https://hydration.jscrate.dev/docs/issues/hp1006) | Attribute missing from the server HTML | Error |
| [HP1007](https://hydration.jscrate.dev/docs/issues/hp1007) | Different element rendered on server and client | Error |
| [HP1008](https://hydration.jscrate.dev/docs/issues/hp1008) | Element only present in the server HTML | Error |
| [HP1009](https://hydration.jscrate.dev/docs/issues/hp1009) | Element missing from the server HTML | Error |
| [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) | React discarded server HTML and rendered a branch again | Error |
| [HP1011](https://hydration.jscrate.dev/docs/issues/hp1011) | React discarded the whole server-rendered page | Error |
| [HP1012](https://hydration.jscrate.dev/docs/issues/hp1012) | Form state differs between server and client | Warning |
| [HP1013](https://hydration.jscrate.dev/docs/issues/hp1013) | dangerouslySetInnerHTML differs between server and client | Error |
| [HP1014](https://hydration.jscrate.dev/docs/issues/hp1014) | Document head differs between server and client | Warning |
| [HP1015](https://hydration.jscrate.dev/docs/issues/hp1015) | Whitespace differs between server and client | Error |

## Problems React reported

Errors and warnings React logged itself. When a DOM finding explains them,
React's message is attached to that finding as evidence instead; these codes
are for the reports nothing else explains, and for page errors.

| Code | Title | Severity |
| --- | --- | --- |
| [HP2001](https://hydration.jscrate.dev/docs/issues/hp2001) | React reported a hydration error | Error |
| [HP2002](https://hydration.jscrate.dev/docs/issues/hp2002) | React warned about a hydration mismatch | Warning |
| [HP2003](https://hydration.jscrate.dev/docs/issues/hp2003) | A Suspense boundary switched to client rendering | Error |
| [HP2004](https://hydration.jscrate.dev/docs/issues/hp2004) | The root switched to client rendering | Error |
| [HP2005](https://hydration.jscrate.dev/docs/issues/hp2005) | An update arrived before hydration finished | Warning |
| [HP2006](https://hydration.jscrate.dev/docs/issues/hp2006) | The server could not finish rendering a boundary | Error |
| [HP2007](https://hydration.jscrate.dev/docs/issues/hp2007) | Uncaught error while loading the page | Warning |

## Markup the browser repaired

Nesting the HTML parser rewrites before React hydrates, nested interactive
elements, duplicate ids and `useId` collisions between React roots.

| Code | Title | Severity |
| --- | --- | --- |
| [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001) | Invalid HTML nesting | Error |
| [HP3002](https://hydration.jscrate.dev/docs/issues/hp3002) | Interactive element nested in another | Error |
| [HP3003](https://hydration.jscrate.dev/docs/issues/hp3003) | Duplicate id attribute | Info |
| [HP3004](https://hydration.jscrate.dev/docs/issues/hp3004) | Two React roots generate the same ids | Warning |

## Changes made outside React

Scripts, browser extensions, CDNs and proxies that changed the page before
React hydrated it.

| Code | Title | Severity |
| --- | --- | --- |
| [HP4001](https://hydration.jscrate.dev/docs/issues/hp4001) | The page was modified before React hydrated | Error |
| [HP4002](https://hydration.jscrate.dev/docs/issues/hp4002) | A browser extension changed the page | Info |
| [HP4003](https://hydration.jscrate.dev/docs/issues/hp4003) | HTML was rewritten between the server and the browser | Error |

## Interaction during hydration

What a user does before the page is interactive, and client-side navigation
compared with a direct load. Most of these need `checks.interactions` or
`checks.navigation`.

| Code | Title | Severity |
| --- | --- | --- |
| [HP5001](https://hydration.jscrate.dev/docs/issues/hp5001) | An interaction before hydration was lost | Warning |
| [HP5002](https://hydration.jscrate.dev/docs/issues/hp5002) | User input was reset during hydration | Error |
| [HP5003](https://hydration.jscrate.dev/docs/issues/hp5003) | Focus was lost during hydration | Warning |
| [HP5004](https://hydration.jscrate.dev/docs/issues/hp5004) | The page differs after client-side navigation | Warning |
| [HP5005](https://hydration.jscrate.dev/docs/issues/hp5005) | Client-side navigation failed | Error |
| [HP5006](https://hydration.jscrate.dev/docs/issues/hp5006) | An element handles the same event twice | Warning |
| [HP5007](https://hydration.jscrate.dev/docs/issues/hp5007) | Scroll position was reset during hydration | Warning |
| [HP5008](https://hydration.jscrate.dev/docs/issues/hp5008) | A custom interaction failed | Error |

## suppressHydrationWarning audit

Differences that `suppressHydrationWarning` hides, structural differences it
cannot hide, and suppressions with nothing to suppress.

| Code | Title | Severity |
| --- | --- | --- |
| [HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) | Mismatch hidden by suppressHydrationWarning | Info |
| [HP6002](https://hydration.jscrate.dev/docs/issues/hp6002) | suppressHydrationWarning cannot hide a structural difference | Error |
| [HP6003](https://hydration.jscrate.dev/docs/issues/hp6003) | suppressHydrationWarning with nothing to suppress | Info |

## Test run problems

The page did not load, React never hydrated, or the page never settled.

| Code | Title | Severity |
| --- | --- | --- |
| [HP9001](https://hydration.jscrate.dev/docs/issues/hp9001) | Hydration did not finish in time | Error |
| [HP9002](https://hydration.jscrate.dev/docs/issues/hp9002) | No React found on the page | Warning |
| [HP9003](https://hydration.jscrate.dev/docs/issues/hp9003) | The page is rendered on the client only | Info |
| [HP9004](https://hydration.jscrate.dev/docs/issues/hp9004) | The page could not be loaded | Error |
| [HP9005](https://hydration.jscrate.dev/docs/issues/hp9005) | The server answered with an error status | Error |
| [HP9006](https://hydration.jscrate.dev/docs/issues/hp9006) | The server HTML could not be captured | Warning |
| [HP9007](https://hydration.jscrate.dev/docs/issues/hp9007) | Some capture data was dropped | Warning |
| [HP9008](https://hydration.jscrate.dev/docs/issues/hp9008) | React loaded but never mounted a root | Warning |
| [HP9009](https://hydration.jscrate.dev/docs/issues/hp9009) | The page never became quiet | Warning |
| [HP9010](https://hydration.jscrate.dev/docs/issues/hp9010) | The route redirected somewhere else | Warning |

## Related

- [Common causes of hydration errors](https://hydration.jscrate.dev/docs/causes), with a fix for each
- [React hydration error messages](https://hydration.jscrate.dev/docs/errors), decoded
- [Ignoring findings](https://hydration.jscrate.dev/docs/ignoring) on purpose
- [How hydration-proof works](https://hydration.jscrate.dev/docs/how-it-works): which comparison finds what
- [Detect hydration errors in CI](https://hydration.jscrate.dev/docs/ci)

---

# HP1001: Text differs between server and client

> HP1001 (text mismatch) means the server HTML has different text than React rendered in the browser. The likely causes, the fix for each, and an example.

Source: https://hydration.jscrate.dev/docs/issues/hp1001
Last updated: 2026-09-18

HP1001 (`text-mismatch`) means the text in the server HTML differs from the
text React rendered in the browser's first render. The finding gives both
values, the element and, in development builds, the line that rendered it.
Find what that component reads that differs between the two renders (the
clock, the locale, browser storage) and make it the same.

| | |
| --- | --- |
| Code | `HP1001` |
| Name | `text-mismatch` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | The server HTML contains different text than the browser rendered during hydration. |

## What HP1001 (`text-mismatch`) means

React expects the first client render to produce exactly the text the server
sent. When a text node differs, React discards the server HTML up to the
nearest Suspense boundary and renders that part again on the client, which is
slower and resets state.

hydration-proof finds the difference in two ways:

- It compares the DOM right before and inside the hydration commit, which shows
  the text React replaced.
- It compares the server text of every element React reused with the text
  React renders for it, which also catches text React left in place.

When the text sits inside a branch React re-rendered, the finding says so in
its evidence ("React discarded the server HTML of `<section>` and rendered it
again on the client"), and no separate [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) is
reported. If only whitespace differs, the code is
[HP1015](https://hydration.jscrate.dev/docs/issues/hp1015) instead.

## The React error it matches

In a development build, React usually reports the same problem, and
hydration-proof attaches React's message to the finding as evidence. These are
the messages for a text difference:

```text
Hydration failed because the server rendered text didn't match the client.
Text content does not match server-rendered HTML.
Warning: Text content did not match. Server: "5:00 AM" Client: "10:00 AM"
Minified React error #418; visit https://react.dev/errors/418
```

[Text content does not match server-rendered HTML](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
covers the React 18 wording, and
[the server rendered HTML didn't match the client](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)
the React 19 one.

## Likely causes

Each finding names its most likely cause with a confidence score. These are
the causes behind HP1001 in the package's own test pages:

| Cause                                              | What differs                                                |
| -------------------------------------------------- | ----------------------------------------------------------- |
| [Time-dependent value](https://hydration.jscrate.dev/docs/causes/time)          | `Date.now()` or `new Date()` read during render             |
| [Timezone difference](https://hydration.jscrate.dev/docs/causes/timezone)       | A date formatted in the server's and the browser's timezone |
| [Locale-dependent formatting](https://hydration.jscrate.dev/docs/causes/locale) | `toLocaleString()` with the runtime's default locale        |
| [Random value](https://hydration.jscrate.dev/docs/causes/random)                | `Math.random()` or `crypto.randomUUID()` in render          |
| [Browser storage](https://hydration.jscrate.dev/docs/causes/storage)            | `localStorage` read behind a `typeof window` check          |
| [Media query](https://hydration.jscrate.dev/docs/causes/media-query)            | `matchMedia` or the window size read during render          |
| [Browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api)       | `navigator.userAgent` and other browser globals             |
| [Different data](https://hydration.jscrate.dev/docs/causes/data)                | The client fetched the data again and got a new result      |

## How to fix it

- Render exactly the same text on the server and in the first client render.
- Move browser-only or time-dependent values into `useEffect`, or compute them
  on the server and pass them down as props.

For example, a greeting that reads `localStorage` renders "guest" on the server
and the stored name in the browser:

```tsx title="welcome.tsx"
"use client";

export function Welcome() {
  const name =
    typeof window === "undefined"
      ? "guest"
      : (localStorage.getItem("name") ?? "guest");

  return <p>Welcome back, {name}</p>;
}
```

Render the value both sides agree on first, and read storage after hydration:

```tsx title="welcome.tsx"
"use client";

import { useEffect, useState } from "react";

export function Welcome() {
  const [name, setName] = useState("guest");

  useEffect(() => {
    setName(localStorage.getItem("name") ?? "guest");
  }, []);

  return <p>Welcome back, {name}</p>;
}
```

The cause page for your finding has the fix that fits it: pass the server's
time as a prop, pass an explicit locale and `timeZone`, or send the data the
server rendered with. `hydration-proof test --probe` reloads the page with one
factor changed at a time (clock, random seed, locale, timezone, theme,
viewport, storage) and turns the likely cause into a proven one; see
[probes](https://hydration.jscrate.dev/docs/probes).

## Prevent it with ESLint

The ESLint plugin reports the usual sources in render code:
[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render),
[`no-random-in-render`](https://hydration.jscrate.dev/docs/rules/no-random-in-render),
[`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale),
[`no-timezone-without-explicit-timezone`](https://hydration.jscrate.dev/docs/rules/no-timezone-without-explicit-timezone),
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render) and
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch).

## When the difference is intentional

For a value that is meant to differ, such as a live clock, put
`suppressHydrationWarning` on the element that holds it: React keeps the server
text, and hydration-proof lists the difference as
[HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) (info) instead. `ignore.textPatterns` ignores a
text difference when both values are equal after removing the patterns, for
example `/\d{2}:\d{2}/` for times. See [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ✖ /status 842ms  1 error
    HP1001 Text differs between server and client  (time-dependent value, 97%)
      #rendered-at  in RenderedAt
      server: "Rendered at 1767225600000"
      client: "Rendered at 1767225600412"
      app/status/rendered-at.tsx:4:10
      → The server and the browser render at different moments. Pass the timestamp the server used as a prop, or render the time after mount (useEffect).
```

The last line is the fix for the likely cause. The HTML report adds the code
around that line, React's message and a screenshot with the element outlined.

## Related

- [Fix date and time hydration errors](https://hydration.jscrate.dev/docs/causes/time)
- [HP1002: an attribute differs](https://hydration.jscrate.dev/docs/issues/hp1002)
- [HP1015: only whitespace differs](https://hydration.jscrate.dev/docs/issues/hp1015)
- [When suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [All issue codes](https://hydration.jscrate.dev/docs/issues)

---

# HP1002: Attribute differs between server and client

> HP1002 (attribute mismatch): an attribute has one value in the server HTML and another in React's client render, and React never fixes it. Causes and fixes.

Source: https://hydration.jscrate.dev/docs/issues/hp1002
Last updated: 2026-09-18

HP1002 (`attribute-mismatch`) means an attribute such as `href`, `id` or
`data-*` has one value in the server HTML and another in the props React
renders on the client. React does not patch attributes during hydration, so
users keep the server value. Compute the attribute from data both sides share.

| | |
| --- | --- |
| Code | `HP1002` |
| Name | `attribute-mismatch` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | An attribute value in the server HTML differs from the value React rendered on the client. React does not patch attributes during hydration. |

## What HP1002 (`attribute-mismatch`) means

The element exists on both sides and React reuses it, but one attribute
differs. React keeps whatever the server sent until the element re-renders for
another reason: a link keeps pointing at the server's URL, an `aria-*` value
stays wrong, a `datetime` stays stale.

Attribute codes are split by what differs:

| Difference                           | Code                          |
| ------------------------------------ | ----------------------------- |
| A value on both sides, but different | HP1002                        |
| `style`                              | [HP1003](https://hydration.jscrate.dev/docs/issues/hp1003) |
| `class`                              | [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) |
| Only in the server HTML              | [HP1005](https://hydration.jscrate.dev/docs/issues/hp1005) |
| Only in React's client render        | [HP1006](https://hydration.jscrate.dev/docs/issues/hp1006) |

hydration-proof compares every attribute React reused with the props React
renders for that element, so it finds attribute mismatches in production
builds, where React 19 reports nothing. Boolean attributes such as `disabled`
and `hidden` are compared by presence. An attribute that changes during the
hydration commit, for example from a layout effect, is an update and not a
mismatch, so it is not reported.

## The React error it matches

Only development builds report it:

```text
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
Warning: Prop `href` did not match. Server: "/pricing?region=eu-west" Client: "/pricing?region=us-east"
```

The first is React 19, the second React 18. See
[attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)
and [Prop `className` did not match](https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match)
for the React 18 warning, which names the prop that differs.

## Likely causes

- A `typeof window` branch or another [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api)
  in the value, like the package's `/attr-mismatch` test page, which builds an
  `href` from a region that differs on each side.
- The [theme](https://hydration.jscrate.dev/docs/causes/theme): an SVG `fill` chosen with
  `prefers-color-scheme`, as on the `/svg-attr` test page.
- A [generated id](https://hydration.jscrate.dev/docs/causes/unstable-id) from a counter or a random value
  in `id`, `for` or `aria-*` attributes.
- A [time-dependent value](https://hydration.jscrate.dev/docs/causes/time) in `datetime` or `title`, or a
  [random value](https://hydration.jscrate.dev/docs/causes/random) anywhere.

## How to fix it

- Compute the attribute from data that is identical on the server and the
  client.
- React does not fix attributes during hydration, so users keep seeing the
  server value until the next update.

Here the server and the browser pick a different region:

```tsx title="pricing-link.tsx"
"use client";

export function PricingLink() {
  const region = typeof window === "undefined" ? "eu-west" : "us-east";
  return <a href={`/pricing?region=${region}`}>See pricing</a>;
}
```

Decide the value once, on the server (from a cookie, a header or the route),
and pass it down, so both renders use the same string:

```tsx title="pricing-link.tsx"
export function PricingLink({ region }: { region: string }) {
  return <a href={`/pricing?region=${region}`}>See pricing</a>;
}
```

For ids, use `useId` instead of counters or random values.

## Prevent it with ESLint

[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) reports
server/browser branches in render code,
[`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render)
browser globals, and [`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) ids built
from random values, the clock or counters.

## When the difference is intentional

`suppressHydrationWarning` covers an element's own attributes: React keeps the
server value, and hydration-proof lists it as [HP6001](https://hydration.jscrate.dev/docs/issues/hp6001)
(info). To stop comparing an attribute everywhere (tracking attributes, for
example), list it in `ignore.attributes`. See
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ✖ /pricing 1.2s  1 error
    HP1002 Attribute differs between server and client  (browser-only api used during render, 59%)
      #pricing-link  in PricingLink
      attribute: href
      server: "/pricing?region=eu-west"
      client: "/pricing?region=us-east"
      components/pricing-link.tsx:5:10
      → Code like `typeof window !== "undefined"` or window/navigator/document access renders differently on the server. Read browser values in useEffect, or render the component on the client only.
```

## Related

- [HP1001: text differs](https://hydration.jscrate.dev/docs/issues/hp1001)
- [HP1003: inline style differs](https://hydration.jscrate.dev/docs/issues/hp1003)
- [HP1004: class name differs](https://hydration.jscrate.dev/docs/issues/hp1004)
- [Why some errors only appear in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)
- [Browser-only APIs during render](https://hydration.jscrate.dev/docs/causes/browser-api)

---

# HP1003: Inline style differs between server and client

> HP1003 (style mismatch): the style attribute in the server HTML differs from the inline style React applies on the client, and React keeps the server's.

Source: https://hydration.jscrate.dev/docs/issues/hp1003
Last updated: 2026-09-18

HP1003 (`style-mismatch`) means the `style` attribute in the server HTML
differs from the inline style React renders on the client. React does not patch
it during hydration, so the element keeps the server's position, size or color.
Make inline styles depend only on data both sides have, or apply them after
mount.

| | |
| --- | --- |
| Code | `HP1003` |
| Name | `style-mismatch` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | The style attribute rendered on the server differs from the style React applies on the client. |

## What HP1003 (`style-mismatch`) means

The element exists on both sides, but its `style` prop produced different
declarations. Styles are compared as parsed declarations, so formatting alone
never counts: only a property whose value differs, or that exists on one side
only.

React 19 reports nothing about it in production, and the page keeps the server
style until the element re-renders. hydration-proof compares the style React
renders for every reused element with the one in the server HTML, so it finds
the difference in production builds too.

Styles written after hydration are not mismatches. A `useLayoutEffect` that
sets `element.style.top` changes the element during the hydration commit, and
hydration-proof treats that as an update, not as HP1003.

## The React error it matches

Only development builds report it:

```text
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
Warning: Prop `style` did not match.
```

See [attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)
for the React 19 message.

## Likely causes

- A position or size computed from the window, behind a `typeof window` check:
  a [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api). The package's
  `/style-mismatch` test page sets `top` to `8px` on the server and `24px` in
  the browser this way.
- A [media query or the window size](https://hydration.jscrate.dev/docs/causes/media-query) read during
  render.
- A value restored from [browser storage](https://hydration.jscrate.dev/docs/causes/storage), such as a
  saved panel width.
- A [random value](https://hydration.jscrate.dev/docs/causes/random), such as a generated color.

## How to fix it

- Make inline styles depend only on data available on both server and client,
  or apply them after mount.

A layout decided from the window size differs as soon as the browser is not
the size the server assumed:

```tsx title="banner.tsx"
"use client";

export function Banner() {
  const top = typeof window !== "undefined" && window.innerWidth > 600 ? 24 : 8;

  return <div style={{ position: "absolute", top }}>Banner</div>;
}
```

Let CSS decide instead. Both renders produce the same markup, and the browser
applies the right value:

```tsx title="banner.tsx"
export function Banner() {
  return <div className="banner">Banner</div>;
}
```

```css title="banner.css"
.banner {
  position: absolute;
  top: 8px;
}

@media (min-width: 601px) {
  .banner {
    top: 24px;
  }
}
```

When the value has to come from JavaScript (a measured height, a drag
position), render a neutral style first and set the real one in an effect.

## Prevent it with ESLint

[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render),
[`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render) and
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) report the
reads that make a style differ.

## When the difference is intentional

`suppressHydrationWarning` on the element keeps the server style without a
warning, and hydration-proof lists the difference as
[HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) (info). To skip an element entirely, add
`data-hydration-proof-ignore` or a selector in `ignore.selectors`; see
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ✖ /home 1.0s  1 error
    HP1003 Inline style differs between server and client  (screen size or media query read during render, 84%)
      #banner  in Banner
      attribute: style
      server: "position: absolute; top: 8px;"
      client: "position: absolute; top: 24px;"
      components/banner.tsx:6:10
      → Use CSS media queries for layout differences, or read matchMedia / window size after mount.
```

## Related

- [HP1002: attribute differs](https://hydration.jscrate.dev/docs/issues/hp1002)
- [HP1004: class name differs](https://hydration.jscrate.dev/docs/issues/hp1004)
- [Screen size and media queries during render](https://hydration.jscrate.dev/docs/causes/media-query)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)

---

# HP1004: Class name differs between server and client

> HP1004 (class mismatch): the class attribute in the server HTML differs from React's className, often a theme or CSS-in-JS. The page keeps the server classes.

Source: https://hydration.jscrate.dev/docs/issues/hp1004
Last updated: 2026-09-18

HP1004 (`class-mismatch`) means the `class` attribute in the server HTML
differs from the `className` React renders on the client. React keeps the
server classes, so the page shows the wrong theme or styles until the element
re-renders. The usual causes are a dark mode check during render and CSS-in-JS
class names generated in a different order.

| | |
| --- | --- |
| Code | `HP1004` |
| Name | `class-mismatch` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | The class attribute rendered on the server differs from the className React renders on the client. The page keeps the server classes. |

## What HP1004 (`class-mismatch`) means

The element exists on both sides, but the set of class names differs. Classes
are compared as a set, so the same names in another order do not count.

React does not patch attributes during hydration. In production, React 19
reports nothing and leaves the server classes in place: a user who prefers dark
mode keeps the light theme. hydration-proof compares every reused
element's classes with the `className` React renders, so it finds this in
production builds too.

## The React error it matches

Only development builds report it:

```text
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
Warning: Prop `className` did not match. Server: "theme-light" Client: "theme-dark"
```

The first is React 19, the second React 18. See
[Prop `className` did not match](https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match) and
[attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match).

## Likely causes

- The [theme](https://hydration.jscrate.dev/docs/causes/theme): the server cannot know the color scheme, so
  a class chosen with `prefers-color-scheme` or a stored preference differs.
  The package's `/dark-mode` test page is found this way.
- [CSS-in-JS class names](https://hydration.jscrate.dev/docs/causes/css-in-js): the library generates class
  names from a counter, and a styled component created on one side only (or
  without the library's server setup) shifts it. The `/css-in-js` test page
  creates one styled component only on the server.
- A [media query](https://hydration.jscrate.dev/docs/causes/media-query) or
  [browser storage](https://hydration.jscrate.dev/docs/causes/storage) read during render.

## How to fix it

- Make class names deterministic between server and client.
- For themes, read the preference on the server (for example from a cookie) or
  set the class with a pre-hydration script and `suppressHydrationWarning` on
  that element.
- For CSS-in-JS, set up the library's server style registry so class names are
  generated in the same order.

A theme read from the browser during render:

```tsx title="theme-preview.tsx"
"use client";

export function ThemePreview() {
  const dark =
    typeof window !== "undefined" &&
    window.matchMedia("(prefers-color-scheme: dark)").matches;

  return <div className={dark ? "theme-dark" : "theme-light"}>Preview</div>;
}
```

Store the theme in a cookie and read it on the server, so the first render
already has the right class (Next.js App Router shown):

```tsx title="app/layout.tsx"
import { cookies } from "next/headers";
import type { ReactNode } from "react";

export default async function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  const theme = (await cookies()).get("theme")?.value ?? "light";

  return (
    <html lang="en" className={theme}>
      <body>{children}</body>
    </html>
  );
}
```

Without a cookie (the first visit), set the class on `<html>` with a small
inline script that runs before hydration, and mark `<html>` with
`suppressHydrationWarning`. The difference is then listed as
[HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) (info), not as an error. See the
[theme cause](https://hydration.jscrate.dev/docs/causes/theme) for the details, and the
[CSS-in-JS cause](https://hydration.jscrate.dev/docs/causes/css-in-js) for the style registry.

## Prevent it with ESLint

[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) reports
`matchMedia` in render code, including the color scheme query, and
[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render) a
theme read from storage.

## When the difference is intentional

A theme class set by a pre-hydration script is the case
`suppressHydrationWarning` exists for. For a legacy area you cannot fix yet,
add an `ignore.issues` rule with `code: "HP1004"`, a route, a reason and an
expiry date; see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ✖ /settings 687ms  1 error
    HP1004 Class name differs between server and client  (theme preference (dark/light mode), 99%)
      #theme  in ThemePreview
      attribute: class
      server: "theme-light"
      client: "theme-dark"
      app/settings/ThemePreview.tsx:9:5
      → The server cannot know the color scheme. Store the theme in a cookie and read it on the server, or set the class with an inline script before hydration and mark that element with suppressHydrationWarning.
```

## Related

- [Fix dark mode hydration mismatches](https://hydration.jscrate.dev/docs/causes/theme)
- [CSS-in-JS class names that differ](https://hydration.jscrate.dev/docs/causes/css-in-js)
- [HP1002: attribute differs](https://hydration.jscrate.dev/docs/issues/hp1002)
- [HP1003: inline style differs](https://hydration.jscrate.dev/docs/issues/hp1003)
- [HP6001: a mismatch hidden by suppressHydrationWarning](https://hydration.jscrate.dev/docs/issues/hp6001)

---

# HP1005: Attribute only present in the server HTML

> HP1005 (extra attribute): the server HTML has an attribute React does not render on the client, so it stays on the page. What causes it and how to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp1005
Last updated: 2026-09-18

HP1005 (`extra-attribute`) means the server HTML has an attribute that React
does not render on the client. React leaves it in place during hydration, so
the element keeps an attribute your client code never set. Remove the attribute
from the server output, or render it on the client too.

| | |
| --- | --- |
| Code | `HP1005` |
| Name | `extra-attribute` |
| Default severity | Warning |
| Group | DOM mismatches |
| What it means | The server HTML has an attribute that React does not render on the client. |

## What HP1005 (`extra-attribute`) means

The element exists on both sides, but one attribute is only in the server's
version. That usually means the component rendered it under a condition that is
true on the server and false in the browser.

hydration-proof compares the attributes of every element React reused with the
props React renders. For attributes present only in the server HTML, it checks
`data-*`, `aria-*`, `id`, `role`,
`title`, `alt`, `lang`, `dir`, `href`, `src`, `tabindex`, `for`, `name` and
`type`. An extra `class` or `style` is reported as
[HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) or [HP1003](https://hydration.jscrate.dev/docs/issues/hp1003).

An attribute a browser extension or another script adds before hydration was
never in the server's response, so it is reported as a change outside React
([HP4001](https://hydration.jscrate.dev/docs/issues/hp4001) or [HP4002](https://hydration.jscrate.dev/docs/issues/hp4002)), not as
HP1005.

## The React error it matches

React 18 warns about it in development:

```text
Warning: Extra attributes from the server: data-rendered-on
```

See [Extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server)
for what the warning means. React 19 reports attribute
differences with
[a tree hydrated but some attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match),
in development only.

## Likely causes

- A server-only branch, such as `typeof window === "undefined"`, that adds the
  attribute: a [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api) check.
- A value that is set on the server and `undefined` in the browser, from
  [browser storage](https://hydration.jscrate.dev/docs/causes/storage) or
  [different data](https://hydration.jscrate.dev/docs/causes/data).
- A [generated id](https://hydration.jscrate.dev/docs/causes/unstable-id) that exists only in the server
  render.

## How to fix it

- Remove the attribute from the server output or render it on the client too.

```tsx title="hero.tsx"
"use client";

export function Hero() {
  const isServer = typeof window === "undefined";

  return (
    <section id="hero" data-rendered-on={isServer ? "server" : undefined}>
      Welcome
    </section>
  );
}
```

Render the same attributes in both places. If the value is only known in the
browser, set it after mount:

```tsx title="hero.tsx"
export function Hero() {
  return <section id="hero">Welcome</section>;
}
```

## Prevent it with ESLint

[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) reports
components that render something different on the server and in the browser.

## When the difference is intentional

If a server or middleware adds an attribute on purpose, list it in
`ignore.attributes` so it is never compared, or add an `ignore.issues` rule
with `code: "HP1005"` and a reason. See [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ⚠ /about 740ms  1 warning
    HP1005 Attribute only present in the server HTML  (browser-only api used during render, 58%)
      #hero  in Hero
      attribute: data-rendered-on
      server: "server"
      client: (absent)
      components/hero.tsx:7:5
      → Code like `typeof window !== "undefined"` or window/navigator/document access renders differently on the server. Read browser values in useEffect, or render the component on the client only.
```

## Related

- [HP1006: attribute missing from the server HTML](https://hydration.jscrate.dev/docs/issues/hp1006)
- [HP1002: attribute differs](https://hydration.jscrate.dev/docs/issues/hp1002)
- [Extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server)
- [Browser extensions and hydration](https://hydration.jscrate.dev/docs/causes/extension)

---

# HP1006: Attribute missing from the server HTML

> HP1006 (missing attribute): React renders an attribute on the client that the server HTML lacks, and hydration never adds it. The causes and how to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp1006
Last updated: 2026-09-18

HP1006 (`missing-attribute`) means React renders an attribute on the client
that the server HTML does not have. React does not add it during hydration, so
the element goes without it until it re-renders: a link without its `target`,
a control without its `aria-*` state. Render the attribute on the server as
well, or add it after mount.

| | |
| --- | --- |
| Code | `HP1006` |
| Name | `missing-attribute` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | React renders an attribute on the client that the server HTML does not have. |

## What HP1006 (`missing-attribute`) means

The element exists on both sides, but one attribute is only in React's client
props. The component computed it from something only the browser has, so the
server rendered `undefined` and left it out.

React does not patch attributes during hydration, and React 19 production
builds report nothing. hydration-proof compares every reused element's
attributes with the props React renders for it, so it finds the missing
attribute in production too. A missing `class` or `style` is reported as
[HP1004](https://hydration.jscrate.dev/docs/issues/hp1004) or [HP1003](https://hydration.jscrate.dev/docs/issues/hp1003).

## The React error it matches

In development, React 19 prints:

```text
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
```

See [attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match).

## Likely causes

- A value from a [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api), such as touch
  support or `navigator.language`, that is `undefined` on the server.
- A flag read from [browser storage](https://hydration.jscrate.dev/docs/causes/storage) or a
  [media query](https://hydration.jscrate.dev/docs/causes/media-query).
- A [random value](https://hydration.jscrate.dev/docs/causes/random) or
  [generated id](https://hydration.jscrate.dev/docs/causes/unstable-id) created only in the browser.

## How to fix it

- Render the attribute on the server as well, or add it after mount in
  `useEffect`.

```tsx title="share-button.tsx"
"use client";

export function ShareButton() {
  const touch = typeof window !== "undefined" && "ontouchstart" in window;

  return (
    <button type="button" data-input={touch ? "touch" : undefined}>
      Share
    </button>
  );
}
```

Start from the value the server can render, and switch after hydration:

```tsx title="share-button.tsx"
"use client";

import { useEffect, useState } from "react";

export function ShareButton() {
  const [touch, setTouch] = useState(false);

  useEffect(() => {
    setTouch("ontouchstart" in window);
  }, []);

  return (
    <button type="button" data-input={touch ? "touch" : undefined}>
      Share
    </button>
  );
}
```

## Prevent it with ESLint

[`no-browser-global-in-render`](https://hydration.jscrate.dev/docs/rules/no-browser-global-in-render) and
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) report the
browser reads and branches that cause it.

## When the difference is intentional

`suppressHydrationWarning` on the element keeps the server's attributes without
a warning; hydration-proof then lists the difference as
[HP6001](https://hydration.jscrate.dev/docs/issues/hp6001) (info). `ignore.attributes` stops comparing an
attribute everywhere. See [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ✖ /posts/42 1.1s  1 error
    HP1006 Attribute missing from the server HTML  (browser-only api used during render, 60%)
      article > button  in ShareButton
      attribute: data-input
      server: (absent)
      client: "touch"
      components/share-button.tsx:7:5
      → Code like `typeof window !== "undefined"` or window/navigator/document access renders differently on the server. Read browser values in useEffect, or render the component on the client only.
```

## Related

- [HP1005: attribute only in the server HTML](https://hydration.jscrate.dev/docs/issues/hp1005)
- [HP1002: attribute differs](https://hydration.jscrate.dev/docs/issues/hp1002)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [Browser-only APIs during render](https://hydration.jscrate.dev/docs/causes/browser-api)

---

# HP1007: Different element rendered on server and client

> HP1007 (element mismatch): the server rendered one element and the client another in the same place, so React threw the server HTML away. Causes and fixes.

Source: https://hydration.jscrate.dev/docs/issues/hp1007
Last updated: 2026-09-18

HP1007 (`element-mismatch`) means the server rendered one element and React
rendered a different one in the same place, such as a `<ul>` on the server and a
`<select>` in the browser. React cannot reuse the server's element, so it
discards that part of the page and renders it again. Render the same element
type on both sides.

| | |
| --- | --- |
| Code | `HP1007` |
| Name | `element-mismatch` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | The server rendered one element and the client rendered a different one in the same place. |

## What HP1007 (`element-mismatch`) means

hydration-proof compares the DOM right before and inside the hydration commit,
and every node keeps its identity, so it sees exactly which element React
replaced and with what. The finding shows the two tags, for example
`server: "<ul>"` and `client: "<select>"`, on the element's position in the
page.

A tag change is structural: React throws the server HTML away up to the
nearest Suspense boundary, which is slower and resets state in that part of
the page. When React re-rendered a branch around the element, the finding's
evidence names that branch.

When invalid HTML is the reason the elements differ (the browser moved a
`<div>` out of a `<p>`), the difference is reported as
[HP3001](https://hydration.jscrate.dev/docs/issues/hp3001) instead, with this one folded into it.

## The React error it matches

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
Warning: Expected server HTML to contain a matching <div> in <div>
```

The first is React 19, the second the React 18 development warning. See
[the server rendered HTML didn't match the client](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)
and [Expected server HTML to contain a matching](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching).

## Likely causes

- A layout chosen with `matchMedia` or the window size during render: a
  [media query](https://hydration.jscrate.dev/docs/causes/media-query).
- A branch on `typeof window`, the user agent or another
  [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api), such as a link on one side and
  a `<span>` on the other.
- A flag from [browser storage](https://hydration.jscrate.dev/docs/causes/storage) or data the client
  fetched again: [different data](https://hydration.jscrate.dev/docs/causes/data).

## How to fix it

- Render the same element type on server and client; branch on data that both
  sides share.

A menu that picks its element from the screen size:

```tsx title="nav-menu.tsx"
"use client";

export function NavMenu() {
  const narrow =
    typeof window !== "undefined" &&
    window.matchMedia("(max-width: 600px)").matches;

  return narrow ? (
    <select aria-label="Menu">
      <option>Docs</option>
    </select>
  ) : (
    <ul>
      <li>Docs</li>
    </ul>
  );
}
```

Render both and let CSS show one, so the markup is the same everywhere:

```tsx title="nav-menu.tsx"
export function NavMenu() {
  return (
    <>
      <select className="nav-narrow" aria-label="Menu">
        <option>Docs</option>
      </select>
      <ul className="nav-wide">
        <li>Docs</li>
      </ul>
    </>
  );
}
```

When the choice really needs JavaScript, render the server's version first and
switch after hydration, or use `useSyncExternalStore` with a
`getServerSnapshot` that returns the server's value.

## Prevent it with ESLint

[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render),
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) and
[`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state)
report the browser reads that pick a different element.

## Example

```text
  ✖ /docs 1.3s  1 error
    HP1007 Different element rendered on server and client  (screen size or media query read during render, 84%)
      #nav > select  in NavMenu
      server: "<ul>"
      client: "<select>"
      components/nav-menu.tsx:9:5
      → Use CSS media queries for layout differences, or read matchMedia / window size after mount.
```

## Related

- [HP1008: element only in the server HTML](https://hydration.jscrate.dev/docs/issues/hp1008)
- [HP1009: element missing from the server HTML](https://hydration.jscrate.dev/docs/issues/hp1009)
- [HP1010: React re-rendered a branch](https://hydration.jscrate.dev/docs/issues/hp1010)
- [Expected server HTML to contain a matching element](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching)
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)

---

# HP1008: Element only present in the server HTML

> HP1008 (extra element): the server HTML contains a node the client render does not produce, so React discards that part of the page. Causes and the fix.

Source: https://hydration.jscrate.dev/docs/issues/hp1008
Last updated: 2026-09-18

HP1008 (`extra-element`) means the server HTML contains an element or text node
that React's first client render does not produce. React cannot match it, so it
discards the server HTML of that part of the page and renders it again. Use the
same condition on both sides instead of rendering server-only nodes.

| | |
| --- | --- |
| Code | `HP1008` |
| Name | `extra-element` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | The server HTML contains a node the client render does not produce. |

## What HP1008 (`extra-element`) means

A component rendered something on the server and nothing (or less) in the
browser. The finding points at the parent element the node was in, and shows
the node as the server value, with `(absent)` as the client value.

Scripts are not counted, and neither are `<link>`, `<meta>`, `<style>`,
`<title>` and `<base>` tags in `<head>` ([HP1014](https://hydration.jscrate.dev/docs/issues/hp1014) covers
the head). A whitespace-only text node on one side is
[HP1015](https://hydration.jscrate.dev/docs/issues/hp1015), and an element the browser's parser moved
because of invalid nesting is [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001).

## The React error it matches

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
Warning: Did not expect server HTML to contain a <div> in <div>
```

The first is React 19, the second the React 18 development warning. See
[Expected server HTML to contain a matching](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching),
which covers both React 18 structure warnings.

## Likely causes

- A component that returns `null` in the browser when a stored flag is set:
  [browser storage](https://hydration.jscrate.dev/docs/causes/storage).
- A server-only branch (`typeof window === "undefined"`) or another
  [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api) check.
- A list that is shorter on the client because the client fetched it again:
  [different data](https://hydration.jscrate.dev/docs/causes/data).
- A [media query](https://hydration.jscrate.dev/docs/causes/media-query) that hides a section in the
  browser.

## How to fix it

- Do not render server-only nodes inside hydrated components; use the same
  condition on both sides.

A cookie notice that returning visitors never see in the browser, but always
get in the server HTML:

```tsx title="cookie-notice.tsx"
"use client";

export function CookieNotice() {
  if (typeof window !== "undefined" && localStorage.getItem("cookies-ok")) {
    return null;
  }

  return <p className="notice">We use cookies.</p>;
}
```

Render what the server rendered, then hide it after hydration:

```tsx title="cookie-notice.tsx"
"use client";

import { useEffect, useState } from "react";

export function CookieNotice() {
  const [accepted, setAccepted] = useState(false);

  useEffect(() => {
    setAccepted(localStorage.getItem("cookies-ok") === "1");
  }, []);

  if (accepted) return null;
  return <p className="notice">We use cookies.</p>;
}
```

Better still, keep the choice in a cookie and read it on the server, so the
notice is never sent to someone who accepted it.

## Prevent it with ESLint

[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render) and
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) report the
checks that make a component render less in the browser.

## Example

```text
  ✖ / 980ms  1 error
    HP1008 Element only present in the server HTML
      #footer  in SiteFooter
      server: "<p class=\"notice\">We use cookies.</p>"
      client: (absent)
      components/site-footer.tsx:6:5
      → Do not render server-only nodes inside hydrated components; use the same condition on both sides.
```

The selector and the source line are those of the parent, here the footer that
renders `CookieNotice`. The HTML report shows the markup on both sides.

## Related

- [HP1009: element missing from the server HTML](https://hydration.jscrate.dev/docs/issues/hp1009)
- [HP1007: a different element](https://hydration.jscrate.dev/docs/issues/hp1007)
- [localStorage and sessionStorage during render](https://hydration.jscrate.dev/docs/causes/storage)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)

---

# HP1009: Element missing from the server HTML

> HP1009 (missing element): React's client render produces a node the server HTML does not contain, so React re-renders that part. Causes and how to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp1009
Last updated: 2026-09-18

HP1009 (`missing-element`) means React's first client render produces an
element or text node that the server HTML does not contain. React cannot
hydrate a node the server never sent, so it discards that part of the page and
renders it again. Render client-only nodes after mount, or with a client-only
component.

| | |
| --- | --- |
| Code | `HP1009` |
| Name | `missing-element` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | The client render produces a node the server HTML does not contain. |

## What HP1009 (`missing-element`) means

A component rendered more in the browser than on the server: a badge, a banner,
a widget that depends on something only the browser knows. The finding points
at the new node and shows it as the client value, with `(absent)` as the server
value.

Scripts are not counted, and neither are `<link>`, `<meta>`, `<style>`,
`<title>` and `<base>` tags added to `<head>` ([HP1014](https://hydration.jscrate.dev/docs/issues/hp1014)
covers the head). A whitespace-only text node is
[HP1015](https://hydration.jscrate.dev/docs/issues/hp1015), and an element a script or extension inserted
before hydration is reported as a change outside React
([HP4001](https://hydration.jscrate.dev/docs/issues/hp4001)).

## The React error it matches

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
Warning: Expected server HTML to contain a matching <div> in <div>
```

The first is React 19, the second the React 18 development warning. See
[Expected server HTML to contain a matching](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching).

## Likely causes

- A count or flag read from [browser storage](https://hydration.jscrate.dev/docs/causes/storage) during
  render.
- A `typeof window !== "undefined"` branch or another
  [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api).
- A section shown only on small screens: a
  [media query](https://hydration.jscrate.dev/docs/causes/media-query).
- A list that is longer on the client because the client fetched it again:
  [different data](https://hydration.jscrate.dev/docs/causes/data).

## How to fix it

- Render client-only nodes after mount (`useEffect`) or with a client-only
  component.

A cart badge that only exists in the browser:

```tsx title="cart-badge.tsx"
"use client";

export function CartBadge() {
  const count =
    typeof window === "undefined"
      ? 0
      : Number(localStorage.getItem("cart-count") ?? 0);

  return (
    <a href="/cart" id="cart">
      Cart
      {count > 0 && <b className="badge">{count}</b>}
    </a>
  );
}
```

Read the count after hydration, so the first client render matches the server:

```tsx title="cart-badge.tsx"
"use client";

import { useEffect, useState } from "react";

export function CartBadge() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    setCount(Number(localStorage.getItem("cart-count") ?? 0));
  }, []);

  return (
    <a href="/cart" id="cart">
      Cart
      {count > 0 && <b className="badge">{count}</b>}
    </a>
  );
}
```

For a whole component that cannot render on the server, see
[client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component) and
[next/dynamic with `ssr: false`](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false).

## Prevent it with ESLint

[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render),
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) and
[`no-match-media-in-render`](https://hydration.jscrate.dev/docs/rules/no-match-media-in-render) report the
reads that make a component render more in the browser.

## Example

```text
  ✖ /shop 1.2s  1 error
    HP1009 Element missing from the server HTML  (localstorage / sessionstorage read during render, 85%)
      #cart > b  in CartBadge
      server: (absent)
      client: "<b class=\"badge\">2</b>"
      components/cart-badge.tsx:12:21
      → Storage is only available in the browser. Render a neutral value first and read storage in useEffect.
```

## Related

- [HP1008: element only in the server HTML](https://hydration.jscrate.dev/docs/issues/hp1008)
- [HP1007: a different element](https://hydration.jscrate.dev/docs/issues/hp1007)
- [HP1010: React re-rendered a branch](https://hydration.jscrate.dev/docs/issues/hp1010)
- [localStorage and sessionStorage during render](https://hydration.jscrate.dev/docs/causes/storage)

---

# HP1010: React discarded server HTML and rendered a branch again

> HP1010 (branch replaced): hydration failed inside a branch, so React threw its server HTML away and rendered it on the client. Why it costs you, and the fix.

Source: https://hydration.jscrate.dev/docs/issues/hp1010
Last updated: 2026-09-18

HP1010 (`branch-replaced`) means hydration failed inside part of the page, so
React threw away that branch's server HTML and rendered it again on the client.
That costs a second render, resets the state inside the branch, and happens on
every page load until the mismatch is fixed. Find the mismatch in that branch
and fix it.

| | |
| --- | --- |
| Code | `HP1010` |
| Name | `branch-replaced` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | Hydration failed inside this branch, so React threw away the server HTML and rendered it on the client. This costs performance and resets state. |

## What HP1010 (`branch-replaced`) means

When React finds a difference it cannot hydrate, it gives up on the nearest
Suspense boundary: it discards the server HTML inside it and renders that part
from scratch. Everything in the branch is created again, so inputs come back
empty and an element that had focus loses it
([HP5002](https://hydration.jscrate.dev/docs/issues/hp5002) and [HP5003](https://hydration.jscrate.dev/docs/issues/hp5003) check both).

hydration-proof sees this by giving every node an identity: it knows which
server nodes React reused and which it replaced. In most cases it also finds
the concrete difference inside the branch, and then reports that instead (a
text, element or attribute code) with "React discarded the server HTML of
`<section>` and rendered it again on the client" as evidence. HP1010 appears on
its own when React replaced a branch but the exact difference inside it could
not be located.

If the replaced part is the whole root rather than a branch, the code is
[HP1011](https://hydration.jscrate.dev/docs/issues/hp1011).

## The React error it matches

React's own report is attached to the finding as evidence:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
There was an error while hydrating this Suspense boundary. Switched to client rendering.
```

The first is React 19, the second React 18. In production they arrive as
minified errors, such as #418. See
[the server rendered HTML didn't match the client](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client)
and [there was an error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating).
When React reports this with no DOM change to go with it, the code is
[HP2003](https://hydration.jscrate.dev/docs/issues/hp2003).

## Likely causes

Any mismatch can make React replace a branch. The common ones are a
[time-dependent value](https://hydration.jscrate.dev/docs/causes/time), a
[browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api) branch,
[browser storage](https://hydration.jscrate.dev/docs/causes/storage) and
[invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html). The full list is on
[common causes of hydration errors](https://hydration.jscrate.dev/docs/causes).

## How to fix it

- Fix the mismatch inside this branch; React re-renders it on every page load
  until then.

1. Read the finding's evidence in the HTML report: React's error and the
   component stack point into the branch.
2. Run `npx hydration-proof test --mode dev` for component names, exact source
   lines and React's full message instead of a minified code.
3. Fix the difference React found, using the cause page it points to, and run
   the test again: the branch is then hydrated instead of replaced.

## Example

```text
  ✖ /products/42 1.6s  1 error
    HP1010 React discarded server HTML and rendered a branch again
      #reviews  in Reviews
      React discarded the server HTML of <section> and rendered it again on the client.
      → Fix the mismatch inside this branch; React re-renders it on every page load until then.
```

## Related

- [HP1011: React discarded the whole page](https://hydration.jscrate.dev/docs/issues/hp1011)
- [HP2003: a Suspense boundary switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2003)
- [HP1001: text differs](https://hydration.jscrate.dev/docs/issues/hp1001)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Do hydration errors hurt SEO and performance?](https://hydration.jscrate.dev/docs/guides/hydration-errors-seo)

---

# HP1011: React discarded the whole server-rendered page

> HP1011 (root replaced): hydration failed outside any Suspense boundary, so React threw away the whole server-rendered page and rendered it again. The fix.

Source: https://hydration.jscrate.dev/docs/issues/hp1011
Last updated: 2026-09-18

HP1011 (`root-replaced`) means hydration failed outside any Suspense boundary,
so React discarded the server HTML of the entire root and rendered the page
again on the client, losing anything the user did before hydration. Fix the
mismatch, or wrap the unstable part in a Suspense boundary so only that part is
re-rendered.

| | |
| --- | --- |
| Code | `HP1011` |
| Name | `root-replaced` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | Hydration failed outside any Suspense boundary, so React re-rendered the entire root on the client. |

## What HP1011 (`root-replaced`) means

React recovers from a hydration failure at the nearest Suspense boundary above
it. With no boundary in between, that is the root: every element on the page is
created again, the server HTML is only a placeholder, and all state is reset.

Like [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010), this code appears on its own only when
hydration-proof saw the replacement but could not locate the concrete
difference. When it finds the difference, it reports that instead, with "React
discarded the server HTML of the whole root" as evidence.

## The React error it matches

React's own report is attached as evidence:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

The first is React 19, the second React 18, minified in production as
[#423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423). See
[there was an error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating).
When React reports this without a DOM change to go with it, the code is
[HP2004](https://hydration.jscrate.dev/docs/issues/hp2004).

## Likely causes

The same mismatches as anywhere else, most often a
[time-dependent value](https://hydration.jscrate.dev/docs/causes/time),
[browser storage](https://hydration.jscrate.dev/docs/causes/storage), a
[theme](https://hydration.jscrate.dev/docs/causes/theme) or [invalid HTML](https://hydration.jscrate.dev/docs/causes/invalid-html) in a
layout shared by every page. See [all causes](https://hydration.jscrate.dev/docs/causes).

## How to fix it

- Fix the mismatch or wrap the unstable part in a Suspense boundary so React
  only re-renders that part.

Fixing the mismatch is the real fix; see [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) for the
steps. A Suspense boundary limits the damage while you do, or around a part
that will always be unstable:

```tsx title="app/page.tsx"
import { Suspense } from "react";

import { Article } from "./article";
import { LastSeen } from "./last-seen";

export default function Page() {
  return (
    <main>
      <Suspense fallback={null}>
        <LastSeen />
      </Suspense>
      <Article />
    </main>
  );
}
```

If `LastSeen` fails to hydrate now, React re-renders only that boundary and
keeps the rest of the server HTML. The finding becomes an HP1010 for the
boundary instead of an HP1011 for the page.

## Example

```text
  ✖ / 1.2s  1 error
    HP1011 React discarded the whole server-rendered page
      main  in RootLayout
      React discarded the server HTML of the whole root (from <main>) and rendered it again on the client.
      → Fix the mismatch or wrap the unstable part in a Suspense boundary so React only re-renders that part.
```

## Related

- [HP1010: React re-rendered one branch](https://hydration.jscrate.dev/docs/issues/hp1010)
- [HP2004: the root switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2004)
- [Minified React error #423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423)
- [Do hydration errors hurt SEO and performance?](https://hydration.jscrate.dev/docs/guides/hydration-errors-seo)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)

---

# HP1012: Form state differs between server and client

> HP1012 (form state mismatch): a form control's value, checked or selected state changed during hydration, and React never reports it. Causes and the fix.

Source: https://hydration.jscrate.dev/docs/issues/hp1012
Last updated: 2026-09-18

HP1012 (`form-state-mismatch`) means a form control's value, checked state or
selected option in the server HTML differs from what React renders on the
client. React sets these as properties during hydration, so the field changes
under the user, and React reports nothing, not even in development. Use
`defaultValue` and `defaultChecked` with values that are identical on both
sides.

| | |
| --- | --- |
| Code | `HP1012` |
| Name | `form-state-mismatch` |
| Default severity | Warning |
| Group | DOM mismatches |
| What it means | A form control value, checked or selected state changed during hydration. |

## What HP1012 (`form-state-mismatch`) means

On the server, React writes a control's state into the HTML: the `value`
attribute of an `<input>`, the text of a `<textarea>`, the `checked` attribute,
and `selected` on the chosen `<option>`. In the browser, React applies the
client value as a DOM property. When the two differ, the value the page showed
is replaced during hydration.

hydration-proof reads each control's state from the server HTML the way the
browser's parser does and compares it with the `value`, `defaultValue`,
`checked` or `defaultChecked` React renders. The package's test pages confirm
that React 18 and 19 are silent here: a `<textarea>` whose `defaultValue`
differs and a `<select>` whose selected option differs produce no React message
at all.

Text a user types before hydration and loses is a different problem,
[HP5002](https://hydration.jscrate.dev/docs/issues/hp5002).

## Likely causes

- A default read from [browser storage](https://hydration.jscrate.dev/docs/causes/storage) or behind a
  `typeof window` check: a [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api).
- A form the server rendered with the result of a submitted Server Action
  (`useActionState` with a permalink) that the client hydrated without that
  state: [Server Action form state](https://hydration.jscrate.dev/docs/causes/form-state).
- A date or number default formatted with the runtime's
  [locale](https://hydration.jscrate.dev/docs/causes/locale).

## How to fix it

- Use `defaultValue`/`defaultChecked` with values that are identical on server
  and client.

A currency picker that restores the saved choice during render:

```tsx title="currency-picker.tsx"
"use client";

export function CurrencyPicker() {
  const saved =
    typeof window === "undefined"
      ? "EUR"
      : (localStorage.getItem("currency") ?? "EUR");

  return (
    <select id="currency" defaultValue={saved} aria-label="Currency">
      <option value="EUR">Euro</option>
      <option value="USD">US dollar</option>
    </select>
  );
}
```

Let the server decide the default (from a cookie, the user's profile or the
URL) and pass it in, so both renders select the same option:

```tsx title="currency-picker.tsx"
export function CurrencyPicker({ currency }: { currency: string }) {
  return (
    <select id="currency" defaultValue={currency} aria-label="Currency">
      <option value="EUR">Euro</option>
      <option value="USD">US dollar</option>
    </select>
  );
}
```

For Server Action state, let the framework pass the form state to
`hydrateRoot` (Next.js does this) and render the form from the action state
only.

## Prevent it with ESLint

[`no-storage-in-initial-render`](https://hydration.jscrate.dev/docs/rules/no-storage-in-initial-render),
[`no-client-only-initial-state`](https://hydration.jscrate.dev/docs/rules/no-client-only-initial-state) and
[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) report the
browser reads that make a default differ.

## Example

```text
  ⚠ /checkout 1.2s  1 warning
    HP1012 Form state differs between server and client  (localstorage / sessionstorage read during render, 84%)
      #currency  in CurrencyPicker
      attribute: value
      server: "EUR"
      client: "USD"
      components/currency-picker.tsx:10:5
      → Storage is only available in the browser. Render a neutral value first and read storage in useEffect.
```

## Related

- [HP5002: user input was reset during hydration](https://hydration.jscrate.dev/docs/issues/hp5002)
- [Server Action form state](https://hydration.jscrate.dev/docs/causes/form-state)
- [HP1013: dangerouslySetInnerHTML differs](https://hydration.jscrate.dev/docs/issues/hp1013)
- [HP1001: text differs](https://hydration.jscrate.dev/docs/issues/hp1001)

---

# HP1013: dangerouslySetInnerHTML differs between server and client

> HP1013 (inner HTML mismatch): the HTML injected with dangerouslySetInnerHTML differs between server and client, and React never patches it. Causes and fix.

Source: https://hydration.jscrate.dev/docs/issues/hp1013
Last updated: 2026-09-18

HP1013 (`inner-html-mismatch`) means the markup you inject with
`dangerouslySetInnerHTML` is different on the server and on the client. React
does not patch it during hydration, so the page keeps the server's version, and
React 19 production builds say nothing. Make the injected HTML
identical on both sides, or render it after mount.

| | |
| --- | --- |
| Code | `HP1013` |
| Name | `inner-html-mismatch` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | The HTML injected with dangerouslySetInnerHTML differs between the server and the client. React does not patch it. |

## What HP1013 (`inner-html-mismatch`) means

The element exists on both sides, but the `__html` string React renders on the
client does not produce the same content as the server HTML. hydration-proof
parses the client's string in an inert document and compares the result with
the element's content, so markup that parses to the same thing (`<br/>` and
`<br>`, for example) is not reported.

The finding has no single server or client value; the HTML report shows both
versions of the element side by side.

## The React error it matches

React 18 warns about it in development:

```text
Warning: Prop `dangerouslySetInnerHTML` did not match.
```

See [Prop `className` did not match](https://hydration.jscrate.dev/docs/errors/prop-classname-did-not-match),
which covers this variant of the warning too. React 19 production builds report
nothing.

## Likely causes

- HTML built behind a `typeof window` check, or processed only in the browser
  (sanitized, highlighted, rewritten): a
  [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api). The package's `/dangerous-html`
  test page injects different markup on each side this way.
- A string that contains a [time](https://hydration.jscrate.dev/docs/causes/time) or a number formatted with
  the runtime's [locale](https://hydration.jscrate.dev/docs/causes/locale).
- Content the client fetched again: [different data](https://hydration.jscrate.dev/docs/causes/data).

## How to fix it

- Make the injected HTML identical on server and client, or render it after
  mount.

Processing the HTML only in the browser gives the two renders different
strings:

```tsx title="post-body.tsx"
"use client";

import { highlight } from "./highlight";

export function PostBody({ html }: { html: string }) {
  const content = typeof window === "undefined" ? html : highlight(html);
  return <div id="post-body" dangerouslySetInnerHTML={{ __html: content }} />;
}
```

Do the processing once, where the data is loaded (on the server or at build
time), and pass the finished string to both renders:

```tsx title="post-body.tsx"
export function PostBody({ html }: { html: string }) {
  return <div id="post-body" dangerouslySetInnerHTML={{ __html: html }} />;
}
```

## Prevent it with ESLint

[`no-window-render-branch`](https://hydration.jscrate.dev/docs/rules/no-window-render-branch) reports the
server/browser branch, and
[`no-date-in-render`](https://hydration.jscrate.dev/docs/rules/no-date-in-render) and
[`no-locale-without-explicit-locale`](https://hydration.jscrate.dev/docs/rules/no-locale-without-explicit-locale)
the values that change the string.

## Example

```text
  ✖ /blog/launch 1.0s  1 error
    HP1013 dangerouslySetInnerHTML differs between server and client  (browser-only api used during render, 60%)
      #post-body  in PostBody
      The markup injected with dangerouslySetInnerHTML differs from what the client renders.
      components/post-body.tsx:7:10
      → Code like `typeof window !== "undefined"` or window/navigator/document access renders differently on the server. Read browser values in useEffect, or render the component on the client only.
```

## Related

- [HP1001: text differs](https://hydration.jscrate.dev/docs/issues/hp1001)
- [HP1002: attribute differs](https://hydration.jscrate.dev/docs/issues/hp1002)
- [Browser-only APIs during render](https://hydration.jscrate.dev/docs/causes/browser-api)
- [Why some errors only appear in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)

---

# HP1014: Document head differs between server and client

> HP1014 (head mismatch): the title, meta tags or stylesheets in the head changed while the page hydrated, so crawlers and link previews see other values.

Source: https://hydration.jscrate.dev/docs/issues/hp1014
Last updated: 2026-09-18

HP1014 (`head-mismatch`) means the `<title>`, a `<meta>` tag or a stylesheet in
the document head changed while the page hydrated. Search engines, link
previews and the first paint use the server's values, so they never see the
final ones. Render the same head values on the server and the client, computed
from data the server has.

| | |
| --- | --- |
| Code | `HP1014` |
| Name | `head-mismatch` |
| Default severity | Warning |
| Group | DOM mismatches |
| What it means | Metadata, stylesheets or scripts in <head> changed during hydration. |

## What HP1014 (`head-mismatch`) means

hydration-proof compares the `<head>` right before hydration with the page after
the hydration commit's effects have run. It reports three things:

| Change                                                                             | What the finding shows                        |
| ---------------------------------------------------------------------------------- | --------------------------------------------- |
| Hydration added a `<title>` with a new value                                       | The server title and the added one            |
| A `<meta>` tag (by `name`, `property`, `http-equiv` or `itemprop`) got new content | The server `content` and the new one          |
| A stylesheet `<link>` from the server HTML was removed                             | Its `href`; the page can flash without styles |

Values are compared as sets, because React 19 adds a new `<title>` or `<meta>`
next to the server's instead of changing it. When that leaves two `<title>`
elements, the browser shows the first one, which is the server's.

Since the comparison runs after effects, a title set from an effect
(`document.title = …`) is reported as well.

## Likely causes

- A title or description built from [browser storage](https://hydration.jscrate.dev/docs/causes/storage) or
  another [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api).
- A [locale](https://hydration.jscrate.dev/docs/causes/locale) or [time](https://hydration.jscrate.dev/docs/causes/time) formatted into
  the title.
- Data the client fetched again: [different data](https://hydration.jscrate.dev/docs/causes/data).

## How to fix it

- Render the same `<title>` and `<meta>` tags on the server and the client, so
  search engines, link previews and the first paint show the final values.
- Compute head values from data the server has (route params, cookies) instead
  of browser-only values.

A React 19 `<title>` that reads a name from storage:

```tsx title="welcome-title.tsx"
"use client";

export function WelcomeTitle() {
  const name =
    typeof window === "undefined"
      ? "Guest"
      : (localStorage.getItem("name") ?? "Guest");

  return <title>{`Welcome, ${name}`}</title>;
}
```

Build the title on the server instead. In the Next.js App Router, that is
`generateMetadata`, which can read cookies:

```tsx title="app/welcome/page.tsx"
import { cookies } from "next/headers";

export async function generateMetadata() {
  const name = (await cookies()).get("name")?.value ?? "Guest";
  return { title: `Welcome, ${name}` };
}

export default function Page() {
  return <h1>Welcome</h1>;
}
```

## When the difference is intentional

A title that changes on purpose after load, such as an unread count, is a
legitimate update. Add an `ignore.issues` rule with `code: "HP1014"`, the route
and a reason; see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ⚠ /welcome 890ms  1 warning
    HP1014 Document head differs between server and client
      head > title
      attribute: title
      server: "Welcome, Guest"
      client: "Welcome, Sohail"
      → Render the same <title> and <meta> tags on the server and the client, so search engines, link previews and the first paint show the final values.
```

## Related

- [Do hydration errors hurt SEO?](https://hydration.jscrate.dev/docs/guides/hydration-errors-seo)
- [HP1001: text differs](https://hydration.jscrate.dev/docs/issues/hp1001)
- [HP1015: whitespace differs](https://hydration.jscrate.dev/docs/issues/hp1015)
- [Configuration: which checks run](https://hydration.jscrate.dev/docs/configuration)

---

# HP1015: Whitespace differs between server and client

> HP1015 (whitespace mismatch): only whitespace differs between the server HTML and React's render, which usually means a CDN or proxy minified the HTML.

Source: https://hydration.jscrate.dev/docs/issues/hp1015
Last updated: 2026-09-18

HP1015 (`whitespace-mismatch`) means the server HTML and React's client render
differ only in whitespace. Your components rarely cause this: it usually means
something rewrote the HTML on its way to the browser, such as a CDN's HTML
minification. Turn off HTML minification for server-rendered React pages.

| | |
| --- | --- |
| Code | `HP1015` |
| Name | `whitespace-mismatch` |
| Default severity | Error |
| Group | DOM mismatches |
| What it means | Only whitespace differs, which usually means something rewrote the HTML between the server and the browser. |

## What HP1015 (`whitespace-mismatch`) means

To React, a space is text like any other. If a minifier removes the space
between `Hello` and `<strong>world</strong>`, a text node React expects is
missing, and hydration fails exactly as it would for different words.

hydration-proof reports HP1015 instead of [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001) when
the two values are equal once all whitespace is removed, and when a
whitespace-only text node exists on one side only. The likely cause is
[HTML rewritten by a CDN or proxy](https://hydration.jscrate.dev/docs/causes/cdn), with a higher confidence
when the response headers show one (such as `cf-ray`, `x-amz-cf-id`, `x-cache`
or `via`).

The package's `/cdn-whitespace` test page shows the difference: loaded
directly it is clean, and loaded through a proxy that collapses whitespace
between tags, like a CDN's minifier, it fails.

The terminal collapses whitespace when it prints values, so the two sides can
look alike there; `report.json` and the HTML report have the exact values.

## Likely causes

- HTML minification at a [CDN or proxy](https://hydration.jscrate.dev/docs/causes/cdn), for example a CDN's
  "Auto Minify" option.
- A server-side HTML post-processor or edge function that reformats the
  response.

## How to fix it

- Turn off HTML minification that removes whitespace (for example CDN "Auto
  Minify") for server-rendered React pages.
- Avoid relying on whitespace-only text nodes between elements.

The first is the fix. The second makes a page less fragile: a space between
two elements is a text node of its own, which is exactly the kind of
whitespace a minifier collapses.

```tsx title="footer-links.tsx"
export function FooterLinks() {
  return (
    <nav>
      <a href="/docs">Docs</a> <a href="/blog">Blog</a>
    </nav>
  );
}
```

Spacing from CSS leaves nothing for a minifier to remove:

```tsx title="footer-links.tsx"
export function FooterLinks() {
  return (
    <nav style={{ display: "flex", gap: "0.5rem" }}>
      <a href="/docs">Docs</a>
      <a href="/blog">Blog</a>
    </nav>
  );
}
```

## When the difference is intentional

It rarely is. If you cannot change the CDN yet, an `ignore.issues` rule with
`code: "HP1015"`, a reason and an expiry date keeps the run green while you
do; see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ✖ /about 1.1s  1 error
    HP1015 Whitespace differs between server and client  (html rewritten by a cdn or proxy, 88%)
      #intro  in Intro
      server: (absent)
      client: "\" \""
      components/intro.tsx:5:7
      → Turn off HTML minification or rewriting (e.g. Cloudflare Auto Minify, email obfuscation) for server-rendered pages.
```

Here the minifier removed the space React renders between two elements, so the
server side is `(absent)` and the client side is that space, quoted.

## Related

- [HTML rewritten by a CDN or proxy](https://hydration.jscrate.dev/docs/causes/cdn)
- [HP4003: HTML rewritten between the server and the browser](https://hydration.jscrate.dev/docs/issues/hp4003)
- [HP1001: text differs](https://hydration.jscrate.dev/docs/issues/hp1001)
- [HP1014: document head differs](https://hydration.jscrate.dev/docs/issues/hp1014)
- [Errors that only happen in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)

---

# HP2001: React reported a hydration error

> HP2001 (React hydration error): React said hydration failed, but the DOM comparison could not locate the difference. How to find it, and what #418 means.

Source: https://hydration.jscrate.dev/docs/issues/hp2001
Last updated: 2026-09-18

HP2001 (`react-hydration-error`) means React reported that hydration failed,
for example with minified error #418, but hydration-proof's DOM comparison
could not tie the failure to a specific element. Run the test in development
mode: React's full message, its component stack and the source lines point to
the difference.

| | |
| --- | --- |
| Code | `HP2001` |
| Name | `react-hydration-error` |
| Default severity | Error |
| Group | Problems React reported |
| What it means | React reported that hydration failed. The DOM comparison could not locate the exact difference. |

## What HP2001 (`react-hydration-error`) means

hydration-proof records React's own errors and warnings, in development and
production builds of React 18 and 19. Most of the time the DOM comparison finds
the difference that made React fail, and React's message is attached to that
finding as evidence: a text mismatch is reported as
[HP1001](https://hydration.jscrate.dev/docs/issues/hp1001), not HP2001.

HP2001 is what is left when React reported a failure in a hydration commit and
no DOM finding from that commit explains it. The finding carries React's
message and, when React provides one, the component stack.

## The React error it matches

These are the messages that become HP2001 when nothing else explains them:

```text
Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
Hydration failed because the initial UI does not match what was rendered on the server.
Text content does not match server-rendered HTML.
Minified React error #418; visit https://react.dev/errors/418
```

The first is React 19, the next two React 18. Production builds show only a
number: #418, or [#425](https://hydration.jscrate.dev/docs/errors/minified-react-error-425) for React 18's
text message. Each has its own page:
[the server rendered HTML didn't match the client](https://hydration.jscrate.dev/docs/errors/hydration-failed-server-rendered-html-didnt-match-client),
[the initial UI does not match](https://hydration.jscrate.dev/docs/errors/hydration-failed-initial-ui-does-not-match),
[text content does not match](https://hydration.jscrate.dev/docs/errors/text-content-does-not-match-server-rendered-html)
and [minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418).

## Likely causes

React's message is generic, so the cause has to be found from the component:
the usual suspects are a [time-dependent value](https://hydration.jscrate.dev/docs/causes/time), a
[browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api) branch,
[browser storage](https://hydration.jscrate.dev/docs/causes/storage) and
[invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html). The difference may also sit
in an element hydration-proof does not compare, such as a subtree you excluded
with `ignore.selectors`.

## How to fix it

- Run hydration-proof in development mode (`--mode dev`) for React's detailed
  diff.

Start with the development build of the same route:

```bash
npx hydration-proof test --mode dev --route /checkout
```

React 19's development message ends with a diff of the server and client
markup (`+` for the client, `-` for the server), and development builds give
hydration-proof the component names and source lines it needs. Then:

1. If the finding becomes a DOM code (HP1001, HP1007…) in development, follow
   that code's page.
2. If it only happens in production, test both modes with `--mode both`:
   issues found in only one mode are marked. See
   [errors that only happen in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production).

## Example

```text
  ✖ /checkout 1.4s  1 error
    HP2001 React reported a hydration error
      Minified React error #418; visit https://react.dev/errors/418?args[]=HTML&args[]= for the full message or use the non-minified dev environment for full errors and additional helpful warnings. (React error #418)
      → Run hydration-proof in development mode (--mode dev) for React's detailed diff.
```

Production builds minify component names, so this finding shows none; the
development run adds component names and source lines.

## Related

- [HP2002: React warned about a mismatch](https://hydration.jscrate.dev/docs/issues/hp2002)
- [HP2004: the root switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2004)
- [Minified React error #418](https://hydration.jscrate.dev/docs/errors/minified-react-error-418)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [All React hydration error messages](https://hydration.jscrate.dev/docs/errors)

---

# HP2002: React warned about a hydration mismatch

> HP2002 (React hydration warning): React logged a hydration mismatch warning in a development build that no DOM finding explains. What it means and what to do.

Source: https://hydration.jscrate.dev/docs/issues/hp2002
Last updated: 2026-09-18

HP2002 (`react-hydration-warning`) means React logged a hydration mismatch
warning in a development build, and no difference hydration-proof found in the same
hydration commit explains it. Read React's message: it names the element or
prop that differs, and often both values. Then fix the difference like any
other mismatch.

| | |
| --- | --- |
| Code | `HP2002` |
| Name | `react-hydration-warning` |
| Default severity | Warning |
| Group | Problems React reported |
| What it means | React logged a hydration mismatch warning (development builds only). |

## What HP2002 (`react-hydration-warning`) means

In development, React logs a warning for many mismatches it can recover from
or does not fix: attributes, extra attributes, text, and elements it expected
or did not expect. hydration-proof reads each warning. When a DOM finding from
the same hydration commit explains it, the warning is attached to that finding
as evidence (a `className` warning to [HP1004](https://hydration.jscrate.dev/docs/issues/hp1004), for
example). HP2002 is a warning nothing else explains.

Production builds do not log these warnings, so HP2002 only appears in
development runs (`--mode dev` or `--mode both`). When React 18 quotes the
values, as in "Prop `title` did not match. Server: … Client: …", the finding
carries the prop name and both values.

## The React error it matches

The development warnings that become HP2002:

```text
A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
Warning: Text content did not match. Server: "5 minutes ago" Client: "6 minutes ago"
Warning: Prop `className` did not match. Server: "theme-light" Client: "theme-dark"
Warning: Expected server HTML to contain a matching <div> in <div>
Warning: Did not expect server HTML to contain a <div> in <div>
Warning: Extra attributes from the server: data-rendered-on
An error occurred during hydration. The server HTML was replaced with client content in <div>
```

The first is React 19, the rest React 18. Nesting warnings, such as
"In HTML, `<div>` cannot be a descendant of `<p>`", are reported as
[HP3001](https://hydration.jscrate.dev/docs/issues/hp3001) instead. Each message has a page under
[React hydration error messages](https://hydration.jscrate.dev/docs/errors), for example
[attributes didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match)
and [Expected server HTML to contain a matching](https://hydration.jscrate.dev/docs/errors/expected-server-html-to-contain-a-matching).

## Likely causes

The warning says what differs; the reason is one of the usual
[causes of hydration errors](https://hydration.jscrate.dev/docs/causes): a
[theme](https://hydration.jscrate.dev/docs/causes/theme) class, a [time](https://hydration.jscrate.dev/docs/causes/time) or
[locale](https://hydration.jscrate.dev/docs/causes/locale) value, or a
[browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api) branch.

## How to fix it

1. Find the element from React's message and the component stack attached to
   the finding (open it in the HTML report).
2. Look up the error message's page for what it means, and the cause page for
   the fix.
3. If the difference is inside an element you excluded with
   `ignore.selectors`, hydration-proof does not compare it; React still does.
   Fix it, or ignore HP2002 for that route with a reason (see
   [ignoring findings](https://hydration.jscrate.dev/docs/ignoring)).

## Related

- [HP2001: React reported a hydration error](https://hydration.jscrate.dev/docs/issues/hp2001)
- [HP2007: an uncaught error while loading](https://hydration.jscrate.dev/docs/issues/hp2007)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [All React hydration error messages](https://hydration.jscrate.dev/docs/errors)

---

# HP2003: A Suspense boundary switched to client rendering

> HP2003 (boundary client rendered): React could not hydrate a Suspense boundary and rendered it on the client instead (React error #422). What to check first.

Source: https://hydration.jscrate.dev/docs/issues/hp2003
Last updated: 2026-09-18

HP2003 (`boundary-client-rendered`) means React could not hydrate a Suspense
boundary and rendered its content on the client instead, throwing the server
HTML inside it away. The rest of the page hydrated normally. Check the error
React reported for the boundary: until it is fixed, the boundary is rendered on
the client on every load.

| | |
| --- | --- |
| Code | `HP2003` |
| Name | `boundary-client-rendered` |
| Default severity | Error |
| Group | Problems React reported |
| What it means | React could not hydrate a Suspense boundary and rendered it on the client instead. |

## What HP2003 (`boundary-client-rendered`) means

When hydration fails inside a Suspense boundary, React recovers there: it
discards the boundary's server HTML and renders it from scratch, and logs why.
hydration-proof compares each boundary's hydration commit on its own, so it
usually also sees the difference React hit and reports that (a DOM code such
as [HP1001](https://hydration.jscrate.dev/docs/issues/hp1001), or [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) for the
replaced branch), with React's message as evidence.

HP2003 stands alone when React reported the switch and no DOM finding from that
commit explains it, for example because the difference is inside a subtree
excluded with `ignore.selectors`. When React attaches the original error, the
finding shows it after "Caused by:".

## The React error it matches

```text
There was an error while hydrating this Suspense boundary. Switched to client rendering.
```

This is React 18's message; production builds show
[minified error #422](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes). See
[there was an error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating).
If the failure is outside every boundary, the whole root switches instead:
[HP2004](https://hydration.jscrate.dev/docs/issues/hp2004).

## Likely causes

- A mismatch inside the boundary: a [time](https://hydration.jscrate.dev/docs/causes/time) value,
  [browser storage](https://hydration.jscrate.dev/docs/causes/storage) or a
  [browser-only API](https://hydration.jscrate.dev/docs/causes/browser-api) branch.
- Data the client fetched again and got a different answer:
  [different data](https://hydration.jscrate.dev/docs/causes/data).
- [Invalid HTML](https://hydration.jscrate.dev/docs/causes/invalid-html) the browser repaired inside the
  boundary.

## How to fix it

- Check the error React reported for this boundary; the boundary is rendered on
  the client until it is fixed.

1. Open the finding in the HTML report. Its evidence has React's message, the
   underlying error when there is one, and the component stack.
2. Run `npx hydration-proof test --mode dev` for readable component names and
   source lines.
3. Fix the difference React found, using the page of the matching DOM code
   or cause, and run the test again.

## Example

```text
  ✖ /dashboard 1.5s  1 error
    HP2003 A Suspense boundary switched to client rendering
      in UsageChart
      There was an error while hydrating this Suspense boundary. Switched to client rendering.
      → Check the error React reported for this boundary; the boundary is rendered on the client until it is fixed.
```

## Related

- [HP1010: React re-rendered a branch](https://hydration.jscrate.dev/docs/issues/hp1010)
- [HP2004: the whole root switched](https://hydration.jscrate.dev/docs/issues/hp2004)
- [HP2006: the server could not finish a boundary](https://hydration.jscrate.dev/docs/issues/hp2006)
- [There was an error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating)

---

# HP2004: The root switched to client rendering

> HP2004 (root client rendered): an error during hydration outside any Suspense boundary made React render the whole page on the client (React error #423).

Source: https://hydration.jscrate.dev/docs/issues/hp2004
Last updated: 2026-09-18

HP2004 (`root-client-rendered`) means an error during hydration happened
outside every Suspense boundary, so React gave up on the whole root and
rendered the entire page on the client. In production this is minified React
error #423. Fix the error React reported, and wrap unstable parts in Suspense
boundaries so one failure cannot re-render the whole page.

| | |
| --- | --- |
| Code | `HP2004` |
| Name | `root-client-rendered` |
| Default severity | Error |
| Group | Problems React reported |
| What it means | An error during hydration outside any Suspense boundary made React render the whole root on the client. |

## What HP2004 (`root-client-rendered`) means

React recovers from a hydration failure at the nearest Suspense boundary above
it. With none in between, that is the root: the server HTML of the whole page
is discarded, every component renders again in the browser, and anything the
user did before hydration is lost.

hydration-proof normally sees the discarded root in the DOM as well, and
reports the concrete difference with React's message as evidence, or
[HP1011](https://hydration.jscrate.dev/docs/issues/hp1011) when it cannot locate one. HP2004 is React's
report when no DOM finding from that commit explains it.

## The React error it matches

```text
There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
```

This is React 18's message; production builds show
[minified React error #423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423). See
[there was an error while hydrating](https://hydration.jscrate.dev/docs/errors/there-was-an-error-while-hydrating).
When the failure is inside a boundary, only that boundary switches:
[HP2003](https://hydration.jscrate.dev/docs/issues/hp2003).

## Likely causes

A mismatch in a part of the page with no Suspense boundary above it, often in
a layout every page shares: a [theme](https://hydration.jscrate.dev/docs/causes/theme) class, a
[time](https://hydration.jscrate.dev/docs/causes/time) value, [browser storage](https://hydration.jscrate.dev/docs/causes/storage) or
[invalid HTML](https://hydration.jscrate.dev/docs/causes/invalid-html).

## How to fix it

- Wrap unstable parts in Suspense boundaries so a hydration error does not
  re-render the whole page.

Fix the error itself first: the finding's evidence has React's message and the
component stack, and `npx hydration-proof test --mode dev` gives readable names
and source lines. A boundary then keeps the next failure local:

```tsx title="app/layout.tsx"
import { Suspense, type ReactNode } from "react";

import { AccountMenu } from "./account-menu";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <header>
          <Suspense fallback={null}>
            <AccountMenu />
          </Suspense>
        </header>
        {children}
      </body>
    </html>
  );
}
```

If `AccountMenu` fails to hydrate, React now client-renders that boundary
only, and the finding becomes [HP2003](https://hydration.jscrate.dev/docs/issues/hp2003) instead.

## Example

```text
  ✖ / 1.2s  1 error
    HP2004 The root switched to client rendering
      There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
      → Wrap unstable parts in Suspense boundaries so a hydration error does not re-render the whole page.
```

## Related

- [HP1011: React discarded the whole page](https://hydration.jscrate.dev/docs/issues/hp1011)
- [HP2003: one Suspense boundary switched](https://hydration.jscrate.dev/docs/issues/hp2003)
- [Minified React error #423](https://hydration.jscrate.dev/docs/errors/minified-react-error-423)
- [Do hydration errors hurt SEO and performance?](https://hydration.jscrate.dev/docs/guides/hydration-errors-seo)

---

# HP2005: An update arrived before hydration finished

> HP2005 (update before hydration): a Suspense boundary or root got an update before it finished hydrating (React errors 421, 424). Fix it with startTransition.

Source: https://hydration.jscrate.dev/docs/issues/hp2005
Last updated: 2026-09-18

HP2005 (`update-before-hydration`) means a state or context update reached a
Suspense boundary, or the root, before React had finished hydrating it, and
React switched it to client rendering (React errors #421 and #424). Wrap updates that run during hydration in
`startTransition`.

| | |
| --- | --- |
| Code | `HP2005` |
| Name | `update-before-hydration` |
| Default severity | Warning |
| Group | Problems React reported |
| What it means | A Suspense boundary or root received an update before it finished hydrating (React errors 421/424). |

## What HP2005 (`update-before-hydration`) means

Hydration is not instant: React hydrates the root first and each Suspense
boundary when its code and content are ready. If something updates state that a
not-yet-hydrated boundary depends on (a context value set in an effect, a parent
re-rendering on load), React has to render the new state right away, cannot
use the server HTML for it, and renders the boundary on the client instead.

The page keeps working, but that part's server HTML is thrown away and
rendered a second time.

## The React error it matches

```text
This Suspense boundary received an update before it finished hydrating.
```

React logs this for a boundary; production builds show #421, or #424 when the
root itself received the update. See
[Suspense boundary received an update before it finished hydrating](https://hydration.jscrate.dev/docs/errors/suspense-boundary-received-update-before-hydrating)
and the [minified React error codes](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes).

## Likely causes

- A provider that sets state in an effect on load, such as a user or theme read
  from [browser storage](https://hydration.jscrate.dev/docs/causes/storage), while boundaries below it are
  still hydrating.
- A parent that re-renders with new props on mount, for example after reading
  a [media query](https://hydration.jscrate.dev/docs/causes/media-query).

## How to fix it

- Wrap updates triggered during hydration in `startTransition`.

An update in an effect is urgent by default:

```tsx title="user-provider.tsx"
"use client";

import { createContext, useEffect, useState, type ReactNode } from "react";

export const UserContext = createContext<string | null>(null);

export function UserProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<string | null>(null);

  useEffect(() => {
    setUser(localStorage.getItem("user"));
  }, []);

  return <UserContext.Provider value={user}>{children}</UserContext.Provider>;
}
```

Marked as a transition, it can wait for the boundaries below to finish
hydrating instead of forcing them to render on the client:

```tsx title="user-provider.tsx"
"use client";

import {
  createContext,
  startTransition,
  useEffect,
  useState,
  type ReactNode,
} from "react";

export const UserContext = createContext<string | null>(null);

export function UserProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<string | null>(null);

  useEffect(() => {
    startTransition(() => {
      setUser(localStorage.getItem("user"));
    });
  }, []);

  return <UserContext.Provider value={user}>{children}</UserContext.Provider>;
}
```

## Example

```text
  ⚠ /account 1.4s  1 warning
    HP2005 An update arrived before hydration finished
      This Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering. The usual way to fix this is to wrap the original update in startTransition.
      → Wrap updates triggered during hydration in startTransition.
```

## Related

- [HP2003: a Suspense boundary switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2003)
- [HP2006: the server could not finish a boundary](https://hydration.jscrate.dev/docs/issues/hp2006)
- [Suspense boundary received an update before hydrating](https://hydration.jscrate.dev/docs/errors/suspense-boundary-received-update-before-hydrating)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)

---

# HP2006: The server could not finish rendering a boundary

> HP2006 (server render error): the server failed to render a Suspense boundary, so the browser had to render it (React error #419). Where to look and the fix.

Source: https://hydration.jscrate.dev/docs/issues/hp2006
Last updated: 2026-09-18

HP2006 (`server-render-error`) means the server threw, or gave up, while
rendering part of the page inside a Suspense boundary. React sent the fallback
instead and rendered that part in the browser (React error #419). The problem is
on the server, not in hydration: check the server logs for the error it threw
while rendering that boundary.

| | |
| --- | --- |
| Code | `HP2006` |
| Name | `server-render-error` |
| Default severity | Error |
| Group | Problems React reported |
| What it means | The server failed to render part of the page and the client had to render it (React error 419). |

## What HP2006 (`server-render-error`) means

With streaming server rendering, an error inside a Suspense boundary does not
fail the whole response. React streams the boundary's fallback, and when the
page loads, the browser renders that boundary from scratch. Until it does,
users see the fallback where the content should be, and the browser does the
work the server should have done.

In a development build, React tells the browser why. In production the reason
stays on the server, and the browser only gets error #419.

## The React error it matches

```text
The server could not finish this Suspense boundary, likely due to an error during server rendering. Switched to client rendering.
Switched to client rendering because the server rendering errored:
Minified React error #419
```

The development message quotes the server's error after the colon, and it says
"aborted" instead of "errored" when the server stopped rendering, for example
after a timeout. See the [minified React error codes](https://hydration.jscrate.dev/docs/errors/minified-react-error-codes)
for #419.

## Likely causes

- A data request that fails on the server: an API that is unreachable from the
  test environment, a missing environment variable or credentials.
- Code that only works in the browser, such as a read of `window`, inside a
  component the server renders:
  [window is not defined](https://hydration.jscrate.dev/docs/errors/window-is-not-defined).
- A server render that is aborted before a slow boundary finishes.

## How to fix it

- Check the server logs: the server threw while rendering this Suspense
  boundary.

1. When hydration-proof started the app, the HTML report lists the error and
   warning lines the server printed while the page loaded. With `--url`, check
   the logs of the server you started.
2. Run `npx hydration-proof test --mode dev` to get the server's error message
   in the browser.
3. Fix the error, or make the component handle it (a guard, an error boundary)
   so the server can finish the boundary. If the test environment lacks data,
   an API or a secret the server needs, seed it with `hooks.setup` or add it to
   the server's environment.

## Example

```text
  ✖ /reports 2.1s  1 error
    HP2006 The server could not finish rendering a boundary
      Minified React error #419; visit https://react.dev/errors/419 for the full message or use the non-minified dev environment for full errors and additional helpful warnings. (React error #419)
      → Check the server logs: the server threw while rendering this Suspense boundary.
```

## Related

- [HP2003: a boundary switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2003)
- [HP2007: an uncaught error while loading](https://hydration.jscrate.dev/docs/issues/hp2007)
- [HP9005: the server answered with an error status](https://hydration.jscrate.dev/docs/issues/hp9005)
- [window is not defined](https://hydration.jscrate.dev/docs/errors/window-is-not-defined)
- [Reports: server logs and the timeline](https://hydration.jscrate.dev/docs/reports)

---

# HP2007: Uncaught error while loading the page

> HP2007 (page error): a script threw an uncaught error while the page loaded. It may or may not be related to hydration. How to read it, fix it or ignore it.

Source: https://hydration.jscrate.dev/docs/issues/hp2007
Last updated: 2026-09-18

HP2007 (`page-error`) means a script threw an error while the page loaded: an
uncaught exception, an unhandled promise rejection, or an error React reported
that is not about hydration. It may or may not be related to hydration. Read the message and stack, and fix the error or confirm
it only happens in the test environment.

| | |
| --- | --- |
| Code | `HP2007` |
| Name | `page-error` |
| Default severity | Warning |
| Group | Problems React reported |
| What it means | A script threw during page load. It may or may not be related to hydration. |

## What HP2007 (`page-error`) means

hydration-proof records every error the page raises while it loads. Errors
that are React hydration messages become HP2xxx codes or evidence for a DOM
finding; everything else becomes HP2007, with the first line of the message as
the finding and the stack as evidence. `console.error` and `console.warn` calls
are not reported this way.

It is a warning by default, since the error may have nothing to do with
hydration. If the same page also has [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) or
[HP2003](https://hydration.jscrate.dev/docs/issues/hp2003), check whether the error comes from the branch
React re-rendered.

Findings without an element are told apart by their message, so the same error
on the same route has the same fingerprint in every run.

## Likely causes

- Code that assumes data the page does not have in the test environment, such
  as an API that is not reachable or a signed-out user.
- A third-party script that fails in an automated browser.
- A real bug in code that runs on load: an effect, an event listener registered
  on load, a failed `fetch` whose rejection nobody handles.

## How to fix it

1. Open the finding in the HTML report: the evidence has the full stack, and
   the timeline shows which scripts and requests ran before the error.
2. Run `npx hydration-proof test --headed --workers 1 --route /account` to
   watch the page in a real browser window.
3. Fix the error. If it comes from the test environment, give the browser the
   data it needs with a scenario's `mocks`, or sign in with a scenario's
   `login`.

## When the difference is intentional

If the error is known and harmless (a third-party widget that fails without a
network, for example), add an `ignore.issues` rule with `code: "HP2007"`, the
route and a reason, or match its `fingerprint` to ignore only that error. See
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Example

```text
  ⚠ /account 1.3s  1 warning
    HP2007 Uncaught error while loading the page
      TypeError: Cannot read properties of undefined (reading 'map')
```

## Related

- [HP2002: React warned about a mismatch](https://hydration.jscrate.dev/docs/issues/hp2002)
- [HP2006: the server could not finish a boundary](https://hydration.jscrate.dev/docs/issues/hp2006)
- [Scenarios, sign-in and mocks](https://hydration.jscrate.dev/docs/scenarios)
- [Troubleshooting](https://hydration.jscrate.dev/docs/troubleshooting)

---

# HP3001: Invalid HTML nesting

> HP3001 (invalid-nesting) means the server HTML nests elements in a way HTML forbids, such as a div in a p. Why the browser repairs it and how to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp3001
Last updated: 2026-09-18

HP3001 (`invalid-nesting`) means the server HTML nests elements in a way HTML
does not allow, such as a `<div>` inside a `<p>`. The browser repairs the
markup while it parses it, so the DOM React hydrates no longer matches what
React rendered. Fix the nesting in the element the finding points at.

| | |
| --- | --- |
| Code | `HP3001` |
| Name | `invalid-nesting` |
| Default severity | Error |
| Group | Markup the browser repaired |
| What it means | The markup nests elements in a way HTML does not allow. Browsers repair it while parsing, so the DOM no longer matches what React rendered. |

## What the HP3001 invalid nesting finding means

hydration-proof reads the server HTML as React wrote it and compares it with
the tree the browser's own parser builds from the same bytes. Every element is
checked with React's own nesting rules, so the finding covers exactly the cases
React warns about in development. It names both elements and the position in
the server HTML:

```text
<div> cannot be a descendant of <p id="intro"> (line 1, column 2317). The browser moved it while parsing, so React cannot hydrate this markup.
```

The HTML parser closes an open `<p>` as soon as a block element starts, and it
adds a `<tbody>` around rows placed directly in a `<table>`:

```text
server HTML:  <p>Intro<div>Details</div></p>
browser DOM:  <p>Intro</p><div>Details</div><p></p>
```

When React hydrates, the nodes are no longer where it rendered them. React
reports a hydration error and renders that part of the page again on the
client, which usually shows up next to this finding as
[HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) or [HP1011](https://hydration.jscrate.dev/docs/issues/hp1011).

The finding is an error when the browser actually moved the element. When the
markup breaks the rules but this browser kept the nesting, it is a warning. A
link in a link, a button in a button or a form in a form is reported as
[HP3002](https://hydration.jscrate.dev/docs/issues/hp3002) instead.

## The React error it corresponds to

React logs the same problem in development builds only. hydration-proof reads
the server HTML, so it finds the nesting in production builds as well:

```text
In HTML, <div> cannot be a descendant of <p>. This will cause a hydration error.
validateDOMNesting(...): <div> cannot appear as a descendant of <p>
In HTML, <tr> cannot be a child of <table>. This will cause a hydration error.
```

[div cannot be a descendant of p](https://hydration.jscrate.dev/docs/errors/div-cannot-be-a-descendant-of-p)
and [validateDOMNesting](https://hydration.jscrate.dev/docs/errors/validatedomnesting) explain each message.

## Likely causes

The cause is always [invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html). It
usually looks like one of these:

- A block element inside a `<p>`: `<div>`, `<ul>`, `<ol>`, `<table>`,
  `<section>`, `<form>`, `<pre>`, `<blockquote>`, `<figure>` or a heading.
- A component that renders a `<div>`, used inside a `<p>`:
  `<p><Card /></p>`. Neither file looks wrong on its own.
- Table markup without its implied wrappers: `<tr>` directly in `<table>`,
  `<td>` directly in `<tbody>`, or a `<div>` between rows.
- A heading inside another heading, or a `<li>` inside another `<li>`.
- A second `<html>` or `<body>` rendered by a nested layout.

## How to fix it

1. Open the finding. It gives the element, the line and column in the server
   HTML and, in a development build, the source line of the component.
2. Change one of the two elements so the nesting is valid: use `<span>` instead
   of `<div>` inside a `<p>`, or turn the outer `<p>` into a `<div>`.
3. Wrap table rows in `<tbody>` and cells in `<tr>`.
4. Check components rendered inside a `<p>`. The problem is often one level
   down, in a component that renders a block element.

A `<div>` inside a `<p>`:

```tsx title="components/intro.tsx"
// Before: the browser closes the <p> when the <div> starts
export function Intro() {
  return (
    <p id="intro">
      Welcome back.
      <div className="details">Read the changelog below.</div>
    </p>
  );
}
```

```tsx title="components/intro.tsx"
// After: the block element is a sibling of the paragraph
export function Intro() {
  return (
    <div id="intro">
      <p>Welcome back.</p>
      <div className="details">Read the changelog below.</div>
    </div>
  );
}
```

Rows without a `<tbody>`:

```tsx title="components/rows.tsx"
export function Rows({ rows }: { rows: { id: string; name: string }[] }) {
  return (
    <table>
      <tbody>
        {rows.map((row) => (
          <tr key={row.id}>
            <td>{row.name}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}
```

## Catch it with ESLint

[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
reports block elements inside `<p>`, rows directly in `<table>` and nested
interactive elements while you type, in Server Components too. It sees nesting
inside one component only: `<p><Card /></p>` where `Card` renders a `<div>` is
something only the real server HTML shows.

## Example

```text
  ✖ /about 842ms  1 error
    HP3001 Invalid HTML nesting  (invalid html nesting, 97%)
      #intro  in Intro
      <div> cannot be a descendant of <p id="intro"> (line 1, column 2317). The browser moved it while parsing, so React cannot hydrate this markup.
      components/intro.tsx:4:5
      → Fix the nesting so the browser does not rewrite it, for example use <span> instead of <div> inside <p>.
```

## When the markup is not yours

Markup from a CMS or a third-party widget may be out of your hands for a while.
Ignore the finding with a reason and an expiry date, so it does not become
permanent:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    issues: [
      {
        code: "HP3001",
        route: "/legacy/**",
        reason: "CMS markup, fixed by the new editor",
        expires: "2026-12-31",
      },
    ],
  },
});
```

[Ignoring findings](https://hydration.jscrate.dev/docs/ignoring) covers selectors, attributes and rules.
`checks.invalidHtml: false` turns off every HP3xxx check at once.

## Related

- [HP3002: interactive element nested in another](https://hydration.jscrate.dev/docs/issues/hp3002)
- [Fix invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html)
- [The validateDOMNesting warning](https://hydration.jscrate.dev/docs/errors/validatedomnesting)
- [HP1010: React rendered a branch again](https://hydration.jscrate.dev/docs/issues/hp1010)
- [How hydration-proof compares the server HTML](https://hydration.jscrate.dev/docs/how-it-works)

---

# HP3002: Interactive element nested in another

> HP3002 (nested-interactive) means a link is inside a link, a button inside a button or a form inside a form. How the browser splits them and how to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp3002
Last updated: 2026-09-18

HP3002 (`nested-interactive`) means the server HTML puts a link inside another
link, a button inside another button or a form inside another form. HTML does
not allow it, so the browser splits the elements while parsing and the DOM no
longer matches React's tree. Move the inner element out of the outer one.

| | |
| --- | --- |
| Code | `HP3002` |
| Name | `nested-interactive` |
| Default severity | Error |
| Group | Markup the browser repaired |
| What it means | Links, buttons and forms cannot contain another element of the same kind. |

## What the HP3002 nested interactive finding means

It is a special case of [HP3001](https://hydration.jscrate.dev/docs/issues/hp3001): the same check of the
server HTML against React's nesting rules, reported under its own code when the
inner element has the same tag as the outer one (`<a>`, `<button>`, `<form>`,
or the legacy `<nobr>`).

The browser repairs each of them differently:

| Nesting                  | What the parser does                                                        |
| ------------------------ | --------------------------------------------------------------------------- |
| `<a>` in `<a>`           | Closes the outer link when the inner one starts, so the two become siblings |
| `<button>` in `<button>` | Closes the outer button, so the inner one moves after it                    |
| `<form>` in `<form>`     | Drops the inner `<form>` tag; its fields belong to the outer form           |

React then hydrates a DOM with a different shape than it rendered. The finding
is an error when the browser moved the element, and a warning when this
browser kept the nesting.

## The React error it corresponds to

In development, React logs the nesting before it reports the hydration error:

```text
In HTML, <a> cannot be a descendant of <a>. This will cause a hydration error.
<a> cannot contain a nested <a>
validateDOMNesting(...): <a> cannot appear as a descendant of <a>
```

The [validateDOMNesting](https://hydration.jscrate.dev/docs/errors/validatedomnesting) page lists the other
variants.

## Likely causes

The cause is [invalid HTML nesting](https://hydration.jscrate.dev/docs/causes/invalid-html), usually one of:

- A card that is one big link and also contains another link or a "Save"
  button.
- A `<Link>` component inside another `<Link>`: both render `<a>`.
- A disclosure or tab button that contains a close or menu button.
- A form component used inside a page that already wraps its content in a
  `<form>`.

## How to fix it

Do not nest links inside links, buttons inside buttons or forms inside forms.

1. **Make the card a container, not a link.** Put the main link on the title
   and stretch it over the card with CSS, and keep the other link or button as
   a sibling.
2. **Put buttons side by side.** A header button and its close button sit next
   to each other in a wrapper element.
3. **Associate controls with a form outside.** A button or input can belong to
   a form it is not inside, with the `form` attribute.

A card with a link inside a link:

```tsx title="components/post-card.tsx"
// Before: the browser closes the outer <a> when the inner one starts
export function PostCard({ post }: { post: Post }) {
  return (
    <a href={`/posts/${post.slug}`} className="card">
      <h3>{post.title}</h3>
      <a href={`/authors/${post.author.slug}`}>{post.author.name}</a>
    </a>
  );
}
```

```tsx title="components/post-card.tsx"
// After: one link per destination; CSS makes the title link cover the card
export function PostCard({ post }: { post: Post }) {
  return (
    <article className="card">
      <h3>
        <a href={`/posts/${post.slug}`} className="card-link">
          {post.title}
        </a>
      </h3>
      <a href={`/authors/${post.author.slug}`} className="card-author">
        {post.author.name}
      </a>
    </article>
  );
}
```

```css title="components/post-card.css"
.card {
  position: relative;
}
.card-link::after {
  content: "";
  position: absolute;
  inset: 0;
}
.card-author {
  position: relative;
  z-index: 1;
}
```

A delete button that needs its own form, inside an edit form:

```tsx title="components/edit-item.tsx"
export function EditItem({ id }: { id: string }) {
  return (
    <>
      <form action="/items/save" method="post">
        <input name="title" />
        <button type="submit">Save</button>
        <button type="submit" form={`delete-${id}`}>
          Delete
        </button>
      </form>
      <form id={`delete-${id}`} action={`/items/${id}/delete`} method="post" />
    </>
  );
}
```

## Catch it with ESLint

[`no-invalid-interactive-nesting`](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)
reports `<a>` in `<a>`, `<button>` in `<button>`, `<form>` in `<form>` and other
interactive content inside links and buttons, in Server Components as well.
Nesting that crosses a component boundary is only visible in the server HTML,
which is where this finding comes from.

## When you cannot change the markup yet

Add an `ignore.issues` rule with `code: "HP3002"`, a `reason` and an `expires`
date; see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring). The page still hydrates with a
different DOM until the markup is fixed.

## Related

- [HP3001: invalid HTML nesting](https://hydration.jscrate.dev/docs/issues/hp3001)
- [HP3003: duplicate id attribute](https://hydration.jscrate.dev/docs/issues/hp3003)
- [Invalid HTML nesting and its fixes](https://hydration.jscrate.dev/docs/causes/invalid-html)
- [React's validateDOMNesting warnings](https://hydration.jscrate.dev/docs/errors/validatedomnesting)
- [The no-invalid-interactive-nesting rule](https://hydration.jscrate.dev/docs/rules/no-invalid-interactive-nesting)

---

# HP3003: Duplicate id attribute

> HP3003 (duplicate-id) means several elements on the page share one id, so labels and ARIA references find only the first. Generate the ids with useId.

Source: https://hydration.jscrate.dev/docs/issues/hp3003
Last updated: 2026-09-18

HP3003 (`duplicate-id`) means several elements on the hydrated page share the
same `id`. Labels, ARIA references and `getElementById` then find only the
first one. It is an info finding, not a hydration mismatch: give every element
a unique id, and generate the ids of repeated components with `useId`.

| | |
| --- | --- |
| Code | `HP3003` |
| Name | `duplicate-id` |
| Default severity | Info |
| Group | Markup the browser repaired |
| What it means | Several elements share the same id. |

## What the HP3003 duplicate id finding means

After the page settles, hydration-proof checks the whole document for ids that
appear more than once:

```text
2 elements (<input>) have id="email". Labels, ARIA references and getElementById find only the first one.
```

A few details of the check:

- Ids inside `<template>` elements and shadow roots are not counted, and
  neither are elements you [ignore](https://hydration.jscrate.dev/docs/ignoring) with
  `[data-hydration-proof-ignore]` or `ignore.selectors`.
- At most 20 duplicate ids are reported per page.
- When the repeated id was generated by React's `useId` in two separate React
  roots, the finding is [HP3004](https://hydration.jscrate.dev/docs/issues/hp3004) instead, with a
  different fix.

Info findings do not fail the run and are not printed in the terminal list.
They appear in the HTML and JSON [reports](https://hydration.jscrate.dev/docs/reports).

## Likely causes

- A component with a hard-coded id used twice on a page, such as a newsletter
  form in both the header and the footer.
- Responsive layouts that render the desktop and the mobile version of the
  same navigation and hide one with CSS.
- SVG icons with fixed ids in `<defs>` (`<linearGradient id="gradient">`),
  rendered once per icon.
- Content from a CMS that repeats anchor ids.

## How to fix it

Give every element a unique id; generate ids for repeated components with
`useId`. It returns the same value on the server and during hydration, so it
does not create a mismatch.

```tsx title="components/newsletter-form.tsx"
// Before: every instance renders id="email"
export function NewsletterForm() {
  return (
    <form>
      <label htmlFor="email">Email</label>
      <input id="email" type="email" name="email" />
    </form>
  );
}
```

```tsx title="components/newsletter-form.tsx"
import { useId } from "react";

// After: each instance gets its own id
export function NewsletterForm() {
  const id = useId();
  return (
    <form>
      <label htmlFor={`${id}-email`}>Email</label>
      <input id={`${id}-email`} type="email" name="email" />
    </form>
  );
}
```

The same works for SVG definitions:

```tsx title="components/logo.tsx"
import { useId } from "react";

export function Logo() {
  const gradientId = useId();
  return (
    <svg viewBox="0 0 24 24" aria-hidden="true">
      <defs>
        <linearGradient id={gradientId}>
          <stop offset="0" stopColor="#0ea5e9" />
          <stop offset="1" stopColor="#6366f1" />
        </linearGradient>
      </defs>
      <circle cx="12" cy="12" r="10" fill={`url(#${gradientId})`} />
    </svg>
  );
}
```

Do not replace a hard-coded id with a counter or a random value: the server and
the browser would generate different ids, which turns this info finding into a
real [hydration mismatch](https://hydration.jscrate.dev/docs/causes/unstable-id).

## Catch it with ESLint

[`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) reports ids built from
`Math.random()`, `Date.now()` or module-level counters, the usual wrong fix for
a duplicate id. A hard-coded id repeated by two instances of a component is
only visible on the rendered page.

## When the duplicate is intentional

Add an `ignore.issues` rule with `code: "HP3003"`, the element's `selector` and
a `reason` (see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring)). `checks.invalidHtml: false`
turns off every HP3xxx check, including this one.

## Related

- [HP3004: two React roots generate the same ids](https://hydration.jscrate.dev/docs/issues/hp3004)
- [Generated ids that differ between renders](https://hydration.jscrate.dev/docs/causes/unstable-id)
- [The no-unstable-id ESLint rule](https://hydration.jscrate.dev/docs/rules/no-unstable-id)
- [HP3002: nested interactive elements](https://hydration.jscrate.dev/docs/issues/hp3002)
- [Reading the HTML and JSON reports](https://hydration.jscrate.dev/docs/reports)

---

# HP3004: Two React roots generate the same ids

> HP3004 (duplicate-use-id) means several React roots on one page call useId without an identifierPrefix and generate the same ids. Give each root a prefix.

Source: https://hydration.jscrate.dev/docs/issues/hp3004
Last updated: 2026-09-18

HP3004 (`duplicate-use-id`) means two or more React roots on the same page use
`useId` without an `identifierPrefix`, so each root generates the same ids.
Labels and ARIA references can then point at an element in the wrong root. Give
every root its own `identifierPrefix`, the same on the server and the client.

| | |
| --- | --- |
| Code | `HP3004` |
| Name | `duplicate-use-id` |
| Default severity | Warning |
| Group | Markup the browser repaired |
| What it means | Several React roots on the page use useId without an identifierPrefix, so they generate the same ids and labels or ARIA references can point at the wrong element. |

## What the HP3004 duplicate use id finding means

`useId` derives an id from the component's position in its root. Two roots with
the same shape start from the same position, so they produce the same ids:
`:R1:` in React 18, `«R1»` in React 19.0 and 19.1, `_R_1_` in React 19.2 and
later.

hydration-proof reports this code when an id that looks generated by `useId`
appears more than once and at least two hydrating roots on the page have no
`identifierPrefix`. Any other repeated id is [HP3003](https://hydration.jscrate.dev/docs/issues/hp3003). The
finding lists the roots without a prefix:

```text
2 elements (<input>) have the React-generated id "_R_0_". 2 React roots on this page use useId without an identifierPrefix, so each one generates the same ids.
Roots without identifierPrefix: #header, #app.
```

The page still hydrates without a mismatch. The bug is what the duplicate ids
connect: a `<label htmlFor>` in one root can focus an input in the other, and
`aria-describedby` can read out the wrong text.

## Likely causes

- A custom server that calls `hydrateRoot` several times, for example for a
  header widget and the main app.
- Micro-frontends or embedded widgets that each hydrate their own root.
- Astro islands: each `<astro-island>` is its own React root. Astro sets an
  `identifierPrefix` for its islands, so on Astro this finding means something
  else hydrates without one (see [Astro](https://hydration.jscrate.dev/docs/frameworks/astro)).

The [unstable id](https://hydration.jscrate.dev/docs/causes/unstable-id) cause covers the related problem of
a prefix that differs between the server and the client.

## How to fix it

Give every React root on the page its own `identifierPrefix`, and pass the same
value to the server render and to `hydrateRoot`, so the ids still match during
hydration:

```tsx title="server.tsx"
import { renderToString } from "react-dom/server";

const headerHtml = renderToString(<Header />, { identifierPrefix: "header-" });
const appHtml = renderToString(<App />, { identifierPrefix: "app-" });
```

```tsx title="entry-client.tsx"
import { hydrateRoot } from "react-dom/client";

hydrateRoot(document.getElementById("header")!, <Header />, {
  identifierPrefix: "header-",
});
hydrateRoot(document.getElementById("app")!, <App />, {
  identifierPrefix: "app-",
});
```

`renderToPipeableStream` and `renderToReadableStream` take the same
`identifierPrefix` option.

Or render the parts in one root, for example with portals, so `useId` generates
unique ids. Portals render on the client only, so this fits parts that do not
need server HTML.

## Catch it with ESLint

[`no-unstable-id`](https://hydration.jscrate.dev/docs/rules/no-unstable-id) keeps ids on `useId` instead of
random values or counters. The collision between roots depends on how the page
is assembled, so only a test of the rendered page finds it.

## When it is intentional

If the duplicate ids are never referenced (no labels, no ARIA attributes), you
can add an `ignore.issues` rule with `code: "HP3004"` and a `reason`; see
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring). A prefix is still the safer choice.

## Related

- [HP3003: duplicate id attribute](https://hydration.jscrate.dev/docs/issues/hp3003)
- [Generated id differs between server and client](https://hydration.jscrate.dev/docs/causes/unstable-id)
- [Astro islands and hydration-proof](https://hydration.jscrate.dev/docs/frameworks/astro)
- [Adapters and custom servers](https://hydration.jscrate.dev/docs/adapters)
- [HP3001: invalid HTML nesting](https://hydration.jscrate.dev/docs/issues/hp3001)

---

# HP4001: The page was modified before React hydrated

> HP4001 (pre-hydration-mutation) means a script, extension or third-party tag changed the server HTML before React hydrated it. Find the script and move it.

Source: https://hydration.jscrate.dev/docs/issues/hp4001
Last updated: 2026-09-18

HP4001 (`pre-hydration-mutation`) means something other than React changed the
server-rendered DOM after the browser parsed it and before React hydrated it: a
script, a browser extension or a third-party tag. React then hydrates markup it
did not render. Find the script and run it after hydration, or keep it out of
React's tree.

| | |
| --- | --- |
| Code | `HP4001` |
| Name | `pre-hydration-mutation` |
| Default severity | Error |
| Group | Changes made outside React |
| What it means | A script, browser extension or third-party tag changed the server-rendered DOM before hydration. |

## What the HP4001 pre-hydration mutation finding means

hydration-proof compares the tree the browser parsed from the server HTML with
the DOM right before React's first hydration commit. React's own streaming
moves (Suspense content revealed from the stream) are undone first, so what is
left was done by other code. The finding shows the value on each side:

```text
Text changed before hydration: "Pro" became "Pro (recommended)".
```

The severity depends on where the change happened:

| Where                                            | Severity                         |
| ------------------------------------------------ | -------------------------------- |
| On an element React renders, inside a React root | error                            |
| On `<html>`, `<body>` or `<head>`                | warning                          |
| Outside every React root                         | info (it cannot break hydration) |

Some changes are not reported: `<link>`, `<script>`, `<style>`, `<meta>` and
similar tags added to or removed from `<head>` (loaders, preloads and style
injection), changes that look like a browser extension (reported as
[HP4002](https://hydration.jscrate.dev/docs/issues/hp4002)), and text or attribute changes on an element
marked with `suppressHydrationWarning` (reported as
[HP6001](https://hydration.jscrate.dev/docs/issues/hp6001)).

## Likely causes

- [A script changed the page before hydration](https://hydration.jscrate.dev/docs/causes/third-party-script):
  A/B testing snippets, personalization or consent tools, translation widgets
  or an inline script of your own that sets text or classes.
- [A browser extension](https://hydration.jscrate.dev/docs/causes/extension) that rewrites text, such as a
  translator.
- A theme script that sets a class on `<html>` before hydration, without
  `suppressHydrationWarning` on that element.

## How to fix it

1. **Find the script.** The finding names the element and both values, and
   the HTML report's timeline shows which scripts loaded before hydration.
   Loading the page with the script blocked in your browser's developer tools
   confirms it.
2. **Run it after hydration.** Load third-party tags after the page is
   interactive, for example with `next/script` and
   `strategy="afterInteractive"` or `"lazyOnload"`.
3. **Or keep it out of React's tree.** A widget that renders into its own
   container appended to `<body>` does not touch elements React hydrates.
4. **For theme scripts,** mark the element the script changes (usually
   `<html>`) with `suppressHydrationWarning`. The change is then listed as an
   intentional difference instead.
5. **If a browser extension causes it,** it cannot be fixed in code; add an
   ignore rule for the extension's attributes.

Loading a tag after hydration in Next.js:

```tsx title="app/layout.tsx"
import Script from "next/script";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://cdn.example.com/widget.js" strategy="lazyOnload" />
      </body>
    </html>
  );
}
```

## Example

```text
  ✖ /pricing 1.3s  1 error
    HP4001 The page was modified before React hydrated  (a script changed the page before hydration, 80%)
      #plan-name
      server: "Pro"
      client: "Pro (recommended)"
      → Load the script after hydration (for example next/script with strategy="afterInteractive" or "lazyOnload"), or make it change only elements outside React's tree.
```

## When the change is expected

If a script you cannot move changes an element on purpose, ignore the element
with `ignore.selectors`, or the attribute with `ignore.attributes`, or add an
`ignore.issues` rule with `code: "HP4001"` and a `reason`. See
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring). `checks.externalChanges: false` turns off
every HP4xxx check.

## Related

- [HP4002: a browser extension changed the page](https://hydration.jscrate.dev/docs/issues/hp4002)
- [HP4003: HTML rewritten between the server and the browser](https://hydration.jscrate.dev/docs/issues/hp4003)
- [Third-party scripts that change the page](https://hydration.jscrate.dev/docs/causes/third-party-script)
- [How the pre-hydration DOM is captured](https://hydration.jscrate.dev/docs/how-it-works)
- [suppressHydrationWarning for theme scripts](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)

---

# HP4002: A browser extension changed the page

> HP4002 (extension-mutation) means a browser extension such as a grammar checker or password manager changed the page before hydration. When to ignore it.

Source: https://hydration.jscrate.dev/docs/issues/hp4002
Last updated: 2026-09-18

HP4002 (`extension-mutation`) means the page changed before hydration in a way
typical of browser extensions: grammar checkers, password managers, dark mode
tools. It is an info finding, because there is nothing to fix in your code.
Ignore it when it is expected, for example when your scenario simulates an
extension.

| | |
| --- | --- |
| Code | `HP4002` |
| Name | `extension-mutation` |
| Default severity | Info |
| Group | Changes made outside React |
| What it means | Changes typical of browser extensions (grammar checkers, password managers, translators) were found. |

## What the HP4002 extension mutation finding means

It comes from the same comparison as [HP4001](https://hydration.jscrate.dev/docs/issues/hp4001): the DOM the
browser parsed from the server HTML against the DOM right before React
hydrated. A change counts as an extension's when it:

- adds an attribute extensions are known for: `data-new-gr-c-s-check-loaded`,
  `data-gr-ext-installed` and `data-gramm` (Grammarly), `data-lt-installed`
  (LanguageTool), password manager and Dark Reader attributes,
  `data-ms-editor`, `cz-shortcut-listen` or `bis_*`;
- or inserts a custom element (a tag with a dash, such as
  `<grammarly-desktop-integration>`) directly into `<html>` or `<body>`.

Other changes an extension makes, such as a translator rewriting text, look like
any other script and are reported as HP4001.

Playwright starts the test browser with a clean profile, so HP4002 usually
means a scenario simulates an extension with `initScripts`, or the run uses a
browser profile that has extensions installed.

## The React warning your users see

Real users do have these extensions. In a React 18 development build, the
attributes a grammar checker adds to `<body>` produce this warning:

```text
Warning: Extra attributes from the server: data-new-gr-c-s-check-loaded,data-gr-ext-installed
```

[Extra attributes from the server](https://hydration.jscrate.dev/docs/errors/extra-attributes-from-the-server)
explains it. React 19 reports the same situation as
[attributes that didn't match](https://hydration.jscrate.dev/docs/errors/tree-hydrated-but-attributes-didnt-match).

## Likely causes

- [A browser extension](https://hydration.jscrate.dev/docs/causes/extension) in the test browser's profile.
- A scenario that simulates one on purpose, to check that the page survives it.

## How to fix it

This comes from a browser extension on the test machine or simulated by your
scenario; ignore it if it is expected.

1. If you did not expect it, test with a clean browser profile: the default
   Playwright browser has no extensions.
2. If you simulate an extension on purpose, ignore its attributes, so they are
   never compared, or ignore the code with a reason (below).
3. If the warning in your own console bothers you, `suppressHydrationWarning`
   on `<body>` stops React from reporting that element's own attributes. It
   does not cover anything inside `<body>`.

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ignore: {
    attributes: [/^data-gr-/, "data-new-gr-c-s-check-loaded"],
    issues: [
      { code: "HP4002", reason: "The extensions scenario simulates Grammarly" },
    ],
  },
});
```

Info findings do not fail the run and are not printed in the terminal list;
the HTML and JSON [reports](https://hydration.jscrate.dev/docs/reports) show them. See
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring) for every way to silence one.

## Related

- [HP4001: the page was modified before React hydrated](https://hydration.jscrate.dev/docs/issues/hp4001)
- [HP4003: HTML rewritten by a CDN or proxy](https://hydration.jscrate.dev/docs/issues/hp4003)
- [Hydration errors caused by browser extensions](https://hydration.jscrate.dev/docs/causes/extension)
- [Scenarios and initScripts](https://hydration.jscrate.dev/docs/scenarios)
- [HP6001: a mismatch hidden by suppressHydrationWarning](https://hydration.jscrate.dev/docs/issues/hp6001)

---

# HP4003: HTML was rewritten between the server and the browser

> HP4003 (html-rewritten) means a CDN, proxy or edge function changed the HTML your server produced before the browser got it. Turn off that HTML rewriting.

Source: https://hydration.jscrate.dev/docs/issues/hp4003
Last updated: 2026-09-18

HP4003 (`html-rewritten`) means the HTML the browser received differs from what
your origin server produced: a CDN, a proxy or an edge function rewrote it on
the way. React then hydrates markup it did not render. Turn off HTML
rewriting (minification, email obfuscation, injection) for server-rendered
pages.

| | |
| --- | --- |
| Code | `HP4003` |
| Name | `html-rewritten` |
| Default severity | Error |
| Group | Changes made outside React |
| What it means | The HTML the browser received differs from what the origin server produced (CDN minification, proxies, edge functions). |

## What the HP4003 html rewritten finding means

React expects the DOM to be exactly the HTML it rendered on the server. Any
layer between your server and the browser that edits the HTML breaks that:

- **Minification** removes whitespace or comments. Whitespace between elements
  is a text node React renders, and comments mark Suspense boundaries.
- **Email obfuscation** replaces email addresses in the text with a placeholder
  and a decoding script.
- **Injection** adds scripts, banners or analytics tags to the markup.

It is an error by default, because the whole page is affected, not one
component.

When only whitespace changed, the difference is usually reported on the element
as [HP1015](https://hydration.jscrate.dev/docs/issues/hp1015) with the cause
[HTML rewritten by a CDN or proxy](https://hydration.jscrate.dev/docs/causes/cdn). hydration-proof raises
its confidence when the response carries CDN headers such as `cf-ray`,
`x-amz-cf-id`, `x-served-by`, `x-cache` or `via`.

## Likely causes

- A CDN feature that minifies HTML (for example "Auto Minify").
- Email address obfuscation turned on for the zone.
- A reverse proxy, edge function or middleware that rewrites the response body.
- A hosting feature that injects scripts into every page.

All of them are the [CDN or proxy](https://hydration.jscrate.dev/docs/causes/cdn) cause.

## How to fix it

Disable HTML rewriting (minification, email obfuscation, injection) for
server-rendered pages at the CDN or proxy.

1. Compare a page served through the CDN with the same page from the origin
   (for example `curl` on both URLs and a diff).
2. Turn off HTML minification. JavaScript and CSS minification are fine; the
   HTML React hydrates must stay as rendered.
3. Turn off email obfuscation and script injection for the routes React
   renders, or render email addresses in a way the feature skips.
4. If an edge function must change the HTML, change the data the page renders
   instead, so React renders the final markup on both sides.

To reproduce the problem locally, test the app through the CDN URL:

```bash
npx hydration-proof test --url https://staging.example.com --route /
```

## When the rewrite is expected

If a proxy adds markup outside React's root on purpose, ignore it with
`ignore.selectors` or an `ignore.issues` rule with `code: "HP4003"` and a
`reason` (see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring)).
`checks.externalChanges: false` turns off every HP4xxx check.

## Related

- [HP1015: whitespace differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1015)
- [HTML rewritten by a CDN or proxy](https://hydration.jscrate.dev/docs/causes/cdn)
- [HP4001: the page was modified before React hydrated](https://hydration.jscrate.dev/docs/issues/hp4001)
- [HP4002: a browser extension changed the page](https://hydration.jscrate.dev/docs/issues/hp4002)
- [Errors that only happen in production](https://hydration.jscrate.dev/docs/guides/hydration-error-only-in-production)

---

# HP5001: An interaction before hydration was lost

> HP5001 (lost-interaction) means a click made while the page loaded did nothing, because the button looked ready before React handled events. How to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp5001
Last updated: 2026-09-18

HP5001 (`lost-interaction`) means a click made while the page was still loading
had no effect: the server-rendered button was visible before React could
handle its events. The same click after hydration works. Keep the control
disabled until the page is interactive, or make it work without JavaScript.

| | |
| --- | --- |
| Code | `HP5001` |
| Name | `lost-interaction` |
| Default severity | Warning |
| Group | Interaction during hydration |
| What it means | A click made while the page was loading had no effect: the page looked ready before React could handle events. |

## What the HP5001 lost interaction finding means

Server rendering shows the page before its JavaScript has loaded. Until React
has hydrated and attached its event listeners, a button is only HTML: a click
on it runs no handler, and the user has no way to tell.

The finding comes from the [interaction checks](https://hydration.jscrate.dev/docs/interactions), which run
with `checks.interactions: true` or `--interactions`. hydration-proof finds the
first button outside forms and links, then loads the page four times: twice
without a click (to make sure the page renders the same each time), once with
a click after hydration and once with a click while the page's scripts are held
back. If the late click changes the page and the early one does not, the click
was lost:

```text
A click on this button while the page was loading did nothing; the same click after hydration changes the page.
```

It is a warning: the page works, but it looks ready before it is. On a slow
connection, that window can last seconds.

## Likely causes

- A large JavaScript bundle for the first view, so hydration starts late.
- An important control inside a part of the page that hydrates last.
- Buttons that only work through a React `onClick`, with no form or link behind
  them.

## How to fix it

### Disable the control until the page is interactive

Show it as disabled or loading. The server and the first client render agree,
and an effect enables it:

```tsx title="components/add-to-cart.tsx"
"use client";

import { useEffect, useState } from "react";

export function AddToCart({ onAdd }: { onAdd: () => void }) {
  const [ready, setReady] = useState(false);
  useEffect(() => setReady(true), []);

  return (
    <button type="button" disabled={!ready} onClick={onAdd}>
      {ready ? "Add to cart" : "Loading…"}
    </button>
  );
}
```

### Make it work without JavaScript

Links navigate and forms submit before hydration. With a Server Action, the
same form works in both cases:

```tsx title="app/product/[id]/add-to-cart.tsx"
import { addToCart } from "./actions";

export function AddToCart({ productId }: { productId: string }) {
  return (
    <form action={addToCart}>
      <input type="hidden" name="productId" value={productId} />
      <button type="submit">Add to cart</button>
    </form>
  );
}
```

### Hydrate important controls first

Ship less JavaScript for the first view. Suspense boundaries hydrate in order
of interaction, so splitting the page into boundaries lets React start with
the part the user touches.

## When it is acceptable

If a short dead window is fine for your app, add an `ignore.issues` rule with
`code: "HP5001"` and a `reason`; see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Related

- [HP5002: user input was reset during hydration](https://hydration.jscrate.dev/docs/issues/hp5002)
- [HP5003: focus lost during hydration](https://hydration.jscrate.dev/docs/issues/hp5003)
- [Interaction and navigation checks](https://hydration.jscrate.dev/docs/interactions)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [What hydration is and why it takes time](https://hydration.jscrate.dev/docs/guides/what-is-hydration)

---

# HP5002: User input was reset during hydration

> HP5002 (input-reset) means text typed or a box checked before hydration finished was cleared or replaced. Keep what users type with uncontrolled inputs.

Source: https://hydration.jscrate.dev/docs/issues/hp5002
Last updated: 2026-09-18

HP5002 (`input-reset`) means text a user typed, or a checkbox they checked,
before the page finished hydrating was cleared or replaced when React took
over. The user loses their input without a warning. Use uncontrolled inputs or
read the current DOM value on mount, and fix any hydration mismatch around the
form.

| | |
| --- | --- |
| Code | `HP5002` |
| Name | `input-reset` |
| Default severity | Error |
| Group | Interaction during hydration |
| What it means | Text typed or an option chosen before hydration finished was cleared or replaced. |

## What the HP5002 input reset finding means

The finding comes from the [interaction checks](https://hydration.jscrate.dev/docs/interactions)
(`checks.interactions: true` or `--interactions`). hydration-proof loads the
page with its scripts held back, like a user on a slow connection, types
`hydration-proof check` into the first text field and checks the first
checkbox. Then it lets the page hydrate and reads the controls again:

```text
Text typed into this field before the page finished hydrating was cleared.
A checkbox checked before the page finished hydrating was unchecked by hydration.
```

When React replaced the field itself, the finding adds: "React replaced the
field during hydration, so the new field lost what was typed." It is an error,
because the user's work is gone.

## Likely causes

- A hydration mismatch in the form or around it. React throws away that
  branch and renders it again, with new, empty inputs; the finding usually
  sits next to [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) or [HP1011](https://hydration.jscrate.dev/docs/issues/hp1011).
- An effect that sets the value on mount, such as restoring a saved draft or a
  value from the URL.
- Controlled inputs whose state is reset by a re-render during hydration.
- [Server Action form state](https://hydration.jscrate.dev/docs/causes/form-state) that the client hydrates
  without.

## How to fix it

1. **Fix any hydration mismatch around the form.** A re-rendered branch creates
   new, empty inputs, so this comes first.
2. **Use uncontrolled inputs** (`defaultValue`, `defaultChecked`). The browser
   keeps what was typed, and React hydrates the field as it is.
3. **Or read the current DOM value when the component mounts,** so text typed
   before hydration is kept in state.

An effect that overwrites the field:

```tsx title="components/search.tsx"
"use client";

import { useEffect, useState } from "react";

// Before: restoring the last query replaces what the user typed
export function Search() {
  const [query, setQuery] = useState("");
  useEffect(() => {
    setQuery(sessionStorage.getItem("last-query") ?? "");
  }, []);
  return (
    <input value={query} onChange={(event) => setQuery(event.target.value)} />
  );
}
```

```tsx title="components/search.tsx"
"use client";

import { useEffect, useRef, useState } from "react";

// After: what the user already typed wins over the saved value
export function Search() {
  const inputRef = useRef<HTMLInputElement>(null);
  const [query, setQuery] = useState("");
  useEffect(() => {
    const typed = inputRef.current?.value ?? "";
    setQuery(
      typed !== "" ? typed : (sessionStorage.getItem("last-query") ?? "")
    );
  }, []);
  return (
    <input
      ref={inputRef}
      value={query}
      onChange={(event) => setQuery(event.target.value)}
    />
  );
}
```

An uncontrolled field needs none of this:

```tsx title="components/newsletter.tsx"
export function Newsletter() {
  return (
    <form action="/subscribe" method="post">
      <input name="email" type="email" defaultValue="" />
      <label>
        <input name="weekly" type="checkbox" defaultChecked={false} /> Weekly
      </label>
      <button type="submit">Subscribe</button>
    </form>
  );
}
```

## When it is acceptable

A field that should reset on load (a one-time code, for example) can be
ignored with an `ignore.issues` rule for `code: "HP5002"`, its `route` and a
`reason`; see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Related

- [HP5003: focus was lost during hydration](https://hydration.jscrate.dev/docs/issues/hp5003)
- [HP5001: a click before hydration was lost](https://hydration.jscrate.dev/docs/issues/hp5001)
- [HP1012: form state differs between server and client](https://hydration.jscrate.dev/docs/issues/hp1012)
- [Interaction checks](https://hydration.jscrate.dev/docs/interactions)
- [HP1010: React rendered a branch again](https://hydration.jscrate.dev/docs/issues/hp1010)

---

# HP5003: Focus was lost during hydration

> HP5003 (focus-lost) means the field a user focused, or the text they selected, was lost while the page hydrated. Why it happens and how to keep focus.

Source: https://hydration.jscrate.dev/docs/issues/hp5003
Last updated: 2026-09-18

HP5003 (`focus-lost`) means the element that had focus, or the text selected
in it, was lost while the page hydrated. A user who started typing before the
page was ready suddenly types into nothing. Avoid re-creating the focused
element during hydration, and do not move focus in effects that run on load.

| | |
| --- | --- |
| Code | `HP5003` |
| Name | `focus-lost` |
| Default severity | Warning |
| Group | Interaction during hydration |
| What it means | The focused element or the text selection was lost during hydration. |

## What the HP5003 focus lost finding means

The finding comes from the [interaction checks](https://hydration.jscrate.dev/docs/interactions)
(`checks.interactions: true` or `--interactions`). With the page's scripts
held back, hydration-proof focuses the first text field and selects text in
it, then lets the page hydrate and checks both again:

```text
The text field that had focus before hydration lost it while the page hydrated.
The text selection in the field changed from 0-5 to 0-0 while the page hydrated.
```

Losing focus is reported with higher confidence than a changed selection. Both
are warnings.

## Likely causes

- A hydration mismatch around the field: React throws away that branch and
  renders a new field, which has no focus. Look for
  [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010) on the same page.
- An effect that calls `focus()` on another element when the page loads, such
  as a search box or a dialog.
- A value set on the field during hydration, which resets the selection (see
  [HP5002](https://hydration.jscrate.dev/docs/issues/hp5002)).

## How to fix it

Avoid re-creating the focused element during hydration (fix mismatches around
it), and do not move focus in effects that run on load.

1. Fix the hydration findings on the same page first; a replaced branch is the
   most common cause.
2. Move focus only in response to a user action, or only when nothing else has
   focus yet:

```tsx title="components/search-box.tsx"
"use client";

import { useEffect, useRef } from "react";

export function SearchBox() {
  const inputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    // Before: inputRef.current?.focus() took focus from the field in use
    if (document.activeElement === document.body) {
      inputRef.current?.focus({ preventScroll: true });
    }
  }, []);

  return <input ref={inputRef} type="search" name="q" />;
}
```

## When it is acceptable

If the page moves focus on purpose (a dialog that opens on load), ignore
`code: "HP5003"` for that route with a `reason`; see
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Related

- [HP5002: user input was reset during hydration](https://hydration.jscrate.dev/docs/issues/hp5002)
- [HP5007: scroll position reset during hydration](https://hydration.jscrate.dev/docs/issues/hp5007)
- [Interaction and navigation checks](https://hydration.jscrate.dev/docs/interactions)
- [HP1010: React discarded server HTML for a branch](https://hydration.jscrate.dev/docs/issues/hp1010)

---

# HP5004: The page differs after client-side navigation

> HP5004 (navigation-mismatch) means a route renders different content when reached through the app's router than when its URL is loaded directly. Fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp5004
Last updated: 2026-09-18

HP5004 (`navigation-mismatch`) means a route renders different content when you
reach it through the app's router than when you load its URL directly. Users
who arrive from a link see one page, users who reload see another. Render the
route from its own data (params, search params, server data), not from the
previous page or client state.

| | |
| --- | --- |
| Code | `HP5004` |
| Name | `navigation-mismatch` |
| Default severity | Warning |
| Group | Interaction during hydration |
| What it means | Navigating to the route inside the app renders different content than loading the URL directly. |

## What the HP5004 navigation mismatch finding means

The finding comes from the [navigation checks](https://hydration.jscrate.dev/docs/interactions)
(`checks.navigation: true` or `--navigation`). hydration-proof opens a page,
navigates to each route with the app's router (`router.push` in Next.js, the
data router in React Router and Remix) and compares the result with a direct
load. Both loads use the same fixed browser clock and random seed, and numbers
are ignored in the comparison, so time and random values do not cause it:

```text
Navigating to this route from another page renders different content than loading /settings directly (2 differences).
```

The check runs twice per route when the router supports prefetching: once as a
plain navigation and once after the router prefetched the route.

It is a warning. Routes that render parallel routes (`@slot` folders) or that
an intercepting route can replace are reported as info, because the difference
is usually intended there.

## Likely causes

- A layout that keeps state between navigations, such as a selected tab or an
  open panel.
- Module-level variables or a client store filled in by the previous page.
- A component that depends on the previous route, the referrer or history
  state.
- [Different data](https://hydration.jscrate.dev/docs/causes/data) on the client: the route fetches again
  after navigation and gets another result.

## How to fix it

1. **Read data from the route.** Params, search params and server data are the
   same for a direct load and a navigation; the previous page's state is not.
2. **Check layouts that keep state between navigations** and components that
   depend on the previous route. Reset that state when the route changes, or
   move it into the URL.

```tsx title="app/settings/tabs.tsx"
"use client";

import { useSearchParams } from "next/navigation";
import { useSettingsStore } from "./store";

// Before: the tab comes from a store the previous page filled in
export function useActiveTabBefore() {
  return useSettingsStore((state) => state.activeTab);
}

// After: the tab comes from the URL, the same on every kind of load
export function useActiveTab() {
  return useSearchParams().get("tab") ?? "profile";
}
```

To start the navigation from a specific page, set `checks.navigation.from`, or
`navigateFrom` on the route.

## When the difference is intended

A modal from an intercepting route or a slot that keeps its page can differ on
purpose. Add an ignore rule for the route:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  checks: { navigation: true },
  ignore: {
    issues: [
      {
        code: "HP5004",
        route: "/photos/*",
        reason: "Opens as a modal after navigation",
      },
    ],
  },
});
```

See [ignoring findings](https://hydration.jscrate.dev/docs/ignoring) for the other fields.

## Related

- [HP5005: client-side navigation failed](https://hydration.jscrate.dev/docs/issues/hp5005)
- [Interaction and navigation checks](https://hydration.jscrate.dev/docs/interactions)
- [Server and client used different data](https://hydration.jscrate.dev/docs/causes/data)
- [Routes and route options](https://hydration.jscrate.dev/docs/routes)
- [HP5001: a click before hydration was lost](https://hydration.jscrate.dev/docs/issues/hp5001)

---

# HP5005: Client-side navigation failed

> HP5005 (navigation-error) means navigating to a route inside the app threw an error, its RSC or data request failed, or the URL never changed. How to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp5005
Last updated: 2026-09-18

HP5005 (`navigation-error`) means navigating to the route inside the app failed:
the navigation threw an error, its data request (an RSC request in Next.js)
failed, or the URL never changed. The route works when loaded directly and
breaks when users click a link to it. Open it through a link and check the
console and network tab.

| | |
| --- | --- |
| Code | `HP5005` |
| Name | `navigation-error` |
| Default severity | Error |
| Group | Interaction during hydration |
| What it means | Navigating to the route inside the app threw an error, its data request failed, or the URL never changed. |

## What the HP5005 navigation error finding means

The finding comes from the [navigation checks](https://hydration.jscrate.dev/docs/interactions)
(`checks.navigation: true` or `--navigation`). hydration-proof opens another
page, navigates to the route with the app's router and records what happens
after the navigation starts:

- an uncaught error on the page;
- an RSC request for the route that fails or answers with a status of 400 or
  more;
- a URL that never changes to the route.

The first problem is in the message, and every problem is listed as evidence:

```text
Navigating to this route from another page failed: The RSC request /dashboard?_rsc=1m2k3 answered 500.
```

RSC requests and prefetches also appear in the report's timeline. It is an
error. A navigation that the framework turns into a full page load (for
example to another root layout) is noted in the timeline, not reported.

## Likely causes

- A Server Component of the route that throws for RSC requests, for example
  because it reads a header or cookie that only a full page request has.
- Middleware or a proxy that blocks or redirects RSC requests.
- A loader or data request that fails when called from the client.
- A client component that throws while rendering the new route.

## How to fix it

1. Open the route through a link in the browser and check the console and the
   network tab for the failed request.
2. Make sure Server Components of the route do not throw for requests that come
   from client-side navigation (RSC requests).
3. Run only this route to reproduce it quickly, with the browser visible
   (below).
4. To navigate from a specific page, set `navigateFrom` on the route, or
   `checks.navigation.from` for all of them; see [routes](https://hydration.jscrate.dev/docs/routes).

```bash
npx hydration-proof test --navigation --route /dashboard --headed
```

## When it is expected

A route that is only reachable by a full page load can be ignored with an
`ignore.issues` rule for `code: "HP5005"` and its `route`; see
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Related

- [HP5004: the page differs after client-side navigation](https://hydration.jscrate.dev/docs/issues/hp5004)
- [Interaction and navigation checks](https://hydration.jscrate.dev/docs/interactions)
- [HP9004: the page could not be loaded](https://hydration.jscrate.dev/docs/issues/hp9004)
- [HP2007: uncaught error while loading the page](https://hydration.jscrate.dev/docs/issues/hp2007)
- [Testing Next.js apps](https://hydration.jscrate.dev/docs/frameworks/nextjs)

---

# HP5006: An element handles the same event twice

> HP5006 (double-handler) means a script listener or inline on* attribute handles an event React also handles on that element, so one click can run twice.

Source: https://hydration.jscrate.dev/docs/issues/hp5006
Last updated: 2026-09-18

HP5006 (`double-handler`) means an element has a React event handler and, for
the same event, a listener added by a script or an inline `on*` attribute. One
click, submit or key press can then run two actions: a double submit, a double
tracking event. Handle the event in one place.

| | |
| --- | --- |
| Code | `HP5006` |
| Name | `double-handler` |
| Default severity | Warning |
| Group | Interaction during hydration |
| What it means | A script or an inline handler attribute handles an event on an element that React also handles, so one action can run twice. |

## What the HP5006 double handler finding means

React handles events at the root of the app. A listener added directly to the
element with `addEventListener`, or an `onclick` attribute in the HTML, runs in
addition to it. hydration-proof records the listeners page scripts add to
elements and compares them with the React props of each element during
hydration:

```text
React handles "click" on this element, and so does a script listener or an inline onclick attribute. One action can run twice.
```

The events it tracks are `click`, `submit`, `input`, `change`, `keydown` and
`keyup`. The check is part of the props audit (`checks.propsAudit`, on by
default), so it runs on every page without `--interactions`. It is a warning,
and it is not reported on elements marked with `suppressHydrationWarning`.

## Likely causes

- An analytics or tag manager script that attaches click listeners to buttons
  and links.
- An older script, such as a jQuery plugin, that enhances the same form React
  renders.
- Server HTML post-processed to add `onclick` or `onsubmit` attributes.
- A [script that changes the page](https://hydration.jscrate.dev/docs/causes/third-party-script) before
  hydration and adds handlers while it does.

## How to fix it

Handle the event in one place: remove the inline `on*` attribute or the script
that adds the listener, or remove the React handler.

When the extra listener only tracks the click, call the tracking code from the
React handler and stop the script from attaching its own:

```tsx title="components/buy-button.tsx"
import { track } from "@/lib/analytics";

export function BuyButton({ onBuy }: { onBuy: () => void }) {
  return (
    <button
      type="button"
      onClick={() => {
        track("buy");
        onBuy();
      }}
    >
      Buy
    </button>
  );
}
```

If the script must stay, check that the two handlers do different things and
that neither submits or navigates twice.

## When it is intentional

If both handlers are meant to run, add an `ignore.issues` rule with
`code: "HP5006"`, the element's `selector` and a `reason`; see
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Related

- [HP5001: a click before hydration was lost](https://hydration.jscrate.dev/docs/issues/hp5001)
- [HP4001: the page was modified before React hydrated](https://hydration.jscrate.dev/docs/issues/hp4001)
- [Scripts that change the page before hydration](https://hydration.jscrate.dev/docs/causes/third-party-script)
- [Configuration: checks](https://hydration.jscrate.dev/docs/configuration)

---

# HP5007: Scroll position was reset during hydration

> HP5007 (scroll-reset) means the page scrolled on its own while it hydrated, so a user who had already scrolled lost their place. Why and how to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp5007
Last updated: 2026-09-18

HP5007 (`scroll-reset`) means the page scrolled on its own while it hydrated.
A user who had already scrolled down to read lost their place. It usually comes
from code that scrolls or moves focus when the page loads. Do not change the
scroll position during hydration; let the browser restore it.

| | |
| --- | --- |
| Code | `HP5007` |
| Name | `scroll-reset` |
| Default severity | Warning |
| Group | Interaction during hydration |
| What it means | The page scrolled on its own while it hydrated, so the user lost their place. |

## What the HP5007 scroll reset finding means

The finding comes from the [interaction checks](https://hydration.jscrate.dev/docs/interactions)
(`checks.interactions: true` or `--interactions`). With the page's scripts
held back, hydration-proof scrolls down, lets the page hydrate and compares the
scroll position. A change of more than 50 pixels is reported:

```text
The page was scrolled to 1200px before hydration and ended at 0px.
```

Pages without scrollable content are skipped. It is a warning.

## Likely causes

- `window.scrollTo(0, 0)` in an effect that runs on mount, often meant to
  reset the scroll on route changes.
- `focus()` on load, which scrolls the focused element into view.
- A hydration mismatch that replaces a large part of the page, so the content
  under the reader changes height.

## How to fix it

Do not change the scroll position during hydration (`scrollTo` in effects,
`focus()` on load); let the browser restore it.

```tsx title="components/search-field.tsx"
"use client";

import { useEffect, useRef } from "react";

export function SearchField() {
  const inputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    // Before: inputRef.current?.focus() scrolled the page to the field
    inputRef.current?.focus({ preventScroll: true });
  }, []);

  return <input ref={inputRef} type="search" name="q" />;
}
```

Leave scrolling on navigation to the framework's router: it restores the
position on back and forward and scrolls to the top on new pages, without
running on the first load.

## When it is intentional

A page that jumps to a section on purpose can be ignored with an
`ignore.issues` rule for `code: "HP5007"` and its `route`; see
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Related

- [HP5003: focus was lost during hydration](https://hydration.jscrate.dev/docs/issues/hp5003)
- [HP5002: user input was reset during hydration](https://hydration.jscrate.dev/docs/issues/hp5002)
- [Interaction checks](https://hydration.jscrate.dev/docs/interactions)
- [HP1011: React discarded the whole server-rendered page](https://hydration.jscrate.dev/docs/issues/hp1011)

---

# HP5008: A custom interaction failed

> HP5008 (interaction-failed) means an interaction from your config threw an error or caused a page error. Run it in a headed browser to see where it fails.

Source: https://hydration.jscrate.dev/docs/issues/hp5008
Last updated: 2026-09-18

HP5008 (`interaction-failed`) means one of the custom interactions in your
config threw an error, or caused an uncaught error on the page while it ran.
Either the steps no longer match the page, or the page breaks when a user does
the same thing. Run the interaction in a headed browser to see where it fails.

| | |
| --- | --- |
| Code | `HP5008` |
| Name | `interaction-failed` |
| Default severity | Error |
| Group | Interaction during hydration |
| What it means | An interaction from the config threw an error or caused a page error. |

## What the HP5008 interaction failed finding means

Custom interactions are Playwright steps you add under `interactions` in the
config. Each one runs on the routes it matches, after hydration by default or
with the page's scripts held back (`when: "before-hydration"`). hydration-proof
reports the interaction by name:

```text
"continue to payment" failed: locator.click: Timeout 30000ms exceeded.
"continue to payment" caused an error on the page: TypeError: Cannot read properties of undefined (reading 'total')
```

Uncaught errors count only when they happen after the steps started. The page
errors are listed as evidence. It is an error, because either the test or the
page is broken.

## Likely causes

- A selector in the steps that no longer matches, after a change to the page.
- Steps that wait for something the page never shows.
- A `before-hydration` interaction that expects React to handle an event: while
  the scripts are held back, only plain HTML behavior works.
- A real bug: the page throws when a user does these steps.
- The page did not hydrate, so the steps never ran; the message says so.

## How to fix it

1. Run the interaction in a headed browser (`--headed`) to see where it
   fails; the command is below.
2. If a step fails, update the locator or the wait in the config. Locators by
   role or label (`getByRole`, `getByLabel`) survive markup changes better
   than CSS selectors.
3. If the page throws, fix the page: the finding's evidence has the error.
4. If a page did not hydrate, look at that page's own findings first, such as
   [HP9001](https://hydration.jscrate.dev/docs/issues/hp9001).

```bash
npx hydration-proof test --route /checkout --headed --workers 1
```

A step that finds its elements by label and role:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  interactions: [
    {
      route: "/checkout",
      name: "continue to payment",
      steps: async ({ page }) => {
        await page.getByLabel("Email").fill("test@example.com");
        await page.getByRole("button", { name: "Continue" }).click();
        await page.getByText("Payment").waitFor();
      },
    },
  ],
});
```

[Interactions](https://hydration.jscrate.dev/docs/interactions) documents every field, including `when` and
`scenarios`.

## Related

- [Interaction and navigation checks](https://hydration.jscrate.dev/docs/interactions)
- [HP5001: a click before hydration was lost](https://hydration.jscrate.dev/docs/issues/hp5001)
- [HP2007: uncaught error while loading the page](https://hydration.jscrate.dev/docs/issues/hp2007)
- [Configuration reference](https://hydration.jscrate.dev/docs/configuration)
- [The CLI and its flags](https://hydration.jscrate.dev/docs/cli)

---

# HP6001: Mismatch hidden by suppressHydrationWarning

> HP6001 (suppressed-mismatch) lists a server and client difference hidden by suppressHydrationWarning. When it is fine, and when it hides a real bug.

Source: https://hydration.jscrate.dev/docs/issues/hp6001
Last updated: 2026-09-18

HP6001 (`suppressed-mismatch`) means the server and client values differ on an
element marked with `suppressHydrationWarning`. React does not report the
difference and keeps the server value. That is fine for intentional
differences such as timestamps or a theme class; check that this one is, and
keep the attribute on the smallest element possible.

| | |
| --- | --- |
| Code | `HP6001` |
| Name | `suppressed-mismatch` |
| Default severity | Info |
| Group | suppressHydrationWarning audit |
| What it means | The server and client values differ on an element marked with suppressHydrationWarning. React keeps the server value. |

## What the HP6001 suppressed mismatch finding means

`suppressHydrationWarning` silences React for one element's own text and
attributes. hydration-proof still compares them, and lists every difference it
hides, so you know what you are suppressing:

```text
Server rendered "10:04:31", the client rendered "10:04:33" (suppressHydrationWarning).
```

It finds them in three places:

- the text and attributes React renders for the marked element, compared with
  the server HTML;
- text that React 18 replaced during hydration on a marked element;
- changes a script made to a marked element before hydration, such as a theme
  script that sets a class on `<html>` (this would otherwise be
  [HP4001](https://hydration.jscrate.dev/docs/issues/hp4001)).

The cause is always [intentional difference](https://hydration.jscrate.dev/docs/causes/suppressed).

### When HP6001 is a warning

The finding is info when the hidden difference looks intentional: the time, a
timezone, a locale, a random value, the theme or a browser extension. When it
looks like something else, such as browser storage, a browser-only API or
different data, it is raised to a warning with this note:

```text
suppressHydrationWarning hides a difference that does not look intentional (localStorage / sessionStorage read during render).
```

That usually means the attribute was added to make an error go away, and users
see the wrong server value until the next render.

## Likely causes

- A timestamp or relative time rendered on both sides, the classic use of the
  attribute (see [time](https://hydration.jscrate.dev/docs/causes/time)).
- A theme script that sets a class or `data-theme` on `<html>` before React
  hydrates (see [theme](https://hydration.jscrate.dev/docs/causes/theme)).
- A value read from storage or `window` and hidden instead of fixed.

## How to fix it

This is fine if the difference is intentional (timestamps, for example). Keep
`suppressHydrationWarning` on the smallest element possible.

The two patterns it exists for:

```tsx title="app/layout.tsx"
// A theme script changes the class on <html> before hydration
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>{children}</body>
    </html>
  );
}
```

```tsx title="components/updated-at.tsx"
// The time on the element itself, not on a wrapper
export function UpdatedAt({ iso }: { iso: string }) {
  return (
    <time dateTime={iso} suppressHydrationWarning>
      {new Date(iso).toLocaleTimeString()}
    </time>
  );
}
```

When the finding is a warning, fix the cause instead: read storage and browser
APIs in an effect, or send the server's data to the client. Then remove the
attribute.

## Configure the audit

`checks.suppressedWarnings` controls the whole HP6xxx group:

| Value              | Effect                                                                            |
| ------------------ | --------------------------------------------------------------------------------- |
| `'info'` (default) | Lists hidden differences as HP6001                                                |
| `'strict'`         | Also reports suppression with nothing to suppress ([HP6003](https://hydration.jscrate.dev/docs/issues/hp6003)) |
| `'off'`            | Drops HP6xxx findings from the report                                             |

Info findings do not fail the run and are not printed in the terminal list;
the HTML and JSON reports show them. To silence a single one, see
[ignoring findings](https://hydration.jscrate.dev/docs/ignoring).

## Catch it with ESLint

[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
reports the attribute where it has no effect or covers more than one element's
text, and with `reportAll: true` every use.

## Related

- [When suppressHydrationWarning is safe](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [HP6002: suppression cannot hide a structural difference](https://hydration.jscrate.dev/docs/issues/hp6002)
- [HP6003: suppressHydrationWarning with nothing to suppress](https://hydration.jscrate.dev/docs/issues/hp6003)
- [Theme preference and dark mode](https://hydration.jscrate.dev/docs/causes/theme)
- [The audit-suppress-hydration-warning rule](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)

---

# HP6002: suppressHydrationWarning cannot hide a structural difference

> HP6002 (suppression-hides-structure) means suppressHydrationWarning is set, but the elements inside still differ, so React re-renders them. How to fix it.

Source: https://hydration.jscrate.dev/docs/issues/hp6002
Last updated: 2026-09-18

HP6002 (`suppression-hides-structure`) means an element is marked with
`suppressHydrationWarning`, but the elements inside it differ between the
server and the client. The attribute only covers the element's own text and
attributes, one level deep, so React still re-renders that part. Fix the
structural difference instead of suppressing it.

| | |
| --- | --- |
| Code | `HP6002` |
| Name | `suppression-hides-structure` |
| Default severity | Error |
| Group | suppressHydrationWarning audit |
| What it means | suppressHydrationWarning only covers text and attributes one level deep; the elements inside still differ. |

## What the HP6002 suppression hides structure finding means

`suppressHydrationWarning` tells React to accept a different text or attribute
value on one element. It does not cover:

- elements inserted or removed inside the marked element;
- a different tag in the same place;
- text or attributes of its children.

When hydration-proof finds one of these inside a marked element, it reports
this code:

```text
suppressHydrationWarning is set here, but the elements inside differ between server and client, so React still re-renders them.
```

Differences in a descendant of a marked element get this note as evidence
instead: "`<div>` has suppressHydrationWarning, but it only covers that
element's own text and attributes, not this descendant."

It is an error: React still reports the mismatch and renders the branch again
on the client, as with [HP1010](https://hydration.jscrate.dev/docs/issues/hp1010).

## Likely causes

- The attribute on a wrapper, with the changing value in a child:
  `<div suppressHydrationWarning><span>{time}</span></div>`.
- A branch that renders different elements on the server and the client, such
  as a [`typeof window` check](https://hydration.jscrate.dev/docs/causes/browser-api), marked in the hope
  that the error goes away.
- A list whose items differ between the two renders.

## How to fix it

`suppressHydrationWarning` only covers the element's own text and attributes;
fix the structural difference.

1. If only a text value differs, move the attribute to the element that holds
   the text.
2. If the elements differ, render the same elements on both sides and fill in
   the client-only part after mount.

```tsx title="components/clock.tsx"
// Before: the text is in the <span>, the attribute is on the <div>
export function Clock() {
  return (
    <div suppressHydrationWarning>
      <span>{new Date().toLocaleTimeString("en-US", { timeZone: "UTC" })}</span>
    </div>
  );
}
```

```tsx title="components/clock.tsx"
// After: the attribute is on the element whose text differs
export function Clock({ now }: { now: Date }) {
  return (
    <div>
      <span suppressHydrationWarning>
        {now.toLocaleTimeString("en-US", { timeZone: "UTC" })}
      </span>
    </div>
  );
}
```

For a whole branch that only exists in the browser, see
[client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component).

## Catch it with ESLint

[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
reports the attribute on an HTML element that has element children (`tooDeep`),
the pattern behind most HP6002 findings.

## Can you ignore it?

`checks.suppressedWarnings: 'off'` drops every HP6xxx finding, this one
included, but React still re-renders the elements. Prefer the fix; if you must
defer it, use an `ignore.issues` rule with a `reason` and an `expires` date
(see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring)).

## Related

- [Why suppressHydrationWarning is not working](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [HP6001: a mismatch hidden by suppressHydrationWarning](https://hydration.jscrate.dev/docs/issues/hp6001)
- [HP6003: suppression with nothing to suppress](https://hydration.jscrate.dev/docs/issues/hp6003)
- [HP1010: React discarded server HTML for a branch](https://hydration.jscrate.dev/docs/issues/hp1010)
- [Browser-only APIs used during render](https://hydration.jscrate.dev/docs/causes/browser-api)

---

# HP6003: suppressHydrationWarning with nothing to suppress

> HP6003 (suppression-unused) means an element has suppressHydrationWarning but its server and client output are identical. Remove it before it hides a bug.

Source: https://hydration.jscrate.dev/docs/issues/hp6003
Last updated: 2026-09-18

HP6003 (`suppression-unused`) means an element is marked with
`suppressHydrationWarning`, but its server and client output are identical:
there is nothing to suppress. The attribute only hides future mistakes on that
element. Remove it, so real mismatches are reported later. It is reported only
with `checks.suppressedWarnings: 'strict'`.

| | |
| --- | --- |
| Code | `HP6003` |
| Name | `suppression-unused` |
| Default severity | Info |
| Group | suppressHydrationWarning audit |
| What it means | The element is marked with suppressHydrationWarning but its server and client output are identical. |

## What the HP6003 suppression unused finding means

During hydration, hydration-proof compares each marked element's text and
attributes with the server HTML. When none of them differs in the tested
scenario, it reports:

```text
suppressHydrationWarning is set, but the server and client output are identical.
```

The finding is info and off by default. Turn it on to clean up old
suppressions:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  checks: { suppressedWarnings: "strict" },
});
```

A difference can depend on the environment. An element that matches in the
default scenario may differ in another timezone or theme, so check the
finding across your [scenarios](https://hydration.jscrate.dev/docs/scenarios) before you remove the
attribute.

## Likely causes

- The value that used to differ was fixed, and the attribute stayed.
- The attribute was copied along with a component.
- A design system passes `suppressHydrationWarning` to elements that never
  need it.

## How to fix it

Remove `suppressHydrationWarning` if nothing on this element differs, so real
mismatches are not hidden later.

```tsx title="components/page-title.tsx"
// Before: static text, nothing can differ
export function PageTitle() {
  return <h1 suppressHydrationWarning>Dashboard</h1>;
}
```

```tsx title="components/page-title.tsx"
export function PageTitle() {
  return <h1>Dashboard</h1>;
}
```

Keep it where the difference only shows up in some environments, such as
`<html>` with a theme script in a dark mode scenario, and ignore the finding
for that element (see [ignoring findings](https://hydration.jscrate.dev/docs/ignoring)).

## Catch it with ESLint

[`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning)
reports the attribute on elements whose attributes and text are all static
(`unused`), and its suggestion removes it.

## Related

- [HP6001: a mismatch hidden by suppressHydrationWarning](https://hydration.jscrate.dev/docs/issues/hp6001)
- [HP6002: suppression cannot hide a structural difference](https://hydration.jscrate.dev/docs/issues/hp6002)
- [Using suppressHydrationWarning safely](https://hydration.jscrate.dev/docs/guides/suppresshydrationwarning)
- [The configuration reference](https://hydration.jscrate.dev/docs/configuration)

---

# HP9001: Hydration did not finish in time

> HP9001 (hydration-timeout) means React loaded but hydration did not finish before the timeout. Raise the timeout or find the Suspense boundary that hangs.

Source: https://hydration.jscrate.dev/docs/issues/hp9001
Last updated: 2026-09-18

HP9001 (`hydration-timeout`) means React loaded on the page, but hydration did
not complete before the timeout, so the page could not be compared. Usually a
Suspense boundary never resolves in the test environment, or the page is very
slow to hydrate. Find the boundary that hangs, or increase the hydration
timeout.

| | |
| --- | --- |
| Code | `HP9001` |
| Name | `hydration-timeout` |
| Default severity | Error |
| Group | Test run problems |
| What it means | React was on the page but hydration did not complete before the timeout. |

## What the HP9001 hydration timeout finding means

hydration-proof waits for React's hydration to finish before it takes its
snapshots. Once React is on the page, it waits up to `ready.hydrationTimeout`
(15 seconds by default), within the page's overall `ready.timeout` (30
seconds). When the time runs out, the finding says how many boundaries are
still waiting:

```text
Hydration did not finish: 2 Suspense or Activity boundaries are still dehydrated.
Hydration did not finish before the timeout.
```

It is an error: nothing after hydration could be checked on that page.

### The info variant

React hydrates some boundaries only when the user interacts with them. When
every pending boundary already has its content and the page has been quiet for
two seconds, hydration-proof stops waiting and reports HP9001 as info instead:

```text
React did not hydrate 1 Suspense boundary whose content had already arrived; React hydrates it on the first interaction.
```

The page is still tested; only those boundaries are not compared.

## Likely causes

- A Suspense boundary whose data never arrives in the test environment: an API
  that is not running, a request the test browser cannot reach, a promise that
  never resolves.
- A slow scenario: throttled network (`network: "slow-3g"`) or CPU (`cpu: 4`)
  with a large bundle.
- A script error that stops hydration part-way; look for
  [HP2007](https://hydration.jscrate.dev/docs/issues/hp2007) on the same page.

## How to fix it

Increase the hydration timeout, or check for Suspense boundaries that never
resolve in the test environment.

1. Open the route with `--headed` and watch which part stays in its fallback.
2. Make the data available to the test: start the API, seed it in
   `hooks.setup`, or answer the browser's requests with `mocks` in the
   scenario (see [scenarios](https://hydration.jscrate.dev/docs/scenarios)).
3. If the page is just slow, raise the limits. Keep `ready.timeout` above
   `ready.hydrationTimeout`, since it covers the whole page:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  ready: { hydrationTimeout: 30_000, timeout: 60_000 },
});
```

A route object can set its own `ready` options, so one slow page does not slow
down the rest; see [routes](https://hydration.jscrate.dev/docs/routes).

## Related

- [HP9009: the page never became quiet](https://hydration.jscrate.dev/docs/issues/hp9009)
- [HP9008: React loaded but never mounted a root](https://hydration.jscrate.dev/docs/issues/hp9008)
- [HP2003: a Suspense boundary switched to client rendering](https://hydration.jscrate.dev/docs/issues/hp2003)
- [The ready options](https://hydration.jscrate.dev/docs/configuration)
- [Troubleshooting test runs](https://hydration.jscrate.dev/docs/troubleshooting)

---

# HP9002: No React found on the page

> HP9002 (no-react) means the page loaded without any React renderer, so nothing was hydrated or tested. Check the URL and that the page's scripts load.

Source: https://hydration.jscrate.dev/docs/issues/hp9002
Last updated: 2026-09-18

HP9002 (`no-react`) means the page loaded without any React renderer, so
nothing was hydrated and nothing on the page was tested. Either the URL does
not serve a React page, or its scripts did not load in the test browser. Check
the URL and the network requests of the page.

| | |
| --- | --- |
| Code | `HP9002` |
| Name | `no-react` |
| Default severity | Warning |
| Group | Test run problems |
| What it means | The page loaded without any React renderer, so nothing was hydrated. |

## What the HP9002 no React finding means

hydration-proof connects to React through the hook React looks for when it
loads. If no renderer has registered two seconds after the page finished
loading, it reports:

```text
No React renderer was found on the page.
```

It is a warning: the page is not broken, but it was not tested either.

On Astro, pages without React islands are normal, and the Astro adapter does
not report them.

## Likely causes

- The route serves a page that is not rendered with React: a static file, a
  page from another app behind the same host, an error page from a proxy.
- The page's scripts fail to load: a 404 on a JavaScript chunk after a deploy,
  a Content Security Policy that blocks them, a CDN origin the test machine
  cannot reach.
- A redirect to a sign-in page of another service (see
  [HP9010](https://hydration.jscrate.dev/docs/issues/hp9010)).

## How to fix it

Check that the URL serves a React page and that its scripts load in the test
browser.

1. Open the route with `--headed` and check the network tab for failed
   scripts.
2. With `--url`, make sure the URL points at the app you mean to test.
3. If the route is not a React page, leave it out with `routes.exclude`:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    exclude: ["/api/**", "/legal/*.html"],
  },
});
```

[Routes](https://hydration.jscrate.dev/docs/routes) explains where routes come from and how to filter them.

## Related

- [HP9003: the page is rendered on the client only](https://hydration.jscrate.dev/docs/issues/hp9003)
- [HP9008: React loaded but never mounted a root](https://hydration.jscrate.dev/docs/issues/hp9008)
- [HP9004: the page could not be loaded](https://hydration.jscrate.dev/docs/issues/hp9004)
- [Troubleshooting](https://hydration.jscrate.dev/docs/troubleshooting)
- [How hydration-proof connects to React](https://hydration.jscrate.dev/docs/how-it-works)

---

# HP9003: The page is rendered on the client only

> HP9003 (client-rendered-page) means React mounted the page with createRoot instead of hydrating server HTML, so there was nothing to compare. What to check.

Source: https://hydration.jscrate.dev/docs/issues/hp9003
Last updated: 2026-09-18

HP9003 (`client-rendered-page`) means React mounted this page with
`createRoot` instead of hydrating server HTML with `hydrateRoot`. There is no
server HTML to compare, so hydration-proof has nothing to test on it. That is
expected for a single-page app; if the page should be server-rendered, check
its entry point.

| | |
| --- | --- |
| Code | `HP9003` |
| Name | `client-rendered-page` |
| Default severity | Info |
| Group | Test run problems |
| What it means | React mounted with createRoot instead of hydrating server HTML. |

## What the HP9003 client rendered page finding means

hydration-proof sees every React root the page creates. When the page's root
is a client root and nothing was hydrated, it reports:

```text
React mounted with createRoot; there is no server HTML to hydrate.
```

A client root that mounts before the hydrating one (a widget, a toast
container) does not trigger it: hydration-proof waits a moment for the
hydrating root first.

It is info: it does not fail the run, and it is not printed in the terminal
list. The HTML and JSON [reports](https://hydration.jscrate.dev/docs/reports) show it.

## Likely causes

- A single-page app, or a route that is rendered only in the browser.
- A page whose whole content is a client-only component, such as
  [`next/dynamic` with `ssr: false`](https://hydration.jscrate.dev/docs/guides/next-dynamic-ssr-false) at
  the top.
- A custom server that sends an empty container and calls `createRoot` in the
  entry file.

## How to fix it

There is nothing to fix if the page is meant to render on the client.

- If the route is client-only by design, leave it out with `routes.exclude`,
  or ignore `code: "HP9003"` for it with a `reason` (see
  [ignoring findings](https://hydration.jscrate.dev/docs/ignoring)).
- If the page should be server-rendered, check that the server renders the
  app's HTML into the container and that the client entry calls `hydrateRoot`:

```tsx title="entry-client.tsx"
import { hydrateRoot } from "react-dom/client";
import { App } from "./app";

hydrateRoot(document.getElementById("root")!, <App />);
```

## Related

- [HP9002: no React found on the page](https://hydration.jscrate.dev/docs/issues/hp9002)
- [HP9008: React loaded but never mounted a root](https://hydration.jscrate.dev/docs/issues/hp9008)
- [Client-only components](https://hydration.jscrate.dev/docs/guides/client-only-component)
- [Testing a custom React server](https://hydration.jscrate.dev/docs/frameworks/custom-server)

---

# HP9004: The page could not be loaded

> HP9004 (navigation-failed) means the test browser could not navigate to the URL at all: the server is not running, the URL is wrong or the connection failed.

Source: https://hydration.jscrate.dev/docs/issues/hp9004
Last updated: 2026-09-18

HP9004 (`navigation-failed`) means the test browser could not navigate to the
URL at all: no response came back, so there is no page to test. The server is
not running, the URL is wrong, or the connection failed. Check that the server
is running and the URL is correct.

| | |
| --- | --- |
| Code | `HP9004` |
| Name | `navigation-failed` |
| Default severity | Error |
| Group | Test run problems |
| What it means | The browser could not navigate to the URL. |

## What the HP9004 navigation failed finding means

The finding carries the browser's own error, for example a refused connection
or a timeout:

```text
page.goto: net::ERR_CONNECTION_REFUSED at http://localhost:3000/pricing
```

It is an error, and no other check runs on that page. A server that answers
with an error status is a different problem:
[HP9005](https://hydration.jscrate.dev/docs/issues/hp9005).

## Likely causes

- With `--url`, the app is not running, or runs on another port.
- The app crashed during the run, so every later page fails.
- A host name that does not resolve, or a certificate the browser rejects.
- A page that takes longer than the page timeout to respond.

## How to fix it

Check that the server is running and the URL is correct.

1. With `--url`, start the app first and open the URL in your own browser.
2. Without `--url`, hydration-proof starts the app itself; check that
   `server.command` works on its own, and raise `server.timeout` for slow
   starts.
3. If only some pages fail, check the app's own logs for a crash during the
   run.
4. For occasional failures, let hydration-proof load the page again with
   `retries` (on CI the default is `1`).

```bash
npx hydration-proof test --url http://localhost:3000 --route /pricing --retries 2
```

A run that stops before any page with "chromium is not installed" is not this
finding: download the browser once.

```bash
npx hydration-proof install
```

## Related

- [HP9005: the server answered with an error status](https://hydration.jscrate.dev/docs/issues/hp9005)
- [HP9002: no React found on the page](https://hydration.jscrate.dev/docs/issues/hp9002)
- [Troubleshooting: the app does not start](https://hydration.jscrate.dev/docs/troubleshooting)
- [Server options in the configuration](https://hydration.jscrate.dev/docs/configuration)
- [The test command and its flags](https://hydration.jscrate.dev/docs/cli)

---

# HP9005: The server answered with an error status

> HP9005 (http-error) means the page's document response had an HTTP error status such as 404 or 500. Fix the route, or list the status the route should return.

Source: https://hydration.jscrate.dev/docs/issues/hp9005
Last updated: 2026-09-18

HP9005 (`http-error`) means the document response for the route had an HTTP
error status, 400 or above, such as a 404 or a 500. The page may still hydrate,
but it is probably not the page you meant to test. Make the route return a
success status, or list the status in the route's expected statuses.

| | |
| --- | --- |
| Code | `HP9005` |
| Name | `http-error` |
| Default severity | Error |
| Group | Test run problems |
| What it means | The document response had an HTTP error status. |

## What the HP9005 http error finding means

hydration-proof checks the status of the document the browser received:

```text
The server answered 500 for http://localhost:3000/products/42.
```

It is an error unless the status is listed in the route's `expectStatus`. The
page is still tested, so a custom 404 page that hydrates with a mismatch is
reported as well.

## Likely causes

- A dynamic route tested with an example value that does not exist, for
  example a product id from `routes.dynamic` that is not in the test database.
- A server error on this route: check the server logs.
- A signed-in page that answers 401 or 403 to a guest scenario.
- An error page on purpose, such as a route for your 404 page.

## How to fix it

Make the route return a success status, or list the status in the route's
expected statuses.

1. For a server error, fix the route; the server logs have the stack trace.
2. For missing data, use example values that exist, or seed them in
   `hooks.setup`.
3. For signed-in pages, test them in a scenario that signs in (see
   [scenarios](https://hydration.jscrate.dev/docs/scenarios)).
4. For a page that should answer with an error, set `expectStatus`:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    paths: ["/", "/pricing", { path: "/404-page", expectStatus: [404] }],
  },
});
```

For Next.js, `routes.notFound` already loads a URL that does not exist and
expects a 404, to check that the not-found page hydrates. [Routes](https://hydration.jscrate.dev/docs/routes)
lists every route option.

## Related

- [HP9004: the page could not be loaded](https://hydration.jscrate.dev/docs/issues/hp9004)
- [HP9010: the route redirected somewhere else](https://hydration.jscrate.dev/docs/issues/hp9010)
- [Route options such as expectStatus](https://hydration.jscrate.dev/docs/routes)
- [Signed-in scenarios](https://hydration.jscrate.dev/docs/scenarios)

---

# HP9006: The server HTML could not be captured

> HP9006 (body-unavailable) means the document body could not be read, so the checks that start from the server HTML were skipped on that page. What to check.

Source: https://hydration.jscrate.dev/docs/issues/hp9006
Last updated: 2026-09-18

HP9006 (`body-unavailable`) means hydration-proof could not read the body of
the document response, so the checks that start from the server HTML were
skipped on that page. The page was still loaded and hydrated. Look at the
reason in the message, and run the page again.

| | |
| --- | --- |
| Code | `HP9006` |
| Name | `body-unavailable` |
| Default severity | Warning |
| Group | Test run problems |
| What it means | The document body was not available, so server-side stages could not be compared. |

## What the HP9006 body unavailable finding means

hydration-proof reads the server HTML from the same navigation the browser
makes, never from a second request. When the browser cannot hand over that
body, the finding gives its reason after the colon:

```text
The document body could not be read: Reading the document body timed out after 15000ms
```

Without the body, the first stages of the [comparison](https://hydration.jscrate.dev/docs/how-it-works)
are missing:

- invalid nesting the browser repaired ([HP3001](https://hydration.jscrate.dev/docs/issues/hp3001),
  [HP3002](https://hydration.jscrate.dev/docs/issues/hp3002));
- changes made before hydration ([HP4001](https://hydration.jscrate.dev/docs/issues/hp4001)).

Checks that compare the DOM before and after hydration, and React's own errors,
still run. It is a warning, because the page was only partly tested.

## Likely causes

- A streamed response that did not finish in time, for example a Suspense
  boundary whose data never arrives, so the server keeps the response open.
- A response the browser did not keep a body for.
- A server that closed the connection before the end of the document.

## How to fix it

1. Run the page again. If the problem comes and goes, `retries` loads failed
   pages again, and `--repeat` shows how often it happens.
2. If the response streams for a long time, find the part of the page that
   keeps it open; the same page often has [HP9001](https://hydration.jscrate.dev/docs/issues/hp9001).
3. If the reason in the message points at the server, check the server logs
   for that request.

[Troubleshooting](https://hydration.jscrate.dev/docs/troubleshooting) covers other problems with loading
pages.

## Related

- [HP9007: some capture data was dropped](https://hydration.jscrate.dev/docs/issues/hp9007)
- [HP9001: hydration did not finish in time](https://hydration.jscrate.dev/docs/issues/hp9001)
- [HP9004: the page could not be loaded](https://hydration.jscrate.dev/docs/issues/hp9004)
- [The six snapshots hydration-proof compares](https://hydration.jscrate.dev/docs/how-it-works)

---

# HP9007: Some capture data was dropped

> HP9007 (capture-truncated) means buffers overflowed while the page was captured, so its results may be incomplete. Why it happens and what to do about it.

Source: https://hydration.jscrate.dev/docs/issues/hp9007
Last updated: 2026-09-18

HP9007 (`capture-truncated`) means some of the data recorded on the page was
dropped because a buffer overflowed, so the results for that page may be
incomplete. It happens on pages that change a very large part of the DOM at
once, or throw a flood of errors. Treat the page's other findings as a
minimum, not the full list.

| | |
| --- | --- |
| Code | `HP9007` |
| Name | `capture-truncated` |
| Default severity | Warning |
| Group | Test run problems |
| What it means | Buffers overflowed while capturing; results may be incomplete. |

## What the HP9007 capture truncated finding means

The runtime hydration-proof injects into the page records DOM changes and the
errors React reports. To keep the page fast, each buffer has a limit: 20,000
DOM changes in one batch and 500 errors per page. What goes beyond it is
counted and dropped:

```text
Capture buffers overflowed ({"entries":3812}); results may be incomplete.
```

`entries` are DOM changes, `errors` are reported errors and `batches` are whole
groups of changes. It is a warning: the findings that were reported are real,
but some may be missing.

## Likely causes

- A page that renders or replaces a very large DOM in one step: a long table,
  a list without virtualization, a whole page rendered again on the client
  (see [HP1011](https://hydration.jscrate.dev/docs/issues/hp1011)).
- An error loop that reports the same error hundreds of times.

## How to fix it

1. Fix the page's other findings first. A root that React renders again on the
   client is a common source of huge mutation batches, and it disappears with
   the mismatch.
2. If the page throws in a loop, fix that error; the first ones are in the
   report.
3. For very large pages, test a smaller variant of the route as well, for
   example with a query that limits the list (`routes.query`), so every
   finding fits in the buffers.

## Related

- [HP9006: the server HTML could not be captured](https://hydration.jscrate.dev/docs/issues/hp9006)
- [HP1011: React discarded the whole server-rendered page](https://hydration.jscrate.dev/docs/issues/hp1011)
- [HP2007: uncaught error while loading the page](https://hydration.jscrate.dev/docs/issues/hp2007)
- [How the page is captured](https://hydration.jscrate.dev/docs/how-it-works)
- [Route options](https://hydration.jscrate.dev/docs/routes)

---

# HP9008: React loaded but never mounted a root

> HP9008 (no-root) means a React renderer loaded on the page but no root was created before the timeout, so nothing was hydrated. Find what stopped the entry.

Source: https://hydration.jscrate.dev/docs/issues/hp9008
Last updated: 2026-09-18

HP9008 (`no-root`) means a React renderer loaded on the page, but the page never
created a React root before the timeout: `hydrateRoot` and `createRoot` were
never called. Nothing was hydrated, so nothing was tested. Usually the app's
entry script stopped early; check the page's console errors and failed
requests.

| | |
| --- | --- |
| Code | `HP9008` |
| Name | `no-root` |
| Default severity | Warning |
| Group | Test run problems |
| What it means | A React renderer was injected but no root was created before the timeout. |

## What the HP9008 no root finding means

hydration-proof sees React register with the page, and then waits for a root.
If none appears a few seconds after the page finished loading, it reports:

```text
React loaded but never mounted a root.
```

It is a warning. Compare it with its neighbors:

| Code                          | React loaded | Root created                    |
| ----------------------------- | ------------ | ------------------------------- |
| [HP9002](https://hydration.jscrate.dev/docs/issues/hp9002) | no           | no                              |
| HP9008                        | yes          | no                              |
| [HP9003](https://hydration.jscrate.dev/docs/issues/hp9003) | yes          | a client root, nothing hydrated |
| [HP9001](https://hydration.jscrate.dev/docs/issues/hp9001) | yes          | yes, hydration did not finish   |

## Likely causes

- The entry script threw before it called `hydrateRoot`; the page usually also
  has [HP2007](https://hydration.jscrate.dev/docs/issues/hp2007).
- A script chunk with the entry failed to load.
- The entry waits for something before it mounts (a feature flag, an auth check,
  a config request) that never answers in the test environment.
- React was loaded by a third-party widget on a page that is not a React app.

## How to fix it

1. Open the route with `--headed` and check the console and the network tab.
2. Fix the error or the failed request that stops the entry.
3. If the entry waits for an API, make the API available to the test, or answer
   the request with `mocks` in the scenario (see [scenarios](https://hydration.jscrate.dev/docs/scenarios)).

```bash
npx hydration-proof test --route /dashboard --headed --workers 1
```

## Related

- [HP9002: no React found on the page](https://hydration.jscrate.dev/docs/issues/hp9002)
- [HP9001: hydration did not finish in time](https://hydration.jscrate.dev/docs/issues/hp9001)
- [HP2007: uncaught error while loading the page](https://hydration.jscrate.dev/docs/issues/hp2007)
- [Troubleshooting](https://hydration.jscrate.dev/docs/troubleshooting)

---

# HP9009: The page never became quiet

> HP9009 (ready-timeout) means the page kept changing, or your ready selector or function never passed, before the timeout. How to set the ready options.

Source: https://hydration.jscrate.dev/docs/issues/hp9009
Last updated: 2026-09-18

HP9009 (`ready-timeout`) means the page hydrated, but its ready conditions were
not met before the timeout: the DOM kept changing, or your ready selector or
function never passed. The final snapshot was taken anyway and may be early.
Set `ready` options that fit the page: a longer timeout, a shorter quiet
period or a selector.

| | |
| --- | --- |
| Code | `HP9009` |
| Name | `ready-timeout` |
| Default severity | Warning |
| Group | Test run problems |
| What it means | The ready conditions (quiet DOM, selector, function) were not met before the timeout. |

## What the HP9009 ready timeout finding means

After hydration, hydration-proof waits for the page to settle before it takes
the stable snapshot. hydration-proof never waits for "network idle". A page
counts as settled when:

1. the element in `ready.selector` exists, if you set one;
2. the page function in `ready.function` returns a truthy value, if you set
   one;
3. no DOM change or React commit happened for `ready.quietMs` (400 ms by
   default).

All three must happen within `ready.timeout` (30 seconds by default). If they
do not, the snapshot is taken at the timeout and the page gets this warning:

```text
The page kept changing until the timeout; the stable snapshot may be early.
```

## Likely causes

- Animations driven by JavaScript, carousels, tickers or a clock that updates
  the DOM more often than `quietMs`.
- Polling or live data that re-renders the page every few hundred
  milliseconds.
- A `ready.selector` that never appears, or a `ready.function` that never
  returns true, for example after a change to the page.
- A slow page that settles, but after the timeout.

## How to fix it

The issue code's advice is to increase the timeout or provide `ready.selector`
for pages with continuous updates. In practice, pick by situation:

| Situation                               | Fix                                                                     |
| --------------------------------------- | ----------------------------------------------------------------------- |
| The page settles, but slowly            | Raise `ready.timeout`, or pass `--timeout`                              |
| The page updates all the time           | Lower `ready.quietMs` for that route, below the interval of the updates |
| The content you care about arrives late | Set `ready.selector` or `ready.function`, so the snapshot waits for it  |
| The selector or function never passes   | Fix it, or remove it                                                    |

A route object can set its own `ready` options, so the rest of the app keeps
the defaults:

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    paths: [
      "/",
      {
        path: "/live-scores",
        ready: { quietMs: 150, selector: "#scoreboard" },
      },
    ],
  },
  ready: { timeout: 45_000 },
});
```

When the updates can be turned off for tests, a scenario can do it before any
page script runs, for example with `localStorage` or `initScripts` (see
[scenarios](https://hydration.jscrate.dev/docs/scenarios)). If none of this fits, ignore
`code: "HP9009"` for the route with a `reason`
([ignoring findings](https://hydration.jscrate.dev/docs/ignoring)).

## Related

- [HP9001: hydration did not finish in time](https://hydration.jscrate.dev/docs/issues/hp9001)
- [Troubleshooting: a page that never settles](https://hydration.jscrate.dev/docs/troubleshooting)
- [The ready options in the configuration](https://hydration.jscrate.dev/docs/configuration)
- [Route options](https://hydration.jscrate.dev/docs/routes)

---

# HP9010: The route redirected somewhere else

> HP9010 (unexpected-redirect) means a route ended on a different URL than requested. For signed-in scenarios that land on a login page, the login did not work.

Source: https://hydration.jscrate.dev/docs/issues/hp9010
Last updated: 2026-09-18

HP9010 (`unexpected-redirect`) means the route ended on a different URL than
the one requested, or than its `expectRedirect`. The page that was tested is
the one it landed on. When a signed-in scenario lands on the login page, its
login did not work. Otherwise, set `expectRedirect` or limit the route to the
scenarios that can open it.

| | |
| --- | --- |
| Code | `HP9010` |
| Name | `unexpected-redirect` |
| Default severity | Warning |
| Group | Test run problems |
| What it means | The route ended on a different URL than requested (or than expectRedirect). A signed-in scenario that lands on a login page usually means its login did not work. |

## What the HP9010 unexpected redirect finding means

hydration-proof compares the path it requested with the path the page ended
on, after every redirect:

```text
/account redirected to /login; the page that was tested is /login.
/old-pricing should redirect to /pricing but ended on /.
```

Without `expectRedirect`, any redirect is a warning. With `expectRedirect`, a
redirect to another path is an error, because the route is known to go
somewhere else.

## Likely causes

- A signed-in page tested in a scenario that is not signed in, or whose sign-in
  did not leave a working session.
- A route that redirects on purpose: an old URL, a locale prefix, a trailing
  slash rule.
- Middleware that redirects the test browser, for example by locale or
  country.

## How to fix it

If the redirect is intended, set `expectRedirect` on the route, or limit the
route to the scenarios that can open it (scenario `include`/`exclude`). For
signed-in scenarios, check the login step or the storage state file.

### A redirect that is intended

```ts title="hydration-proof.config.ts"
import { defineConfig } from "hydration-proof";

export default defineConfig({
  routes: {
    paths: ["/", { path: "/old-pricing", expectRedirect: "/pricing" }],
  },
  scenarios: [
    { name: "guest", exclude: ["/account/**"] },
    {
      name: "customer",
      include: ["/account/**"],
      storageState: "auth/customer.json",
    },
  ],
});
```

### A login that did not work

1. Watch the login with the browser visible and one worker (the command is
   below).
2. Make the `login` function wait for the page after signing in, for example
   with `page.waitForURL("**/account")`, so the session cookie is set before
   the pages are tested.
3. Check that the session cookie is not limited to another domain than the
   tested app.
4. With `storageState`, record the file again: sessions in it expire.

```bash
npx hydration-proof test --scenario customer --headed --workers 1
```

A `login` that throws stops the run with exit code 2; HP9010 means it finished
but left no working session. [Scenarios and sign-in](https://hydration.jscrate.dev/docs/scenarios) has a
full example.

## Related

- [Scenarios and signed-in pages](https://hydration.jscrate.dev/docs/scenarios)
- [Troubleshooting: signed-in pages end on the login page](https://hydration.jscrate.dev/docs/troubleshooting)
- [HP9005: the server answered with an error status](https://hydration.jscrate.dev/docs/issues/hp9005)
- [HP9002: no React found on the page](https://hydration.jscrate.dev/docs/issues/hp9002)
- [Route options such as expectRedirect](https://hydration.jscrate.dev/docs/routes)

---