Dev overlay, watch mode and dashboard

Run hydration-proof dev to open your app with a hydration error overlay. It checks each page you load directly and shows findings both on the page and in the terminal. Each finding includes the changed element, both values, a likely cause, and a fix.

Open the overlay

npx hydration-proof dev

The command starts your development server and opens a browser. Development mode is the default, so source locations are available when React provides them. You can also:

• --url http://localhost:3000 uses an app that is already running.
• --route /pricing opens that page first.
• --scenario dark-mobile browses in one of your scenarios.
• --mode production checks the production build instead.
• --browser firefox or --channel chrome picks the browser.

What the hydration error overlay shows

The badge shows whether the page is being checked, passed, or has findings. Open the panel to see each issue code, component, changed values, cause, and suggested fix. From there you can:

• Highlight scrolls to the element and outlines it.
• Open file:line opens the source in your editor.
• Copy puts a Markdown summary of the finding on the clipboard, ready for an issue or a pull request. Copy report does the same for every finding on the page.
• Docs opens the page for the issue code.
• Re-run reloads the page and checks it again.

The overlay exists only in the test browser. It does not change your app or bundle. Its styles are isolated from your page.

After client-side navigation, reload the page to check the new route. Until then, the overlay still shows the last direct-load result.

Open files in your editor

Open file:line uses HYDRATION_PROOF_EDITOR, then VISUAL, then EDITOR to choose an editor:

export HYDRATION_PROOF_EDITOR=cursor

Otherwise it looks for cursor, code, windsurf, codium, zed, webstorm, idea, or subl on your PATH. It opens only files inside the project.

How it differs from the Next.js dev overlay

The overlay runs the same checks as hydration-proof test, including differences that React's own overlay may not report:

• It compares the server HTML with the hydrated DOM, so it also finds markup the browser repaired and changes that other scripts or extensions made before hydration.
• With --mode production, it finds the attribute differences React does not report in production builds.
• Each finding gets a likely cause and a fix for that cause.
• It works with every framework hydration-proof supports, not only Next.js.

You can use both overlays. See the Next.js overlay comparison.

Watch mode: test --watch

Use watch mode to re-run checks when files change, without browsing each page yourself:

npx hydration-proof test --watch

Watch mode starts the development server once and checks the routes. After a file change, it rechecks affected routes. Changes to config or environment files trigger a wider run. Use --mode production to check an existing production build; watch mode does not rebuild it after each change. Stop with Ctrl+C.

Dashboard: hydration-proof ui

npx hydration-proof ui --open

The dashboard is a local page for starting runs, following progress, and opening the latest report. You can select routes and enable probes, interactions, or navigation checks. --port chooses a port; --open opens the dashboard in your browser.

The dashboard listens only on 127.0.0.1 and requires the access token in the printed URL. Stop it with Ctrl+C.

Options

Related

• hydration-proof and the Next.js dev overlay
• How to debug hydration errors
• Every command and flag of the CLI
• Hydration errors in Next.js
• Prove the cause of a finding with probes