perf(react-router): avoid redundant link hydration updates

[Sheraff]

🎯 Changes

Avoid the extra hydration-triggered render for React Links whose active matching does not compare URL hashes.

Every Link currently subscribes to a hydration snapshot that changes from false to true. That schedules another render and invalidates the Link's location selector, even when its output does not depend on hydration. An @internal overload of useHydrated lets these Links use equal server/client snapshots without a separate helper. The implementation defaults enabled to true; declaration emission strips the boolean overload, preserving the public no-argument API. Hash-sensitive Links retain the deferred active-state update they need.

Found while investigating the 1,000-link table in e18e/framework-tracker#200.

Verified work reduction

Controlled hydration case	Before	After
Ordinary Link render-prop calls during hydration	2	1
Matching hash-sensitive Link active-state sequence	false → true	false → true

This avoids one hydration-snapshot-induced update per ordinary Link. Other parent/router updates can still cause renders. An improvement in e18e's FP/FCP, interaction latency, or SSR throughput has not been established.

The regression tests exercise distinct server/client fragment state, active/inactive props, DOM-node reuse, toggling hash matching after hydration, and a delayed Suspense hydration boundary. They check both recoverable errors and hydration diagnostics.

Validation

The local checks below passed for commit 544927c03d. The internal-overload follow-up (88a3c208ea) is left to CI, as requested.

Original validation used NX_BASE=origin/main, CI=1, and NX_DAEMON=false:

• pnpm test:eslint --outputStyle=stream --skipRemoteCache — passed.
• pnpm test:types --outputStyle=stream --skipRemoteCache — passed.
• pnpm test:unit --outputStyle=stream --skipRemoteCache — passed; React Router: 1,180 passed, one skipped.
• pnpm nx run tanstack-react-start-e2e-basic:test:e2e--vite-ssr --outputStyle=stream --skipRemoteCache -- tests/navigation.spec.ts tests/client-only.spec.ts — 11 passed.
• Formatting and git diff --check passed.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
• I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Bug Fixes
  • Fixed unnecessary hydration-triggered rerenders for links that do not compare URL hashes.
  • Preserved correct active-state updates for links that include URL hash comparisons.
  • Improved link behavior when hydration occurs within delayed loading boundaries.
  • Prevented related hydration and console errors during link rendering.
  • Ensured ordinary links retain their server-rendered state during hydration while hash-sensitive links update correctly.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 544927c

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	16m 19s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1m 37s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-09-15 15:40:28 UTC

[github-actions]

🚀 Changeset Version Preview

4 package(s) bumped directly, 19 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-router	1.170.36 → 1.170.37	Changeset
@tanstack/router-core	1.171.30 → 1.171.31	Changeset
@tanstack/solid-router	1.170.34 → 1.170.35	Changeset
@tanstack/vue-router	1.170.33 → 1.170.34	Changeset
@tanstack/react-start	1.168.54 → 1.168.55	Dependent
@tanstack/react-start-client	1.168.34 → 1.168.35	Dependent
@tanstack/react-start-rsc	0.1.53 → 0.1.54	Dependent
@tanstack/react-start-server	1.167.41 → 1.167.42	Dependent
@tanstack/router-cli	1.167.36 → 1.167.37	Dependent
@tanstack/router-generator	1.167.36 → 1.167.37	Dependent
@tanstack/router-plugin	1.168.38 → 1.168.39	Dependent
@tanstack/router-vite-plugin	1.167.38 → 1.167.39	Dependent
@tanstack/solid-start	1.168.52 → 1.168.53	Dependent
@tanstack/solid-start-client	1.168.33 → 1.168.34	Dependent
@tanstack/solid-start-server	1.167.40 → 1.167.41	Dependent
@tanstack/start-client-core	1.170.30 → 1.170.31	Dependent
@tanstack/start-plugin-core	1.171.44 → 1.171.45	Dependent
@tanstack/start-server-core	1.169.35 → 1.169.36	Dependent
@tanstack/start-static-server-functions	1.167.35 → 1.167.36	Dependent
@tanstack/start-storage-context	1.167.32 → 1.167.33	Dependent
@tanstack/vue-start	1.168.51 → 1.168.52	Dependent
@tanstack/vue-start-client	1.167.36 → 1.167.37	Dependent
@tanstack/vue-start-server	1.167.40 → 1.167.41	Dependent

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 7db4fc18-e8a0-44e8-bb5f-36fbef0e80a9

