fix(router-core): support parsed params in matchRoute

[LadyBluenotes]

matchRoute now resolves matches through the processed route tree.

• Applies route params.parse results before comparing or returning params.
• Preserves parsed parent params for child parsers and handles repeated param names.
• Uses route precedence and parser rejection during matching, so lower-priority or rejected routes no longer match through raw path templates.
• Replaces findSingleMatch and its cache with findRouteMatch.
• Normalizes exact trailing-slash matching while leaving fuzzy matching unchanged.
• Keeps caseSensitive, basepath, search, pending, optional-param, and wildcard behavior covered.

matchRoute now returns false for destination templates that are not registered in the route tree.

Includes the reproducer from #2460.

Closes #2450.

Summary by CodeRabbit

• Bug Fixes
  • Fixed route matching to correctly apply custom typed params.parse/params.stringify.
  • Match results now return parsed parameters (not raw strings) and fail when typed parsing is rejected or throws.
  • Search and basepath matching now align with parsed params for consistent results across nested routes.
• Tests
  • Added/expanded matchRoute and useMatchRoute coverage for React, Solid, and Vue, including numeric conversion, non-canonical slugs, and search mismatch cases.
• Chores
  • Added a patch changeset for the route-matching fix.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: af4b87d9-0cd5-46e6-9821-c5369b926b71

📥 Commits

Reviewing files that changed from the base of the PR and between 24a76d9 and 06a3de5.

📒 Files selected for processing (7)

• packages/router-core/src/new-process-route-tree.ts
• packages/router-core/src/router.ts
• packages/router-core/tests/match-by-path.test.ts
• packages/router-core/tests/match-route.test.ts
• packages/router-core/tests/optional-path-params-clean.test.ts
• packages/router-core/tests/optional-path-params.test.ts
• packages/router-core/tests/path.test.ts

 ______________________________
< Bugs bunny, at your service. >
 ------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

📝 Walkthrough

Walkthrough

matchRoute now parses route parameters before matching and returns typed values. Core tests cover parser behavior and existing matching modes, while React, Solid, and Vue tests verify typed results from useMatchRoute.

Changes

Typed route matching

Layer / File(s)	Summary
Parse parameters during route matching packages/router-core/src/router.ts, .changeset/plenty-jokes-listen.md	matchRoute parses parameters across the destination route branch, rejects invalid parser results, compares parsed values, returns typed parameters, and records a patch release.
Validate core matchRoute behavior packages/router-core/tests/match-route.test.ts	Tests cover typed values, parser failures, slug parsing, parent-child parsing, generic and fuzzy matching, search parameters, and base paths.
Verify typed useMatchRoute results packages/react-router/tests/Matches.test.tsx, packages/solid-router/tests/Matches.test.tsx, packages/vue-router/tests/Matches.test.tsx	Adapter tests verify that useMatchRoute returns numeric parameters produced by custom route parsers.

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

Sequence Diagram(s)

sequenceDiagram
  participant useMatchRoute
  participant RouterCoreMatchRoute
  participant RouteParamParser
  useMatchRoute->>RouterCoreMatchRoute: Match route with typed params
  RouterCoreMatchRoute->>RouteParamParser: Parse raw URL parameters
  RouteParamParser-->>RouterCoreMatchRoute: Return parsed params or rejection
  RouterCoreMatchRoute-->>useMatchRoute: Return typed match or false

Loading

Suggested reviewers: Sheraff, nlynzaad

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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 clearly summarizes the main fix: parsed params support in matchRoute.
Linked Issues check	✅ Passed	The changes address #2450 by applying route param parsing during matchRoute and adding regression tests for numeric typed params.
Out of Scope Changes check	✅ Passed	The added tests and changeset entry are directly tied to the parsed-params matchRoute fix and do not introduce unrelated scope.

✨ 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 match-route-parsed-params

---

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.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 06a3de5

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	⛔ Cancelled	17s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-07-11 20:09:17 UTC

