# 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)