TanStack Query (React Query) v5 の staleTime と gcTime の違い

// TanStack Query v5 公式仕様：クエリ設定
import { useQuery } from '@tanstack/react-query';

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: fetchUser,
  staleTime: 1000 * 60 * 5, // 5分間はデータを「新鮮」とみなし再取得を抑制
  gcTime: 1000 * 60 * 30,   // 非アクティブ後 30分間メモリにキャッシュ保持 (v5仕様)
});

v5 Breaking Change: cacheTime から gcTime への改名理由

TanStack Query v5 では、従来の cacheTime というプロパティ名が gcTime (Garbage Collection Time) へ改名されました。

旧名称の cacheTime は「キャッシュが有効な時間（staleTimeの意味）」と開発者に誤解されやすかったため、「使用されなくなったデータがガベージコレクション（メモリ消去）されるまでの猶予時間」 であることが明確な gcTime に変更されました。

---

2つのパラメータの機能比較表

評価軸	staleTime (デフォルト: 0ms)	gcTime (デフォルト: 5分)
役割	データが “Fresh”（新鮮） である期間	”Inactive”（非アクティブ） なデータがメモリに残る時間
カウント開始	クエリ成功・データ取得完了の瞬間	そのクエリを使うコンポーネントが全アンマウントされた瞬間
期限切れ時の挙動	次のコンポーネント描画やフォーカス時にバックグラウンド再取得	メモリからデータが完全削除され、次回はローディング表示

---

実際に起こるバグ：gcTime < staleTime 設定の事故

gcTime を staleTime よりも短く設定してしまうと（例: staleTime: 10分, gcTime: 1分）、ユーザーが別ページへ遷移して1分以上経った後に戻ってきた際、データはまだ「新鮮」な判定ルール内であるにもかかわらず、メモリ上のキャッシュがガベージコレクションによって消去されているため、画面が一瞬白く空表示（またはローディング）になるバグが発生します。

gcTime は常に staleTime と同等か、それ以上に長い値を設定してください。