Everything about hydration-proof starts from one goal: find, explain and prevent React hydration problems before users see them. It is an open-source project with two npm packages, a CLI that tests every route of your app in a real browser and an ESLint plugin that flags risky render code. Sohail Khan writes it, under the MIT license.
The two packages
| Package | What it does | Start here |
|---|---|---|
hydration-proof | A CLI and Node API. It loads every route of a server-rendered React app in a real browser through Playwright, compares the server HTML with the hydrated DOM, and reports each difference with a stable issue code, a likely cause and a fix | Quick start |
eslint-plugin-hydration-proof | 15 ESLint rules that catch hydration mismatches in render code while you write it | ESLint plugin |
Both are released together, at the same version; see releases.
Principles
- Nothing is added to your app. The CLI injects its runtime into the test browser only. Your code and build are not modified, and nothing ships in your production bundle.
- No telemetry. Nothing about your app, your run or your machine is uploaded: no analytics, no crash reporting, no version check.
- No install scripts. The package has no
postinstallor other lifecycle script. Browsers are only downloaded when you runhydration-proof install. - One runtime dependency.
playwright-coreis the only one, and it has none of its own. The ESLint plugin has no runtime dependencies. - Stable interfaces. Issue codes, exit codes, the report schema and fingerprints do not change their meaning. From 1.0 on, the compatibility promise says what follows semver.
- Every detection is proven. Each detection has a fixture case: a broken page and a correct control, checked against React's own verdict. Every false positive that gets fixed becomes a recorded control page, so it cannot come back.
Who makes it
hydration-proof is written by Sohail Khan. The source is on GitHub at re-sohail/hydration-proof, and this site is its documentation.
Both packages are released under the MIT license, copyright Sohail Khan.
Questions about hydration-proof
Report a bug or ask for a feature
Open an issue on GitHub. A bug report with a minimal reproduction is the most valuable contribution: include the version, the command you ran and the output. The troubleshooting page covers the common problems first.
Report a security issue
Report vulnerabilities privately through GitHub security advisories, not in public issues. Include the version, the command you ran and, if you can, an app that shows the problem. You get a first reply within a week, and security fixes are released for the latest minor version. Security describes what hydration-proof does with your app's data.
Contribute
CONTRIBUTING.md has the setup and the checks to run. Contributions follow a few rules:
- No new runtime dependencies. Use Node built-ins or write the code.
- A new detection needs a fixture case, a broken page and a correct control, and must keep detection at 100% with 0 false positives.
- A user-visible change needs a changeset that describes it for the changelog.