perf(react-router): add match selector compares

[Sheraff]

Summary

• add selector compares for Match and Outlet store subscriptions
• subscribe OnRendered to the resolved location key instead of passing resetKey

Tests

• Not run in this PR-only step

Summary by CodeRabbit

• Refactor
  • Reduced unnecessary re-renders for route matches and outlets to improve app responsiveness and performance.
  • Improved root-route rendering logic and tracking so rendering callbacks fire more reliably when navigation state meaningfully changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6f82c305-5333-4e96-aae8-9eb7e498650a

📥 Commits

Reviewing files that changed from the base of the PR and between ae94df8 and 9926ac4.

📒 Files selected for processing (1)

• packages/react-router/src/Match.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/react-router/src/Match.tsx

---

📝 Walkthrough

Walkthrough

This PR adds equality comparators for Match/Outlet useStore subscriptions to avoid unnecessary rerenders and refactors OnRendered to derive and track a renderedLocationKey from resolvedLocation.state.__TSR_key for effect re-invocation.

Changes

Match subscription and OnRendered optimization

Layer / File(s)	Summary
Equality comparator helpers packages/react-router/src/Match.tsx	matchViewFieldsEqual and outletMatchSelectionEqual functions added to compare selected store fields.
Match and Outlet subscription filtering packages/react-router/src/Match.tsx	Match subscription now uses matchViewFieldsEqual; Outlet selects [routeId, parentGlobalNotFound] with outletMatchSelectionEqual to suppress unrelated updates.
OnRendered location key tracking packages/react-router/src/Match.tsx	OnRendered converted to a prop-less component that reads renderedLocationKey from resolvedLocation.state.__TSR_key, uses it as the layout-effect dependency, and preserves the previous resolved location for change info.

🎯 3 (Moderate) | ⏱️ ~20 minutes

🐰
I nibble at renders, soft and quick,
Filters in place to skip the tick.
Keys whispered low, effects re-run,
Fewer hops now get the job done.
A hop, a skip, and fewer lights ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'perf(react-router): add match selector compares' directly and accurately reflects the main changes: adding equality comparators/selector compares to improve performance in the Match component and related store subscriptions.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 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-router-match-selector-compares

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 620e967

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	❌ Failed	10m 7s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1m 20s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-10 22:16:58 UTC

[github-actions]

🚀 Changeset Version Preview

