Bundler Plugins

Integrate TanStack Router with Webpack, ESBuild, Rspack, or other bundlers

TanStack Router provides universal bundler plugins for Webpack, ESBuild, and Rspack through a single package. These plugins enable automatic route generation, code splitting, and hot module replacement across different bundlers.

Installation

Install the universal plugin package:

npm install -D @tanstack/router-plugin
# or
pnpm add -D @tanstack/router-plugin
# or
yarn add -D @tanstack/router-plugin

This single package provides plugins for all supported bundlers.

Webpack Plugin

Basic Setup

Add the plugin to your webpack.config.js:

const { TanStackRouterWebpack } = require('@tanstack/router-plugin/webpack')

module.exports = {
  plugins: [
    TanStackRouterWebpack(),
  ],
}

With TypeScript:

import { TanStackRouterWebpack } from '@tanstack/router-plugin/webpack'
import type { Configuration } from 'webpack'

const config: Configuration = {
  plugins: [
    TanStackRouterWebpack(),
  ],
}

export default config

Configuration

Pass configuration options to the plugin:

import { TanStackRouterWebpack } from '@tanstack/router-plugin/webpack'

const config: Configuration = {
  plugins: [
    TanStackRouterWebpack({
      target: 'react',
      routesDirectory: './src/routes',
      generatedRouteTree: './src/routeTree.gen.ts',
      autoCodeSplitting: true,
    }),
  ],
}

export default config

Specialized Webpack Plugins

Use separate plugins for generation and code splitting:

import {
  TanStackRouterGeneratorWebpack,
  TanStackRouterCodeSplitterWebpack,
} from '@tanstack/router-plugin/webpack'

const config: Configuration = {
  plugins: [
    TanStackRouterGeneratorWebpack({
      routesDirectory: './src/routes',
    }),
    TanStackRouterCodeSplitterWebpack({
      autoCodeSplitting: true,
    }),
  ],
}

export default config

With React

const { TanStackRouterWebpack } = require('@tanstack/router-plugin/webpack')
const ReactRefreshWebpackPlugin = require('@pmmmwh/react-refresh-webpack-plugin')

module.exports = {
  plugins: [
    new ReactRefreshWebpackPlugin(),
    TanStackRouterWebpack({ target: 'react' }),
  ],
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              ['@babel/preset-react', { runtime: 'automatic' }],
              '@babel/preset-typescript',
            ],
          },
        },
      },
    ],
  },
}

ESBuild Plugin

Basic Setup

Add the plugin to your ESBuild configuration:

const { build } = require('esbuild')
const { TanStackRouterEsbuild } = require('@tanstack/router-plugin/esbuild')

build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [TanStackRouterEsbuild()],
})

With TypeScript:

import { build } from 'esbuild'
import { TanStackRouterEsbuild } from '@tanstack/router-plugin/esbuild'

await build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [TanStackRouterEsbuild()],
})

Configuration

import { TanStackRouterEsbuild } from '@tanstack/router-plugin/esbuild'

await build({
  plugins: [
    TanStackRouterEsbuild({
      target: 'react',
      routesDirectory: './src/routes',
      generatedRouteTree: './src/routeTree.gen.ts',
      autoCodeSplitting: true,
    }),
  ],
})

Specialized ESBuild Plugins

import {
  TanStackRouterGeneratorEsbuild,
  TanStackRouterCodeSplitterEsbuild,
} from '@tanstack/router-plugin/esbuild'

await build({
  plugins: [
    TanStackRouterGeneratorEsbuild(),
    TanStackRouterCodeSplitterEsbuild(),
  ],
})

With React and JSX

import { build } from 'esbuild'
import { TanStackRouterEsbuild } from '@tanstack/router-plugin/esbuild'

await build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [TanStackRouterEsbuild({ target: 'react' })],
  loader: {
    '.tsx': 'tsx',
    '.ts': 'ts',
  },
  jsx: 'automatic',
})

Rspack Plugin

Basic Setup

Add the plugin to your Rspack configuration:

const { TanStackRouterRspack } = require('@tanstack/router-plugin/rspack')

module.exports = {
  plugins: [
    TanStackRouterRspack(),
  ],
}

With TypeScript and Rsbuild:

import { defineConfig } from '@rsbuild/core'
import { pluginReact } from '@rsbuild/plugin-react'
import { TanStackRouterRspack } from '@tanstack/router-plugin/rspack'

export default defineConfig({
  plugins: [pluginReact()],
  tools: {
    rspack: {
      plugins: [TanStackRouterRspack()],
    },
  },
})

Configuration

import { TanStackRouterRspack } from '@tanstack/router-plugin/rspack'

export default defineConfig({
  tools: {
    rspack: {
      plugins: [
        TanStackRouterRspack({
          target: 'react',
          routesDirectory: './src/routes',
          generatedRouteTree: './src/routeTree.gen.ts',
          autoCodeSplitting: true,
        }),
      ],
    },
  },
})

Specialized Rspack Plugins

