react-tanstack-router

React SPA（Vite/Webpack/Rspack、Next.js ではない）向けに TanStack Router を実装します。自動生成される型安全性を備えたファイルベースルーティング、動的ルートパラメータ（`$postId`）、Zod/Valibot による search-params バリデーション、TanStack Query（`ensureQueryData`）と統合されたローダー（`Route.useLoaderData()`）、`Outlet` を用いたネストされたレイアウト、依存性注入のためのルートコンテキスト、`beforeLoad` ガードによる保護されたルート、intent/render 時のプリロードを扱います。

SOLID に基づくモジュール構成全体（modules/cores/lib/router/、interfaces//queries//components/ を備えた機能モジュール）、React Router からの移行（useParams()→Route.useParams()、loader→loader オプション）、エラーバウンダリ/404 処理をカバーします。状態管理（react-state）やフォーム（react-forms）はカバーしません — これらは別のスキルです。Next.js のルーティングには App Router（nextjs-16）を使用してください。このスキルではありません。

TanStack Router

ファイルベースルーティング、ローダー、search params バリデーション、TanStack Query との深い統合を備えた、React 向けの 100% 型安全なルーターです。

エージェントワークフロー（必須）

実装の前に、必ず 3 つのエージェントを並列で起動してください。それぞれ name を指定した Agent 呼び出し 1 回ずつです。

1. fuse-ai-pilot:explore-codebase - 既存のルートとナビゲーションパターンを分析する
2. fuse-ai-pilot:research-expert - Context7/Exa 経由で最新の TanStack Router ドキュメントを検証する
3. mcp__context7__query-docs - ファイルベースルーティングと型安全なパターンを確認する

実装後は、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

なぜ TanStack Router なのか？

TanStack Router は、search params バリデーションを伴う型安全なルーティングを必要とする React SPA に推奨される選択肢です。

機能	TanStack Router	React Router v7
型安全性	完全な推論	自動生成
ファイルベースルーティング	組み込み	フレームワークモード
Search Params バリデーション	Zod、Valibot	手動
プリロード	Intent、render	限定的
TanStack Query 統合	ネイティブ	手動

使用する場面

• Vite、Webpack、または Rspack を使った React SPA → installation.md を参照
• 型安全なルーティングが必要 → typescript.md を参照
• Search params バリデーションが必要 → search-params.md を参照
• データ取得に TanStack Query を使用 → tanstack-query.md を参照
• Next.js ではない（代わりに App Router を使用）

---

重要なルール

1. 常にファイルベースルーティングを使用する - 自動生成される型安全性 → file-based-routing.md
2. 常に search params をバリデーションする - Zod v4 スキーマを validateSearch に直接渡す（zodValidator は Zod v3 のみ） → search-params.md
3. 常に Route.useLoaderData() を使用する - グローバルの useLoaderData ではなく → hooks.md
4. 常にルーターの型を登録する - declare module '@tanstack/react-router' → typescript.md
5. useEffect よりもローダーを優先する - レンダリング前のデータ取得 → loaders.md
6. TanStack Query を統合する - キャッシュ、ミューテーション、楽観的更新のために → tanstack-query.md
7. SOLID アーキテクチャに従う - モジュール、インターフェース、ファイルサイズ制限 → solid-react skill

---

クイックリファレンス: 何を読むべきか

新しいプロジェクトを始める

1. 設定のために installation.md を読む
2. ベースとしてテンプレート basic-setup.md をコピーする

機能モジュール（posts、users など）を作成する

1. templates/feature-module.md のアーキテクチャに従う
2. クエリには tanstack-query.md のパターンを使用する

認証を実装する

1. 概念については auth-guards.md を読む
2. テンプレート auth-protected-routes.md をコピーする

フィルター/検索付きページの作成

1. Zod バリデーションについて search-params.md を読む
2. テンプレート search-filters.md をコピーする

ネストされたレイアウトを持つダッシュボードの作成

1. 概念について nested-routes.md を読む
2. テンプレート dashboard-layout.md をコピーする

---

プロジェクト構造（SOLID アーキテクチャ）

solid-react スキルの SOLID 原則に従った推奨構造です。

src/
├── modules/
│   ├── cores/                      # Shared between features
│   │   ├── lib/
│   │   │   ├── router/router.ts    # Router configuration
│   │   │   └── query/client.ts     # QueryClient configuration
│   │   ├── components/layouts/     # Shared layouts
│   │   └── interfaces/             # Shared types
│   └── [feature]/                  # Feature module
│       ├── src/
│       │   ├── interfaces/         # Module types
│       │   ├── queries/            # TanStack Query options
│       │   └── components/         # Module components
│       └── index.ts                # Public exports
├── routes/                         # Route definitions ONLY
│   ├── __root.tsx
│   └── [feature]/
└── routeTree.gen.ts               # Auto-generated (DO NOT MODIFY)

完全なテンプレート: templates/basic-setup.md

---

リファレンスガイド

概念（references/）- 概念に関するドキュメント

