TanStack Router bundler plugin for route generation and automatic code splitting. Supports Vite, Webpack, Rspack, and esbuild. Configures autoCodeSplitting, routesDirectory, target framework, and code split groupings.
@tanstack/router-plugin)Bundler plugin that powers TanStack Router's file-based routing and automatic code splitting. Works with Vite, Webpack, Rspack, and esbuild via unplugin.
CRITICAL: The router plugin MUST come before the framework plugin (React, Solid, Vue) in the Vite config. Wrong order causes route generation and code splitting to fail silently.
npm install -D @tanstack/router-plugin
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
export default defineConfig({
plugins: [
// MUST come before react()
tanstackRouter({
target: 'react',
autoCodeSplitting: true,
}),
react(),
],
})
// webpack.config.js
const { tanstackRouter } = require('@tanstack/router-plugin/webpack')
module.exports = {
plugins: [
tanstackRouter({
target: 'react',
autoCodeSplitting: true,
}),
],
}
// rspack.config.js
const { tanstackRouter } = require('@tanstack/router-plugin/rspack')
module.exports = {
plugins: [
tanstackRouter({
target: 'react',
autoCodeSplitting: true,
}),
],
}
import { tanstackRouter } from '@tanstack/router-plugin/esbuild'
import esbuild from 'esbuild'
esbuild.build({
plugins: [
tanstackRouter({
target: 'react',
autoCodeSplitting: true,
}),
],
})
| Option | Type | Default | Description |
|---|---|---|---|
target | 'react' | 'solid' | 'vue' | 'react' | Target framework |
routesDirectory | string | './src/routes' | Directory containing route files |
generatedRouteTree | string | './src/routeTree.gen.ts' | Path for generated route tree |
autoCodeSplitting | boolean | undefined | Enable automatic code splitting |
enableRouteGeneration | boolean | true | Set to false to disable route generation |
| Option | Type | Default | Description |
|---|---|---|---|
routeFilePrefix | string | undefined | Prefix filter for route files |
routeFileIgnorePrefix | string | '-' | Prefix to exclude files from routing |
routeFileIgnorePattern | string | undefined | Pattern to exclude from routing |
indexToken | string | RegExp | { regex: string; flags?: string } | 'index' | Token identifying index routes |
routeToken | string | RegExp | { regex: string; flags?: string } | 'route' | Token identifying route config files |
tanstackRouter({
target: 'react',
autoCodeSplitting: true,
codeSplittingOptions: {
// Default groupings for all routes
defaultBehavior: [['component'], ['errorComponent'], ['notFoundComponent']],
// Per-route custom splitting
splitBehavior: ({ routeId }) => {
if (routeId === '/dashboard') {
// Keep loader and component together for dashboard
return [['loader', 'component'], ['errorComponent']]
}
// Return undefined to use defaultBehavior
},
},
})
| Option | Type | Default | Description |
|---|---|---|---|
quoteStyle | 'single' | 'double' | 'single' | Quote style in generated code |
semicolons | boolean | false | Use semicolons in generated code |
disableTypes | boolean | false | Disable TypeScript types |
disableLogging | boolean | false | Suppress plugin logs |
addExtensions | boolean | string | false | Add file extensions to imports |
enableRouteTreeFormatting | boolean | true | Format generated route tree |
import { routes } from './routes'
tanstackRouter({
target: 'react',
virtualRouteConfig: routes, // or './routes.ts'
})
The composed plugin assembles up to 3 sub-plugins:
routeTree.gen.tsautoCodeSplitting: true) — Splits route files into lazy-loaded chunks using virtual modulesFor advanced use, each sub-plugin is exported separately from the Vite entry:
import {
tanstackRouter, // Composed (default)
tanstackRouterGenerator, // Generator only
tanStackRouterCodeSplitter, // Code splitter only
} from '@tanstack/router-plugin/vite'
The router plugin must come before the framework plugin. Otherwise, route generation and code splitting fail silently.
// WRONG — react() before tanstackRouter()