# Dev overlay, watch mode and dashboard

> hydration-proof dev opens your app with a hydration error overlay: every page you open is checked, with the element, both values, the cause and source line.

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

`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

```bash
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](https://hydration.jscrate.dev/docs/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`:

```sh
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](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay)
for a full comparison.

> **Next.js allowedDevOrigins**
>
> hydration-proof opens the Next.js dev server on `localhost`, because Next.js
> blocks development resources for other hosts. If you test a dev server through
> another host name, add it to `allowedDevOrigins` in `next.config`.

## Watch mode: test --watch

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

```bash
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`](https://hydration.jscrate.dev/docs/ci#test-only-what-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

```bash
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

| Option | What it does |
| --- | --- |
| `-c, --config <file>` | Config file |
| `-u, --url <url>` | Use an app that is already running |
| `-r, --route <path>` | Page to open first (default: the first configured route, or /) |
| `-s, --scenario <name>` | Scenario to browse in (default: the first one) |
| `--mode <mode>` | development (default) or production |
| `--browser <name>` | chromium (default), firefox or webkit |
| `--channel <name>` | Use an installed browser, e.g. chrome |

| Option | What it does |
| --- | --- |
| `-c, --config <file>` | Config file |
| `-p, --port <port>` | Port (default: a free port) |
| `--open` | Open the dashboard in the default browser |

## Related

- [hydration-proof and the Next.js dev overlay](https://hydration.jscrate.dev/docs/compare/nextjs-dev-overlay)
- [How to debug hydration errors](https://hydration.jscrate.dev/docs/guides/debug-hydration-errors)
- [Every command and flag of the CLI](https://hydration.jscrate.dev/docs/cli)
- [Hydration errors in Next.js](https://hydration.jscrate.dev/docs/frameworks/nextjs)
- [Prove the cause of a finding with probes](https://hydration.jscrate.dev/docs/probes)