router-plugin

路由器插件（@tanstack/router-plugin）

为 TanStack Router 的基于文件的路由和自动代码拆分提供支持的打包器插件。通过 unplugin 支持 Vite、Webpack、Rspack 和 esbuild。

重要：在 Vite 配置中，路由器插件必须放在框架插件（React、Solid、Vue）之前。顺序错误会导致路由生成和代码拆分静默失败。

安装

npm install -D @tanstack/router-plugin

打包器设置

Vite（最常用）

// 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

// webpack.config.js
const { tanstackRouter } = require('@tanstack/router-plugin/webpack')

module.exports = {
  plugins: [
    tanstackRouter({
      target: 'react',
      autoCodeSplitting: true,
    }),
  ],
}

Rspack

// rspack.config.js
const { tanstackRouter } = require('@tanstack/router-plugin/rspack')

module.exports = {
  plugins: [
    tanstackRouter({
      target: 'react',
      autoCodeSplitting: true,
    }),
  ],
}

esbuild

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

esbuild.build({
  plugins: [
    tanstackRouter({
      target: 'react',
      autoCodeSplitting: true,
    }),
  ],
})

配置选项

核心选项

选项	类型	默认值	说明
target	'react' | 'solid' | 'vue'	'react'	目标框架
routesDirectory	string	'./src/routes'	包含路由文件的目录
generatedRouteTree	string	'./src/routeTree.gen.ts'	生成的路由树路径
autoCodeSplitting	boolean	undefined	启用自动代码拆分

文件约定选项

选项	类型	默认值	说明
routeFilePrefix	string	undefined	路由文件的前缀筛选器
routeFileIgnorePrefix	string	'-'	从路由中排除文件的前缀
routeFileIgnorePattern	string	undefined	从路由中排除文件的模式
indexToken	string | RegExp | { regex: string; flags?: string }	'index'	用于标识索引路由的标记
routeToken	string | RegExp | { regex: string; flags?: string }	'route'	用于标识路由配置文件的标记

代码拆分选项

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
    },
  },
})

输出选项

选项	类型	默认值	说明
quoteStyle	'single' | 'double'	'single'	生成代码中的引号样式
semicolons	boolean	false	在生成代码中使用分号
disableTypes	boolean	false	禁用 TypeScript 类型
disableLogging	boolean	false	禁止输出插件日志
addExtensions	boolean | string	false	为导入路径添加文件扩展名
enableRouteTreeFormatting	boolean	true	格式化生成的路由树

虚拟路由配置

import { routes } from './routes'

tanstackRouter({
  target: 'react',
  virtualRouteConfig: routes, // or './routes.ts'
})

工作原理

组合插件最多由 3 个子插件组成：

1. 路由生成器（始终启用）——监视路由文件并生成 routeTree.gen.ts
2. 代码拆分器（当 autoCodeSplitting: true 时启用）——使用虚拟模块将路由文件拆分为延迟加载的代码块
3. HMR（开发模式下，代码拆分器关闭时启用）——热重载路由变更，无需完全刷新

路由重构工作流

移动、重命名、添加或删除文件路由时：

1. 修改 routesDirectory 下的源文件。导出的路由标识符名称保持为 Route。
2. 让打包器插件重新生成路由树；如果项目使用 CLI，则运行 pnpm exec tsr generate。
3. 检查生成的差异，确认路由 ID、父级、路径和导入符合预期。切勿手动修复 routeTree.gen.ts。
4. 更新引用旧路由的链接、重定向、from 窄化、参数、预加载调用和测试。
5. 运行路由生成测试、类型测试和生产构建。编辑器类型检查通过，并不能证明插件已正确生成新路由或将其拆分。

提交 routeTree.gen.ts；它是应用在运行时使用的生成源文件。

单独导出的插件

如需高级用法，可从 Vite 入口分别导出每个子插件：

import {
  tanstackRouter, // Composed (default)
  tanstackRouterGenerator, // Generator only
  tanStackRouterCodeSplitter, // Code splitter only
} from '@tanstack/router-plugin/vite'

常见错误

1. 严重：Vite 配置中的插件顺序错误

路由器插件必须位于框架插件之前。否则，路由生成和代码拆分会静默失败。

// WRONG — react() before tanstackRouter()
plugins: [react(), tanstackRouter({ target: 'react' })]

// CORRECT — tanstackRouter() first
plugins: [tanstackRouter({ target: 'react' }), react()]

2. 高：非 React 框架缺少 target 选项

target 的默认值为 'react'。对于 Solid 或 Vue，必须显式设置该选项。

// WRONG for Solid — generates React imports
tanstackRouter({ autoCodeSplitting: true })

// CORRECT for Solid
tanstackRouter({ target: 'solid', autoCodeSplitting: true })

3. 中：混淆 autoCodeSplitting 和手动惰性路由

启用 autoCodeSplitting 后，插件会自动处理代码拆分。你无需手动调用 createLazyRoute 或 lazyRouteComponent——插件会在构建时转换路由文件。

// WRONG — manual lazy loading with autoCodeSplitting enabled
const LazyAbout = lazyRouteComponent(() => import('./about'))

// CORRECT — just write normal route files, plugin handles splitting
// src/routes/about.tsx
export const Route = createFileRoute('/about')({
  component: AboutPage,
})

function AboutPage() {
  return <h1>About</h1>
}

4. 高：编辑生成的路由树

对 routeTree.gen.ts 的修改会被覆盖，还可能导致源路由、生成的类型和运行时路由不一致。应修正路由文件名或插件配置，然后重新生成并检查生成的差异。

交叉引用

• @tanstack/router-core#router-core/code-splitting — 手动代码拆分概念
• @tanstack/virtual-file-routes#virtual-file-routes — 以编程方式构建路由树