react-query-best-practices

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

重要: このガイドは React Query v4 を対象としています。パターンによっては v5 で異なる場合があります。

TkDodo の信頼性の高いブログシリーズに基づく、React Query v4（TanStack Query）の包括的なガイドです。影響度順に分類された 7 カテゴリ、24 のルールが含まれています。

適用するタイミング

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

• 新しいクエリやミューテーションを実装するとき
• React Query に WebSocket を統合するとき
• クエリの無効化パターンを設定するとき
• React Query の動作をデバッグするとき
• レンダリングのパフォーマンスを最適化するとき
• TypeScript との統合に関する質問があるとき

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

優先度	カテゴリ	影響度	プレフィックス
1	クエリキーとパターン	CRITICAL	query-
2	ミューテーションと更新	CRITICAL	mutation-
3	キャッシュ戦略	HIGH	cache-
4	WebSocket の統合	HIGH	websocket-
5	TypeScript との統合	MEDIUM	typescript-
6	テストパターン	MEDIUM	testing-
7	よくある落とし穴	MEDIUM	troubleshoot-
8	v5 への移行	HIGH	migration-

クイックリファレンス

1. クエリキーとパターン（CRITICAL）

• query-keys-as-dependencies - すべての queryFn のパラメーターを queryKey に含める
• query-key-factory - キーを一貫して生成するためにファクトリーパターンを使用する
• query-select-transforms - データ変換には select オプションを使用する
• query-status-check-order - まずデータ、次にエラー、最後に読み込み状態を確認する
• query-tracked-properties - 使用するプロパティのみを分割代入する
• query-placeholder-vs-initial - それぞれのアプローチを使うタイミングを把握する
• query-dependent-enabled - 依存するクエリには enabled オプションを使用する

2. ミューテーションと更新（CRITICAL）

• mutation-prefer-mutate - mutateAsync() より、コールバックを使う mutate() を使用する
• mutation-invalidation - ミューテーション後にクエリを無効化する
• mutation-direct-cache-update - 適切な場合はキャッシュを直接更新する
• mutation-optimistic-updates - 成功をすぐに表示し、失敗時にはロールバックする
• mutation-callback-separation - クエリのロジックはフックに、UI の効果はコンポーネントに記述する

3. キャッシュ戦略（HIGH）

• cache-stale-time - ドメインに適した staleTime を設定する
• cache-refetch-triggers - 本番環境では再取得のトリガーを有効にしておく

4. WebSocket の統合（HIGH）

• websocket-event-invalidation - イベントを使って無効化をトリガーする
• websocket-stale-time-infinity - WS で管理するデータには staleTime: Infinity を設定する
• websocket-reconnection - 再接続時に古いクエリを無効化する

5. TypeScript との統合（MEDIUM）

• typescript-infer-dont-specify - TypeScript の型推論に任せ、queryFn に型を付ける
• typescript-zod-validation - 実行時の検証には Zod を使用する

6. テストパターン（MEDIUM）

• testing-fresh-client - テストごとに新しい QueryClient を作成する
• testing-msw-mocking - ネットワークのモックには MSW を使用する

7. よくある落とし穴（MEDIUM）

• troubleshoot-copy-to-state - クエリデータをローカル状態にコピーしない
• troubleshoot-missing-key-deps - すべての依存関係をクエリキーに含める
• troubleshoot-fetch-not-reject - fetch で HTTP エラーを処理する

8. v5 への移行（重要）

• migration-single-signature - すべてのフックが単一のオブジェクト引数を取るようになりました
• migration-status-pending - status の 'loading' が 'pending' に変更され、isLoading のセマンティクスも変更されました
• migration-cache-time-to-gc-time - cacheTime が gcTime に改名されました
• migration-keep-previous-data - keepPreviousData が、identity 関数を使う placeholderData に変更されました
• migration-query-callbacks-removed - useQuery から onSuccess/onError/onSettled が削除されました
• migration-suspense-hooks - 新しい useSuspenseQuery、useSuspenseInfiniteQuery フックが追加されました
• migration-throw-on-error - useErrorBoundary が throwOnError に改名されました
• migration-remove-method - query.remove() が削除されました。queryClient.removeQueries() を使用してください
• migration-initial-page-param - infinite query で initialPageParam が必須になりました
• migration-refetch-page-to-max-pages - refetchPage が maxPages に置き換えられました
• migration-hydration-boundary - Hydrate コンポーネントが HydrationBoundary に改名されました
• migration-refetch-interval-callback - refetchInterval コールバックが受け取るのは query のみになりました
• migration-context-to-query-client - context prop が削除されました。queryClient を直接渡してください
• migration-misc-breaking-changes - React 18 が最低要件になり、サーバーでの retry=0、hashKey、isDataEqual などが変更されました

基本的な考え方

1. React Query はデータ取得ライブラリではありません - 非同期状態マネージャーです
2. サーバー状態 ≠ クライアント状態 - グローバル状態マネージャーで両者を混在させないでください
3. Stale-while-revalidate - キャッシュ済みデータをすぐに表示し、バックグラウンドで取得します
4. クエリキーは依存関係です - queryFn で使うすべての変数を含めてください

使用方法

詳しい説明とコード例については、各ルールファイルを参照してください。

rules/query-key-factory.md
rules/mutation-invalidation.md
rules/websocket-event-invalidation.md

各ルールファイルには、次の内容が含まれています。

• 重要な理由の簡潔な説明
• 誤ったコード例
• 正しいコード例

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

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