Vite Plugin API

Vite Plugin

Vite plugin for TanStack Router with automatic route generation, code splitting, and development features.

Installation

npm install @tanstack/router-plugin

Basic Usage

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

export default defineConfig({
  plugins: [
    tanstackRouter()
  ]
})

Configuration Options

routesDirectory · string

Directory containing route files.

Default: './src/routes'

tanstackRouter({
  routesDirectory: './app/routes'
})

generatedRouteTree · string

Output path for generated route tree file.

Default: './src/routeTree.gen.ts'

tanstackRouter({
  generatedRouteTree: './app/routeTree.gen.ts'
})

routeFileIgnorePrefix · string

Prefix to ignore when generating routes.

Default: '-'

tanstackRouter({
  routeFileIgnorePrefix: '_'
})

Files starting with this prefix (e.g., _component.tsx) will be ignored.

routeFileIgnorePattern · RegExp

Pattern to ignore when generating routes.

tanstackRouter({
  routeFileIgnorePattern: /\.test\./
})

quoteStyle · 'single' | 'double'

Quote style for generated code.

Default: 'single'

tanstackRouter({
  quoteStyle: 'double'
})

semicolons · boolean

Whether to use semicolons in generated code.

Default: false

tanstackRouter({
  semicolons: true
})

autoCodeSplitting · boolean

Enable automatic code splitting.

Default: false

tanstackRouter({
  autoCodeSplitting: true
})

codeSplittingOptions · CodeSplittingOptions

Advanced code splitting configuration.

tanstackRouter({
  autoCodeSplitting: true,
  codeSplittingOptions: {
    defaultBehavior: [
      ['component'],
      ['pendingComponent', 'errorComponent']
    ]
  }
})

enableRouteGeneration · boolean

Enable/disable route generation.

Default: true

tanstackRouter({
  enableRouteGeneration: false
})

Code Splitting Options

Configure how routes are split into separate chunks.

defaultBehavior · Array<Array<string>>

Default splitting strategy for all routes.

Default: [['component'], ['pendingComponent'], ['errorComponent'], ['notFoundComponent']]

codeSplittingOptions: {
  // Split component and loader together
  defaultBehavior: [
    ['component', 'loader'],
    ['pendingComponent'],
    ['errorComponent']
  ]
}

splitBehavior · (params: { routeId: string }) => Array<Array<string>> | undefined

Custom splitting strategy per route.

codeSplittingOptions: {
  splitBehavior: ({ routeId }) => {
    // Don't split the index route
    if (routeId === '/') {
      return undefined
    }
    
    // Custom splitting for admin routes
    if (routeId.startsWith('/admin')) {
      return [
        ['component', 'loader', 'pendingComponent']
      ]
    }
    
    // Use default for others
    return undefined
  }
}

deleteNodes · Array<string>

Route properties to remove during splitting.

codeSplittingOptions: {
  deleteNodes: ['staticData', 'meta']
}

addHmr · boolean

Add Hot Module Replacement support.

Default: true

codeSplittingOptions: {
  addHmr: false
}

Examples

Basic Setup

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

export default defineConfig({
  plugins: [
    react(),
    tanstackRouter()
  ]
})

Custom Routes Directory

import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({
      routesDirectory: './src/pages',
      generatedRouteTree: './src/pages/routeTree.gen.ts'
    })
  ]
})

With Code Splitting

import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({
      autoCodeSplitting: true,
      codeSplittingOptions: {
        // Split components and loaders separately
        defaultBehavior: [
          ['component'],
          ['loader'],
          ['pendingComponent', 'errorComponent']
        ]
      }
    })
  ]
})

Custom File Patterns

import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({
      routeFileIgnorePrefix: '_',
      routeFileIgnorePattern: /\.(test|spec)\./,
      quoteStyle: 'double',
      semicolons: true
    })
  ]
})

Per-Route Code Splitting

import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({
      autoCodeSplitting: true,
      codeSplittingOptions: {
        splitBehavior: ({ routeId }) => {
          // Don't split the root and index routes
          if (routeId === '__root__' || routeId === '/') {
            return undefined
          }
          
          // Split admin routes more aggressively
          if (routeId.startsWith('/admin')) {
            return [
              ['component'],
              ['loader'],
              ['beforeLoad'],
              ['pendingComponent'],
              ['errorComponent']
            ]
          }
          
          // Default splitting for other routes
          return [
            ['component', 'pendingComponent'],
            ['loader'],
            ['errorComponent']
          ]
        }
      }
    })
  ]
})

Monorepo Setup

import { defineConfig } from 'vite'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
import path from 'path'

export default defineConfig({
  plugins: [
    tanstackRouter({
      routesDirectory: path.resolve(__dirname, './src/routes'),
      generatedRouteTree: path.resolve(__dirname, './src/routeTree.gen.ts')
    })
  ]
})

With Multiple Environments

import { defineConfig } from 'vite'
import { tanstackRouter } from '@tanstack/router-plugin/vite'

export default defineConfig(({ mode }) => ({
  plugins: [
    tanstackRouter({
      autoCodeSplitting: mode === 'production',
      codeSplittingOptions: {
        addHmr: mode === 'development'
      }
    })
  ]
}))

Generated Files

The plugin generates a routeTree.gen.ts file:

// routeTree.gen.ts (auto-generated)
import { Route as rootRoute } from './routes/__root'
import { Route as IndexRoute } from './routes/index'
import { Route as PostsRoute } from './routes/posts'
import { Route as PostsIndexRoute } from './routes/posts/index'
import { Route as PostsPostIdRoute } from './routes/posts/$postId'

export const routeTree = rootRoute.addChildren([
  IndexRoute,
  PostsRoute.addChildren([
    PostsIndexRoute,
    PostsPostIdRoute
  ])
])

File-Based Routing Conventions

src/routes/
  __root.tsx         -> / (root layout)
  index.tsx          -> / (index page)
  about.tsx          -> /about
  posts.tsx          -> /posts (layout)
  posts/
    index.tsx        -> /posts (index)
    $postId.tsx      -> /posts/:postId
    $postId/
      edit.tsx       -> /posts/:postId/edit
  _components/       -> Ignored (starts with _)
  -utils.ts          -> Ignored (starts with -)

TypeScript Support

The plugin automatically generates TypeScript types:

// Generated types are automatically picked up
import { Link } from '@tanstack/react-router'

// Full autocomplete for routes
<Link to="/posts/$postId" params={{ postId: '123' }} />

Hot Module Replacement

The plugin supports HMR for route updates:

• Add/remove route files → route tree updates automatically
• Edit route components → hot reload without full page refresh
• Update route config → route tree regenerates

Troubleshooting

Routes Not Generating

Check that:

• routesDirectory path is correct
• Route files have proper extensions (.tsx, .ts)
• Files don’t start with ignore prefix

Type Errors

Ensure:

• Generated route tree file is in your tsconfig.json include
• Router is properly registered in your app

// tsconfig.json
{
  "include": [
    "src/**/*",
    "src/routeTree.gen.ts" // Include generated file
  ]
}