TanStack QueryによるReactクライアントキャッシュ入門
Reactにおけるサーバー状態キャッシュを徹底解説。staleTimeとgcTimeの違い、重複排除、キャッシュ破棄、楽観的更新の実践パターン。
Reactアプリケーションを開発していると、必ず直面する共通の課題があります。「APIから一度データを取得したのに、別コンポーネントや画面遷移のたびに再度APIを呼ぶ必要があるのだろうか?」
例えば、GET /api/users/123 というエンドポイントを考えてみましょう。ヘッダーコンポーネントがアバター表示のためにユーザー情報を取得し、プロフィールカードも同じ情報を必要とし、アクティビティフィードも同じユーザー情報を参照します。
Header Component ──→ GET /api/users/123
Profile Component ──→ GET /api/users/123
ActivityFeed Component ──→ GET /api/users/123text従来の useEffect と useState を組み合わせたアプローチでは、各コンポーネントがマウントされるたびに重複したリクエストがネットワークへ送信されます。その結果、無駄な通信トラフィックが発生し、ローディングスピナーが何度もちらつき、サーバーに余計な負荷をかけることになります。
[!NOTE] TL;DR:
@tanstack/react-query(旧称 React Query)は、単なるfetch()やaxiosのラッパーライブラリではありません。実態はクライアントサイドのサーバー状態キャッシュ(Server-State Cache)であり、同一リクエストの重複排除(deduplication)、バックグラウンド再検証、キャッシュライフサイクル管理(staleTimeとgcTime)、そして楽観的UI更新(Optimistic Updates)を包括的に提供します。
1. 根本的な課題:自作キャッシュ(DIY Cache)の落とし穴#
重複リクエストを回避しようとして、多くの開発者が最初に思いつくのが Map によるインメモリキャッシュの自作です。
const userCache = new Map<number, Promise<User> | User>()
export async function getUser(userId: number): Promise<User> {
if (userCache.has(userId)) {
return userCache.get(userId)!
}
const promise = fetch(`/api/users/${userId}`)
.then((res) => res.json())
.then((data) => {
userCache.set(userId, data)
return data
})
userCache.set(userId, promise)
return promise
}typescript一見するとシンプルに見えますが、プロダクションの要件が複雑化するにつれて、自作キャッシュは深刻な設計課題に突き当たります。
- キャッシュデータの有効期限はいつ切れるのか?(Stale管理)
- バックグラウンドでの自動再取得はどう実装するのか?(ウィンドウ復帰時、ネットワーク再接続時)
- ユーザーが名前を更新した際、画面上の全コンポーネントへどう通知するのか?(キャッシュの無効化・Invalidation)
- 通信切断時のローディング、エラーハンドリング、再試行(Retry)はどう制御するのか?
- 高速に画面を切り替えた際の競合(Race Condition)はどう防ぐのか?
- ユーザーが長時間放置した場合、メモリリークを起こさずに解放できるか?(ガベージコレクション)
- ページネーションや無限スクロール(Infinite Scroll)への対応は?
単純な Map から始まったコードは、結果として専用キャッシュライブラリの車輪の再発明へと向かいます。この課題を解決するために作られたのが TanStack Query です。
2. メンタルモデル(ELI5):サーバー状態 vs. クライアント状態#
TanStack Queryを正しく理解するための最重要概念は、フロントエンドの状態を2つに分類することです。
10歳の子どもにもわかる例え(ELI5)#
- クライアント状態(Client State): 自分の勉強机の上にある自由帳のようなものです。何を描くか、どのページを開くか、どの色のペンを使うかは完全にあなたの自由であり、外部の誰かが勝手に書き換えることはありません。例:ドロワーの開閉、ダークモード設定、入力フォームの一時入力値。
- サーバー状態(Server State): 公立図書館から借りてきた本のようなものです。あなたが手元に持っているのは一時的なスナップショットにすぎません。図書館側では著者が改訂版を発行したかもしれず、他の利用者が借りて内容が変わっているかもしれません。
[!WARNING] フロントエンドはサーバー状態の「所有者」ではありません。真実の単一ソース(Single Source of Truth)は常にリモートデータベースにあります。そのため、クライアントのメモリにあるデータは、取得した瞬間から古くなる(staleになる)可能性を常に孕んでいます。
APIデータをReduxやZustandなどのグローバルストアに無理に詰め込むべきでない理由はここにあります。Redux/Zustandは同期的なクライアント状態に最適化されており、TanStack Queryは非同期なサーバー状態のキャッシュ仲介役として設計されています。
3. TanStack Query キャッシュの動作原理#
基本的な実装例を見てみましょう。まず、Reactツリーを QueryClientProvider でラップします。
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { UserProfile } from './UserProfile'
const queryClient = new QueryClient()
export function App() {
return (
<QueryClientProvider client={queryClient}>
<UserProfile userId={123} />
</QueryClientProvider>
)
}tsxコンポーネント内で useQuery を利用します。
import { useQuery } from '@tanstack/react-query'
interface User {
id: number
name: string
email: string
}
async function fetchUser(userId: number): Promise<User> {
const res = await fetch(`/api/users/${userId}`)
if (!res.ok) throw new Error('ユーザー情報の取得に失敗しました')
return res.json()
}
export function UserProfile({ userId }: { userId: number }) {
const { data, isPending, error } = useQuery({
queryKey: ['user', userId],
queryFn: () => fetchUser(userId),
})
if (isPending) return <div className="skeleton">読み込み中...</div>
if (error) return <div className="alert-error">エラー: {error.message}</div>
return (
<div className="card">
<h2>{data.name}</h2>
<p>{data.email}</p>
</div>
)
}tsxqueryKey はキャッシュのエントリ識別子#
TanStack Queryは、配列として指定された queryKey を決定論的にシリアライズし、キャッシュハッシュテーブルのキーとして管理します。
['user', 123] ──→ キャッシュエントリ A: { id: 123, name: 'John' }
['user', 456] ──→ キャッシュエントリ B: { id: 456, name: 'Alice' }
['posts', 123] ──→ キャッシュエントリ C: [ ... ]text全く異なるコンポーネント階層にある複数のコンポーネントが同時に ['user', 123] を指定して useQuery を呼んだ場合、TanStack Queryは同一キーを検知し、既存キャッシュを即座に再利用します。
4. リクエストの重複排除(Request Deduplication)#
ダッシュボード画面などで、同一ユーザーの情報を参照するコンポーネントが同時にマウントされるケースを考えます。
重複排除機構がない場合、ブラウザは同一エンドポイントへ3本のHTTPリクエストを飛ばします。TanStack Queryは同一の queryKey を持つ進行中(in-flight)のリクエストを自動的に1本にまとめ、共有された1つのPromiseから全コンポーネントへデータを供給します。
5. staleTime vs. gcTime:最大の誤解を解き明かす#
TanStack Queryを利用する上で、最も混同されやすいのがこの2つの設定パラメータです。
| 設定項目 | 旧名称 | 本質的な役割 | デフォルト値 |
|---|---|---|---|
staleTime | staleTime | 取得したデータが「新鮮(fresh)」とみなされる期間(過ぎるとstaleになる) | 0 ms |
gcTime | cacheTime | どのコンポーネントにも使われなくなった(inactive)キャッシュがメモリ上に保持される期間 | 5 * 60 * 1000(5分) |
00秒: APIデータ取得完了 ──────→ データは「Fresh(新鮮)」
│
│ (staleTime期間内: 別コンポーネントがマウントされてもAPIは呼ばずキャッシュを即返却)
▼
60秒: staleTime満了 ─────────→ データは「Stale(古い)」へ遷移(キャッシュには残る!)
│
│ (ユーザーが画面遷移し、['users'] を参照するコンポーネントが全滅)
▼
70秒: クエリがInactive化 ────→ gcTimeのカウントダウン開始(5分)
│
▼
370秒: gcTime満了 ───────────→ メモリ(RAM)から完全に消去(ガベージコレクション)text[!TIP] 黄金ルール:
staleTime: 60000は「60秒後にキャッシュが破棄される」という意味ではありません。「60秒経過したらデータが古くなったとみなす」という意味です。TanStack Queryは Stale-While-Revalidate の原則に従い、古いデータであっても即座にUIへ表示して画面の白飛びを防ぎつつ、裏で静かに最新データを取得して差し替えます。
マスターデータ向けの推奨設定#
国一覧やカテゴリマスタなど、更新頻度が極めて低いデータの場合:
export const categoriesQueryOptions = {
queryKey: ['categories'],
queryFn: fetchCategories,
staleTime: 10 * 60 * 1000, // 10分間は新鮮とみなす
gcTime: 60 * 60 * 1000, // 画面を離れても60分間はメモリに保持
}typescript6. トレードオフ:パフォーマンス vs. 新鮮さ#
クライアントサイドキャッシュには常にトレードオフが存在します。
パフォーマンス最大化(通信削減) ◄───────────► 即時性重視(リアルタイム性)
大きな staleTime staleTime = 0textサーバー側でユーザー名が "John" から "Mike" に変更されたとしても、クライアントが staleTime: 10分 を設定していれば、有効期限が切れるか再検証が走るまで画面には "John" が表示され続けます。
TanStack Queryはユーザー体験を損なわずにデータを最新に保つため、自動バックグラウンド再取得トリガーを備えています。
refetchOnWindowFocus(デフォルト:true): ブラウザの別タブから戻ってきた際に、staleなクエリを自動更新。refetchOnReconnect(デフォルト:true): ネットワーク復帰時に自動更新。refetchOnMount(デフォルト:true): コンポーネント再マウント時、データがstaleであれば裏で再取得。
7. 更新処理とキャッシュ破棄(Mutation & Invalidation)#
データの新規作成・更新・削除(POST, PUT, DELETE)を行う場合は、useMutation と queryClient.invalidateQueries を連携させます。
標準的な実装例:
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
export function UserManagement() {
const queryClient = useQueryClient()
// 1. 一覧取得
const { data: users, isPending } = useQuery({
queryKey: ['users'],
queryFn: async () => {
const res = await fetch('/api/users')
return res.json()
},
staleTime: 60_000,
})
// 2. 作成Mutation
const addMutation = useMutation({
mutationFn: async (newUser: { name: string }) => {
const res = await fetch('/api/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(newUser),
})
if (!res.ok) throw new Error('ユーザー作成に失敗しました')
return res.json()
},
onSuccess: () => {
// ['users'] で始まる全キャッシュを破棄・再取得対象にする
queryClient.invalidateQueries({ queryKey: ['users'] })
},
})
if (isPending) return <div>読み込み中...</div>
return (
<div>
<ul>
{users?.map((u: { id: number; name: string }) => (
<li key={u.id}>{u.name}</li>
))}
</ul>
<button
type="button"
disabled={addMutation.isPending}
onClick={() => addMutation.mutate({ name: '新規ユーザー' })}
>
{addMutation.isPending ? '保存中...' : 'ユーザー追加'}
</button>
</div>
)
}tsx8. 最高のユーザー体験を作る:楽観的更新(Optimistic Updates)#
「いいね」ボタンやタスクの完了チェックなど、ユーザーの直感的な操作に対して300ms〜1秒のサーバー応答を待たせると、アプリが重く感じられます。
楽観的更新(Optimistic Update)では、サーバーへのリクエスト送信と同時に画面上のキャッシュを即時更新し、万が一APIエラーが発生した場合には元の状態へと自動ロールバックします。
import { useMutation, useQueryClient } from '@tanstack/react-query'
interface Post {
id: number
title: string
likes: number
}
export function useLikePost(postId: number) {
const queryClient = useQueryClient()
return useMutation({
mutationFn: async () => {
const res = await fetch(`/api/posts/${postId}/like`, { method: 'POST' })
if (!res.ok) throw new Error('いいね処理に失敗しました')
return res.json()
},
onMutate: async () => {
// 1. 進行中の再取得をキャンセルして競合を防止
await queryClient.cancelQueries({ queryKey: ['post', postId] })
// 2. ロールバック用に現行キャッシュのスナップショットを保存
const previousPost = queryClient.getQueryData<Post>(['post', postId])
// 3. キャッシュの値を先行して即時インクリメント
queryClient.setQueryData<Post>(['post', postId], (old) => {
if (!old) return old
return { ...old, likes: old.likes + 1 }
})
// 4. スナップショットをコンテキストとして返却
return { previousPost }
},
onError: (_err, _variables, context) => {
// エラー発生時は以前のスナップショットへ復元
if (context?.previousPost) {
queryClient.setQueryData(['post', postId], context.previousPost)
}
},
onSettled: () => {
// 成功・失敗を問わず、最終的にリモートの正確な状態と同期
queryClient.invalidateQueries({ queryKey: ['post', postId] })
},
})
}tsx9. TanStack Query と ブラウザHTTPキャッシュの棲み分け#
「ブラウザにはすでに Cache-Control や ETag によるHTTPキャッシュがあるのに、なぜTanStack Queryが必要なのか?」という疑問をよく耳にします。
両者は全く異なるアーキテクチャ層で動作しています。
| 比較軸 | TanStack Query | ブラウザ HTTP キャッシュ |
|---|---|---|
| 保存場所 | JavaScript ヒープメモリ | ブラウザディスク / メモリ |
| コンポーネント認識 | Reactのライフサイクル(マウント、アンマウント)と連動 | URLとHTTPヘッダーのみを認識 |
| UIへの反応性 | データ更新時に自動でReact再レンダリングをトリガー | DOMレンダリングとは一切無関係 |
| 重複排除 | 同時実行中のPromiseを複数コンポーネントで共有 | 同時リクエスト時に重複送信される場合がある |
| 楽観的更新 & ロールバック | ファーストクラスで完全対応 | 非対応 |
両者は対立するものではなく、HTTPキャッシュがネットワーク転送量を削減し(304 Not Modified など)、TanStack Queryが滑らかでリアクティブな画面描画を担うという強力な補完関係にあります。
10. 実務で役立つ Query Key Factory パターン#
中規模以上のプロダクトで、['users', id, 'posts'] のような生の配列をコンポーネント各所にベタ書きすると、タイポや無効化漏れの原因になります。
Query Key Factory パターンを活用することで、キー定義を一元管理できます。
export const userKeys = {
all: ['users'] as const,
lists: () => [...userKeys.all, 'list'] as const,
list: (filters: { page: number; search?: string }) =>
[...userKeys.lists(), filters] as const,
details: () => [...userKeys.all, 'detail'] as const,
detail: (id: number) => [...userKeys.details(), id] as const,
}typescriptこの階層構造により:
- 全ユーザー関連キャッシュの一括破棄:
queryClient.invalidateQueries({ queryKey: userKeys.all }) - 一覧のみ破棄し、個別詳細は保持:
queryClient.invalidateQueries({ queryKey: userKeys.lists() }) - 特定ユーザーの購読:
queryKey: userKeys.detail(userId)
安全かつ直感的にキャッシュをコントロールできます。
11. 導入すべきケースと不要なケース#
強く推奨されるケース:#
- 管理画面(ダッシュボード、管理ポータル)、SaaS、CRM、Eコマースサイト。
- 画面をまたいで同一エンティティを参照・更新するリッチなWebアプリ。
- React + Vite や Next.js(Client Components)を中心としたSPA。
導入が不要なケース:#
- お問い合わせフォームを1回送信するだけの静的ランディングページ。
- Next.js App Router の React Server Components(RSC)中心で構築され、データフェッチとキャッシュがサーバー側で完結しているシステム。
12. まとめ#
TanStack Queryは単なるデータフェッチ用の便利ツールではなく、クライアントサイドでサーバー状態を調和させるための専用キャッシュエンジンです。
- クライアント状態(Zustand/useState)と サーバー状態(TanStack Query)の分離
queryKeyによる一意のキャッシュ管理staleTime(鮮度)とgcTime(破棄タイマー)の適切な使い分け- Mutation ➔ Invalidate ➔ Refetch の堅牢な更新フロー
これらを正しく理解して活用することで、不要なAPI通信を撲滅し、ユーザーにとっても開発者にとっても心地よいアプリケーションを構築できます。