[github-actions]

🚀 Changeset Version Preview

1 package(s) bumped directly, 22 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/router-core	1.171.14 → 1.171.15	Changeset
@tanstack/react-router	1.170.17 → 1.170.18	Dependent
@tanstack/react-start	1.168.27 → 1.168.28	Dependent
@tanstack/react-start-client	1.168.15 → 1.168.16	Dependent
@tanstack/react-start-rsc	0.1.26 → 0.1.27	Dependent
@tanstack/react-start-server	1.167.21 → 1.167.22	Dependent
@tanstack/router-cli	1.167.18 → 1.167.19	Dependent
@tanstack/router-generator	1.167.18 → 1.167.19	Dependent
@tanstack/router-plugin	1.168.19 → 1.168.20	Dependent
@tanstack/router-vite-plugin	1.167.19 → 1.167.20	Dependent
@tanstack/solid-router	1.170.17 → 1.170.18	Dependent
@tanstack/solid-start	1.168.27 → 1.168.28	Dependent
@tanstack/solid-start-client	1.168.15 → 1.168.16	Dependent
@tanstack/solid-start-server	1.167.21 → 1.167.22	Dependent
@tanstack/start-client-core	1.170.13 → 1.170.14	Dependent
@tanstack/start-plugin-core	1.171.19 → 1.171.20	Dependent
@tanstack/start-server-core	1.169.16 → 1.169.17	Dependent
@tanstack/start-static-server-functions	1.167.18 → 1.167.19	Dependent
@tanstack/start-storage-context	1.167.16 → 1.167.17	Dependent
@tanstack/vue-router	1.170.16 → 1.170.17	Dependent
@tanstack/vue-start	1.168.26 → 1.168.27	Dependent
@tanstack/vue-start-client	1.167.18 → 1.167.19	Dependent
@tanstack/vue-start-server	1.167.21 → 1.167.22	Dependent

[pkg-pr-new]

More templates

• 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-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• 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@7776

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 24a76d9

[github-actions]

Bundle Size Benchmarks

• Commit: 677686c5b32b
• Measured at: 2026-07-11T15:51:12.213Z
• Baseline source: history:a3e24c35a58d
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.43 KiB	+56 B (+0.06%)	87.29 KiB	274.14 KiB	76.08 KiB	▁▃▃▃▃▅▅▅▅▅▅█
react-router.full	91.18 KiB	+81 B (+0.09%)	91.04 KiB	286.03 KiB	79.20 KiB	▁▃▃▃▃▅▅▅▅▅▅█
solid-router.minimal	35.62 KiB	+59 B (+0.16%)	35.50 KiB	106.33 KiB	32.12 KiB	▁▃▃▃▃▅▅▅▅▅▅█
solid-router.full	40.69 KiB	+76 B (+0.18%)	40.56 KiB	121.55 KiB	36.54 KiB	▁▃▃▃▃▅▅▅▅▅▅█
vue-router.minimal	53.13 KiB	+66 B (+0.12%)	53.00 KiB	150.37 KiB	47.80 KiB	▁▃▃▃▃▅▅▅▅▅▅█
vue-router.full	59.10 KiB	+64 B (+0.11%)	58.97 KiB	169.13 KiB	52.95 KiB	▁▃▃▃▃▅▅▅▅▅▅█
react-start.minimal	102.11 KiB	+84 B (+0.08%)	101.97 KiB	322.56 KiB	88.30 KiB	▁▂▂▂▄▅▅▅▅▅▅█
react-start.deferred-hydration	102.85 KiB	+89 B (+0.08%)	101.99 KiB	323.94 KiB	89.06 KiB	▁▂▂▂▄▅▅▅▅▅▅█
react-start.full	105.53 KiB	+87 B (+0.08%)	105.40 KiB	332.49 KiB	91.36 KiB	▁▂▂▂▄▅▅▅▅▅▅█
react-start.rsbuild.minimal	99.82 KiB	+80 B (+0.08%)	99.65 KiB	316.99 KiB	85.93 KiB	▁▂▂▂▃▅▅▅▅▅▅█
react-start.rsbuild.minimal-iife	100.22 KiB	+78 B (+0.08%)	100.06 KiB	317.92 KiB	86.29 KiB	▁▂▂▂▃▅▅▅▅▅▅█
react-start.rsbuild.full	103.03 KiB	+72 B (+0.07%)	102.86 KiB	327.04 KiB	88.74 KiB	▁▂▂▂▃▅▅▅▅▅▅█
solid-start.minimal	49.77 KiB	+63 B (+0.12%)	49.64 KiB	152.51 KiB	43.95 KiB	▁▃▃▃▄▆▆▆▆▆▆█
solid-start.deferred-hydration	53.03 KiB	+61 B (+0.11%)	49.70 KiB	160.55 KiB	46.92 KiB	▁▃▃▃▄▆▆▆▆▆▆█
solid-start.full	55.59 KiB	+78 B (+0.14%)	55.46 KiB	169.56 KiB	48.98 KiB	▁▃▃▃▄▅▅▅▅▅▅█
vue-start.minimal	71.18 KiB	+49 B (+0.07%)	71.05 KiB	207.63 KiB	63.06 KiB	▁▃▃▃▅▆▆▆▆▆▆█
vue-start.full	75.20 KiB	+66 B (+0.09%)	75.07 KiB	220.26 KiB	66.62 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.