import {
  TanStackRouterGeneratorRspack,
  TanStackRouterCodeSplitterRspack,
} from '@tanstack/router-plugin/rspack'

export default defineConfig({
  tools: {
    rspack: {
      plugins: [
        TanStackRouterGeneratorRspack(),
        TanStackRouterCodeSplitterRspack(),
      ],
    },
  },
})

Configuration Options

All bundler plugins support the same configuration options:

target · 'react' | 'solid' | 'vue' · default: "react"

The framework you’re using with TanStack Router

routesDirectory · string · default: "./src/routes"

The directory containing your route files

generatedRouteTree · string · default: "./src/routeTree.gen.ts"

Where to output the generated route tree file

routeFilePrefix · string

Optional prefix for route files

routeFileIgnorePrefix · string · default: "-"

Files starting with this prefix will be ignored

quoteStyle · 'single' | 'double' · default: "single"

Quote style for generated code

semicolons · boolean · default: false

Whether to include semicolons in generated code

autoCodeSplitting · boolean

Automatically enable code splitting for routes

disableTypes · boolean · default: false

Disable TypeScript type generation

disableLogging · boolean · default: false

Disable plugin logging output

codeSplittingOptions · CodeSplittingOptions

Advanced code splitting configuration:

{
  defaultBehavior: [
    ['component'],
    ['pendingComponent'],
    ['errorComponent'],
    ['notFoundComponent']
  ],
  splitBehavior: ({ routeId }) => {
    // Custom logic per route
    return undefined // use default
  },
  deleteNodes: ['loader'],
  addHmr: true
}

Code Splitting

All plugins support automatic code splitting:

// Any bundler plugin
{
  autoCodeSplitting: true,
  codeSplittingOptions: {
    defaultBehavior: [
      ['component'],
      ['pendingComponent'],
      ['errorComponent', 'notFoundComponent'],
    ],
    splitBehavior: ({ routeId }) => {
      // Don't split critical routes
      if (routeId === '/' || routeId === '/login') {
        return undefined
      }
      // Custom split for admin
      if (routeId.startsWith('/admin')) {
        return [['component', 'pendingComponent']]
      }
      return undefined // use default
    },
  },
}

TypeScript Support

All plugins generate TypeScript types automatically. Ensure your tsconfig.json includes the generated files:

{
  "compilerOptions": {
    "strict": true,
    "moduleResolution": "bundler"
  },
  "include": [
    "src",
    "src/routeTree.gen.ts"
  ]
}

Validation with Zod

The plugins use Zod for configuration validation:

import { configSchema } from '@tanstack/router-plugin'

// Validate your config
const config = configSchema.parse({
  target: 'react',
  routesDirectory: './src/routes',
})

Using Unplugin Directly

The plugins are built with unplugin, which provides a unified plugin interface. You can use the raw unplugin factories:

import { createWebpackPlugin } from 'unplugin'
import { unpluginRouterGeneratorFactory } from '@tanstack/router-plugin'

const customPlugin = createWebpackPlugin(unpluginRouterGeneratorFactory)

Comparison with CLI

Bundler plugins vs CLI (tsr watch):

Feature	Bundler Plugin	CLI
Route generation	✅	✅
Watch mode	✅ (automatic)	✅ (manual)
HMR	✅	❌
Code splitting	✅	❌
Build integration	✅ (native)	❌ (separate process)
Setup complexity	Medium	Low

Recommendation: Use bundler plugins for better integration and features. Use CLI only if your bundler is not supported.

Comparison with Vite Plugin

The Vite plugin is the recommended choice for Vite projects:

// ✅ Recommended for Vite
import { tanstackRouter } from '@tanstack/router-plugin/vite'

// ⚠️ Also works, but use Vite-specific export
import { TanStackRouterWebpack } from '@tanstack/router-plugin/webpack'

See Vite Plugin for Vite-specific documentation.

Troubleshooting

Plugin not working

1. Verify the plugin is properly imported for your bundler
2. Check that configuration options are valid
3. Ensure route files exist in the configured directory
4. Check bundler logs for errors

Routes not generating

1. Verify routesDirectory path is correct
2. Check file naming conventions match expected patterns
3. Ensure bundler is running in watch/dev mode
4. Check for configuration validation errors

Type errors

1. Include generated route tree in tsconfig.json
2. Restart your TypeScript server
3. Verify disableTypes is not set to true
4. Check that route files have valid TypeScript

Code splitting not working

1. Set autoCodeSplitting: true
2. Verify codeSplittingOptions configuration is valid
3. Check that route components are properly exported
4. Ensure bundler supports dynamic imports

Webpack-specific issues

1. Check React Refresh plugin order
2. Verify babel configuration includes JSX transform
3. Ensure source maps are enabled for debugging

ESBuild-specific issues

1. Configure JSX transform: jsx: 'automatic'
2. Set correct loaders for .tsx and .ts files
3. ESBuild plugin support is limited - consider Vite

Rspack-specific issues

1. Use within tools.rspack.plugins array
2. Ensure Rsbuild React plugin is configured
3. Check Rspack version compatibility (>= 1.0.2)