Skip to main content
The TanStack Router CLI (@tanstack/router-cli) provides command-line tools for generating route files and watching for changes in your routing structure.

​
Installation

Install the CLI as a development dependency: 
npm install -D @tanstack/router-cli
# or
pnpm add -D @tanstack/router-cli
# or
yarn add -D @tanstack/router-cli

​
Configuration

Create a tsr.config.json file in your project root to configure the router generator: 
{
  "routesDirectory": "./src/routes",
  "generatedRouteTree": "./src/routeTree.gen.ts",
  "quoteStyle": "single",
  "semicolons": false,
  "disableTypes": false,
  "addExtensions": false,
  "disableLogging": false
}

​
Configuration Options

​
routesDirectory
string
default:"./src/routes"
The directory where your route files are located
​
generatedRouteTree
string
default:"./src/routeTree.gen.ts"
The path where the generated route tree file will be created
​
routeFilePrefix
string
Optional prefix for route files (e.g., “route” would match “route.home.tsx”)
​
routeFileIgnorePrefix
string
default:"-"
Files starting with this prefix will be ignored by the route generator
​
routeFileIgnorePattern
string
A regex pattern to match files that should be ignored
​
quoteStyle
'single' | 'double'
default:"single"
The quote style to use in generated files
​
semicolons
boolean
default:false
Whether to include semicolons in generated files
​
disableTypes
boolean
default:false
Disable TypeScript type generation (outputs .js files instead)
​
disableLogging
boolean
default:false
Disable logging output from the CLI
​
addExtensions
boolean | string
default:false
Add file extensions to imports in generated files. Can be true for .js or a custom extension like .ts
​
routeTreeFileHeader
string[]
Custom headers to add to the generated route tree fileDefault:
[
  "/* eslint-disable */",
  "// @ts-nocheck",
  "// noinspection JSUnusedGlobalSymbols"
]
​
autoCodeSplitting
boolean
Automatically enable code splitting for your routes
​
indexToken
string | RegExp | object
default:"index"
The token to use for index routes (e.g., “index.tsx” matches index routes)
​
routeToken
string | RegExp | object
default:"route"
The token to use for route files (e.g., “route.tsx” for file-based routing)

​
CLI Commands

The CLI provides two main commands:

​
generate

Generate the route tree once: 
npx tsr generate
This command:
  • Reads your route files from the configured routesDirectory
  • Generates a type-safe route tree file at the configured generatedRouteTree path
  • Creates TypeScript types for all routes, search params, and path params

​
watch

Continuously watch for changes and regenerate routes: 
npx tsr watch
This command:
  • Runs the generator initially
  • Watches your routesDirectory for changes
  • Automatically regenerates the route tree whenever files are added, modified, or deleted
  • Keeps running until manually stopped

​
Usage in Scripts

Add the CLI commands to your package.json scripts: 
{
  "scripts": {
    "routes:generate": "tsr generate",
    "routes:watch": "tsr watch",
    "dev": "tsr watch --silent & vite"
  }
}
Then run: 
npm run routes:generate  # Generate once
npm run routes:watch     # Watch for changes
npm run dev             # Development with auto-generation

​
Generated Route Tree

The CLI generates a route tree file that looks like this: 
/* eslint-disable */
// @ts-nocheck
// noinspection JSUnusedGlobalSymbols

import { createFileRoute } from '@tanstack/react-router'

// Route imports
import { Route as rootRoute } from './routes/__root'
import { Route as AboutRoute } from './routes/about'
import { Route as IndexRoute } from './routes/index'

// Route tree
export const routeTree = rootRoute.addChildren([
  AboutRoute,
  IndexRoute,
])
This generated file:
  • Is fully type-safe
  • Should not be edited manually (regenerated on changes)
  • Exports a routeTree you can pass to createRouter()
  • Can be safely committed to version control

​
Working Without the CLI

While the CLI is the recommended approach, you can also use the bundler plugins instead: These plugins integrate route generation directly into your build process.

​
Requirements

  • Node.js >= 20.19
  • A TypeScript or JavaScript project
  • File-based routing structure in your project

​
Troubleshooting

​
Routes not generating

  1. Check that your routesDirectory path is correct in tsr.config.json
  2. Ensure route files follow the naming convention (e.g., route.tsx or use custom routeToken)
  3. Verify the CLI has permission to write to the generatedRouteTree location

​
Type errors after generation

  1. Restart your TypeScript server in your IDE
  2. Run tsc --noEmit to check for type errors
  3. Ensure the generated file is not excluded in your tsconfig.json

​
Watch mode not detecting changes

  1. Ensure the process is still running
  2. Try stopping and restarting the watch command
  3. Check that your file system supports file watching

Build docs developers (and LLMs) love

Get started for freeTalk to us