2 package(s) bumped directly, 7 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-router	1.170.15 → 1.170.16	Changeset
@tanstack/solid-router	1.170.15 → 1.170.16	Changeset
@tanstack/react-start	1.168.25 → 1.168.26	Dependent
@tanstack/react-start-client	1.168.13 → 1.168.14	Dependent
@tanstack/react-start-rsc	0.1.24 → 0.1.25	Dependent
@tanstack/react-start-server	1.167.19 → 1.167.20	Dependent
@tanstack/solid-start	1.168.25 → 1.168.26	Dependent
@tanstack/solid-start-client	1.168.13 → 1.168.14	Dependent
@tanstack/solid-start-server	1.167.19 → 1.167.20	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: d693a821b115
• Measured at: 2026-06-10T22:07:39.087Z
• Baseline source: history:52db7034fd83
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.29 KiB	+30 B (+0.03%)	87.15 KiB	273.66 KiB	75.88 KiB	▃▁▁▁▁▁▁▁▁▁▃█
react-router.full	91.02 KiB	+38 B (+0.04%)	90.88 KiB	285.56 KiB	79.09 KiB	█▇▇▇▇▇▇▁▁▁▁▃
solid-router.minimal	35.48 KiB	0 B (0.00%)	35.36 KiB	105.86 KiB	32.03 KiB	▃▆▆▆▆▆▆▆█▁▁
solid-router.full	40.53 KiB	0 B (0.00%)	40.41 KiB	121.08 KiB	36.46 KiB	█▄▄▄▄▄▄▄▅▁▁
vue-router.minimal	52.97 KiB	0 B (0.00%)	52.84 KiB	149.90 KiB	47.62 KiB	█▆▆▆▆▆▆▆▁▁▁
vue-router.full	58.96 KiB	0 B (0.00%)	58.83 KiB	168.66 KiB	52.87 KiB	█▁▁▁▁▁▁▁▅▅▅
react-start.minimal	101.91 KiB	+28 B (+0.03%)	101.77 KiB	321.98 KiB	88.21 KiB	▂▁▁▁▁▁▁▁▂▂▃█
react-start.deferred-hydration	102.65 KiB	+37 B (+0.04%)	101.80 KiB	323.36 KiB	88.90 KiB	▂▁▁▁▁▁▁▂▂▂▂█
react-start.full	105.31 KiB	+39 B (+0.04%)	105.18 KiB	331.91 KiB	91.06 KiB	▃▃▃████▁▁▁▂▆
react-start.rsbuild.minimal	99.63 KiB	+39 B (+0.04%)	99.46 KiB	316.43 KiB	85.79 KiB	▂▃▃▃▃▃▃▁▂▂▃█
react-start.rsbuild.minimal-iife	100.03 KiB	+37 B (+0.04%)	99.87 KiB	317.37 KiB	86.08 KiB	▂▃▃▃▃▃▃▁▂▂▃█
react-start.rsbuild.full	102.86 KiB	+41 B (+0.04%)	102.68 KiB	326.48 KiB	88.53 KiB	▄▅▅████▁▁▁▁▅
solid-start.minimal	49.60 KiB	0 B (0.00%)	49.47 KiB	151.93 KiB	43.79 KiB	▁▇▇▇▇▇▇▇█▂▂
solid-start.deferred-hydration	52.86 KiB	0 B (0.00%)	49.53 KiB	159.97 KiB	46.81 KiB	▁▆▆▆▆▆▆▆█▅▅
solid-start.full	55.40 KiB	0 B (0.00%)	55.27 KiB	168.97 KiB	48.80 KiB	▃▁▁▇▇▇▇▇█▆▆
vue-start.minimal	71.02 KiB	0 B (0.00%)	70.89 KiB	207.04 KiB	62.93 KiB	▂▁▁▁▁▁▁▁███
vue-start.full	75.01 KiB	0 B (0.00%)	74.88 KiB	219.68 KiB	66.40 KiB	▂▁▁▇▇▇▇▇███

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-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-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@7596

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 9926ac4

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/react-router/src/Match.tsx`:
- Around line 34-35: The equality comparator matchViewFieldsEqual currently only
compares routeId and _displayPending, so changes to match.ssr are ignored;
update matchViewFieldsEqual (the function named matchViewFieldsEqual that takes
AnyRouteMatch a and b) to also compare a.ssr === b.ssr so it matches the useMemo
dependencies that include match.ssr and prevents stale matchState when ssr
changes.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1b3cf076-503f-439e-a25d-639ea300b66b

📥 Commits

Reviewing files that changed from the base of the PR and between 52db703 and ae94df8.

📒 Files selected for processing (1)

• packages/react-router/src/Match.tsx

[codspeed-hq]

Merging this PR will improve performance by 6.28%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 5 untouched benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	client-side navigation loop (react)	58.7 ms	55.3 ms	+6.28%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing perf/react-router-match-selector-compares (9926ac4) with main (52db703)}

[nx-cloud]

Nx Cloud is proposing a fix for your failed CI:

We fixed the ESLint error introduced by this PR by moving the // eslint-disable-next-line react-hooks/rules-of-hooks directive to immediately precede the React.useRef call in OnRendered. Previously, the directive was placed before a block of multi-line comments, causing it to suppress the @ts-expect-error line instead of the hook call, which left React.useRef unguarded after the early return. This resolves the single blocking error in @tanstack/react-router:test:eslint.

Tip

✅ We verified this fix by re-running @tanstack/react-router:test:eslint.

diff --git a/packages/react-router/src/Match.tsx b/packages/react-router/src/Match.tsx
index acecde90..3e37579c 100644
--- a/packages/react-router/src/Match.tsx
+++ b/packages/react-router/src/Match.tsx
@@ -247,13 +247,13 @@ function OnRendered() {
     return null
   }
 
-  // eslint-disable-next-line react-hooks/rules-of-hooks
   // @ts-expect-error -- init to `undefined` but don't write `undefined` to shave bytes
   // Track the resolvedLocation as of the last render so that onRendered can
   // report the correct fromLocation. By the time this effect fires,
   // resolvedLocation has already been updated to the new location by
   // Transitioner, so we cannot use router.stores.resolvedLocation.get()
   // directly as the fromLocation.
+  // eslint-disable-next-line react-hooks/rules-of-hooks
   const prevResolvedLocationRef = React.useRef<
     ParsedLocation<any> | undefined
   >()

  

Or Apply changes locally with:

npx nx-cloud apply-locally AsVF-7DDa

Apply fix locally with your editor ↗   View interactive diff ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}