トピック	リファレンス	参照すべきタイミング
セットアップ	installation.md	Vite/Webpack の設定、React Router の移行
ファイルルーティング	file-based-routing.md	命名規則、routes/ の構造
URL パラメータ	route-params.md	動的ルート $postId、パース
検索パラメータ	search-params.md	Zod バリデーション、URL フィルター、ページネーション
データ読み込み	loaders.md	ローダー、プリフェッチ、TanStack Query の統合
ナビゲーション	navigation.md	Link、useNavigate、リダイレクト
コンテキスト	route-context.md	依存性注入、QueryClient、ユーザー
レイアウト	nested-routes.md	ネストされたレイアウト、Outlet、パスなしルート
エラー	error-handling.md	エラーバウンダリ、404、保留状態
遅延読み込み	code-splitting.md	コード分割、バンドル最適化
プリロード	preloading.md	プリロードの意図/レンダリング、プリフェッチ
認証	auth-guards.md	保護されたルート、RBAC、ログインリダイレクト
TanStack Query	tanstack-query.md	queryOptions、ミューテーション、キャッシュ
SSR	ssr.md	サーバーサイドレンダリング、TanStack Start
TypeScript	typescript.md	型登録、型推論、型安全性
DevTools	devtools.md	Router DevTools のセットアップ
Hooks API	hooks.md	useParams、useSearch、useNavigate など
コンポーネント	components.md	Link、Outlet、Navigate、RouterProvider

テンプレート（references/templates/）- コピー&ペースト可能な完全なコード

テンプレート	使用するタイミング
basic-setup.md	SOLID アーキテクチャで新しいプロジェクトを開始する
feature-module.md	完全なフィーチャーモジュール（インターフェース、クエリ、コンポーネント）を作成する
auth-protected-routes.md	ログイン、保護されたルート、RBAC を実装する
search-filters.md	URL フィルター、ページネーション、ソートを備えたページ
dashboard-layout.md	サイドバー、タブ、ネストされたレイアウトを備えたダッシュボード

---

コアパターン

1. コンテキストを持つルートルート

依存性注入のためのルーターコンテキスト設定。

// src/routes/__root.tsx
export const Route = createRootRouteWithContext<RouterContext>()({
  component: RootComponent,
})

詳細: route-context.md テンプレート: templates/basic-setup.md

2. ローダーと TanStack Query を持つファイルルート

キャッシュを伴うデータ読み込みの推奨パターン。

// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: ({ context: { queryClient }, params }) =>
    queryClient.ensureQueryData(postQueryOptions(params.postId)),
  component: PostPage,
})

詳細: loaders.md、tanstack-query.md テンプレート: templates/feature-module.md

3. Zod バリデーションによる検索パラメータ

URL 経由の型安全なフィルターとページネーション。

// src/routes/posts/index.tsx
const searchSchema = z.object({
  page: z.number().min(1).default(1),
  sort: z.enum(['newest', 'oldest']).default('newest'),
})

export const Route = createFileRoute('/posts/')({
  validateSearch: searchSchema, // Zod v4 = Standard Schema, no adapter
})

詳細: search-params.md テンプレート: templates/search-filters.md

4. 保護されたルート

リダイレクトを伴う認証ガード。

// src/routes/_authenticated/_authenticated.tsx
export const Route = createFileRoute('/_authenticated')({
  beforeLoad: ({ context, location }) => {
    if (!context.user) {
      throw redirect({ to: '/login', search: { redirect: location.href } })
    }
  },
})

詳細: auth-guards.md テンプレート: templates/auth-protected-routes.md

5. Outlet を使ったネストされたレイアウト

ダッシュボード向けのネストされたレイアウト。

// src/routes/_dashboard/_dashboard.tsx
export const Route = createFileRoute('/_dashboard')({
  component: () => (
    <DashboardLayout>
      <Outlet />
    </DashboardLayout>
  ),
})

詳細: nested-routes.md テンプレート: templates/dashboard-layout.md

---

ベストプラクティス

推奨事項

パターン	参照
Route API (Route.useParams()) を使用する	hooks.md
Zod で検索パラメータをバリデーションする	search-params.md
ローダーで ensureQueryData を使用する	tanstack-query.md
リンクの意図に基づいてプリロードする	preloading.md
インターフェースを interfaces/ で分離する	solid-react skill

非推奨事項

アンチパターン	理由	代替手段
from を指定しない useLoaderData()	型安全ではない	Route.useLoaderData()
フェッチに useEffect を使用する	最適ではない	ローダーを使用する
検索パラメータをミューテートする	イミュータビリティ	navigate({ search: {...} })
エラーバウンダリを省略する	UX の低下	errorComponent を追加する
コンポーネント内にインターフェースを置く	結合	interfaces/ フォルダー

---

React Router からの移行

完全な移行ガイドについては installation.md を参照してください。

React Router	TanStack Router
useParams()	Route.useParams()
useSearchParams()	Route.useSearch()
useLoaderData()	Route.useLoaderData()
loader 関数	loader オプション
action 関数	TanStack Query のミューテーション

---

バージョン履歴

• v1.x - 頻繁なリリース（インクリメンタルなバージョニング）
• 主なマイルストーン: Head/meta タグ、検索パラメータミドルウェア、Zod アダプター