Optimize route tree sibling sorting

[Sheraff]

What

• record dynamic sibling arrays when they first become sortable
• sort only those arrays after route parsing finishes
• remove the recursive pass over every node in the route tree
• cover reverse-order optional, wildcard, and route-mask siblings

Why

Most nodes do not contain competing dynamic siblings. Tracking the few arrays that need ordering avoids traversing the entire parsed tree a second time while preserving the existing comparator and post-parse ordering.

Bundle impact

Prior isolated prototype measurements from the same main commit used as this PR's base:

• react-router.minimal: -214 B raw, -18 B gzip, -75 B Brotli
• solid-router.minimal: -213 B raw, -31 B gzip, -27 B Brotli

Validation

• router-core focused unit tests (172 passed)
• router-core type tests (TypeScript 5.6–7.0)
• router-core ESLint (0 errors; existing warnings only)
• router-core production build

Summary by CodeRabbit

• Bug Fixes

  • Improved route matching so prefixed and suffixed optional or wildcard routes are prioritized correctly, regardless of declaration order.
  • Improved specificity ordering for dynamic, optional, and wildcard route masks.

• Tests

  • Added coverage for route and route-mask matching priorities.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: fbf880bf-4056-46df-a48b-297b66f4e9e3

📥 Commits

Reviewing files that changed from the base of the PR and between 697ebb6 and f07a855.

📒 Files selected for processing (2)

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

---

📝 Walkthrough

Walkthrough

Route parsing now records sortable dynamic, optional, and wildcard sibling arrays. Route trees and route masks sort those arrays after parsing. Tests cover specificity when routes and masks are declared in least-specific order.

Changes

Route sorting

Layer / File(s)	Summary
Sortable array collection packages/router-core/src/new-process-route-tree.ts	parseSegments propagates a sortable-array accumulator and records dynamic, optional, and wildcard sibling arrays when they reach two elements.
Post-parse route and mask sorting packages/router-core/src/new-process-route-tree.ts	processRouteTree and processRouteMasks sort recorded arrays after parsing. The recursive full-tree sorting pass is removed.
Route priority coverage packages/router-core/tests/new-process-route-tree.test.ts	Tests verify specificity for prefixed and suffixed optional, wildcard, and route-mask patterns.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: optimizing route tree sibling sorting.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/optimize-route-tree-sorting

---

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 f07a855

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

---

☁️ Nx Cloud last updated this comment at 2026-08-05 22:24:23 UTC

[github-actions]

Bundle Size Benchmarks

• Commit: b064b5733bc5
• Measured at: 2026-08-05T22:16:20.995Z
• Baseline source: history:697ebb6ddbd4
• Dashboard: bundle-size history

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

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.09 KiB	-19 B (-0.02%)	86.96 KiB	268.92 KiB	75.96 KiB	████▂▂▂▂▂▁▂▁
react-router.full	90.84 KiB	-54 B (-0.06%)	90.71 KiB	280.87 KiB	79.10 KiB	████▃▃▃▃▃▂▃▁
solid-router.minimal	34.77 KiB	-31 B (-0.09%)	34.64 KiB	99.75 KiB	31.34 KiB	████▂▂▂▂▂▁▁▁
solid-router.full	39.87 KiB	-26 B (-0.06%)	39.75 KiB	114.93 KiB	35.82 KiB	████▂▂▂▂▂▁▁▁
vue-router.minimal	52.07 KiB	-26 B (-0.05%)	51.94 KiB	142.91 KiB	46.91 KiB	████▂▂▂▂▂▁▁▁
vue-router.full	58.01 KiB	-42 B (-0.07%)	57.88 KiB	161.58 KiB	52.14 KiB	████▂▂▂▂▂▁▁▁
react-start.minimal	100.56 KiB	-40 B (-0.04%)	100.42 KiB	312.07 KiB	87.32 KiB	███████▁▁▁▁▁
react-start.deferred-hydration	101.30 KiB	-41 B (-0.04%)	100.44 KiB	313.44 KiB	88.00 KiB	███████▁▁▁▁▁
react-start.full	103.92 KiB	-5 B (-0.00%)	103.78 KiB	322.02 KiB	90.25 KiB	███████▁▁▁▁▁
react-start.rsbuild.minimal	100.21 KiB	-27 B (-0.03%)	100.04 KiB	316.58 KiB	86.33 KiB	▁▁▁▁▂▂▂█████
react-start.rsbuild.minimal-iife	100.61 KiB	-32 B (-0.03%)	100.45 KiB	317.52 KiB	86.67 KiB	▁▁▁▁▂▂▂████▇
react-start.rsbuild.full	103.52 KiB	-52 B (-0.05%)	103.35 KiB	326.67 KiB	89.12 KiB	▁▁▁▁▃▃▃████▇
solid-start.minimal	48.15 KiB	-35 B (-0.07%)	48.02 KiB	141.89 KiB	42.78 KiB	███████▁▁▁▁▁
solid-start.deferred-hydration	51.41 KiB	-31 B (-0.06%)	48.08 KiB	149.93 KiB	45.83 KiB	███████▁▁▁▁▁
solid-start.full	53.41 KiB	-24 B (-0.04%)	53.28 KiB	157.62 KiB	47.47 KiB	████▆▆▆▁▁▁▁▁
vue-start.minimal	68.91 KiB	-60 B (-0.08%)	68.78 KiB	194.90 KiB	61.30 KiB	████▆▆▆▁▁▁▁▁
vue-start.full	72.91 KiB	-18 B (-0.02%)	72.78 KiB	207.41 KiB	64.65 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-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-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@7969

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: f07a855