[codspeed-hq]

Merging this PR will degrade performance by 9.66%

⚠️ 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

⚡ 3 improved benchmarks
❌ 6 regressed benchmarks
✅ 171 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	mem server peak-large-page (react)	948.6 KB	2,110 KB	-55.04%
❌	Memory	mem server error-paths redirect (vue)	304.6 KB	404 KB	-24.59%
❌	Memory	mem server peak-large-page (solid)	769.6 KB	802.8 KB	-4.14%
❌	Simulation	client-route-tree-scale navigation loop (react)	74.1 ms	77.2 ms	-3.98%
❌	Memory	mem server error-paths not-found (react)	262 KB	271.9 KB	-3.65%
❌	Simulation	ssr streaming deferred (react)	70.6 ms	72.9 ms	-3.13%
⚡	Memory	mem server streaming-peak chunked (vue)	13.9 MB	11.1 MB	+25.41%
⚡	Simulation	client-loaders navigation loop (react)	55.5 ms	52.8 ms	+5.2%
⚡	Memory	mem server server-fn-churn (react)	283 KB	271.4 KB	+4.26%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing match-route-parsed-params (24a76d9) with main (a3e24c3)}

[Sheraff]

I think it makes sense to fix this. But also router.matchRoute is broken more generally because it does not take the route tree into account. It could return true for the specific route you're asking for, but when actually compared against the entire tree, another route would match because it had higher matching priority.

[LadyBluenotes]

I think it makes sense to fix this. But also router.matchRoute is broken more generally because it does not take the route tree into account. It could return true for the specific route you're asking for, but when actually compared against the entire tree, another route would match because it had higher matching priority.

Added a regression for osts/edit versus posts/$postId. So when full-tree matching identifies /posts/edit as the winner, matchRoute({ to: '/posts/$postId' }) now returns false. The existing fallback remains for route branches that cannot be resolved through parser-aware tree matching :))

[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 has identified a possible root cause for your failed CI:

We determined that this failure is unrelated to the PR's changes, which are scoped entirely to router-core param parsing logic. The tanstack-start-example-rscs:build task fails due to a nitro/nitro-nightly package version incompatibility (ERR_PACKAGE_PATH_NOT_EXPORTED) in the environment. No fix is required on this PR.

No code changes were suggested for this issue.

Trigger a rerun:

View detailed reasoning on Nx Cloud ↗

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

[LadyBluenotes]

@Sheraff made the changes we talked about in discord