# hydration-proof vs react-hydration-overlay

> A react-hydration-overlay alternative that adds no code to your app: test every route in CI and production builds, with the element, values and cause.

Source: https://hydration.jscrate.dev/docs/compare/react-hydration-overlay
Last updated: 2026-09-18

If you are looking for a react-hydration-overlay alternative, hydration-proof covers the same need, the server and client HTML side by side, without code in your app. Builder.io's overlay wraps your app and shows a diff on the page when hydration fails. hydration-proof tests every route in a real browser, locally or in CI, in development and production builds.

## At a glance

|               | Builder.io's overlay                              | hydration-proof                                                        |
| ------------- | ------------------------------------------------- | ---------------------------------------------------------------------- |
| How it runs   | A component and a build plugin in your app        | A CLI that drives Playwright browsers; nothing in your app             |
| When          | While you browse, in development                  | In the terminal and CI; an optional overlay while you browse           |
| Pages         | The one you open                                  | Every discovered route                                                 |
| Builds        | Development (not intended for production)         | Production (default), development, or both                             |
| Shows         | The server and client HTML of the page, as a diff | The element, both values, component, source line, likely cause and fix |
| Frameworks    | Next.js (plugin), webpack                         | Next.js, React Router, Remix, Astro, Vite SSR, custom servers          |
| Status        | Beta, version 0.3.0                               | Stable, version 1.0                                                    |
| Fails a build | No                                                | Yes, with exit code `1`                                                |

## What Builder.io's overlay does well

[Builder.io's hydration overlay](https://github.com/BuilderIO/hydration-overlay) is a small, focused tool:

- **A whole-page diff.** An injected script captures the server HTML before hydration. When a hydration error happens, the overlay compares it with the client HTML and shows the difference on top of the page.
- **Simple setup for Next.js.** Wrap the app in `HydrationOverlay` and add `withHydrationOverlay` to `next.config.js`; `appRootSelector` points it at `main` for the App Router. A webpack plugin covers other setups.
- **Visual and immediate.** You see the diff where the error happened, without leaving the browser.

It has about 8,000 weekly downloads on npm.

## Where hydration-proof differs

- **Nothing added to your app.** The overlay is a dependency, a wrapper component and a build plugin, and its README says it "is not intended for production use". hydration-proof injects its runtime into the test browser only; your code and bundle do not change.
- **Every route, in CI.** The overlay reports the page you open. hydration-proof discovers routes and tests all of them, in every [scenario](https://hydration.jscrate.dev/docs/scenarios) you configure, and fails the build when it finds a problem.
- **Production builds and silent mismatches.** The overlay is for development builds, and React 19 production builds do not report attribute mismatches at all. hydration-proof tests production builds by default and compares every attribute with what React renders on the client, so it finds those too.
- **Where the difference started.** The overlay's README notes that because React re-renders the whole app after a hydration failure, its diff can show false positives, and that React's changes to inline `style` formatting (an added `;`, different whitespace) can look like differences. hydration-proof gives every node an identity across its snapshots and compares attributes with the props React renders, so it reports the element where a difference started ([how it works](https://hydration.jscrate.dev/docs/how-it-works)).
- **A cause, not only a diff.** Each finding has a [stable issue code](https://hydration.jscrate.dev/docs/issues), the component and source line, and a [likely cause](https://hydration.jscrate.dev/docs/causes) with a confidence score.
- **Frameworks beyond Next.js.** The overlay's README lists Remix and Vite SSR support as still needed. hydration-proof detects React Router, Remix, Astro and Vite SSR apps, and works with any server through `--url`.

## Switching to a react-hydration-overlay alternative

1. Remove the `HydrationOverlay` wrapper and the `withHydrationOverlay` plugin from `next.config.js`, then uninstall the package.
2. Install hydration-proof and run it once:

   ```bash
   npm install -D hydration-proof
   npx hydration-proof install
   npx hydration-proof test
   ```

3. For the same browse-and-see workflow, run `npx hydration-proof dev`. It opens the app with a hydration overlay that shows each page's findings, highlights the element and opens the source line in your editor ([dev overlay](https://hydration.jscrate.dev/docs/dev-overlay)).

## Sources

As of September 2026:

- [BuilderIO/hydration-overlay on GitHub](https://github.com/BuilderIO/hydration-overlay): README, setup, beta status and known false positives; about 530 stars
- [The package on npm](https://www.npmjs.com/package/@builder.io/react-hydration-overlay): version 0.3.0, published October 2024; 7,963 downloads in the week of September 10–16, 2026
- [hydration-proof: how it works](https://hydration.jscrate.dev/docs/how-it-works)

## Related

- [Next.js dev overlay compared](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay)
- [The hydration-proof dev overlay](https://hydration.jscrate.dev/docs/dev-overlay)
- [Debugging hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [All comparisons](https://hydration.jscrate.dev/docs/comparison)
- [Quick start](https://hydration.jscrate.dev/docs/quick-start)