tanstack-router-best-practices

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

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

適用する場面

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

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

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

クイックリファレンス

型安全性（プレフィックス：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 — プリロードの stale time を設定する
• preload-manual — 手動プリロードを戦略的に使用する

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

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

使い方

rules/ ディレクトリにある各ルールファイルには、以下が記載されています。

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

詳細リファレンス

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