Skip to main content
skill CX Codex

virtual-file-routes — Claude Code skill: what it does, how to install

The virtual-file-routes skill for Claude Code builds route trees programmatically instead of relying on filesystem conventions. It triggers during router configuration updates.

MIT 108 installs ★ 15,341 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add TanStack/router --skill virtual-file-routes -a claude-code
Open on GitHub

What virtual-file-routes does

The skill constructs routes via root nodes, indexes, paths, layouts, and subtrees. File paths remain relative to the routes directory. Physical file routing directories can be mounted with URL prefixes.

Types infer automatically. Explicit type casting or annotation is strictly forbidden.

The @tanstack/virtual-file-routes package must be installed via npm, and the configuration passed to the router plugin before running.

What it helps with

  • build route trees programmatically with root and index nodes
  • mount a filesystem routing directory at a URL prefix
  • create a layout wrapper without adding a URL segment
  • define a virtual subtree configuration

Example prompts for the agent

  • Build the route tree using rootRoute and add an index route
  • Mount the posts directory using physical
  • Configure the virtual subtree using defineVirtualSubtreeConfig

How to install virtual-file-routes

1Skills CLI (Vercel)

npx skills add TanStack/router --skill virtual-file-routes -a claude-code

2Manually: put the files in place

~/.claude/skills/virtual-file-routes/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/virtual-file-routes/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about virtual-file-routes

How to install virtual-file-routes in Claude Code?

Run npx skills add TanStack/router --skill virtual-file-routes -a claude-code followed by ~/.claude/skills/virtual-file-routes/SKILL.md.

What does virtual-file-routes do?

It generates application route trees programmatically as an alternative to standard filesystem conventions.

What is required to run virtual-file-routes?

The @tanstack/virtual-file-routes package and the TanStack Router plugin configured in the project.

Source text

SKILL.md · MIT
---
name: virtual-file-routes
description: >-
  Programmatic route tree building as an alternative to filesystem
  conventions: rootRoute, index, route, layout, physical,
  defineVirtualSubtreeConfig. Use with TanStack Router plugin's
  virtualRouteConfig option.
metadata:
  type: core
  library: tanstack-router
  library_version: '1.162.0'
sources:
  - TanStack/router:packages/virtual-file-routes/src
  - TanStack/router:docs/router/routing/virtual-file-routes.md
---

# 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

```bash
npm install @tanstack/virtual-file-routes
```

## API Reference

### `rootRoute(file, children?)`

Creates the root of a virtual route tree.

```ts
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.

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

index('home.tsx')
```

### `route(path, ...)`

Creates a route node. Three call signatures:

```ts
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.

```ts
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.

```ts
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.

```ts
// 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:

```ts
// 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:

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

## Full Example

```ts
// 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.

```ts
// 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.

```ts
// 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.

```ts
// 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.

© TanStack · MIT · TanStack/router

Similar skills

All skills for Frontend and UI →
tanstack-router oakoss tanstack-router adds guidance for type-safe file-based React routing with @tanstack/react-router. Useful for loaders, search param validation, and code splitting. CX Codex +1 150installs tanstack-router-react-cursorrules-prompt-file PatrickJS tanstack-router-react-cursorrules-prompt-file enforces TanStack Router v1 patterns in React: file-based routing, Zod search param validation, loaders, and auth guards via beforeLoad. CX Codex +1 ★ 41,178repo stars nextjs-dynamic-routes-params wsimmonds nextjs-dynamic-routes-params — a skill that steers the agent through App Router dynamic segments and the params prop in Next.js 15+. Useful when a page depends on an ID or slug from the URL. CX Codex +1 304installs tanstack-router-best-practices DeckardGer tanstack-router-best-practices — a rule set for TanStack Router in React: type safety, data loading, search params, navigation. Useful once routing in a project grows past a few pages. CX Codex +1 7,200installs tanstack-start-cursorrules-prompt-file PatrickJS tanstack-start-cursorrules-prompt-file — a Cursor rule for TanStack Start, a full-stack React framework with SSR, server functions and type safety. Triggers when you work on Start projects, TanStack Router routes or Vinxi config files. CX Codex +1 ★ 41,178repo stars azure-virtual-network MicrosoftDocs A skill bundling Microsoft documentation on Azure Virtual Network design, configuration, and operations. Covers subnets, routing, NSGs, peering, and network security across best practices and deployment patterns. CX Codex +1 217installs

From the same set25

The whole set →
deployment deployment deploys TanStack Start to Cloudflare Workers, Netlify, Vercel, Node.js, Bun, and Railway. Controls SSR per route, static prerendering, and SEO config. CX Codex +1 210installs path-params path-params — a skill for handling dynamic URL parameters in TanStack Router. Teaches agents to capture variable path segments, set up optional routes, and create patterns with prefixes and suffixes. CX Codex +1 208installs middleware Covers TanStack Start middleware: createMiddleware, context chaining via next(), sendContext for cross-boundary transfers, and global registration in src/start.ts. CX Codex +1 206installs server-routes This skill guides an agent through API endpoints in TanStack Router, including HTTP handlers and request parsing. Use it when routes need an HTTP contract. CX Codex +1 205installs ssr The ssr skill for Claude Code configures streaming or non-streaming server-side rendering in TanStack Router for projects integrating the router with an existing server. CX Codex +1 202installs auth-server-primitives auth-server-primitives is a Claude Code skill for server-side authentication in TanStack Start. It covers session handling, OAuth, password-reset defenses, and protection for server functions. CX Codex +1 201installs migrate-from-react-router migrate-from-react-router is a Claude Code skill with a step-by-step checklist for moving from React Router v7 to TanStack Router, covering routes, navigation, and search params. CX Codex +1 188installs bundle-size-optimization bundle-size-optimization — a skill that makes the agent measure TanStack Router client bundles and compare each candidate against a saved baseline. Useful when gzip creeps up after a change. CX Codex +1 139installs

Project sponsors

Companies that keep this analytics open