tanstack-router-best-practices

TanStack Router のベストプラクティス

React アプリケーションに TanStack Router のパターンを実装するための包括的なガイドラインです。これらのルールにより、型安全性、データ読み込み、ナビゲーション、コード構成を最適化できます。

適用するタイミング

• アプリケーションのルーティングを設定するとき
• 新しいルートやレイアウトを作成するとき
• 検索パラメーターの処理を実装するとき
• データローダーを設定するとき
• コード分割を設定するとき
• TanStack Query と連携するとき
• ナビゲーションパターンをリファクタリングするとき

優先度別のルールカテゴリ

優先度	カテゴリ	ルール	効果
CRITICAL	型安全性	4 rules	実行時エラーを防ぎ、リファクタリングを可能にします
CRITICAL	ルート構成	5 rules	保守しやすいルート構造を実現します
HIGH	ルーター設定	1 rule	グローバルなルーターのデフォルト設定
HIGH	データ読み込み	6 rules	データ取得とキャッシュを最適化します
HIGH	検索パラメーター	5 rules	型安全な URL の状態管理を可能にします
HIGH	エラー処理	1 rule	404 やエラーを適切に処理します
MEDIUM	ナビゲーション	5 rules	UX とアクセシビリティを向上させます
MEDIUM	コード分割	3 rules	バンドルサイズを削減します
MEDIUM	プリロード	3 rules	体感パフォーマンスを向上させます
LOW	ルートコンテキスト	3 rules	依存性注入を可能にします

クイックリファレンス

型安全性（プレフィックス：ts-）

• ts-register-router — グローバルな型推論のためにルーター型を登録する
• ts-use-from-param — 型の絞り込みに from パラメーターを使用する
• ts-route-context-typing — createRootRouteWithContext でルートコンテキストに型を付ける
• ts-query-options-loader — 型推論のためにローダーで queryOptions を使用する

ルーター設定（プレフィックス：router-）

• router-default-options — ルーターのデフォルト設定を行う（scrollRestoration、defaultErrorComponent など）

ルート構成（プレフィックス：org-）

• org-file-based-routing — 規約に沿うためにファイルベースルーティングを優先する
• org-route-tree-structure — 階層的なルートツリーのパターンに従う
• org-pathless-layouts — 共通レイアウトにパスレスルートを使用する
• org-index-routes — インデックスルートとレイアウトルートを理解する
• org-virtual-routes — 仮想ファイルルートを理解する

データ読み込み（プレフィックス：load-）

• load-use-loaders — データ取得にルートローダーを使用する
• load-loader-deps — キャッシュ制御のために loaderDeps を定義する
• load-ensure-query-data — TanStack Query とともに ensureQueryData を使用する
• load-deferred-data — 重要なデータと重要でないデータを分割する
• load-error-handling — ローダーのエラーを適切に処理する
• load-parallel — 並列ルート読み込みを活用する

検索パラメーター（プレフィックス：search-）

• search-validation — 検索パラメーターは必ず検証する
• search-type-inheritance — 親の検索パラメーター型を活用する
• search-middleware — 検索パラメーターのミドルウェアを使用する
• search-defaults — 適切なデフォルト値を設定する
• search-custom-serializer — カスタム検索パラメーターシリアライザーを設定する

エラー処理（プレフィックス：err-）

• err-not-found — 見つからないルートを適切に処理する

ナビゲーション（プレフィックス：nav-）

• nav-link-component — ナビゲーションには Link コンポーネントを優先する
• nav-active-states — アクティブリンクの状態を設定する
• nav-use-navigate — プログラムによるナビゲーションには useNavigate を使用する
• nav-relative-paths — 相対パスによるナビゲーションを理解する
• nav-route-masks — モーダル URL にルートマスクを使用する

コード分割（プレフィックス：split-）

• split-lazy-routes — コード分割に .lazy.tsx を使用する
• split-critical-path — 重要な設定はメインのルートファイルに保持する
• split-auto-splitting — 可能な場合は autoCodeSplitting を有効にする

事前読み込み（プレフィックス：preload-）

• preload-intent — 意図に基づく事前読み込みを有効にする
• preload-stale-time — 事前読み込みの有効期限を設定する
• preload-manual — 手動で戦略的に事前読み込みを行う

ルートコンテキスト（プレフィックス：ctx-）

• ctx-root-context — ルートでコンテキストを定義する
• ctx-before-load — beforeLoad でコンテキストを拡張する
• ctx-dependency-injection — 依存性注入にコンテキストを使用する

使用方法

rules/ ディレクトリ内の各ルールファイルには、次の内容が含まれています。

1. 説明 — このパターンが重要な理由
2. 悪い例 — 避けるべきアンチパターン
3. 良い例 — 推奨される実装
4. コンテキスト — このルールを適用する状況、または適用しない状況

全リファレンス

詳しいガイダンスとコード例については、rules/ ディレクトリ内の個々のルールファイルを参照してください。