feat(router-generator): allow virtual file routes without file names (#2500)

Author: schiller-manuel

docs/framework/react/guide/virtual-file-routes.md

@@ -99,6 +99,19 @@ const virtualRouteConfig = rootRoute('root.tsx', [
 ])
 ```
 
+You can also define a virtual route without a file name. This allows to set a common path prefix for its children:
+
+```tsx
+import { route } from '@tanstack/virtual-file-routes'
+
+const virtualRouteConfig = rootRoute('root.tsx', [
+  route('/hello', [
+    route('/world', 'world.tsx'), // full path will be "/hello/world"
+    route('/universe', 'universe.tsx'), // full path will be "/hello/universe"
+  ]),
+])
+```
+
 ## Virtual Index Route
 
 The `index` function is used to create a virtual index route. It takes a file name. Here's an example of a virtual index route:

examples/react/basic-virtual-file-based/routes.ts

@@ -13,9 +13,11 @@ export const routes = rootRoute('root.tsx', [
     route('$postId', 'posts/posts-detail.tsx'),
   ]),
   layout('first', 'layout/first-layout.tsx', [
-    layout('second', 'layout/second-layout.tsx', [
-      route('/layout-a', 'a.tsx'),
-      route('/layout-b', 'b.tsx'),
+    layout('layout/second-layout.tsx', [
+      route('route-without-file', [
+        route('/layout-a', 'a.tsx'),
+        route('/layout-b', 'b.tsx'),
+      ]),
     ]),
   ]),
   physical('/classic', 'file-based-subtree'),

examples/react/basic-virtual-file-based/src/routeTree.gen.ts

@@ -8,6 +8,8 @@
 
 // This file is auto-generated by TanStack Router
 
+import { createFileRoute } from '@tanstack/react-router'
+
 // Import Routes
 
 import { Route as rootRoute } from './routes/root'
@@ -24,6 +26,10 @@ import { Route as ClassicHelloUniverseImport } from './routes/file-based-subtree
 import { Route as bImport } from './routes/b'
 import { Route as aImport } from './routes/a'
 
+// Create Virtual Routes
+
+const Import = createFileRoute('/_first/_second-layout/route-without-file')()
+
 // Create/Update Routes
 
 const postsPostsRoute = postsPostsImport.update({
@@ -47,7 +53,7 @@ const postsPostsDetailRoute = postsPostsDetailImport.update({
 } as any)
 
 const layoutSecondLayoutRoute = layoutSecondLayoutImport.update({
-  id: '/_second',
+  id: '/_second-layout',
   getParentRoute: () => layoutFirstLayoutRoute,
 } as any)
 
@@ -76,14 +82,19 @@ const ClassicHelloUniverseRoute = ClassicHelloUniverseImport.update({
   getParentRoute: () => ClassicHelloRouteRoute,
 } as any)
 
+const Route = Import.update({
+  path: '/route-without-file',
+  getParentRoute: () => layoutSecondLayoutRoute,
+} as any)
+
 const bRoute = bImport.update({
   path: '/layout-b',
-  getParentRoute: () => layoutSecondLayoutRoute,
+  getParentRoute: () => Route,
 } as any)
 
 const aRoute = aImport.update({
   path: '/layout-a',
-  getParentRoute: () => layoutSecondLayoutRoute,
+  getParentRoute: () => Route,
 } as any)
 
 // Populate the FileRoutesByPath interface
@@ -125,8 +136,8 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof postsPostsHomeImport
       parentRoute: typeof postsPostsImport
     }
-    '/_first/_second': {
-      id: '/_first/_second'
+    '/_first/_second-layout': {
+      id: '/_first/_second-layout'
       path: ''
       fullPath: ''
       preLoaderRoute: typeof layoutSecondLayoutImport
@@ -139,18 +150,11 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof postsPostsDetailImport
       parentRoute: typeof postsPostsImport
     }
-    '/_first/_second/layout-a': {
-      id: '/_first/_second/layout-a'
-      path: '/layout-a'
-      fullPath: '/layout-a'
-      preLoaderRoute: typeof aImport
-      parentRoute: typeof layoutSecondLayoutImport
-    }
-    '/_first/_second/layout-b': {
-      id: '/_first/_second/layout-b'
-      path: '/layout-b'
-      fullPath: '/layout-b'
-      preLoaderRoute: typeof bImport
+    '/_first/_second-layout/route-without-file': {
+      id: '/_first/_second-layout/route-without-file'
+      path: '/route-without-file'
+      fullPath: '/route-without-file'
+      preLoaderRoute: typeof Import
       parentRoute: typeof layoutSecondLayoutImport
     }
     '/classic/hello/universe': {
@@ -174,21 +178,45 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ClassicHelloIndexImport
       parentRoute: typeof ClassicHelloRouteImport
     }
+    '/_first/_second-layout/route-without-file/layout-a': {
+      id: '/_first/_second-layout/route-without-file/layout-a'
+      path: '/layout-a'
+      fullPath: '/route-without-file/layout-a'
+      preLoaderRoute: typeof aImport
+      parentRoute: typeof rootRoute
+    }
+    '/_first/_second-layout/route-without-file/layout-b': {
+      id: '/_first/_second-layout/route-without-file/layout-b'
+      path: '/layout-b'
+      fullPath: '/route-without-file/layout-b'
+      preLoaderRoute: typeof bImport
+      parentRoute: typeof rootRoute
+    }
   }
 }
 
 // Create and export the route tree
 
-interface layoutSecondLayoutRouteChildren {
+interface RouteChildren {
   aRoute: typeof aRoute
   bRoute: typeof bRoute
 }
 
-const layoutSecondLayoutRouteChildren: layoutSecondLayoutRouteChildren = {
+const RouteChildren: RouteChildren = {
   aRoute: aRoute,
   bRoute: bRoute,
 }
 
+const RouteWithChildren = Route._addFileChildren(RouteChildren)
+
+interface layoutSecondLayoutRouteChildren {
+  Route: typeof RouteWithChildren
+}
+
+const layoutSecondLayoutRouteChildren: layoutSecondLayoutRouteChildren = {
+  Route: RouteWithChildren,
+}
+
 const layoutSecondLayoutRouteWithChildren =
   layoutSecondLayoutRoute._addFileChildren(layoutSecondLayoutRouteChildren)
 
@@ -239,23 +267,25 @@ export interface FileRoutesByFullPath {
   '/classic/hello': typeof ClassicHelloRouteRouteWithChildren
   '/posts/': typeof postsPostsHomeRoute
   '/posts/$postId': typeof postsPostsDetailRoute
-  '/layout-a': typeof aRoute
-  '/layout-b': typeof bRoute
+  '/route-without-file': typeof RouteWithChildren
   '/classic/hello/universe': typeof ClassicHelloUniverseRoute
   '/classic/hello/world': typeof ClassicHelloWorldRoute
   '/classic/hello/': typeof ClassicHelloIndexRoute
+  '/route-without-file/layout-a': typeof aRoute
+  '/route-without-file/layout-b': typeof bRoute
 }
 
 export interface FileRoutesByTo {
   '/': typeof homeRoute
   '': typeof layoutSecondLayoutRouteWithChildren
   '/posts': typeof postsPostsHomeRoute
   '/posts/$postId': typeof postsPostsDetailRoute
-  '/layout-a': typeof aRoute
-  '/layout-b': typeof bRoute
+  '/route-without-file': typeof RouteWithChildren
   '/classic/hello/universe': typeof ClassicHelloUniverseRoute
   '/classic/hello/world': typeof ClassicHelloWorldRoute
   '/classic/hello': typeof ClassicHelloIndexRoute
+  '/route-without-file/layout-a': typeof aRoute
+  '/route-without-file/layout-b': typeof bRoute
 }
 
 export interface FileRoutesById {
@@ -265,13 +295,14 @@ export interface FileRoutesById {
   '/posts': typeof postsPostsRouteWithChildren
   '/classic/hello': typeof ClassicHelloRouteRouteWithChildren
   '/posts/': typeof postsPostsHomeRoute
-  '/_first/_second': typeof layoutSecondLayoutRouteWithChildren
+  '/_first/_second-layout': typeof layoutSecondLayoutRouteWithChildren
   '/posts/$postId': typeof postsPostsDetailRoute
-  '/_first/_second/layout-a': typeof aRoute
-  '/_first/_second/layout-b': typeof bRoute
+  '/_first/_second-layout/route-without-file': typeof RouteWithChildren
   '/classic/hello/universe': typeof ClassicHelloUniverseRoute
   '/classic/hello/world': typeof ClassicHelloWorldRoute
   '/classic/hello/': typeof ClassicHelloIndexRoute
+  '/_first/_second-layout/route-without-file/layout-a': typeof aRoute
+  '/_first/_second-layout/route-without-file/layout-b': typeof bRoute
 }
 
 export interface FileRouteTypes {
@@ -283,36 +314,39 @@ export interface FileRouteTypes {
     | '/classic/hello'
     | '/posts/'
     | '/posts/$postId'
-    | '/layout-a'
-    | '/layout-b'
+    | '/route-without-file'
     | '/classic/hello/universe'
     | '/classic/hello/world'
     | '/classic/hello/'
+    | '/route-without-file/layout-a'
+    | '/route-without-file/layout-b'
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
     | ''
     | '/posts'
     | '/posts/$postId'
-    | '/layout-a'
-    | '/layout-b'
+    | '/route-without-file'
     | '/classic/hello/universe'
     | '/classic/hello/world'
     | '/classic/hello'
+    | '/route-without-file/layout-a'
+    | '/route-without-file/layout-b'
   id:
     | '__root__'
     | '/'
     | '/_first'
     | '/posts'
     | '/classic/hello'
     | '/posts/'
-    | '/_first/_second'
+    | '/_first/_second-layout'
     | '/posts/$postId'
-    | '/_first/_second/layout-a'
-    | '/_first/_second/layout-b'
+    | '/_first/_second-layout/route-without-file'
     | '/classic/hello/universe'
     | '/classic/hello/world'
     | '/classic/hello/'
+    | '/_first/_second-layout/route-without-file/layout-a'
+    | '/_first/_second-layout/route-without-file/layout-b'
   fileRoutesById: FileRoutesById
 }
 
@@ -354,7 +388,7 @@ export const routeTree = rootRoute
     "/_first": {
       "filePath": "layout/first-layout.tsx",
       "children": [
-        "/_first/_second"
+        "/_first/_second-layout"
       ]
     },
     "/posts": {
@@ -376,25 +410,24 @@ export const routeTree = rootRoute
       "filePath": "posts/posts-home.tsx",
       "parent": "/posts"
     },
-    "/_first/_second": {
+    "/_first/_second-layout": {
       "filePath": "layout/second-layout.tsx",
       "parent": "/_first",
       "children": [
-        "/_first/_second/layout-a",
-        "/_first/_second/layout-b"
+        "/_first/_second-layout/route-without-file"
       ]
     },
     "/posts/$postId": {
       "filePath": "posts/posts-detail.tsx",
       "parent": "/posts"
     },
-    "/_first/_second/layout-a": {
-      "filePath": "a.tsx",
-      "parent": "/_first/_second"
-    },
-    "/_first/_second/layout-b": {
-      "filePath": "b.tsx",
-      "parent": "/_first/_second"
+    "/_first/_second-layout/route-without-file": {
+      "filePath": "",
+      "parent": "/_first/_second-layout",
+      "children": [
+        "/_first/_second-layout/route-without-file/layout-a",
+        "/_first/_second-layout/route-without-file/layout-b"
+      ]
     },
     "/classic/hello/universe": {
       "filePath": "file-based-subtree/hello/universe.tsx",
@@ -407,6 +440,14 @@ export const routeTree = rootRoute
     "/classic/hello/": {
       "filePath": "file-based-subtree/hello/index.tsx",
       "parent": "/classic/hello"
+    },
+    "/_first/_second-layout/route-without-file/layout-a": {
+      "filePath": "a.tsx",
+      "parent": "/_first/_second-layout/route-without-file"
+    },
+    "/_first/_second-layout/route-without-file/layout-b": {
+      "filePath": "b.tsx",
+      "parent": "/_first/_second-layout/route-without-file"
     }
   }
 }

examples/react/basic-virtual-file-based/src/routes/a.tsx

@@ -1,6 +1,8 @@
 import { createFileRoute } from '@tanstack/react-router'
 
-export const Route = createFileRoute('/_first/_second/layout-a')({
+export const Route = createFileRoute(
+  '/_first/_second-layout/route-without-file/layout-a',
+)({
   component: LayoutAComponent,
 })
 

examples/react/basic-virtual-file-based/src/routes/b.tsx

@@ -1,6 +1,8 @@
 import { createFileRoute } from '@tanstack/react-router'
 
-export const Route = createFileRoute('/_first/_second/layout-b')({
+export const Route = createFileRoute(
+  '/_first/_second-layout/route-without-file/layout-b',
+)({
   component: LayoutBComponent,
 })
 

examples/react/basic-virtual-file-based/src/routes/layout/second-layout.tsx

@@ -1,6 +1,6 @@
 import { Link, Outlet, createFileRoute } from '@tanstack/react-router'
 
-export const Route = createFileRoute('/_first/_second')({
+export const Route = createFileRoute('/_first/_second-layout')({
   component: LayoutComponent,
 })
 
@@ -10,15 +10,15 @@ function LayoutComponent() {
       <div>I'm a nested layout</div>
       <div className="flex gap-2 border-b">
         <Link
-          to="/layout-a"
+          to="/route-without-file/layout-a"
           activeProps={{
             className: 'font-bold',
           }}
         >
           Layout A
         </Link>
         <Link
-          to="/layout-b"
+          to="/route-without-file/layout-b"
           activeProps={{
             className: 'font-bold',
           }}

examples/react/basic-virtual-file-based/src/routes/root.tsx

@@ -36,7 +36,7 @@ function RootComponent() {
           Posts
         </Link>{' '}
         <Link
-          to="/layout-a"
+          to="/route-without-file/layout-a"
           activeProps={{
             className: 'font-bold',
           }}

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

@@ -13,14 +13,14 @@ const indexRouteSchema = z.object({
 
 const layoutRouteSchema: z.ZodType<LayoutRoute> = z.object({
   type: z.literal('layout'),
-  id: z.string(),
+  id: z.string().optional(),
   file: z.string(),
   children: z.array(z.lazy(() => virtualRouteNodeSchema)).optional(),
 })
 
 const routeSchema: z.ZodType<Route> = z.object({
   type: z.literal('route'),
-  file: z.string(),
+  file: z.string().optional(),
   path: z.string(),
   children: z.array(z.lazy(() => virtualRouteNodeSchema)).optional(),
 })