fix(react-router): avoid throwing in useMatch selector by Sheraff · Pull Request #7595 · TanStack/router

Sheraff · 2026-06-10T19:07:31Z

Summary

Move the React useMatch missing-match invariant out of the store selector by returning the existing dummyStore sentinel.
Preserve shouldThrow: false returning undefined and add coverage for selectors that legitimately return undefined.

Verification

CI=1 NX_DAEMON=false pnpm nx run @tanstack/react-router:test:unit --outputStyle=stream --skipRemoteCache -- tests/useMatch.test.tsx
CI=1 NX_DAEMON=false pnpm nx run @tanstack/react-router:test:unit --outputStyle=stream --skipRemoteCache
CI=1 NX_DAEMON=false pnpm nx run @tanstack/react-router:test:types --outputStyle=stream --skipRemoteCache
React client-nav benchmark: verified pre-change production invariant branch was hit 17,856 times across 4,960 measured navigations; sentinel path removes those selector-time throws.
Checked Solid/Vue adapters with temporary instrumentation; they had 0 missing-match throws in their client-nav benchmarks and do not need this change.

Summary by CodeRabbit

Refactor
- Improved match selection internals, yielding a performance improvement when navigating away from a previously matched route.
Tests
- Added coverage for an edge case where a match is found but a user-provided selector returns undefined, ensuring stable rendering and selector invocation.

coderabbitai · 2026-06-10T19:07:47Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 84ab56c1-8aa0-4622-9ddb-f0e35c2e449b

📥 Commits

Reviewing files that changed from the base of the PR and between c6be088 and e99d31b.

📒 Files selected for processing (2)

.changeset/empty-olives-melt.md
packages/react-router/src/useMatch.tsx

✅ Files skipped from review due to trivial changes (1)

.changeset/empty-olives-melt.md

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

packages/react-router/src/useMatch.tsx

📝 Walkthrough

Walkthrough

The PR refactors client-side return logic in useMatch to apply a dummyStore fallback inside the selector and store the useStore result as matchSelection; a test was added for when select returns undefined.

Changes

useMatch selector fallback handling

Layer / File(s)	Summary
Client-side selector fallback implementation and test `packages/react-router/src/useMatch.tsx`, `packages/react-router/tests/useMatch.test.tsx`, `.changeset/empty-olives-melt.md`	Client-side `useMatch` now uses `useStore(matchStore ?? dummyStore, selector)` to produce `matchSelection` (selector applies `dummyStore` fallback); returns `matchSelection` only when it differs from `dummyStore`, otherwise performs the existing `opts.shouldThrow` invariant/undefined behavior. Test added for a found match where `select` returns `undefined`. Changeset added for a patch release.

Sequence Diagram(s)

sequenceDiagram
  participant useMatch
  participant useStore
  participant selector
  participant matchStore
  useMatch->>useStore: useStore(matchStore ?? dummyStore, selector)
  useStore->>selector: execute selector (apply dummyStore fallback)
  selector->>useStore: selected value or dummyStore
  useStore->>useMatch: matchSelection
  useMatch->>useMatch: if matchSelection !== dummyStore -> return selection
  useMatch->>useMatch: else -> opts.shouldThrow -> invariant/return undefined

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

TanStack/router#7577: Overlaps changes to packages/react-router/src/useMatch.tsx that modify client-side match selection and structural-sharing behavior.

Poem

🐰 A selector that falls back just right,
When undefined returns from the height,
With dummyStore standing guard,
The match flows in unbarred—
Tests confirm it shines bright! ✨

🚥 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 title accurately describes the main change: moving the invariant logic out of the useMatch selector to avoid throwing, which is the core of this performance optimization.
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 fix/react-use-match-missing-sentinel

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

nx-cloud · 2026-06-10T19:08:03Z

View your CI Pipeline Execution ↗ for commit e99d31b

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

☁️ Nx Cloud last updated this comment at 2026-06-10 19:39:20 UTC

github-actions · 2026-06-10T19:08:22Z

🚀 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 · 2026-06-10T19:10:29Z

Bundle Size Benchmarks

