tanstack-query-best-practices

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

React アプリケーションで TanStack Query（React Query）のパターンを実装するための包括的なガイドラインです。これらのルールは、データ取得、キャッシュ、ミューテーション、サーバー状態の同期を最適化します。

適用するタイミング

• 新しいデータ取得ロジックを作成するとき
• クエリ設定を行うとき
• ミューテーションと楽観的更新を実装するとき
• キャッシュ戦略を設定するとき
• SSR/SSG と統合するとき
• 既存のデータ取得コードをリファクタリングするとき

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

優先度	カテゴリ	ルール	影響
CRITICAL	クエリキー	5 ルール	キャッシュの不具合やデータの不整合を防ぎます
CRITICAL	キャッシュ	5 ルール	パフォーマンスとデータの鮮度を最適化します
HIGH	ミューテーション	6 ルール	データの整合性と UI の一貫性を確保します
HIGH	エラー処理	3 ルール	ユーザー体験の低下を防ぎます
MEDIUM	プリフェッチ	4 ルール	体感パフォーマンスを向上させます
MEDIUM	並列クエリ	2 ルール	動的な並列データ取得を可能にします
MEDIUM	無限クエリ	3 ルール	ページネーションの不具合を防ぎます
MEDIUM	SSR 統合	4 ルール	適切なハイドレーションを可能にします
LOW	パフォーマンス	4 ルール	不要な再レンダリングを減らします
LOW	オフラインサポート	2 ルール	オフラインファーストのパターンを可能にします

クイックリファレンス

クエリキー（プレフィックス：qk-）

• qk-array-structure — クエリキーには常に配列を使用します
• qk-include-dependencies — クエリが依存するすべての変数を含めます
• qk-hierarchical-organization — キーを階層的に整理します（エンティティ → ID → フィルター）
• qk-factory-pattern — 複雑なアプリケーションではクエリキーファクトリーを使用します
• qk-serializable — すべてのキー要素が JSON シリアライズ可能であることを確認します

キャッシュ（プレフィックス：cache-）

• cache-stale-time — データの変動性に応じて適切な staleTime を設定します
• cache-gc-time — 非アクティブなクエリを保持する gcTime を設定します
• cache-defaults — QueryClient レベルで適切なデフォルト値を設定します
• cache-invalidation — 広範なパターンよりも対象を絞った無効化を使用します
• cache-placeholder-vs-initial — placeholder データと initial データの違いを理解します

ミューテーション（プレフィックス：mut-）

• mut-invalidate-queries — ミューテーション後は、関連するクエリを必ず無効化します
• mut-optimistic-updates — 応答性の高い UI を実現するため、楽観的更新を実装します
• mut-rollback-context — onMutate からロールバック用のコンテキストを渡します
• mut-error-handling — ミューテーションのエラーを適切に処理します
• mut-loading-states — ミューテーションの読み込み状態には isPending を使用します
• mut-mutation-state — コンポーネント間で状態を追跡するには useMutationState を使用します

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

• err-error-boundaries — useQueryErrorResetBoundary とエラーバウンダリーを使用します
• err-retry-config — リトライロジックを適切に設定します
• err-fallback-data — 適切な場合はフォールバックデータを提供します

プリフェッチ（プレフィックス：pf-）

• pf-intent-prefetch — ユーザーの操作意図（ホバー、フォーカス）に応じてプリフェッチします
• pf-route-prefetch — ルート遷移中にデータをプリフェッチします
• pf-stale-time-config — プリフェッチ時に staleTime を設定します
• pf-ensure-query-data — 条件付きのプリフェッチには ensureQueryData を使用します

無限クエリ（プレフィックス：inf-）

• inf-page-params — 必ず getNextPageParam を指定します
• inf-loading-guards — 追加データを取得する前に isFetchingNextPage を確認します
• inf-max-pages — 大規模なデータセットでは maxPages の使用を検討します

SSR 統合（プレフィックス：ssr-）

• ssr-dehydration — SSR では dehydrate/hydrate パターンを使用します
• ssr-client-per-request — リクエストごとに QueryClient を作成します
• ssr-stale-time-server — サーバーでは staleTime を長めに設定します
• ssr-hydration-boundary — HydrationBoundary でラップします

並列クエリ（プレフィックス：parallel-）

• parallel-use-queries — 動的な並列クエリには useQueries を使用します
• query-cancellation — クエリのキャンセルを適切に実装します

パフォーマンス (プレフィックス: perf-)

• perf-select-transform — select を使ってデータを変換/フィルタリングする
• perf-structural-sharing — 構造的共有を活用する
• perf-notify-change-props — notifyOnChangeProps で再レンダリングを制限する
• perf-placeholder-data — placeholderData を使って UI を即時表示する

オフラインサポート (プレフィックス: offline-)

• network-mode — オフラインサポート用にネットワークモードを設定する
• persist-queries — オフラインサポート用にクエリの永続化を設定する

使用方法

rules/ ディレクトリ内の各ルールファイルには以下が含まれます。

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

完全なリファレンス

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