fix(router-generator): respect explicit virtual route siblings

Preserve virtual-config parentage during flattening and prefer it during parent resolution so sibling routes like /posts and /posts/$id stay siblings

fixes #5822

Author: schiller-manuel

packages/router-generator/src/filesystem/virtual/getRouteNodes.ts

@@ -26,12 +26,27 @@ function ensureLeadingUnderScore(id: string) {
   return `_${id}`
 }
 
-function flattenTree(node: RouteNode): Array<RouteNode> {
+function flattenTree(
+  node: RouteNode,
+  parentRoutePath?: string,
+): Array<RouteNode> {
+  // Store the explicit parent's routePath for virtual routes.
+  // This prevents the generator from auto-nesting based on path matching.
+  //
+  // Skip setting an explicit virtual parent when the parent is the synthetic
+  // virtual root (`/${rootPathId}`). This keeps top-level virtual routes using
+  // the generator's normal parent inference (instead of forcing them to attach
+  // directly to the root route node).
+  const isRootParent = parentRoutePath === `/${rootPathId}`
+  if (parentRoutePath !== undefined && !isRootParent) {
+    node._virtualParentRoutePath = parentRoutePath
+  }
+
   const result = [node]
 
   if (node.children) {
     for (const child of node.children) {
-      result.push(...flattenTree(child))
+      result.push(...flattenTree(child, node.routePath))
     }
   }
   delete node.children

packages/router-generator/src/generator.ts

@@ -1420,35 +1420,54 @@ ${acc.routeTree.map((child) => `${child.variableName}Route: typeof ${getResolved
     prefixMap: RoutePrefixMap,
     config?: Config,
   ) {
-    let parentRoute = hasParentRoute(prefixMap, node, node.routePath)
-
-    // Check routeNodesByPath for a closer parent that may not be in prefixMap.
-    //
-    // Why: The prefixMap excludes lazy routes by design. When lazy-only routes are
-    // nested inside a pathless layout, the virtual route created from the lazy file
-    // won't be in the prefixMap, but it will be in routeNodesByPath.
-    //
-    // Example: Given files _layout/path.lazy.tsx and _layout/path.index.lazy.tsx:
-    //   - prefixMap contains: /_layout (from route.tsx)
-    //   - routeNodesByPath contains: /_layout AND /_layout/path (virtual from lazy)
-    //   - For /_layout/path/, hasParentRoute returns /_layout (wrong)
-    //   - But the correct parent is /_layout/path (the virtual route from path.lazy.tsx)
-    //
-    // Optimization: Only search if we might find a closer parent. The search walks
-    // up from the immediate parent path, so if the first candidate matches what
-    // prefixMap found, there's no closer parent to find.
-    if (node.routePath) {
-      const lastSlash = node.routePath.lastIndexOf('/')
-      if (lastSlash > 0) {
-        const immediateParentPath = node.routePath.substring(0, lastSlash)
-        const candidate = acc.routeNodesByPath.get(immediateParentPath)
-        if (
-          candidate &&
-          candidate.routePath !== node.routePath &&
-          candidate !== parentRoute
-        ) {
-          // Found a closer parent in routeNodesByPath that differs from prefixMap result
-          parentRoute = candidate
+    let parentRoute: RouteNode | null = null
+
+    // Virtual routes with explicit parent-child relationships should respect
+    // the explicit parent instead of auto-nesting based on path matching.
+    // Check if this node has an explicit parent from virtual config.
+    if (node._virtualParentRoutePath !== undefined) {
+      // Look up the explicit parent in routeNodesByPath
+      const explicitParent = acc.routeNodesByPath.get(
+        node._virtualParentRoutePath,
+      )
+      if (explicitParent) {
+        parentRoute = explicitParent
+      } else {
+        // If the explicit parent hasn't been processed yet, try prefixMap
+        parentRoute = prefixMap.get(node._virtualParentRoutePath) ?? null
+      }
+    } else {
+      // Standard path-based parent inference
+      parentRoute = hasParentRoute(prefixMap, node, node.routePath)
+
+      // Check routeNodesByPath for a closer parent that may not be in prefixMap.
+      //
+      // Why: The prefixMap excludes lazy routes by design. When lazy-only routes are
+      // nested inside a pathless layout, the virtual route created from the lazy file
+      // won't be in the prefixMap, but it will be in routeNodesByPath.
+      //
+      // Example: Given files _layout/path.lazy.tsx and _layout/path.index.lazy.tsx:
+      //   - prefixMap contains: /_layout (from route.tsx)
+      //   - routeNodesByPath contains: /_layout AND /_layout/path (virtual from lazy)
+      //   - For /_layout/path/, hasParentRoute returns /_layout (wrong)
+      //   - But the correct parent is /_layout/path (the virtual route from path.lazy.tsx)
+      //
+      // Optimization: Only search if we might find a closer parent. The search walks
+      // up from the immediate parent path, so if the first candidate matches what
+      // prefixMap found, there's no closer parent to find.
+      if (node.routePath) {
+        const lastSlash = node.routePath.lastIndexOf('/')
+        if (lastSlash > 0) {
+          const immediateParentPath = node.routePath.substring(0, lastSlash)
+          const candidate = acc.routeNodesByPath.get(immediateParentPath)
+          if (
+            candidate &&
+            candidate.routePath !== node.routePath &&
+            candidate !== parentRoute
+          ) {
+            // Found a closer parent in routeNodesByPath that differs from prefixMap result
+            parentRoute = candidate
+          }
         }
       }
     }

packages/router-generator/src/types.ts

@@ -13,6 +13,13 @@ export type RouteNode = {
   children?: Array<RouteNode>
   parent?: RouteNode
   createFileRouteProps?: Set<string>
+  /**
+   * When a route is defined in virtual config with explicit parent-child relationships,
+   * this property stores the parent's routePath. This prevents the generator from
+   * auto-nesting routes based on path prefix matching.
+   * See issue #5822 for context.
+   */
+  _virtualParentRoutePath?: string
 }
 
 export interface GetRouteNodesResult {

packages/router-generator/tests/generator.test.ts

@@ -165,6 +165,20 @@ function rewriteConfigByFolderName(folderName: string, config: Config) {
       config.indexToken = /[a-z]+-page/
       config.routeToken = /[a-z]+-layout/
       break
+    case 'virtual-sibling-routes':
+      {
+        // Test case for issue #5822: Virtual routes should respect explicit sibling relationships
+        // Routes /posts and /posts/$id should remain siblings under the layout,
+        // NOT auto-nested based on path matching
+        const virtualRouteConfig = rootRoute('__root.tsx', [
+          layout('_main', 'layout.tsx', [
+            route('/posts', 'posts.tsx'),
+            route('/posts/$id', 'post-detail.tsx'),
+          ]),
+        ])
+        config.virtualRouteConfig = virtualRouteConfig
+      }
+      break
     default:
       break
   }

packages/router-generator/tests/generator/virtual-sibling-routes/routeTree.snapshot.ts

@@ -0,0 +1,103 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as layoutRouteImport } from './routes/layout'
+import { Route as postsRouteImport } from './routes/posts'
+import { Route as postDetailRouteImport } from './routes/post-detail'
+
+const layoutRoute = layoutRouteImport.update({
+  id: '/_main',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const postsRoute = postsRouteImport.update({
+  id: '/posts',
+  path: '/posts',
+  getParentRoute: () => layoutRoute,
+} as any)
+const postDetailRoute = postDetailRouteImport.update({
+  id: '/posts/$id',
+  path: '/posts/$id',
+  getParentRoute: () => layoutRoute,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof layoutRouteWithChildren
+  '/posts': typeof postsRoute
+  '/posts/$id': typeof postDetailRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof layoutRouteWithChildren
+  '/posts': typeof postsRoute
+  '/posts/$id': typeof postDetailRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/_main': typeof layoutRouteWithChildren
+  '/_main/posts': typeof postsRoute
+  '/_main/posts/$id': typeof postDetailRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/posts' | '/posts/$id'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/posts' | '/posts/$id'
+  id: '__root__' | '/_main' | '/_main/posts' | '/_main/posts/$id'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  layoutRoute: typeof layoutRouteWithChildren
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/_main': {
+      id: '/_main'
+      path: ''
+      fullPath: '/'
+      preLoaderRoute: typeof layoutRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/_main/posts': {
+      id: '/_main/posts'
+      path: '/posts'
+      fullPath: '/posts'
+      preLoaderRoute: typeof postsRouteImport
+      parentRoute: typeof layoutRoute
+    }
+    '/_main/posts/$id': {
+      id: '/_main/posts/$id'
+      path: '/posts/$id'
+      fullPath: '/posts/$id'
+      preLoaderRoute: typeof postDetailRouteImport
+      parentRoute: typeof layoutRoute
+    }
+  }
+}
+
+interface layoutRouteChildren {
+  postsRoute: typeof postsRoute
+  postDetailRoute: typeof postDetailRoute
+}
+
+const layoutRouteChildren: layoutRouteChildren = {
+  postsRoute: postsRoute,
+  postDetailRoute: postDetailRoute,
+}
+
+const layoutRouteWithChildren =
+  layoutRoute._addFileChildren(layoutRouteChildren)
+
+const rootRouteChildren: RootRouteChildren = {
+  layoutRoute: layoutRouteWithChildren,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()

packages/router-generator/tests/generator/virtual-sibling-routes/routes/__root.tsx

@@ -0,0 +1,3 @@
+import { createRootRoute } from '@tanstack/react-router'
+
+export const Route = createRootRoute()

packages/router-generator/tests/generator/virtual-sibling-routes/routes/layout.tsx

@@ -0,0 +1,5 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_main')({
+  component: () => 'Layout',
+})

packages/router-generator/tests/generator/virtual-sibling-routes/routes/post-detail.tsx

@@ -0,0 +1,5 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_main/posts/$id')({
+  component: () => 'Post Detail',
+})

packages/router-generator/tests/generator/virtual-sibling-routes/routes/posts.tsx

@@ -0,0 +1,5 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/_main/posts')({
+  component: () => 'Posts List',
+})