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).
- 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
- 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 you configure. - 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