Skip to content

fix(react-router): suppress nonce hydration warning in <Links> - #15721

Merged
brophdawg11 merged 5 commits into
remix-run:mainfrom
lord-0011:fix/links-nonce-hydration-warning
Nov 20, 2026
Merged

brophdawg11 merged 5 commits into
remix-run:mainfrom
lord-0011:fix/links-nonce-hydration-warning

Conversation

@lord-0011

@lord-0011 lord-0011 commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #15603

Since #15170 (v7.18.0), <Links> falls back to the <ServerRouter nonce> value from FrameworkContext, so the server renders nonce="..." on the critical CSS <style>/<link> and on route <link>s. In the browser, <HydratedRouter> doesn't provide a nonce, so <Links> renders nonce={undefined} and React logs a hydration mismatch:

  <Links>
    <link
      data-react-router-critical-css=""
      rel="stylesheet"
      href="/@react-router/critical.css?pathname=/"
+     nonce={undefined}
-     nonce=""
    >

This happens with the setup from the Security guide (nonce on <ServerRouter> and renderToPipeableStream only), on React 19.2 as well as 19.3.

<Scripts> and <ScrollRestoration> have the same server/client difference, but their elements already use suppressHydrationWarning (e.g. the <link rel="modulepreload" nonce={scriptProps.nonce} suppressHydrationWarning /> elements in <Scripts>), so only <Links> warns.

Changes

  • <Links>: add suppressHydrationWarning to the critical CSS <style>, the critical CSS <link>, and the route <link> elements, matching <Scripts> and <ScrollRestoration>. The server-rendered nonce is unchanged and stays on the elements.
  • Test in components-test.tsx: renders <Links /> with renderToString using a FrameworkContext with a nonce, then hydrates it with a context without a nonce and asserts no console.error. It fails without this change (the same nonce={undefined} / nonce="server-nonce" diff for <style> and <link>) and passes with it.
  • Default root error boundary and hydrate fallback: add suppressHydrationWarning to the dev-warning <script nonce> in RemixRootDefaultErrorBoundary and RemixRootDefaultHydrateFallback. They have the same mismatch (reported in the review). Covered by error-boundaries-test.tsx, where both tests fail without the change and pass with it.
  • Change file packages/react-router/.changes/patch.links-nonce-hydration-warning.md.

Alternative

Another option would be to provide the nonce on the client (for example a nonce prop on <HydratedRouter>, or reading .nonce from an existing element) so the client renders the same value. That's a larger API change, so this PR follows the existing <Scripts> approach. Happy to switch if you'd prefer that direction.

Testing

  • pnpm test packages/react-router/__tests__/dom/ssr/components-test.tsx packages/react-router/__tests__/dom/ssr/error-boundaries-test.tsx: 27/27 pass (the new tests fail on main).
  • pnpm typecheck, pnpm run changes:validate and Prettier pass; pnpm lint has no errors.
  • Running pnpm test packages/react-router/ locally on Windows, two unrelated suites (data-browser-router-test.tsx, special-characters-test.tsx) hit timing/timeouts under parallel load; the rest pass.

AI disclosure: I used an AI coding assistant to help prepare this change. I reproduced the issue with the linked repro, reviewed the diff line by line, and confirmed the new test fails without the fix and passes with it.

@lord-0011

Copy link
Copy Markdown
Contributor Author

I've opened #15721 with a fix and a regression test.

@zachthedev

Copy link
Copy Markdown

The default root error boundary has the same mismatch, and this PR doesn't cover it. When a loader throws and the app
exports no ErrorBoundary, its <script nonce> warns too (pa/ma are RemixRootDefaultErrorBoundary/BoundaryShell):

<pa error={Error}>
  <ma title="Applicatio..." isOutsideRemixApp={undefined}>
    <h1>
    <pre>
    <script
+     nonce={undefined}
-     nonce=""

Repro, framework mode with ssr: true:

  1. entry.server.tsx passes the nonce to <ServerRouter> and renderToReadableStream, and sends a CSP with it.
  2. root.tsx has Meta, Links, ScrollRestoration, Scripts and a CSS import, and no ErrorBoundary.
  3. Add a route whose loader throws.
  4. NODE_ENV=development react-router build --mode development, serve with createRequestHandler(build, 'development'),
    open the route in Chromium. Without NODE_ENV=development nothing warns.

With this PR's change applied, / is clean and the throwing route still warns for the <script>.

react-router 8.5.1, react 19.3.1, Chromium 156.

@lord-0011

Copy link
Copy Markdown
Contributor Author

Thanks for catching this! You're right: RemixRootDefaultErrorBoundary renders its "Hey developer" <script> with the FrameworkContext nonce and no suppressHydrationWarning, so it has the same server/client mismatch. RemixRootDefaultHydrateFallback has the same dev-only <script nonce> too.

I pushed a commit that adds suppressHydrationWarning to both scripts. It also adds __tests__/dom/ssr/error-boundaries-test.tsx, which server-renders each component with a nonce and hydrates it without one. Both tests fail without the change (the same nonce={undefined} / nonce="server-nonce" diff on the <script>) and pass with it. I updated the change file to match.

Replace the original hydration tests with the council-reviewed cases for
critical CSS, route links, default developer scripts and page prefetches.
Add browser coverage for hydration and nonce preservation, and clarify
the change file. The runtime fix is already present in PR remix-run#15721.
@brophdawg11

Copy link
Copy Markdown
Contributor

Pushed c5c00db to strengthen the regression coverage around the existing fix:

  • Replaced the original hydration tests with separate cases for inline/external critical CSS, route stylesheets, and the default error-boundary/hydrate-fallback developer scripts. The tests explicitly check that the target elements render, hydration reuses the same DOM nodes, and the server nonce survives. Checking that the developer scripts actually render prevents a warning assertion from passing without exercising the affected element.
  • Added a Framework Mode Chromium regression covering successful hydration and interaction, retained stylesheet/prefetch nonces, and absence of hydration warnings. The component tests also cover Framework and RSC page-prefetch links, which already passed without additional suppression.
  • Tightened the change-file wording to describe the affected elements precisely.

I also tested whether carrying the document nonce into client FrameworkContext could replace suppression. An isolated harness using this commit's actual components, React 19.2.7, and Chromium ran 40 combinations across the five affected elements:

CSP response header Matching client nonce Suppression Elements producing hydration warnings
Present Yes Off 5/5
Present Yes On 0/5
Absent Yes Off 0/5

With CSP enabled, the browser exposes the value through .nonce but hides it from getAttribute("nonce"). React still compares the client nonce against the empty attribute value. All cases retained the original nodes and nonce values, hydrated a working button, and had no CSP violations.

This supports keeping the existing suppression approach. The experiment injected client context directly; it did not implement nonce transport in HydratedRouter. Automatic client propagation would be a separate API decision, and the runtime changes in this PR remain unchanged.

The full repository suites were not rerun after replaying the follow-up commit onto this PR's head; the isolated browser experiment used the resulting commit's component source.

Authored by an AI agent on behalf of @brophdawg11

Include main at 6abdb19, which advanced during merge validation.

@brophdawg11 brophdawg11 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 956b64a. The six-file PR diff retains the reviewed nonce fix and regression coverage after merging main. The Chromium matrix confirmed that matching client context alone does not eliminate nonce hydration warnings under CSP, while suppression preserves DOM identity and nonce values. No code blockers found; merge remains contingent on CI.

Authored by an AI agent on behalf of @brophdawg11

@brophdawg11
brophdawg11 merged commit e2950be into remix-run:main Nov 20, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs]: How to use a nonce without React 19.3 hydration warning

3 participants