fix: prevent virtual sibling routes from being incorrectly nested by path prefix

[schiller-manuel]

fixes #5431

Summary by CodeRabbit

• Bug Fixes

  • Refined how virtual route parent paths are resolved, ensuring explicit parent information is properly utilized
  • Improved root-level virtual route handling to correctly maintain sibling relationships without auto-nesting based on shared prefixes

• Tests

  • Added comprehensive test coverage for root-level virtual routes with overlapping path prefixes to verify correct sibling relationship handling

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 146c1e6 and b1f7779.

📒 Files selected for processing (9)

• packages/router-generator/src/filesystem/physical/getRouteNodes.ts
• packages/router-generator/src/filesystem/virtual/getRouteNodes.ts
• packages/router-generator/src/generator.ts
• packages/router-generator/src/types.ts
• packages/router-generator/tests/generator.test.ts
• packages/router-generator/tests/generator/virtual-root-sibling-routes/routeTree.snapshot.ts
• packages/router-generator/tests/generator/virtual-root-sibling-routes/routes/__root.tsx
• packages/router-generator/tests/generator/virtual-root-sibling-routes/routes/device/route.tsx
• packages/router-generator/tests/generator/virtual-root-sibling-routes/routes/history/route.tsx

---

📝 Walkthrough

Walkthrough

The PR refactors virtual parent path tracking in the router-generator. It removes explicit parent tracking from physical virtual subtrees, centralizes virtual parent path computation in the virtual filesystem handler via a new _virtualParentRoutePath property, and refines explicit parent resolution logic in the generator to handle root-level virtual routes correctly.

Changes

Cohort / File(s)	Summary
Virtual Parent Path Propagation packages/router-generator/src/filesystem/virtual/getRouteNodes.ts	Refactored flattenTree to remove explicit parentRoutePath parameter. Now computes and assigns _virtualParentRoutePath property on all created route nodes, centralizing virtual parent path tracking across index, file, virtual, and layout cases.
Physical Route Node Handling packages/router-generator/src/filesystem/physical/getRouteNodes.ts	Deletes _virtualParentRoutePath property from virtual subtree nodes after path normalization, removing explicit parent tracking in physical directory tree processing.
Explicit Parent Resolution packages/router-generator/src/generator.ts	Refines explicit virtual parent resolution to only use explicit parent when it exists (no path-based fallback). Adds special-case handling to keep nodes at root level if explicit parent equals root path. Updated comments reference issues #5822 and #5431.
Documentation packages/router-generator/src/types.ts	Updated RouteNode comment to reference issues #5822 and #5431 instead of #5822 alone.
Test Configuration packages/router-generator/tests/generator.test.ts	Added new "virtual-root-sibling-routes" test case with two sibling routes at root level (/device/$id and /device/$id/history/$filename) sharing a path prefix without parent-child relationship.
Test Route Fixtures packages/router-generator/tests/generator/virtual-root-sibling-routes/routeTree.snapshot.ts, routes/__root.tsx, routes/device/route.tsx, routes/history/route.tsx	Generated route tree definitions and route files for the virtual-root-sibling-routes test case, including type-safe interface mappings and module augmentation for TanStack Router with two dynamic routes under a virtual root.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fix(router-generator): respect explicit virtual route siblings #6458: Modifies how explicit virtual parent paths (_virtualParentRoutePath) are propagated and respected throughout the generator and filesystem route-node handling.
• fix: correctly search for parent route in generator #6581: Adjusts parent route resolution logic in the router-generator, specifically how path-based parent lookup and virtual-parent propagation interact.
• fix: Fix conflicting paths error when lazy loading layout and index r… #6251: Changes virtual/explicit parent resolution and routePath-based parent lookup mechanisms affecting parent linkage in generated routes.

Suggested labels

package: router-generator, package: virtual-file-routes

Suggested reviewers

• nlynzaad
• Sheraff

Poem

🐰 In virtual woods where paths entwine,
We mark the parents, line by line.
Root siblings dance, no nesting required,
With explicit paths, the logic's wired. ✨

🚥 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 'fix: prevent virtual sibling routes from being incorrectly nested by path prefix' clearly and specifically describes the main change—fixing incorrect nesting of virtual sibling routes that share path prefixes.
Linked Issues check	✅ Passed	The PR changes directly address issue #5431 by refining virtual parent resolution logic, handling root-level virtual routes, and adding test coverage for sibling routes sharing path prefixes without establishing parent-child relationships.
Out of Scope Changes check	✅ Passed	All changes are directly related to fixing virtual route nesting issues: modifications to route node processing, virtual parent path tracking, parent resolution logic, and comprehensive test coverage for the specific scenario described in issue #5431.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-5431

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit b1f7779

Command	Status	Duration	Result
nx run tanstack-router-e2e-bundle-size:build --...	✅ Succeeded	1m 28s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-03-01 01:25:16 UTC

[github-actions]

Bundle Size Benchmarks

• Commit: 146c1e609e84
• Measured at: 2026-03-01T01:15:03.844Z
• Baseline source: history:b2a71ee211ed
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Raw	Brotli	Trend
react-router.minimal	86.58 KiB	0 B (0.00%)	272.45 KiB	75.22 KiB	▁▁▁▂▂▂▂▇▇██
react-router.full	89.61 KiB	0 B (0.00%)	282.78 KiB	77.90 KiB	▁▁▁▂▂▂▂▇▇██
solid-router.minimal	35.88 KiB	0 B (0.00%)	107.56 KiB	32.26 KiB	▁▁▁▅▅▅▅▇▇██
solid-router.full	40.21 KiB	0 B (0.00%)	120.61 KiB	36.13 KiB	▁▁▁▅▅▅▅▇▇██
vue-router.minimal	51.75 KiB	0 B (0.00%)	147.54 KiB	46.50 KiB	▁▁▁▅▅▅▅▇▇██
vue-router.full	56.55 KiB	0 B (0.00%)	163.12 KiB	50.86 KiB	▁▁▁▄▄▄▄▆▆██
react-start.minimal	99.11 KiB	0 B (0.00%)	311.58 KiB	85.68 KiB	▁▁▁▂▂▂▂▅▅██
react-start.full	102.49 KiB	0 B (0.00%)	321.36 KiB	88.62 KiB	▁▁▁▁▁▁▁▆▆██
solid-start.minimal	48.19 KiB	0 B (0.00%)	145.13 KiB	42.67 KiB	▁▁▁▅▅▅▅▇▇██
solid-start.full	53.67 KiB	0 B (0.00%)	161.05 KiB	47.33 KiB	▁▁▁▄▄▄▄▇▇██

Trend sparkline is historical gzip bytes 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-rsc
• 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-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@6789

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 6560ae4