Virtual File Routes (@tanstack/virtual-file-routes)

Build route trees programmatically instead of relying on filesystem conventions. Useful when you want explicit control over route structure, need to mix virtual and physical routes, or want to define route subtrees within file-based routing directories.

Use this skill only when the project config contains virtualRouteConfig, a virtual route config file, or __virtual.ts. Ordinary file-route changes belong to Router Core and the Router Plugin.

CRITICAL: Types are FULLY INFERRED. Never cast, never annotate inferred values.

Install

npm install @tanstack/virtual-file-routes

API Reference

rootRoute(file, children?)

Creates the root of a virtual route tree.

import { rootRoute, index, route } from '@tanstack/virtual-file-routes'

const routes = rootRoute('root.tsx', [
  index('index.tsx'),
  route('/about', 'about.tsx'),
])

index(file)

Creates an index route — the default rendered when the parent path matches exactly.

import { index } from '@tanstack/virtual-file-routes'

index('home.tsx')

route(path, ...)

Creates a route node. Three call signatures:

import { route, index } from '@tanstack/virtual-file-routes'

// Leaf route: path + file
route('/about', 'about.tsx')

// Branch route: path + file + children
route('/dashboard', 'dashboard.tsx', [
  index('dashboard-index.tsx'),
  route('/settings', 'settings.tsx'),
])

// Path prefix only (no file): groups children under a URL segment
route('/api', [route('/users', 'users.tsx'), route('/posts', 'posts.tsx')])

layout(file, children) or layout(id, file, children)

Creates a pathless layout route — wraps children without adding a URL segment.

import { layout, route, index } from '@tanstack/virtual-file-routes'

// ID derived from filename
layout('authLayout.tsx', [
  route('/dashboard', 'dashboard.tsx'),
  route('/settings', 'settings.tsx'),
])

// Explicit ID
layout('admin-layout', 'adminLayout.tsx', [route('/admin', 'admin.tsx')])

physical(pathPrefix, directory) or physical(directory)

Mounts a directory of file-based routes at a URL prefix. Uses TanStack Router's standard file-based routing conventions within that directory.

import { physical } from '@tanstack/virtual-file-routes'

// Mount posts/ directory under /posts
physical('/posts', 'posts')

// Merge features/ directory at the current level
physical('features')

defineVirtualSubtreeConfig(config)

Type helper for __virtual.ts files inside file-based routing directories. Identity function that provides type inference.

// src/routes/admin/__virtual.ts
import {
  defineVirtualSubtreeConfig,
  index,
  route,
} from '@tanstack/virtual-file-routes'

export default defineVirtualSubtreeConfig([
  index('home.tsx'),
  route('$id', 'details.tsx'),
])

Integration with Router Plugin

Pass the virtual route config to the TanStack Router plugin:

// vite.config.ts
import { defineConfig } from 'vite'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
import { routes } from './routes'

export default defineConfig({
  plugins: [
    tanstackRouter({
      target: 'react', // or 'solid', 'vue'
      virtualRouteConfig: routes,
    }),
    // Add your framework's Vite plugin here
  ],
})

Or reference a file path:

tanstackRouter({
  target: 'react',
  virtualRouteConfig: './routes.ts',
})

Full Example

// routes.ts
import {
  rootRoute,
  route,
  index,
  layout,
  physical,
} from '@tanstack/virtual-file-routes'

export const routes = rootRoute('root.tsx', [
  index('index.tsx'),

  layout('authLayout.tsx', [
    route('/dashboard', 'app/dashboard.tsx', [
      index('app/dashboard-index.tsx'),
      route('/invoices', 'app/dashboard-invoices.tsx', [
        index('app/invoices-index.tsx'),
        route('$id', 'app/invoice-detail.tsx'),
      ]),
    ]),
  ]),

  // Mount file-based routing from posts/ directory
  physical('/posts', 'posts'),
])

Common Mistakes

1. HIGH: Forgetting that file paths are relative to routesDirectory

File paths in rootRoute, index, route, and layout are relative to the routesDirectory configured in the router plugin (default: ./src/routes). Do not use absolute paths or paths relative to the project root.

// WRONG — absolute path
route('/about', '/src/routes/about.tsx')

// CORRECT — relative to routesDirectory
route('/about', 'about.tsx')

2. MEDIUM: Using physical() without matching directory structure

The directory passed to physical() must exist inside routesDirectory and follow TanStack Router's file-based routing conventions.

// WRONG — directory doesn't exist or wrong location
physical('/blog', 'src/blog')

// CORRECT — relative to routesDirectory
physical('/blog', 'blog')
// Expects: src/routes/blog/ (with route files inside)

3. MEDIUM: Confusing layout() with route()

layout() creates a pathless wrapper — it does NOT add a URL segment. Use route() for URL segments.

// This does NOT create a /dashboard URL
layout('dashboardLayout.tsx', [route('/dashboard', 'dashboard.tsx')])

// The URL is /dashboard, and dashboardLayout.tsx wraps it

Refactor Audit

After changing a virtual tree:

1. Confirm there is exactly one rootRoute and that every referenced file exists relative to routesDirectory.
2. Check each route, layout, and physical node for duplicate effective paths or IDs.
3. Confirm each physical() directory is mounted once at the intended path prefix and does not overlap a virtual child.
4. Regenerate routeTree.gen.ts and inspect parentage, full paths, and imports. Do not edit generated output.
5. Update links, redirects, params, and from narrowing, then run generator tests, type tests, and a production build.