The Next.js dev overlay hydration error view shows the problem on the page you have open in
next dev. hydration-proof checks the routes it discovers in development or
production builds and can run in CI. Use the overlay to fix the page in front
of you, then run hydration-proof to check routes you may not have opened.
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).
- 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/- Serverlegend (Next.js 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
- Discovered routes, not only the one you opened. A mismatch on a page
you did not visit never reaches the overlay. hydration-proof discovers
routes from
app/,pages/and build output, then tests them in each scenario you configure. Add examples for dynamic routes it cannot discover on its own. - Production builds. The overlay is a development tool. hydration-proof tests the production build by default, and
--mode bothtests 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,styleorhrefis found anyway. - Changes outside React. Browser extensions, scripts that edit the page before hydration, and CDN rewrites are reported under their own codes (HP4001 to HP4003).
- Stable codes and causes. Each finding has an issue code that never changes meaning, and a likely cause with a confidence score.
--probeproves the cause by changing one factor at a time. - CI. It exits with code
1when it finds a problem, writes JSON, JUnit, SARIF and HTML reports, and supports baselines so you can adopt it without a red pipeline (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:
npm install -D hydration-proof
npx hydration-proof install
npx hydration-proof test --mode bothhydration-proof also has its own development 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, "Hydration error improvements"
- Next.js 16.2 release notes, "Hydration Diff Indicator"
- Next.js: Text content does not match server-rendered HTML
- hydration-proof: how it works