📥 Commits

Reviewing files that changed from the base of the PR and between 544927c and 88a3c20.

📒 Files selected for processing (2)

• packages/react-router/src/ClientOnly.tsx
• packages/react-router/src/link.tsx

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The change folds conditional hydration into the overloaded useHydrated hook. Links enable it only when activeOptions.includeHash is set. New tests cover standard links, hash-sensitive links, and delayed Suspense hydration.

Changes

Hydration-aware links

Layer / File(s)	Summary
Conditional hydration state packages/react-router/src/ClientOnly.tsx, packages/react-router/src/link.tsx	Adds an internal boolean overload to useHydrated and removes useHydratedWhen. Links pass the includeHash condition to useHydrated.
Hydration behavior validation and release metadata packages/react-router/tests/link-hydration.test.tsx, .changeset/large-rockets-push.md	Adds tests for standard links, hash-sensitive links, delayed Suspense hydration, and recoverable errors. Declares a patch release.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Refactor · Severity of issue fixed: Low

Suggested reviewers: schiller-manuel

Merge Risk: ⚪ Minimal · up to 88a3c

The hydration behavior is covered for ordinary, hash-sensitive, and delayed links, with no unresolved merge-blocking risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the main change: preventing redundant hydration updates for React Router links.
Description check	✅ Passed	The description clearly explains the change, motivation, tests, validation results, release impact, and changeset. One checklist item about understanding AI-assisted code remains unchecked, but the de…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/react-link-hydration-snapshot

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Bundle Size Benchmarks

• Commit: 183fbfa3f7dd
• Measured at: 2026-09-15T15:24:57.619Z
• Baseline source: history:8e164d28f9e9
• Dashboard: bundle-size history

The following scenarios have bundle-size changes compared with the baseline:

Scenario	Current (gzip)	Initial (gzip)	Raw	Brotli	Trend
react-router.minimal	84.0 KiB +14 B	83.8 KiB +13 B	261.6 KiB +25 B	73.2 KiB -18 B	▂▂▂▂▂████▁▁▃
react-router.full	87.5 KiB +27 B	87.3 KiB +29 B	273.3 KiB +27 B	76.2 KiB +12 B	▄▄▄▄▃████▂▁▅
react-start.minimal	96.9 KiB +12 B	96.8 KiB +11 B	303.9 KiB +25 B	84.1 KiB +23 B	▂▂▂▂▁████▄▄▅
react-start.query-integration	104.3 KiB +13 B	104.1 KiB +14 B	330.4 KiB +25 B	90.4 KiB -29 B	▂▂▂▂▁████▄▄▅
react-start.deferred-hydration	97.6 KiB +21 B	96.8 KiB +14 B	305.2 KiB +25 B	84.8 KiB +138 B	▁▁▁▁▁████▃▃▅
react-start.full	100.1 KiB +17 B	99.9 KiB +14 B	313.6 KiB +25 B	86.8 KiB +7 B	▁▁▁▁▁████▃▃▅
react-start.rsbuild.minimal	100.2 KiB +29 B	100.1 KiB +29 B	314.4 KiB +86 B	86.5 KiB +74 B	▁▁▁▁▁██▇▇▆▆█
react-start.rsbuild.minimal-iife	100.6 KiB +28 B	100.5 KiB +28 B	315.3 KiB +86 B	86.8 KiB -113 B	▁▁▁▁▁████▆▆█
react-start.rsbuild.full	103.5 KiB +30 B	103.3 KiB +30 B	324.5 KiB +86 B	89.3 KiB +167 B	▁▁▁▁▁████▅▅▇

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

[pkg-pr-new]

More templates

• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsbuild
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-example-next-migration
• tanstack-start-example-rscs
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@8435

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@8435

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8435

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@8435

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@8435

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@8435

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@8435

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@8435

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@8435

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@8435

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@8435

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@8435

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@8435

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@8435

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@8435

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@8435

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@8435

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@8435

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@8435

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@8435

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@8435

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@8435

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@8435

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@8435

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@8435

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@8435

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@8435

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@8435

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8435

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@8435

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@8435

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@8435

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@8435

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@8435

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8435

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@8435

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@8435

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@8435

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@8435

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@8435

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@8435

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@8435

commit: 88a3c20

[codspeed]

Merging this PR will not alter performance

✅ 180 untouched benchmarks

---

_{Comparing perf/react-link-hydration-snapshot (88a3c20) with main (8e164d2)}