Dev overlay, watch mode and dashboard

hydration-proof dev opens your app in a browser with a hydration error overlay. Every page you open is checked the way hydration-proof test checks it, and the findings appear in a panel in the corner of the page and in the terminal: the element, the server and client values, the likely cause, the fix and the source line.

Open the overlay

npx hydration-proof dev

It starts the development server for you and opens a browser window. By default it uses the development build (--mode development), which gives exact source lines. Useful options:

• --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

A badge in the corner shows the state of the current page: checking, no problems, or the number of errors and warnings. The panel opens by itself when the page has an error. For each finding it shows the code, the element, the component, the likely cause with its confidence (or "proven"), both values and the first fix, with these actions:

• 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 is injected by the test browser. Your app is not changed, nothing is added to its bundle, and the checks ignore the overlay. It renders in a shadow root, so its styles and your app's styles stay apart.

Client-side navigations keep the result of the last loaded page. Reload to check the page you navigated to.

Open files in your editor

Open file:line uses the editor named in HYDRATION_PROOF_EDITOR, VISUAL or EDITOR, in that order, such as code, cursor, zed, webstorm, subl or nvim:

export HYDRATION_PROOF_EDITOR=cursor

Without one, it uses the first of cursor, code, windsurf, codium, zed, webstorm, idea and subl found on your PATH. Only files inside the project are opened.

How it differs from the Next.js dev overlay

Unlike an overlay that shows the hydration errors React itself logs, the hydration-proof overlay runs the same checks as hydration-proof test:

• 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.

The two work side by side. See hydration-proof and the Next.js dev overlay for a full comparison.

Watch mode: test --watch

Watch mode re-runs the tests while you work, with no browser window to click through:

npx hydration-proof test --watch

It starts the development server once, tests every route, then waits for changes. After each change, only the routes the changed files can affect are tested, the same way --changed chooses them. Changes to package.json, configs or environment files test every route. Add --mode production to test the production server instead; it is not rebuilt on changes. Stop it with Ctrl+C.

Dashboard: hydration-proof ui

npx hydration-proof ui --open

A local page to start test runs (all routes or some, with probes, interaction or navigation checks), follow their output live and read the latest HTML report. --port picks the port (a free one by default), and --open opens it in your default browser.

The dashboard listens on 127.0.0.1 only, and the printed URL contains a random access token that every request needs. It refuses requests for other host names and cross-site requests. 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