Adapters

hydration-proof adapters tell the CLI how to build and start your app, where its routes are, and which markup the framework adds that is not page content. With the default adapter: "auto", the adapter is chosen from package.json and your config files. Set it yourself when detection is wrong, or write one for a framework it does not know.

Which hydration-proof adapters are built in?

With adapter: "auto", adapters from plugins are tried first, then the built-in ones in the order of the table. The first match wins, and none is used when nothing matches.

Each adapter also knows the file that means a build exists, such as .next/BUILD_ID for Next.js. By default the app is built only when that file is missing (server.buildWhen: "if-missing"); --build forces a fresh build.

What else an adapter handles

• Framework markup. Markup the framework adds is left out of every comparison: the Next.js route announcer, dev overlay and RSC payload scripts, the React Router and Remix context scripts, Astro's island loader and dev toolbar, and Vite's client and React Refresh scripts.
• The development server host. The next adapter opens next dev on localhost, because Next.js blocks development resources for other hosts.
• The not-found page. The next, react-router, remix and astro adapters also load /hydration-proof-not-found and check that the not-found page hydrates. It must answer 404. Turn this off with routes.notFound: false.
• Client navigation. Adapters with a router in the last column support navigation checks, which compare a client-side navigation to each route with loading it directly.

Dynamic routes use one syntax for every framework: [id], [...slug] (catch-all) and [[lang]] (optional). React Router's :id, * and :lang? are converted, so routes.dynamic looks the same everywhere:

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

Choose an adapter

Set adapter when detection picks the wrong framework, or to skip detection altogether:

import { defineConfig } from "hydration-proof";
 
export default defineConfig({ adapter: "react-router" });

An unknown name stops the run with exit code 2 and lists the adapters that exist. To see what was detected, and how many routes it found, run:

npx hydration-proof doctor

Every adapter can be overridden: server.command, server.build, server.devCommand and routes in your config always win.

Custom React servers

For Express, Fastify, node:http or any other server that renders React, use the node adapter (or none) with your own commands:

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  adapter: "node",
  server: {
    build: "npm run build",
    command: "node server.js", // listens on process.env.PORT
    devCommand: "node --watch server.js",
  },
  routes: { paths: ["/", "/pricing", "/products/1"] },
});

{port} in a command is replaced with the port hydration-proof chose, and the same port is in the PORT environment variable. A custom start command only gets a build step when you configure server.build.

Streaming servers are supported. With renderToPipeableStream or renderToReadableStream, Suspense boundaries that hydrate later are compared on their own. Custom React servers covers the setup in detail.

Astro islands

Each <astro-island> hydrates as its own React root, so findings are reported per island. Astro changes island attributes (ssr, props, client and others) while it loads them; these are never compared. Pages without any React are normal in an Astro site and are not reported.

Islands that call useId need an identifierPrefix, or two roots generate the same ids. Astro's React integration sets one per island; without it hydration-proof reports HP3004. See Astro hydration errors.

Write an adapter with defineAdapter

For a framework hydration-proof does not know, create an adapter with defineAdapter, directly in the config or in a plugin:

import { existsSync } from "node:fs";
import { join } from "node:path";
import { defineAdapter, defineConfig } from "hydration-proof";
 
const waku = defineAdapter({
  name: "waku",
  detect: (rootDir) => existsSync(join(rootDir, "waku.config.ts")),
  commands: () => ({
    build: "waku build",
    start: "waku start --port {port}",
    dev: "waku dev --port {port}",
    buildOutput: "dist/index.js",
  }),
  discoverRoutes: () => [
    {
      pattern: "/",
      dynamic: false,
      router: "app",
      file: "src/pages/index.tsx",
    },
  ],
  normalizers: [
    {
      name: "waku-data",
      match: (node) =>
        node.k === 1 &&
        node.tag === "script" &&
        node.attrs.some(([name]) => name === "data-waku")
          ? "drop"
          : undefined,
    },
  ],
  navigation: {
    navigate: `(url) => { window.__WAKU_ROUTER__?.push(url); return Boolean(window.__WAKU_ROUTER__); }`,
  },
  notFound: true,
});
 
export default defineConfig({ adapter: waku });

The options that are not functions, with their types:

The adapter API is part of the stable public API: see compatibility. To share an adapter between apps, put it in a plugin's adapters list.

Related

• Next.js hydration errors and the next adapter
• React Router and Remix apps
• Vite SSR apps
• Routes: discovery, dynamic values, sitemaps and crawling
• Plugins: normalizers, detectors, routes and reporters