[github-actions]

🚀 Changeset Version Preview

5 package(s) bumped directly, 18 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-router	1.170.20 → 1.170.21	Changeset
@tanstack/router-core	1.171.17 → 1.171.18	Changeset
@tanstack/solid-router	1.170.20 → 1.170.21	Changeset
@tanstack/start-server-core	1.169.20 → 1.169.21	Changeset
@tanstack/vue-router	1.170.19 → 1.170.20	Changeset
@tanstack/react-start	1.168.37 → 1.168.38	Dependent
@tanstack/react-start-client	1.168.18 → 1.168.19	Dependent
@tanstack/react-start-rsc	0.1.36 → 0.1.37	Dependent
@tanstack/react-start-server	1.167.25 → 1.167.26	Dependent
@tanstack/router-cli	1.167.23 → 1.167.24	Dependent
@tanstack/router-generator	1.167.23 → 1.167.24	Dependent
@tanstack/router-plugin	1.168.25 → 1.168.26	Dependent
@tanstack/router-vite-plugin	1.167.25 → 1.167.26	Dependent
@tanstack/solid-start	1.168.36 → 1.168.37	Dependent
@tanstack/solid-start-client	1.168.18 → 1.168.19	Dependent
@tanstack/solid-start-server	1.167.25 → 1.167.26	Dependent
@tanstack/start-client-core	1.170.16 → 1.170.17	Dependent
@tanstack/start-plugin-core	1.171.28 → 1.171.29	Dependent
@tanstack/start-static-server-functions	1.167.21 → 1.167.22	Dependent
@tanstack/start-storage-context	1.167.19 → 1.167.20	Dependent
@tanstack/vue-start	1.168.35 → 1.168.36	Dependent
@tanstack/vue-start-client	1.167.21 → 1.167.22	Dependent
@tanstack/vue-start-server	1.167.25 → 1.167.26	Dependent

[codspeed-hq]

Merging this PR will regress 5 benchmarks

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

⚡ 4 improved benchmarks
❌ 5 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 error-paths unmatched (react)	317.5 KB	741.7 KB	-57.2%
❌	Memory	mem client unique-location-churn (solid)	341.2 KB	524.8 KB	-34.97%
❌	Memory	mem server peak-large-page (react)	1.7 MB	2.5 MB	-32.15%
❌	Memory	mem server error-paths redirect (vue)	338.6 KB	487.5 KB	-30.53%
❌	Simulation	ssr control-flow route headers (react)	63.8 ms	66.1 ms	-3.48%
⚡	Memory	mem server server-fn-churn (vue)	4,147.3 KB	264.6 KB	×16
⚡	Memory	mem server error-paths unmatched (vue)	2,142.1 KB	484.9 KB	×4.4
⚡	Memory	mem server error-paths redirect (solid)	388 KB	283.8 KB	+36.75%
⚡	Memory	mem client navigation-churn (vue)	1.3 MB	1.2 MB	+4.12%

Tip

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

---

_{Comparing codex/optimize-route-tree-sorting (f07a855) with main (697ebb6)}