Hydration Proof

Search documentation

Find a page or section

About hydration-proof

hydration-proofv1.0.0View as Markdown

Find, explain and prevent React hydration problems before users see them.

About hydration-proof: it is an open-source CLI and ESLint plugin for React hydration problems. The CLI tests your app's routes in a real browser; the plugin catches risky render code while you write it. Sohail Khan maintains both packages under the MIT license.

The two packages

hydration-proof is the CLI and Node API. It loads routes in a Playwright browser, compares server HTML with the page React hydrated, and reports differences with an issue code, likely cause and fix. Start with the quick start.

eslint-plugin-hydration-proof has 15 rules that flag risky render code as you write it. See the ESLint plugin guide.

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 postinstall or other lifecycle script. Browsers are only downloaded when you run hydration-proof install.
  • One runtime dependency. playwright-core is 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.