router-plugin

Router Plugin（@tanstack/router-plugin）

TanStack Router のファイルベースルーティングと自動コード分割を実現するバンドラープラグインです。unplugin を介して Vite、Webpack、Rspack、esbuild で動作します。

CRITICAL：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 — プログラムによるルートツリー