Most of the TanStack Router documentation is written for file-based routing. This guide is mostly intended to help you understand in more detail how to configure file-based routing and the technical details behind how it works.
To enable file-based route generation, you'll need to install either the @tanstack/router-vite-plugin or @tanstack/router-cli package to generate your route tree file.
The @tanstack/router-vite-plugin Vite plugin will automatically generate your route configuration through Vite's dev and build processes. It is the easiest way to use TanStack Router's route generation features.
npm install @tanstack/router-vite-plugin
npm install @tanstack/router-vite-plugin
To enable the Vite plugin, add it to your vite.config.ts file:
// vite.config.ts
import { defineConfig } from 'vite'
import { TanStackRouterVite } from '@tanstack/router-vite-plugin'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
// ...,
TanStackRouterVite(),
],
})
// vite.config.ts
import { defineConfig } from 'vite'
import { TanStackRouterVite } from '@tanstack/router-vite-plugin'
// https://vitejs.dev/config/
export default defineConfig({
plugins: [
// ...,
TanStackRouterVite(),
],
})
With the plugin enabled, Vite will now watch your configured routesDirectory and generate your route tree whenever a file is added, removed, or changed.
If you are unable to use Vite, you can always use the Router CLI (which is what the Vite plugin uses) to generate your route configuration from your package dev/build scripts.
npm install @tanstack/router-cli
npm install @tanstack/router-cli
With the CLI installed, the following commands are made available via the tsr command
Generates the routes for a project based on the provided configuration.
Usage:
tsr generate
tsr generate
Continuously watches the specified directories and regenerates routes as needed.
Usage:
tsr watch
tsr watch
File-based routing comes with some sane defaults that should work for most projects:
{
"routesDirectory": "./src/routes",
"generatedRouteTree": "./src/routeTree.gen.ts",
"routeFileIgnorePrefix": "-",
"quoteStyle": "single"
}
{
"routesDirectory": "./src/routes",
"generatedRouteTree": "./src/routeTree.gen.ts",
"routeFileIgnorePrefix": "-",
"quoteStyle": "single"
}
If these defaults work for your project, you don't need to configure anything at all! However, if you need to customize the configuration, you can do so by creating a tsr.config.json file in the root of your project directory.
The following options are available for configuration via the tsr.config.json file:
🚨 Important: Do not set the routeFilePrefix, routeFileIgnorePrefix, or routeFileIgnorePattern options, to match any of the tokens used in the file-naming conventions section.
routeFilePrefix
routeFileIgnorePrefix
routeFileIgnorePattern
routesDirectory
generatedRouteTree
quoteStyle
semicolons
disableTypes
addExtensions
disableLogging
routeTreeFileHeader
[
'/* prettier-ignore-start */',
'/* eslint-disable */',
'// @ts-nocheck',
'// noinspection JSUnusedGlobalSymbols'
]
[
'/* prettier-ignore-start */',
'/* eslint-disable */',
'// @ts-nocheck',
'// noinspection JSUnusedGlobalSymbols'
]
routeTreeFileFooter
[
'/* prettier-ignore-end */'
]
[
'/* prettier-ignore-end */'
]
File-based routing requires that you follow a few simple file naming conventions to ensure that your routes are generated correctly. The concepts these conventions enable are covered in detail in the Route Trees & Nesting guide.
💡 Remember: The file-naming conventions for your project could be affected by what options are configured in your tsr.config.json. By default, the routeFileIgnorePrefix option is set to -, as such files and directories starting with - will not be considered for routing.
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.