Configuration

The hydration-proof config is optional: the framework, the build and start commands and the routes are detected. When you need to change something, write a TypeScript file that exports defineConfig({ ... }). Every option has a default, and command-line flags override the file.

The hydration-proof config file

hydration-proof reads the first of these files it finds in the directory it runs in: hydration-proof.config.{ts,mts,js,mjs,cjs,json}.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  routes: {
    dynamic: { "/products/[id]": ["1", "42"] },
  },
});

• TypeScript is loaded by Node.js itself, with no extra tooling (it needs Node.js 22.18 or newer). Use plain types only: no enum, no namespace and no parameter properties. Relative imports need their file extension (./routes.ts).
• defineConfig returns the object unchanged. It is there for type checking and completion.
• Unknown options are errors, with a suggestion when the name looks like a typo ("is not a known option. Did you mean ...?").
• configVersion is optional and currently always 1. Setting it lets a future version that changes the format migrate the file instead of guessing.
• An older config is updated with hydration-proof migrate (see the CLI).

For a JSON config, point $schema at the schema in the package to get completion in your editor:

{
  "$schema": "./node_modules/hydration-proof/schema/config.json",
  "routes": { "exclude": ["/api/**", "/admin/**"] }
}

The same schema is published at https://hydration.jscrate.dev/schema/config.json.

server

How the app is built and started, or the URL of one that is already running. The adapter supplies the commands, so most apps leave this out. {port} in a command is replaced with the chosen port, which is also passed as PORT. The app, and everything it spawned, is stopped when the run ends.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  server: {
    build: "pnpm build",
    command: "pnpm start --port {port}",
    // Build only when there is no build output yet; "always" in CI
    buildWhen: "if-missing",
    env: { NEXT_PUBLIC_API_URL: "http://localhost:4000" },
    timeout: 180_000,
  },
});

To test an app you started yourself, set url (or pass --url): nothing is built or started. mode: "both" tests the production build and the development server (devCommand) in one run.

routes

Which pages are tested. Without paths, routes are discovered from the framework and the build output. Dynamic routes need example values, or they are skipped. Routes explains every source, the glob syntax and the route cache.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  routes: {
    discover: true,
    // Routes discovery cannot see: redirects, rewrites, anything behind a flag
    paths: ["/pricing?plan=team"],
    // One real value per dynamic segment, or the route is skipped
    dynamic: {
      "/blog/[slug]": ["hello-world"],
      "/products/[id]": ["1", "42"],
    },
    exclude: ["/api/**", "/admin/**"],
    sitemap: true,
  },
});

scenarios

The browser environments every route is tested in. By default there is one scenario, default, that uses this machine's locale and timezone and a light color scheme, so a server started on the same machine renders with the same values. Scenarios also carry cookies, storage and a login function for signed-in pages; see scenarios.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  scenarios: [
    { name: "default" },
    { name: "dark-mobile", colorScheme: "dark", viewport: "mobile" },
    { name: "karachi", locale: "ur-PK", timezoneId: "Asia/Karachi" },
  ],
});

matrix

Tests every scenario in combinations of environments, so a problem that only shows up in one locale, timezone, theme, screen size or browser is found. Pairwise selection (the default) tests every pair of values at least once with few combinations. The environment matrix guide has the details and the limits of each browser.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  matrix: {
    locale: ["en-US", "de-DE", "ar-EG"],
    timezoneId: ["UTC", "Asia/Karachi", "America/Los_Angeles"],
    colorScheme: ["light", "dark"],
    viewport: ["desktop", "mobile"],
    // Custom axes: feature flags, tenants, currencies
    axes: {
      checkout: {
        new: { cookies: [{ name: "flag-checkout", value: "new" }] },
        old: {},
      },
    },
  },
});

The first value of every axis is the baseline and is always tested. --no-matrix tests the scenarios as configured.

probes

probes: true (or --probe) proves the cause of value mismatches. Pages with text or attribute differences are loaded again with one thing changed at a time: the clock, the random seed, the locale, the timezone, the theme, the viewport or storage. Each probed page costs up to 9 extra page loads, so probes are off by default. See probes.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  probes: { factors: ["time", "random"], maxPages: 5 },
  // Load every page 3 times and mark findings seen in only some runs as flaky
  repeat: 3,
});

