Routes

To test every route for hydration errors, hydration-proof combines the routes it discovers from your framework and build output with the paths, dynamic values, sitemap entries and crawled links you configure. Every page in the report records where its route came from. A dynamic route needs example values, or it is skipped with a note.

Where routes come from

include, exclude and --grep apply to routes from every source.

Discovery for each framework

Discovery is on when you do not list paths. The adapter decides where routes come from:

List routes yourself

paths adds routes discovery cannot know about: redirects, rewrites, pages behind a flag, or every route of a framework without discovery. An entry is a path string, with an optional query, or an object with more options:

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  routes: {
    paths: [
      "/",
      "/pricing?plan=team",
      // A page that is meant to answer 404
      { path: "/404-page", expectStatus: [404], ready: { selector: "#app" } },
      // A page that is meant to redirect
      { path: "/account", expectRedirect: "/login" },
      // Only in one scenario
      { path: "/admin", scenarios: ["admin"] },
    ],
  },
});

• expectStatus lists HTTP statuses that are not errors for the route.
• expectRedirect is the path the route should end on. Without it, a page that ends on another path is reported as HP9010.
• ready overrides the ready options for this route, for example a page that never goes quiet.
• scenarios limits the route to some scenarios.

Dynamic routes

A route like /products/[id] has nothing to render until it has a value. Give it example values in dynamic:

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  routes: {
    dynamic: {
      "/products/[id]": ["1", "42"],
      // Several parameters: separate the values with "/";
      // a catch-all takes the rest
      "/[lang]/docs/[...slug]": ["en/getting-started/install"],
    },
  },
});

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

For Next.js, pages the build pre-rendered with generateStaticParams or getStaticPaths are tested without any config: up to manifestExamples values (3 by default) are taken per dynamic route from the build output. Dynamic routes that end up with no values are skipped, and the run lists them in a note.

Query-string variants

When a page renders differently for a query string, test each variant:

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  routes: {
    query: { "/search": ["?q=shoes", "?q=&page=2"] },
  },
});

Routes from the sitemap

sitemap: true (or --sitemap) also tests the routes in your sitemap. It reads the Sitemap: lines of robots.txt and /sitemap.xml; you can also give a sitemap URL or path. Sitemap indexes are followed, and absolute URLs are moved to the tested app, so a sitemap that names https://example.com still works locally.

Crawl links from tested pages

crawl: true (or --crawl) also tests same-origin links found on the tested pages, to a depth of 2 and at most 50 routes. Pass { depth, limit } to change that. Crawled links are grouped under the most specific known route pattern, and crawling never leaves the app's origin.

The not-found page

For Next.js, notFound is on: hydration-proof also loads /hydration-proof-not-found and checks that your not-found page hydrates. That URL must answer with a 404. Set notFound: false to skip it.

Include and exclude routes with globs

include and exclude take globs, matched against the route's path:

• * matches one path segment.
• ** matches any number of segments, and /blog/** also matches /blog.
• exclude defaults to ["/api/**"]. Setting it replaces that default, so keep /api/** in your list.

import { defineConfig } from "hydration-proof";
 
export default defineConfig({
  routes: {
    include: ["/", "/blog/**", "/products/*"],
    exclude: ["/api/**", "/admin/**"],
  },
});

Scenarios have their own include and exclude, for pages only one identity can open.

Choose routes on the command line

# Only these routes; discovery, the sitemap and the not-found probe are off
npx hydration-proof test --route / --route /pricing
 
# Only routes whose path matches a regular expression
npx hydration-proof test --grep "^/blog"
 
# Also the sitemap, and links found on tested pages
npx hydration-proof test --sitemap --crawl
 
# Only the routes the files changed since main can affect
npx hydration-proof test --changed main

--grep applies to routes from every source. --changed reads an import graph of your sources; see CI for how it picks routes.

The route cache

Discovered routes are cached in .hydration-proof/cache/routes.json. The cache key covers the Next.js build id and the modification times of the route folders, so a new build or a changed route folder invalidates it. Sitemap and crawled routes are never cached.

If a new page is missing, run with --no-cache, or set cache: false in the config to always discover again:

npx hydration-proof test --no-cache

How to test every route for hydration errors in a Next.js app

This config, from the package's examples, is what most Next.js apps end up with after the first run: discovery, one real value per dynamic segment, and the routes that are not pages.

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/**"],
  },
});

All route options

Related

• Scenarios and signed-in pages
• Frameworks and adapters: how each one discovers routes
• Configuration reference
• Split the routes across CI jobs
• HP9010: a page ended on an unexpected URL