Hydration error tools compared

Here are the main hydration error tools compared. Use React's console or the Next.js overlay while working on a page. Use lint rules to catch risky code before it runs. Use hydration-proof to check routes in CI, and Sentry to see errors from real users.

Hydration error tools compared

Runtime tools show what happened on a page. Linters inspect source code before it runs, so they cannot detect a CDN rewrite, browser extension, or changed server response.

When to choose each

The browser console and the Next.js dev overlay

Use the console and overlay while developing a page. React can name the component and show a diff, but these tools cover only the page you open. See hydration-proof vs the Next.js dev overlay.

react-hydration-overlay

@builder.io/react-hydration-overlay adds a visual diff when an error happens on the open page. It requires an app wrapper and plugin. See hydration-proof vs react-hydration-overlay for setup and limitations.

Sentry

Sentry Session Replay helps investigate an error a real user encountered. Its hydration diff compares the page before and after React hydrated. See hydration-proof vs Sentry.

ESLint rules

Lint rules run in your editor and CI before the page loads:

• 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.
• eslint-plugin-validate-jsx-nesting (version 0.1.1) reports invalid HTML nesting in JSX. See hydration-proof vs eslint-plugin-validate-jsx-nesting.
• eslint-plugin-hydration-proof has 15 rules aimed at hydration: browser globals, storage, matchMedia, locale and timezone formatting, generated ids and more.

hydration-proof

Use hydration-proof to check routes in a browser, including a production build. It runs in CI and reports the changed element, both values, and a likely cause. Start with the quick start, then add it to CI.

How the tools fit together

You can use them together:

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
• The ESLint plugin and all its rules
• Debug a hydration error
• React hydration error FAQ