feat(router-core): params.priority route option as tie breaker in matching algorithm

[Sheraff]

Summary by CodeRabbit

• New Features

  • Added params.priority to control matching order among routes that use custom param parsing; higher values are tried first (default 0). Acts as a tie-breaker for competing parse-driven routes; static route specificity still takes precedence.

• Documentation

  • Added guide and API docs explaining priority behavior, defaults, examples, and fallthrough when a parse returns false.

• Tests

  • Added tests for priority ordering, parse invocation order, defaults, and fallthrough behavior.

[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: 99e4aff0-1b22-469b-93bf-1c5aec8e591a

📥 Commits

Reviewing files that changed from the base of the PR and between 62649e8 and 654005c.

📒 Files selected for processing (1)

• packages/router-core/tests/new-process-route-tree.test.ts

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

• packages/router-core/tests/new-process-route-tree.test.ts

---

📝 Walkthrough

Walkthrough

This PR introduces a params.priority property to route options that controls matching order when multiple routes use params.parse. Higher-priority routes are attempted first, and if a parse function returns false, matching falls through to the next lower-priority candidate. The feature is defined in public API types, implemented in route tree processing with priority-aware sorting, tested comprehensively, and documented for users.

Changes

Parsed Route Param Priority

Layer / File(s)	Summary
Public API type definition packages/router-core/src/route.ts	The exported ParamsOptions type adds an optional priority?: number field to the params options object, enabling developers to specify priority values for param-based route matching.
Route tree processing and priority-aware matching packages/router-core/src/new-process-route-tree.ts	During route tree processing, route.options.params.priority is captured and stored on segment nodes (defaulting to 0). Static and dynamic node constructors initialize the priority field. The SegmentNode type gains a priority property, and sortDynamic logic now compares priority when both candidates have parse functions, ordering higher-priority routes first. The internal RouteLike type is extended to accept priority.
Test coverage for priority behavior packages/router-core/tests/match-params.test.ts, packages/router-core/tests/new-process-route-tree.test.ts	The TestRoute test helper type is extended to support optional priority. An existing static-route precedence test is updated to set high priority on the parsed route. New test cases verify that priority breaks ties between multiple params.parse routes, that missing priority defaults to 0 (with parse invocation ordering assertions), and that a higher-priority params.parse returning false falls through to the next lower-priority candidate. The processRouteTree snapshot is updated to include priority: 0 on nodes.
User-facing documentation and release notes docs/router/api/router/RouteOptionsType.md, docs/router/guide/path-params.md, .changeset/kind-rivers-joke.md	API reference documents the params.priority property type and default. A new guide section explains priority ordering with an example and fallback scenarios. A changeset entry records the minor release addition referencing the priority tie-breaker behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nudge the routes with tiny paws,
A number nudges hopeful cause.
Higher hops first, then lower try,
If parse says "no", another'll vie.
Tie-breakers hum where pathways cross.

🚥 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: introducing a params.priority route option that serves as a tie breaker in the route matching algorithm, which is the core feature across all modified files.
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 feat-router-core-params-priority-matching

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit f5429c9

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

---

☁️ Nx Cloud last updated this comment at 2026-05-16 09:23:09 UTC

[github-actions]

🚀 Changeset Version Preview

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

🟨 Minor bumps

Package	Version	Reason
@tanstack/router-core	1.170.1 → 1.171.0	Changeset

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-router	1.170.1 → 1.170.2	Dependent
@tanstack/react-start	1.168.2 → 1.168.3	Dependent
@tanstack/react-start-client	1.167.1 → 1.167.2	Dependent
@tanstack/react-start-rsc	0.1.2 → 0.1.3	Dependent
@tanstack/react-start-server	1.167.1 → 1.167.2	Dependent
@tanstack/router-cli	1.167.2 → 1.167.3	Dependent
@tanstack/router-generator	1.167.2 → 1.167.3	Dependent
@tanstack/router-plugin	1.168.2 → 1.168.3	Dependent
@tanstack/router-vite-plugin	1.167.2 → 1.167.3	Dependent
@tanstack/solid-router	1.170.1 → 1.170.2	Dependent
@tanstack/solid-start	1.168.2 → 1.168.3	Dependent
@tanstack/solid-start-client	1.167.1 → 1.167.2	Dependent
@tanstack/solid-start-server	1.167.1 → 1.167.2	Dependent
@tanstack/start-client-core	1.169.1 → 1.169.2	Dependent
@tanstack/start-plugin-core	1.170.2 → 1.170.3	Dependent
@tanstack/start-server-core	1.168.1 → 1.168.2	Dependent
@tanstack/start-static-server-functions	1.167.1 → 1.167.2	Dependent
@tanstack/start-storage-context	1.167.1 → 1.167.2	Dependent
@tanstack/vue-router	1.170.1 → 1.170.2	Dependent
@tanstack/vue-start	1.168.2 → 1.168.3	Dependent
@tanstack/vue-start-client	1.167.1 → 1.167.2	Dependent
@tanstack/vue-start-server	1.167.1 → 1.167.2	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-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-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 654005c

[github-actions]

Bundle Size Benchmarks

• Commit: 706c63fe32a8
• Measured at: 2026-05-16T09:22:46.081Z
• Baseline source: history:b3f2ab809e0f
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.33 KiB	+35 B (+0.04%)	87.19 KiB	274.21 KiB	75.94 KiB	▁▁▇▇▇▇▇▇▇▇▇█
react-router.full	90.85 KiB	+36 B (+0.04%)	90.72 KiB	285.71 KiB	78.92 KiB	▁▁▇▇▇▇▇▇▇▇▇█
solid-router.minimal	35.55 KiB	+41 B (+0.11%)	35.43 KiB	106.50 KiB	32.01 KiB	▁▁▆▆▆▆▆▆▆▆▆█
solid-router.full	40.27 KiB	+38 B (+0.09%)	40.14 KiB	120.71 KiB	36.18 KiB	▁▁▆▆▆▆▆▆▆▆▆█
vue-router.minimal	53.33 KiB	+41 B (+0.08%)	53.19 KiB	151.65 KiB	47.89 KiB	▁▁▆▆▆▆▆▆▆▆▆█
vue-router.full	58.45 KiB	+37 B (+0.06%)	58.32 KiB	167.82 KiB	52.41 KiB	▁▁▆▆▆▆▆▆▆▆▆█
react-start.minimal	102.01 KiB	+38 B (+0.04%)	101.87 KiB	322.65 KiB	88.30 KiB	▁▃▇▇▇▇▇▇▇▇▇█
react-start.full	105.44 KiB	+35 B (+0.03%)	105.30 KiB	332.98 KiB	91.12 KiB	▁▃▇▇▇▇▇▇▇▇▇█
react-start.rsbuild.minimal	99.63 KiB	+40 B (+0.04%)	99.46 KiB	317.11 KiB	85.63 KiB	▁▃▇▇▇▇▇▇▇▇▇█
react-start.rsbuild.full	102.93 KiB	+43 B (+0.04%)	102.76 KiB	327.55 KiB	88.49 KiB	▁▃▇▇▇▇▇▇▇▇▇█
solid-start.minimal	49.66 KiB	+46 B (+0.09%)	49.53 KiB	152.62 KiB	43.81 KiB	▁▃▇▇▇▇▇▇▇▇▇█
solid-start.full	55.44 KiB	+38 B (+0.07%)	55.31 KiB	169.52 KiB	48.77 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.

[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 updated the inline snapshot in new-process-route-tree.test.ts to include the new priority: 0 field that the PR added to every SegmentNode. Without this update, the builds segment tree correctly test fails because the serialized tree no longer matches the stored snapshot. Adding "priority": 0 to all seven nodes in the snapshot restores the match and confirms the field is correctly initialized on every node type.

Tip

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

Warning

The suggested diff is too large to display here, but you can view it on Nx Cloud ↗

  

Or Apply changes locally with:

npx nx-cloud apply-locally XNJf-hqVM

Apply fix locally with your editor ↗   View interactive diff ↗

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