Hydration Proof

Search documentation

Find a page or section

Hydration error tools compared

hydration-proofv1.0.0View as Markdown

Where each tool runs, when, and what it can see.

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

ToolRuns whereWhenWhat it catchesProduction buildsCI
Browser console (React's own errors)The browser tab you have openWhile you browseWhat React reports for that page, with a component stack in developmentMinified codes such as #418; React 19 does not report attribute mismatchesNo
Next.js dev overlayThe browser, with next devDevelopment only, one page at a timeThe errors React reports; since Next.js 16.2 with a + Client / - Server diffNoNo
@builder.io/react-hydration-overlayThe browser, wrapped around your app root, with a Next.js or webpack pluginWhen a hydration error happens on the page you have openA diff between the server and client rendersNot intended for production useNo
Sentry Session ReplayYour users' browsersAfter the fact, for errors captured with a replayA diff of the page before and after hydration (HTML and visual)YesNo
eslint-plugin-react-hooks (purity)Your editor and lint stepBefore the code runsImpure calls in components and hooks: Date.now(), new Date(), Math.random(), crypto.randomUUID(), performance.now()Not applicableYes, as a lint step
eslint-plugin-validate-jsx-nestingYour editor and lint stepBefore the code runsInvalid HTML nesting written in JSX, such as <p> inside <p>Not applicableYes, as a lint step
eslint-plugin-hydration-proofYour editor and lint stepBefore the code runs15 rules for render code: time, random values, browser globals, storage, media queries, locale and timezone formatting, unstable ids, invalid nesting, suppressHydrationWarningNot applicableYes, as a lint step
hydration-proofA real browser driven by Playwright, on your machine or a CI runnerOn demand, for every routeText 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 fixYes: production is the default, --mode both tests bothYes: 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 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.

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.

ESLint rules

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

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, then add it to 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: