tanstack-query

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

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

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• 新しいクエリ、ミューテーション、データ取得ロジックを記述する場合
• キャッシュ戦略（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 または skipToken を使用する

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

• mutation-optimistic-updates - ロールバックに対応した楽観的更新を実装する
• mutation-invalidate-onsettled - ミューテーションの契約に応じて無効化コールバックを選択する
• mutation-cancel-queries - 楽観的更新の前にクエリをキャンセルする
• mutation-setquerydata - キャッシュを即座に更新するには setQueryData を使用する
• mutation-avoid-parallel - 同じデータに対する並列ミューテーションを避ける

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

• prefetch-avoid-waterfalls - リクエストのウォーターフォールを避ける
• prefetch-on-hover - 体感速度を高めるためにホバー時にプリフェッチする
• prefetch-in-queryfn - キーが判明した時点で後続のプリフェッチを開始する
• prefetch-server-components - Server Components でプリフェッチする
• prefetch-infinite-query - queryClient.infiniteQuery (5.102+) で無限リストをプリフェッチする
• 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 Boundary と組み合わせる
• suspense-parallel-queries - Suspense クエリを useSuspenseQueries と組み合わせる
• suspense-boundaries-placement - Suspense Boundary を戦略的に配置する

7. エラーと再試行の処理（MEDIUM）

• error-retry-config - 指数バックオフを用いて再試行を設定する
• error-conditional-retry - エラーの種類に応じた条件付き再試行を使用する
• error-global-handler - 共通エラーにはグローバルエラーハンドラーを使用する
• error-display-patterns - エラーを適切に表示する
• error-throw-on-error - Error Boundary とともに throwOnError を使用する

8. レンダリングの最適化（低〜中）

• render-select-memoize - select 関数をメモ化する
• render-select-derived - select を使ってデータを導出し、再レンダリングを減らす
• render-notify-props - notifyOnChangeProps よりも追跡対象プロパティを優先する
• render-structural-sharing - 構造的共有について理解する
• render-tracked-props - 追跡対象プロパティによる最適化を維持する

使用方法

まずプロジェクトのルートで実行します。

npx -y @pymodel/react-frontend-skills detect                       # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill tanstack-query  # deprecated APIs → rule IDs

上記のルールのうちタスクに該当するものと、scan で検出された項目ごとに references/<rule-id>.md を読み、重要な理由と誤ったコード・正しいコードを確認してください。

関連スキル

• テストで API レスポンスをモックする方法については、msw スキルを参照してください
• React 19 のデータ取得パターンについては、react スキルを参照してください