tanstack-query

TanStack Query

TanStack Query v5 に関わる作業、特に @tanstack/react-query、サーバー状態のキャッシュ、クエリ／ミューテーションのライフサイクルに関する問題、SSR のハイドレーション、React Query／TanStack Query v4 からの移行では、このスキルを使用してください。

ワークフロー

1. コードを変更する前に、ローカルの Query の構成を確認します。
   • @tanstack/react-query、@tanstack/query-core、開発者ツール、永続化／ブロードキャストのパッケージ、ESLint プラグイン、React、フレームワークのルーター、テストユーティリティのパッケージバージョン。
   • プロバイダーの設定：QueryClient、QueryClientProvider、SSR のリクエストスコープ、デフォルトオプション、開発者ツール、永続化プロバイダー。
   • クエリの規約：クエリキーのファクトリー、queryOptions、mutationOptions、カスタムフック、ルーターローダー、SSR の事前取得、無効化ヘルパー。
   • 実行時の目的：クライアントのみでのフェッチ、サーバーでの事前取得とハイドレーション、ルートの事前読み込み、オフライン／永続化、または複数タブ間の同期。
2. 現在の動作、パッケージの差異、SSR、永続化、または移行についてドキュメントを確認します。source-map.md から始めてください。
3. インストール、プロバイダーの設定、デフォルト値、クエリキー、useQuery、TypeScript のオプションについては、setup-core.md を使用してください。
4. 依存クエリ、並列クエリ、ページネーション、無限クエリ、無効化可能なクエリ、キャンセル可能なクエリ、選択クエリ、パフォーマンスが重要なクエリについては、query-patterns.md を使用してください。
5. useMutation、無効化、キャッシュへの直接書き込み、楽観的更新、ミューテーションスコープ、オフラインミューテーションについては、mutations-cache.md を使用してください。
6. 事前取得、ルーター統合、SSR、ハイドレーション、Suspense、Server Components、ストリーミングに関する注意事項については、ssr-prefetching.md を使用してください。
7. 永続化、ブロードキャスト同期、開発者ツール、ESLint、テスト、移行の確認については、production-tooling.md を使用してください。

実装上の判断

• TanStack Query はサーバー状態の管理に使用し、ローカルなクライアント UI 状態の代替として扱わないでください。
• クエリキーはキャッシュの識別情報です。クエリ関数で使用する変更可能な変数をすべて含め、キーはシリアライズ可能な状態にしてください。
• v5 では、すべての箇所でオブジェクト構文を優先してください。v3／v4 の位置引数によるシグネチャを再導入しないでください。
• 再利用可能なクエリとミューテーションには、型付けされた queryOptions と mutationOptions のヘルパーを優先してください。
• 命令的な読み取りと事前取得には、queryClient.query ／ queryClient.infiniteQuery（v5.102 以降）を使用してください。fetchQuery、prefetchQuery、ensureQueryData とそれぞれの無限クエリ版は非推奨です。既存コードでは引き続き動作するようにしつつ、新たな呼び出しは追加しないでください。
• staleTime は意図を持って設定してください。デフォルトでは、古くなったデータはマウント時、ウィンドウフォーカス時、再接続時に再フェッチされます。これは適切な場合もありますが、仕組みを理解していないと不要な通信につながります。
• ミューテーション後は、対象を絞った無効化をデフォルトとして使用してください。ミューテーションのレスポンスに正確な更新済みオブジェクトが含まれている場合は、不変の setQueryData を使用してください。
• 楽観的更新では、保留中の状態が必要な箇所が 1 つだけなら、UI レベルの variables を優先してください。複数の箇所で反映が必要な場合は、キャッシュレベルの onMutate によるロールバックを使用してください。
• SSR では、サーバー上でリクエストごとのクエリクライアントを作成し、ブラウザーでは安定したクライアントを使用してください。ユーザー間でデータが漏れる可能性のある、モジュールレベルのサーバーキャッシュは避けてください。
• テストでは、各テストに専用の QueryClient を用意し、リトライを無効にして、キャッシュ状態を共有するのではなく、クライアントをクリアするか再作成してください。

検証

リポジトリに既存のチェックがある場合は、それを優先してください。TanStack Query に関わる重要な変更では、以下から該当するものを実施してください。

• クエリキー、クエリ関数の戻り値、select、ミューテーションの変数、SSR のハイドレーションに関する型チェック。
• 無効化、楽観的更新のロールバック、キャッシュの更新、依存クエリ、ページネーション、無限クエリ、エラー状態に関する対象を絞ったテスト。
• 読み込み、古いデータ、バックグラウンドフェッチ、ページネーション、ミューテーションの保留中／エラー状態、ハイドレーション、フォーカス／再接続時の動作に関するブラウザーのスモークテスト。
• 事前取得、ハイドレーション、古くなるまでの時間、またはプロバイダーの配置を変更する場合は、SSR またはルーターローダーのスモークテスト。
• リポジトリで @tanstack/eslint-plugin-query を使用している場合は、ESLint Query プラグインのチェック。