tanstack-router

TanStack Router

TanStack Router に関わる作業、特に @tanstack/react-router、src/routes/**、src/router.tsx、ルートツリーの生成、型安全なナビゲーション、ルートが所有するデータ読み込みに関わる場合は、このスキルを使用してください。

ワークフロー

1. まず、ローカルの Router 構成を確認します。
   • @tanstack/react-router、@tanstack/router-plugin、開発者ツール、アダプター、Query／SSR 統合のパッケージバージョン。
   • ルーティング方式：ファイルベース、コードベース、仮想ファイルルート、または混在。
   • ルートのエントリーポイント：src/routes/__root.tsx、src/router.tsx、生成された src/routeTree.gen.ts、アプリ／クライアントのエントリー、存在する場合は SSR エントリー。
   • 動作に影響するルートオプション：validateSearch、params、beforeLoad、loaderDeps、loader、pendingComponent、errorComponent、notFoundComponent、search.middlewares、staleTime、gcTime、preload、SSR 統合。
2. 現在の動作、新しいバージョン、SSR、テスト、ルート生成、または移行については、ドキュメントを確認します。source-map.md から始めてください。
3. セットアップ、インストール、ルートツリー生成、ファイル名、ルートの隣への非ルートモジュール（-components、-hooks、-lib、…）の配置については、setup-route-trees.md を使用してください。
4. リンク、ナビゲーション、パラメーター、検索パラメーター、マスク、URL の状態については、navigation-url-state.md を使用してください。
5. ローダー、コンテキスト、認証ガード、Query 統合、エラー／Not Found 境界、プリロード、遅延データについては、loaders-context-errors.md を使用してください。
6. SSR、デプロイ時のリライト、テスト、開発者ツール、ESLint、本番環境でのチェックについては、production-testing.md を使用してください。

実装上の判断

• リポジトリがすでにコードベースのルートを使用している場合、またはユーザーから別途指定がある場合を除き、ファイルベースのルーティングを優先してください。
• routeTree.gen.ts は生成物として扱ってください。手動で編集せず、リポジトリのバンドラー／CLI フローを通じて再生成してください。
• ルートが所有する UI／フック／ヘルパーは、ハイフンで始まるフォルダー（routeFileIgnorePrefix、デフォルトは -）にまとめてください。routes/ の下にハイフンで始まらない非ルートファイルを置かないでください。
• ナビゲーションの型を維持してください。to にパラメーターやクエリー文字列を補間してパスを組み立てないでください。to、params、search、hash は個別に渡してください。
• URL の検索状態を読み取るすべてのルートで validateSearch を宣言してください。ローダーが実際に使用する検索フィールドのみを公開するために loaderDeps を使用してください。
• ルートの UX に関するゲート、リダイレクト、コンテキストの拡張には beforeLoad を使用してください。ルートガードを、非公開データの認可境界として扱わないでください。
• ルート間で共有する依存関係はルーターコンテキストに置いてください。beforeLoad や loader 内で React フックを直接呼び出さないでください。
• Router 組み込みの SWR ローダーキャッシュと、TanStack Query などの外部キャッシュのどちらを使うか、明示的に決定してください。Query が鮮度を管理する場合は、ルーターのプリロードの stale time を 0 に設定し、重複排除は Query に任せてください。Query 5.102 以降では、queryClient.query(...) を使って読み込んでください。ensureQueryData／prefetchQuery／fetchQuery は非推奨です。
• React の errorComponent／onCatch エラーは unknown として型付けし、message を読み取る前に型を絞り込んでください。
• ローダーデータの型を正しく保ち、UI のちらつきを避けるため、Not Found のリソースはローダー内で notFound() を使って処理してください。

検証

リポジトリに既存のチェックがあれば、それを優先してください。重要な Router の変更では、関連する項目を実施してください。

• 開発／ビルド、または Router CLI コマンドを明示的に実行してルートツリーを生成する。
• ルート参照、パラメーター、検索、ローダー、コンテキストについて型チェックする。
• ルートのマッチング、検索値の検証、ローダー、認証リダイレクト、Not Found／エラー境界、ナビゲーションを対象としたテストを行う。
• 直接読み込み、クライアントナビゲーション、戻る／進む、更新、本番環境でのリライト動作をブラウザーでスモークテストする。