fix(router-core): favor index matches, or deepest non-index

[Sheraff]

Fix #5912

All things being equal, a shorter route should only be favored over a longer one w/ skipped optional segments if that shorter route is an index route. Otherwise, favor deeper routes, even if that means we have to skip many optional segments.

This changes the expectations for 2 of our existing unit tests, but we didn't have a strong opinion on either of those tests:

• '/{-$other}/posts/new', '/posts/new' matching path /posts/new
  => used to match /posts/new, with this PR will match /{-$other}/posts/new
• '/foo/{-$p}.tsx', '/foo/{-$p}/{-$x}.tsx' matching path /foo
  => used to match /foo/{-$p}.tsx, with this PR will match /foo/{-$p}/{-$x}.tsx

Summary by CodeRabbit

• Bug Fixes

  • Refined route matching so deeper optional segments are preferred in tie situations and index routes correctly win when applicable, improving specificity decisions in complex hierarchies.

• Tests

  • Updated and added tests to verify new resolution behavior for optional/deeper route chains and index-vs-optional edge cases.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This PR fixes route matching when optional parameters coexist with layout routes. The changes modify the early-termination condition in getNodeMatch to require index route status and enhance the tie-breaker logic in isFrameMoreSpecific to consider node depth and index flags, improving specificity comparison for optional parameter chains.

Changes

Cohort / File(s)	Summary
Core route matching logic packages/router-core/src/new-process-route-tree.ts	Modified early-return condition for perfect matches to require node.isIndex alongside statics === partsLength. Expanded isFrameMoreSpecific tie-breaker logic to compare optionals, depth, and index-flag status when dynamics are equal.
Route matching test suite packages/router-core/tests/new-process-route-tree.test.ts	Updated test expectations to reflect new matching behavior: deeper optional chains now preferred over shallower routes; added test for optional child vs. shorter route preference; expanded edge-case coverage for optional/deeper chain scenarios and index-route precedence.

Sequence Diagram

sequenceDiagram
    participant Router as Route Matcher
    participant Old as Old Logic
    participant New as New Logic
    
    Note over Router,New: Matching "/posts" with optional {-$category}
    
    rect rgb(200, 220, 240)
    Note over Old,New: Perfect match detection
    Old->>Old: Check statics === partsLength?
    Old->>Old: ❌ Early return (missing index check)
    New->>New: Check statics === partsLength && node.isIndex?
    New->>New: ✓ Properly gate early termination
    end
    
    rect rgb(220, 240, 200)
    Note over Old,New: Tie-breaker when dynamics equal
    Old->>Old: Limited comparison
    New->>New: Compare optionals → depth → index flag
    New->>New: ✓ More precise specificity ranking
    end
    
    Note over Router: Result: Layout routes + optional params now match correctly

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Logic density: Route matching tie-breaker logic is intricate; the addition of index-flag and depth comparisons requires careful verification of ordering and edge cases.
• Behavioral shift: Test expectations changed significantly, indicating non-trivial matching behavior changes that need validation against the reported issue.
• Scope: Changes are localized to one implementation file, but affect critical routing behavior.

Areas requiring extra attention:

• Verify that the new node.isIndex requirement in getNodeMatch doesn't inadvertently break other route patterns
• Confirm the ordering of tie-breaker comparisons (optionals → depth → index) produces correct specificity rankings
• Validate test scenario coverage matches real-world layout + optional parameter combinations

Possibly related PRs

• refactor(router-core): Process routeTree into segment tree instead of flatRoutes #5722: Introduced the segment-tree rewrite and the matching/tie-breaker logic that these changes refine and extend.
• refactor(router-core): processRouteTree in its own file #5128: Related route-tree processing refactoring; touched ranking and sorting logic in the same subsystem.

Suggested labels

package: router-core

Suggested reviewers

• schiller-manuel
• nlynzaad

Poem

🐰 A layout route once blocked the way,
Optional chains would lose their say,
Now depth and index flags align,
And matching logic runs just fine—
No more ghosts in empty slots today! ✨

Pre-merge checks and finishing touches

❌ 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%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: fixing route matching to favor index routes or deepest non-index routes, which directly addresses the linked issue about optional parameter matching.
Linked Issues check	✅ Passed	The code changes implement logic to prioritize index route matches and deeper optional chains, directly fixing the issue where optional param routes failed to match base URLs when layout routes existed.
Out of Scope Changes check	✅ Passed	All changes are scoped to the route matching logic in new-process-route-tree.ts and its tests, directly addressing the optional parameter matching issue without introducing unrelated modifications.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-router-core-favor-index-or-deepest-route-matches

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 6300434

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

---

☁️ Nx Cloud last updated this comment at 2025-11-21 17:35:28 UTC

[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-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-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
• 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-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/router/@tanstack/arktype-adapter@5933

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5933

@tanstack/eslint-plugin-router

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

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5933

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5933

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5933

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5933

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5933

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5933

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5933

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5933

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5933

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5933

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5933

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5933

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5933

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5933

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5933

commit: 6300434