ready

When a page counts as settled before the final snapshot. hydration-proof never waits for "network idle": it waits for a quiet period without DOM changes or React commits. For pages with animations, polling or live data that never go quiet, set a selector or a function, or lower quietMs.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  ready: {
    quietMs: 400,
    selector: "[data-page-ready]",
    // A page function, as a string, that must return a truthy value
    function: "() => window.__APP_READY__ === true",
  },
});

A route can override these with its own ready (see routes).

checks

Turns individual checks on or off. Everything that compares the server HTML with the hydrated page is on by default. The interaction and navigation checks load each page several extra times, so they are off until you enable them; see interactions and navigation, which also covers the top-level interactions option for custom Playwright steps.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  checks: {
    // Also flag suppressHydrationWarning that hides nothing
    suppressedWarnings: "strict",
    interactions: true,
    navigation: { from: "/", maxRoutes: 10 },
  },
});

ignore

Findings to leave out. Ignored findings stay in the report, marked as ignored, and do not fail the run. An issues rule needs a reason, and a rule past its expires date fails the run, so a temporary exception cannot become permanent. Ignoring findings covers when to use each kind.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  ignore: {
    // Third-party markup that is expected to differ
    selectors: ["#ad-slot", "[data-chat-widget]"],
    attributes: [/^data-gtm-/],
    issues: [
      {
        code: "HP4001",
        route: "/checkout",
        reason: "The payment iframe rewrites its container. Ticket ACME-431.",
        expires: "2026-12-31",
      },
    ],
  },
});

[data-hydration-proof-ignore] is always in selectors, so you can also mark an element in your markup.

ci

When the run fails: the lowest failing severity, a warning limit, a baseline of accepted findings, budgets and a history file for trends. Baselines and budgets explains how to adopt hydration-proof on an app that already has findings.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  ci: {
    failOn: "warning",
    maxWarnings: 10,
    newIssuesOnly: true,
    budget: {
      warning: 5,
      codes: { HP1004: 3 },
      routes: { "/legacy/**": { error: 2 } },
    },
    history: true,
  },
});

hooks

Code that runs around the test run, after the app is up. setup runs once per build mode, before any page is tested and before the scenario logins, and may return a teardown function. Teardown functions always run, even when testing fails. An error in setup stops the run. There are only these two hooks; sign-in belongs in a scenario's login.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  hooks: {
    // Seed data or create users. May return a teardown function.
    setup: async ({ baseUrl }) => {
      await fetch(`${baseUrl}/api/test/seed`, { method: "POST" });
      return async () => {
        await fetch(`${baseUrl}/api/test/reset`, { method: "POST" });
      };
    },
  },
});

owners

Who owns a finding. Owners come from route globs in the config and from the CODEOWNERS entries of the source files, and they are shown in every report and can be filtered in the HTML report.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  owners: {
    routes: { "/checkout/**": ["@acme/payments"] },
    codeowners: true,
  },
});

Other options

The table lists every top-level option, including the ones above:

adapter and plugins

adapter is "auto" by default: it is chosen from package.json and the framework's config files. Name one to override it, or pass your own from defineAdapter(). Plugins add normalizers, cause detectors, route providers, reporters and adapters. See adapters and plugins.

browser

redact

Redaction is on by default: emails, tokens, card numbers and secret URL parameters are removed from every report. Add patterns, black out elements in screenshots, or set redact: false to keep everything. See security.

projects

A config at the root of a monorepo can list the apps to test. Each app keeps its own config, and the run writes one combined report. See monorepos.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  projects: ["apps/web", { path: "apps/admin", name: "admin" }],
});

sourceOrigins

To report a file:line, hydration-proof downloads the page's scripts and their source maps, but only from the app's own origin. If your app serves its bundles from a CDN, allow that origin too:

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  sourceOrigins: ["https://cdn.example.com"],
});

Findings are still reported when a source map is skipped, only without a source location.

Related

• The CLI: flags that override these options
• Test every route: discovery, dynamic values and globs
• Scenarios and signed-in pages
• Ignore known findings with a reason and an expiry date
• Run it in CI