Commit: c43eadccb947
Measured at: 2026-06-10T19:31:10.437Z
Baseline source: history:41e7a24f693b
Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
`react-router.minimal`	87.26 KiB	+12 B (+0.01%)	87.12 KiB	273.58 KiB	75.86 KiB	██▂▂▂▂▂▂▁▂▂█
`react-router.full`	90.98 KiB	-1 B (-0.00%)	90.85 KiB	285.48 KiB	79.16 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.88 KiB	+2 B (+0.00%)	101.75 KiB	321.90 KiB	88.29 KiB	▄▄▁▁▁▁▁▁▁▆▆█
`react-start.deferred-hydration`	102.62 KiB	+1 B (+0.00%)	101.77 KiB	323.28 KiB	88.84 KiB	▇▇▁▁▁▁▁▁▇▇▇█
`react-start.full`	105.28 KiB	+4 B (+0.00%)	105.14 KiB	331.83 KiB	91.05 KiB	▃▃▃▃████▁▁▁▂
`react-start.rsbuild.minimal`	99.59 KiB	+5 B (+0.00%)	99.42 KiB	316.35 KiB	85.74 KiB	▅▅██████▁▅▅▇
`react-start.rsbuild.minimal-iife`	100.00 KiB	+5 B (+0.00%)	99.83 KiB	317.29 KiB	86.09 KiB	▃▃██████▁▆▆█
`react-start.rsbuild.full`	102.82 KiB	+5 B (+0.00%)	102.64 KiB	326.41 KiB	88.46 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 · 2026-06-10T19:12:34Z

More templates

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: e99d31b

nx-cloud

Important

At least one additional CI pipeline execution has run since the conclusion below was written and it may no longer be applicable.

Nx Cloud is proposing a fix for your failed CI:

We removed the redundant as any cast on the return matchSelection statement in useMatch.tsx, which was flagged as an error by @typescript-eslint/no-unnecessary-type-assertion. The assertion was a no-op because the useStore selector already infers matchSelection as any at that point, so the cast did not change the type. This change resolves the single ESLint error that caused the @tanstack/react-router:test:eslint task to fail.

Tip

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

diff --git a/packages/react-router/src/useMatch.tsx b/packages/react-router/src/useMatch.tsx
index 32fba9bc..6c1d0342 100644
--- a/packages/react-router/src/useMatch.tsx
+++ b/packages/react-router/src/useMatch.tsx
@@ -184,7 +184,7 @@ export function useMatch<
   )
 
   if (matchSelection !== dummyStore) {
-    return matchSelection as any
+    return matchSelection
   }
 
   if (opts.shouldThrow ?? true) {

Or Apply changes locally with:

npx nx-cloud apply-locally zIOc-9rVw

Apply fix locally with your editor ↗ View interactive diff ↗

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

codspeed-hq · 2026-06-10T19:25:55Z

Merging this PR will not alter performance

✅ 6 untouched benchmarks

_{Comparing fix/react-use-match-missing-sentinel (e99d31b) with main (41e7a24)¹}

No successful run was found on main (6f1daf5) during the generation of this report, so 41e7a24 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

fix(react-router): avoid throwing in useMatch selector

c6be088

github-actions Bot added the package: react-router label Jun 10, 2026

nx-cloud Bot reviewed Jun 10, 2026

View reviewed changes

lint fix and changeset

e99d31b

Sheraff merged commit 52db703 into main Jun 10, 2026
20 checks passed

Sheraff deleted the fix/react-use-match-missing-sentinel branch June 10, 2026 20:11

This was referenced Jun 10, 2026

ci: Version Packages #7576

Merged

ci: Version Packages brenelz/router#2

Open

ci: Version Packages hgq287/router#2

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(react-router): avoid throwing in useMatch selector#7595

fix(react-router): avoid throwing in useMatch selector#7595
Sheraff merged 2 commits into
mainfrom
fix/react-use-match-missing-sentinel

Sheraff commented Jun 10, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 10, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

nx-cloud Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

nx-cloud Bot left a comment •

edited

Loading

Uh oh!

codspeed-hq Bot commented Jun 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

Sheraff commented Jun 10, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Poem

❌ Failed checks (1 warning)

Uh oh!

nx-cloud Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Changeset Version Preview

🟩 Patch bumps

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Benchmarks

Uh oh!

pkg-pr-new Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nx-cloud Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Nx Cloud is proposing a fix for your failed CI:

Uh oh!

codspeed-hq Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Sheraff commented Jun 10, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 10, 2026 •

edited

Loading

nx-cloud Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

pkg-pr-new Bot commented Jun 10, 2026 •

edited

Loading

nx-cloud Bot left a comment •

edited

Loading

codspeed-hq Bot commented Jun 10, 2026 •

edited

Loading