tanstack-query

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

TanStack Query v5 アプリケーション向けの包括的なパフォーマンス最適化ガイドです。自動リファクタリングとコード生成の指針となるよう、影響度順に優先順位付けした 8 カテゴリ、40 のルールを収録しています。

適用するタイミング

次のような場合に、これらのガイドラインを参照してください。

• 新しいクエリ、ミューテーション、またはデータ取得ロジックを作成するとき
• キャッシュ戦略（staleTime、gcTime）を実装するとき
• パフォーマンスの問題やリクエストのウォーターフォールについてコードをレビューするとき
• 既存の TanStack Query コードをリファクタリングするとき
• 無限クエリ、Suspense、または楽観的更新を実装するとき

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

優先度	カテゴリ	影響度	プレフィックス
1	クエリキーの構造	CRITICAL	tquery-
2	キャッシュ設定	CRITICAL	cache-
3	ミューテーションのパターン	HIGH	mutation-
4	プリフェッチとウォーターフォール	HIGH	prefetch-
5	無限クエリ	MEDIUM	infinite-
6	Suspense の統合	MEDIUM	suspense-
7	エラーとリトライの処理	MEDIUM	error-
8	レンダリングの最適化	LOW-MEDIUM	render-

クイックリファレンス

1. クエリキーの構造（CRITICAL）

• tquery-key-factories - クエリキーのファクトリーを一元管理します
• tquery-hierarchical-keys - 汎用的なものから具体的なものへとキーを構成します
• tquery-always-arrays - クエリキーには常に配列を使用します
• tquery-serializable-objects - キーにはシリアライズ可能なオブジェクトを使用します
• tquery-options-pattern - 型安全に共有するには queryOptions を使用します
• tquery-colocate-keys - クエリキーを機能と同じ場所に配置します

2. キャッシュ設定（CRITICAL）

• cache-staletime-gctime - staleTime と gcTime の違いを理解します
• cache-global-defaults - グローバルなデフォルト値を適切に設定します
• cache-placeholder-vs-initial - placeholderData と initialData を正しく使い分けます
• cache-invalidation-precision - 正確に無効化します
• cache-refetch-triggers - 自動再取得のトリガーを制御します
• cache-enabled-option - 条件付きクエリには enabled を使用します

3. ミューテーションのパターン（HIGH）

• mutation-optimistic-updates - ロールバックを伴う楽観的更新を実装します
• mutation-invalidate-onsettled - onSuccess ではなく onSettled で無効化します
• mutation-cancel-queries - 楽観的更新の前にクエリをキャンセルします
• mutation-setquerydata - キャッシュを即座に更新するには setQueryData を使用します
• mutation-avoid-parallel - 同じデータへの並列ミューテーションを避けます

4. プリフェッチとウォーターフォール（HIGH）

• prefetch-avoid-waterfalls - リクエストのウォーターフォールを避けます
• prefetch-on-hover - 体感速度を高めるため、ホバー時にプリフェッチします
• prefetch-in-queryfn - queryFn で依存データをプリフェッチします
• prefetch-server-components - Server Components でプリフェッチします
• prefetch-flatten-api - API をフラット化してウォーターフォールを減らします

5. 無限クエリ（MEDIUM）

• infinite-max-pages - maxPages で無限クエリのページ数を制限します
• infinite-flatten-pages - レンダリング用にページをフラット化します
• infinite-refetch-behavior - 無限クエリの再取得時の動作を理解します
• infinite-loading-states - 無限クエリの読み込み状態を正しく処理します

6. Suspense の統合（MEDIUM）

• suspense-use-suspense-hooks - 読み込み状態を簡潔にするため、Suspense フックを使用します
• suspense-error-boundaries - Suspense には必ず Error Boundaries を組み合わせます
• suspense-parallel-queries - useSuspenseQueries で Suspense クエリを組み合わせます
• suspense-boundaries-placement - Suspense 境界を適切な位置に配置します

7. エラーとリトライの処理（MEDIUM）

• error-retry-config - 指数バックオフを使用してリトライを設定します
• error-conditional-retry - エラーの種類に基づく条件付きリトライを使用します
• error-global-handler - よくあるエラーにはグローバルエラーハンドラーを使用します
• error-display-patterns - エラーを適切に表示します
• error-throw-on-error - Error Boundaries とともに throwOnError を使用します

8. レンダリングの最適化（LOW-MEDIUM）

• render-select-memoize - select 関数をメモ化する
• render-select-derived - select を使用してデータを導出し、再レンダリングを減らす
• render-notify-props - notifyOnChangeProps を使用して再レンダリングを制限する
• render-structural-sharing - 構造共有について理解する
• render-tracked-props - すべてのプロパティを分割代入するのを避ける

使用方法

詳しい説明とコード例については、個別のリファレンスファイルをお読みください。

• セクションの定義 - カテゴリー構成と影響レベル
• リファレンスファイル：references/{prefix}-{slug}.md

各リファレンスファイルには、以下が含まれています。

• 重要な理由についての簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加の背景情報と参考資料

関連スキル

• 型安全なクエリフックを生成するには、orval スキルをご覧ください
• テストで API レスポンスをモックするには、test-msw スキルをご覧ください
• React 19 のデータ取得パターンについては、react-19 スキルをご覧ください

コンパイル済みドキュメント全文

すべてのルールを展開した完全なガイドについては、AGENTS.md をご覧ください。