※本記事には広告(楽天アフィリエイト)リンクが含まれる場合があります。
「useEffect と useState でAPIを叩くコードが複雑になり過ぎた」「ローディング・エラー・リフェッチの管理が煩雑で、同じ処理をコンポーネントごとに書いている」——Reactで非同期データを扱う際のこの悩みを根本から解決するのが TanStack Query(旧React Query) です。
TanStack Query は 非同期状態管理のデファクトスタンダード として、2026年現在も多くの React プロジェクトで採用されています。v5 ではAPIが整理されて Suspense との統合が強化され、Next.js App Router との組み合わせも格段に使いやすくなりました。
この記事では、TanStack Query v5 のインストールから useQuery・useMutation・useInfiniteQuery の実践的な使い方、キャッシュ戦略、Suspense モード、Next.js App Router との統合、SWR との比較まで徹底解説します。
TanStack Queryとは?なぜ必要か
TanStack Query(以前は React Query という名称でした)は、サーバー状態(Server State)を管理するためのライブラリです。React の useState や Redux・Zustand は「クライアント状態」を管理するためのものですが、API レスポンスのキャッシュ・リフェッチ・更新などの「サーバー状態」には不向きです。
素のuseEffectによる問題点
多くの開発者が最初に書くデータ取得コードはこのような形です。
// よくあるuseEffect実装(問題あり)
function UserList() {
const [users, setUsers] = useState([]);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
fetch('/api/users')
.then(res => res.json())
.then(data => {
setUsers(data);
setLoading(false);
})
.catch(err => {
setError(err);
setLoading(false);
});
}, []);
if (loading) return <p>Loading...</p>;
if (error) return <p>Error!</p>;
return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}
このコードには多くの問題があります。コンポーネントをアンマウントした後にレスポンスが返ってきた場合のメモリリーク、同じデータを別コンポーネントで重複リクエスト、ウィンドウフォーカス時の自動更新なし、エラー時のリトライなし——TanStack Query はこれらをすべて自動で解決してくれます。
TanStack Queryが解決すること
| 課題 | TanStack Queryの解決策 |
|---|---|
| 重複リクエストの排除 | 同一クエリキーは自動的にデデュープ(1リクエストにまとめ) |
| キャッシュ管理 | staleTime / gcTime で柔軟にキャッシュライフを制御 |
| バックグラウンド更新 | ウィンドウフォーカス・ネットワーク復帰時に自動リフェッチ |
| エラーリトライ | 失敗時に指数バックオフで自動リトライ(デフォルト3回) |
| Optimistic UI | useMutation の onMutate フックで楽観的更新が簡単 |
| ページネーション・無限スクロール | useInfiniteQuery で専用API提供 |
| Suspense統合 | v5でuseSuspenseQuery等が正式対応 |
インストールとセットアップ
パッケージのインストール
npm install @tanstack/react-query
# DevtoolsはReact DevToolsのような開発支援ツール(本番には不要)
npm install @tanstack/react-query-devtools
QueryClientProviderの設定
アプリケーションのルートに QueryClientProvider をセットアップします。Next.js の App Router を使っている場合は後述の方法を参照してください。
// main.tsx(Viteの場合)
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 1000 * 60 * 5, // 5分間はstaleにしない
retry: 2, // 失敗時は2回リトライ
},
},
});
function App() {
return (
<QueryClientProvider client={queryClient}>
<YourApp />
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
);
}
useQuery — データ取得の基礎
useQuery は TanStack Query の中心的なフックです。クエリキーとフェッチ関数を渡すだけで、ローディング・エラー・データの状態管理を自動で行います。
基本的な使い方
import { useQuery } from '@tanstack/react-query';
type User = { id: number; name: string; email: string };
async function fetchUser(id: number): Promise<User> {
const res = await fetch(`/api/users/${id}`);
if (!res.ok) throw new Error('Failed to fetch user');
return res.json();
}
function UserProfile({ userId }: { userId: number }) {
const { data, isPending, isError, error } = useQuery({
queryKey: ['users', userId], // キャッシュのキー
queryFn: () => fetchUser(userId),
});
if (isPending) return <p>読み込み中...</p>;
if (isError) return <p>エラー: {error.message}</p>;
return (
<div>
<h2>{data.name}</h2>
<p>{data.email}</p>
</div>
);
}
queryKeyの設計
クエリキーはキャッシュを識別する配列です。依存する値(ID・フィルター条件など)をキーに含めると、値が変わると自動でリフェッチされます。
// IDごとに別キャッシュ
queryKey: ['users', userId]
// フィルター付き
queryKey: ['users', { status: 'active', page: 1 }]
// ネストしたリソース
queryKey: ['posts', postId, 'comments']
useQueryの主要オプション
| オプション | 説明 | デフォルト値 |
|---|---|---|
staleTime |
データが「古い」とみなされるまでの時間(ms) | 0 |
gcTime |
未使用キャッシュをメモリから削除するまでの時間 | 5分 |
retry |
失敗時のリトライ回数 | 3 |
refetchOnWindowFocus |
ウィンドウフォーカス時に自動リフェッチするか | true |
enabled |
falseにするとクエリを実行しない(条件付きフェッチ) | true |
select |
取得データを変換する関数 | — |
placeholderData |
データ取得中に表示するプレースホルダーデータ | — |
条件付きフェッチ(enabled)
ユーザーがログインしている場合だけデータを取得したい、前のクエリが完了してから次を取得したいといった場合は enabled オプションを使います。
function UserPosts({ userId }: { userId: number | null }) {
const { data } = useQuery({
queryKey: ['posts', userId],
queryFn: () => fetchPosts(userId!),
enabled: userId !== null, // userIdがある場合のみフェッチ
});
}
useMutation — データの作成・更新・削除
useMutation は API への書き込み操作(POST/PUT/DELETE)に使います。useQuery と違い、自動実行ではなく手動でトリガーします。
基本的なuseMutation
import { useMutation, useQueryClient } from '@tanstack/react-query';
type CreatePostInput = { title: string; body: string };
type Post = { id: number; title: string; body: string };
async function createPost(input: CreatePostInput): Promise<Post> {
const res = await fetch('/api/posts', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(input),
});
if (!res.ok) throw new Error('Failed to create post');
return res.json();
}
function NewPostForm() {
const queryClient = useQueryClient();
const mutation = useMutation({
mutationFn: createPost,
onSuccess: () => {
// 投稿一覧のキャッシュを無効化して再取得
queryClient.invalidateQueries({ queryKey: ['posts'] });
},
});
const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
const form = e.currentTarget;
mutation.mutate({
title: form.title.value,
body: form.body.value,
});
};
return (
<form onSubmit={handleSubmit}>
<input name="title" required />
<textarea name="body" required />
<button type="submit" disabled={mutation.isPending}>
{mutation.isPending ? '送信中...' : '投稿する'}
</button>
{mutation.isError && <p className="error">{mutation.error.message}</p>}
</form>
);
}
Optimistic Update(楽観的更新)
サーバーの応答を待たずに UI をすぐ更新し、失敗した場合はロールバックする「楽観的更新」は、onMutate・onError・onSettled の3つのコールバックで実装します。
const mutation = useMutation({
mutationFn: updateTodo,
onMutate: async (newTodo) => {
// 進行中のリフェッチをキャンセル
await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] });
// 現在のキャッシュを保存(ロールバック用)
const previous = queryClient.getQueryData(['todos', newTodo.id]);
// 楽観的にキャッシュを更新
queryClient.setQueryData(['todos', newTodo.id], newTodo);
return { previous };
},
onError: (err, newTodo, context) => {
// エラー時はロールバック
queryClient.setQueryData(['todos', newTodo.id], context?.previous);
},
onSettled: (data, error, variables) => {
// 成功・失敗どちらでも最終的にリフェッチ
queryClient.invalidateQueries({ queryKey: ['todos', variables.id] });
},
});
useInfiniteQuery — 無限スクロールとページネーション
「もっと読む」ボタンや無限スクロールを実装する場合は useInfiniteQuery を使います。v5 では API が整理されて使いやすくなりました。
import { useInfiniteQuery } from '@tanstack/react-query';
import { useIntersectionObserver } from './hooks';
type PostsPage = {
posts: Post[];
nextCursor: number | null;
};
async function fetchPosts({ pageParam }: { pageParam: number }): Promise<PostsPage> {
const res = await fetch(`/api/posts?cursor=${pageParam}&limit=10`);
return res.json();
}
function InfinitePostList() {
const {
data,
fetchNextPage,
hasNextPage,
isFetchingNextPage,
} = useInfiniteQuery({
queryKey: ['posts'],
queryFn: fetchPosts,
initialPageParam: 0,
getNextPageParam: (lastPage) => lastPage.nextCursor,
});
const { ref } = useIntersectionObserver({
onChange: (inView) => {
if (inView && hasNextPage) fetchNextPage();
},
});
return (
<div>
{data?.pages.flatMap(page => page.posts).map(post => (
<PostCard key={post.id} post={post} />
))}
{isFetchingNextPage && <p>読み込み中...</p>}
<div ref={ref} /> {/* 監視対象要素 */}
</div>
);
}
キャッシュ戦略とstaleTime設計
TanStack Query のキャッシュ設計の核心は staleTime(新鮮さの期限) と gcTime(キャッシュ保持期間) の使い分けです。
staleTimeとgcTimeの違い
staleTime:データがフレッシュとみなされる時間。この時間内は同一クエリが呼ばれてもネットワークリクエストを発生させません。0(デフォルト)の場合、マウントのたびにバックグラウンドリフェッチが走ります。
gcTime:クエリの購読がなくなった後(コンポーネントがアンマウントされた後)、キャッシュをメモリから削除するまでの時間(デフォルト5分)。gcTime 内に再度アクセスがあれば、古いデータを即座に表示しながらバックグラウンドでリフェッチします。
用途別のstaleTime設計例
// ユーザープロフィール(あまり変わらないデータ)
useQuery({
queryKey: ['user', userId],
queryFn: fetchUser,
staleTime: 1000 * 60 * 10, // 10分
});
// ダッシュボードの統計(頻繁に更新)
useQuery({
queryKey: ['dashboard', 'stats'],
queryFn: fetchStats,
staleTime: 1000 * 30, // 30秒
refetchInterval: 1000 * 60, // 1分ごとにポーリング
});
// ほぼ変わらない設定データ
useQuery({
queryKey: ['config'],
queryFn: fetchConfig,
staleTime: Infinity, // 再起動まで更新しない
});
キャッシュの手動操作
QueryClient を使うとキャッシュを直接読み書きできます。サーバーサイドレンダリングや楽観的更新、デバッグ時に便利です。
const queryClient = useQueryClient();
// キャッシュを読む
const user = queryClient.getQueryData(['users', userId]);
// キャッシュに書き込む
queryClient.setQueryData(['users', userId], newUserData);
// クエリを無効化(次アクセス時にリフェッチ)
queryClient.invalidateQueries({ queryKey: ['users'] });
// キャッシュを削除
queryClient.removeQueries({ queryKey: ['users', userId] });
// すべてのクエリをリフェッチ
queryClient.refetchQueries({ type: 'active' });
Suspenseモード(v5対応)
TanStack Query v5 では Suspense との統合が強化され、専用フック useSuspenseQuery が追加されました。Suspense を使うとローディング・エラー状態を親コンポーネントへ委譲でき、コンポーネント本体をすっきり保てます。
import { useSuspenseQuery } from '@tanstack/react-query';
import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';
// Suspenseを使う場合、isPending チェック不要
function UserProfile({ userId }: { userId: number }) {
const { data } = useSuspenseQuery({
queryKey: ['users', userId],
queryFn: () => fetchUser(userId),
});
// dataは必ず存在(ローディング中はSuspenseが処理)
return <p>{data.name}</p>;
}
// 親コンポーネントでSuspenseとErrorBoundaryを設定
function UserPage({ userId }: { userId: number }) {
return (
<ErrorBoundary fallback={<p>エラーが発生しました</p>}>
<Suspense fallback={<p>読み込み中...</p>}>
<UserProfile userId={userId} />
</Suspense>
</ErrorBoundary>
);
}
useSuspenseQueryの注意点
useSuspenseQuery を使う場合、enabled オプションは使用できません。フェッチを条件付きにしたい場合は通常の useQuery を使うか、コンポーネントの条件分岐で制御する必要があります。
Next.js App Router との統合
Next.js App Router(RSC: React Server Components)でTanStack Query を使う場合、特有のセットアップが必要です。Server Component でデータをプリフェッチしてクライアントに渡す「Hydration」パターンが推奨されます。
QueryClientのシングルトン管理
// lib/query-client.ts
import { QueryClient } from '@tanstack/react-query';
function makeQueryClient() {
return new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000, // SSR直後は1分間リフェッチしない
},
},
});
}
let browserQueryClient: QueryClient | undefined;
export function getQueryClient() {
if (typeof window === 'undefined') {
// サーバー:毎回新しいクライアント(リクエスト間でキャッシュを共有しない)
return makeQueryClient();
}
// ブラウザ:シングルトン
if (!browserQueryClient) browserQueryClient = makeQueryClient();
return browserQueryClient;
}
Providers コンポーネント(Client Component)
// app/providers.tsx
'use client';
import { QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { getQueryClient } from '@/lib/query-client';
export function Providers({ children }: { children: React.ReactNode }) {
const queryClient = getQueryClient();
return (
<QueryClientProvider client={queryClient}>
{children}
<ReactQueryDevtools />
</QueryClientProvider>
);
}
Server Componentでプリフェッチ
// app/users/page.tsx(Server Component)
import { dehydrate, HydrationBoundary } from '@tanstack/react-query';
import { getQueryClient } from '@/lib/query-client';
import { UserList } from './user-list';
export default async function UsersPage() {
const queryClient = getQueryClient();
// サーバーサイドでプリフェッチ
await queryClient.prefetchQuery({
queryKey: ['users'],
queryFn: fetchUsers,
});
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<UserList />
</HydrationBoundary>
);
}
// components/user-list.tsx(Client Component)
'use client';
import { useQuery } from '@tanstack/react-query';
export function UserList() {
// サーバー側でプリフェッチ済みのためローディングなしで即表示
const { data } = useQuery({
queryKey: ['users'],
queryFn: fetchUsers,
});
return <ul>{data?.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}
TanStack Query vs SWR 比較
React 向けの非同期状態管理ライブラリとして SWR(Vercelが開発)も人気があります。用途によって選び方が変わります。
| 比較項目 | TanStack Query v5 | SWR v2 |
|---|---|---|
| バンドルサイズ | 約47KB(gzip) | 約8KB(gzip) |
| Mutation機能 | ◎ useMutation が充実 | △ useSWRMutation は限定的 |
| 無限スクロール | ◎ useInfiniteQuery | ◎ useSWRInfinite |
| Suspense対応 | ◎ useSuspenseQuery(v5) | ◎ suspense: true オプション |
| 楽観的更新 | ◎ onMutateで組み込み対応 | △ mutate()の第3引数で対応 |
| Devtools | ◎ 専用ツールが強力 | △ 基本的なLogger |
| キャッシュ細粒度制御 | ◎ QueryClient API が豊富 | △ やや限定的 |
| 学習コスト | 中(多機能の分だけ把握が必要) | 低(シンプルなAPI) |
TanStack Query を選ぶべきケース:複雑なフォーム送信・楽観的更新が多い、キャッシュをきめ細かく制御したい、Devtools を活用したい、チームでの大規模開発。
SWR を選ぶべきケース:バンドルサイズを最小化したい、Vercel / Next.js との統合を優先したい、シンプルな読み取り専用データが中心のアプリ。
React Query Devtoolsの活用
TanStack Query の開発体験を向上させる強力な Devtools が公式提供されています。キャッシュの状態・各クエリのステータス・リフェッチのタイミングをリアルタイムで可視化できます。
Devtoolsの機能
- クエリインスペクター:全クエリのキーと現在ステータス(fresh / stale / fetching / inactive)を一覧表示
- データビューワー:キャッシュに保持されている実際のデータをJSON形式で閲覧
- タイムライン:リフェッチのタイミングと所要時間をグラフで確認
- 手動操作:特定のクエリを強制リフェッチ・無効化・削除
// 開発環境のみDevtoolsを表示する設定
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
<ReactQueryDevtools
initialIsOpen={false}
buttonPosition="bottom-right"
/>
本番ビルドでは NODE_ENV === 'production' の場合に自動で除外されるため、バンドルサイズへの影響を気にせず追加できます。
カスタムフックでの再利用パターン
useQuery を直接コンポーネントで使うのではなく、カスタムフックに切り出すと再利用性・テスタビリティが向上します。
// hooks/use-user.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
export const userKeys = {
all: ['users'] as const,
detail: (id: number) => ['users', id] as const,
};
export function useUser(id: number) {
return useQuery({
queryKey: userKeys.detail(id),
queryFn: () => fetchUser(id),
staleTime: 1000 * 60 * 5,
});
}
export function useUpdateUser() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: updateUser,
onSuccess: (data) => {
queryClient.setQueryData(userKeys.detail(data.id), data);
queryClient.invalidateQueries({ queryKey: userKeys.all });
},
});
}
// コンポーネントでの使用
function UserCard({ userId }: { userId: number }) {
const { data, isPending } = useUser(userId);
const updateMutation = useUpdateUser();
// ...
}
userKeys のようにクエリキーをオブジェクトとして集約する「Query Key Factory」パターンは、大規模プロジェクトでの管理を容易にします。
よくあるパターンとアンチパターン
やっておくべき設計
- staleTime を適切に設定する:デフォルト0ではマウントのたびにリフェッチが走り、パフォーマンスが低下します
- クエリキーをファクトリ関数で管理する:invalidateQueries が意図通りに動作するよう、キー設計を統一する
- useMutation の onSuccess でキャッシュ更新する:書き込み後に関連クエリを invalidate して整合性を保つ
- カスタムフックに切り出す:コンポーネントとデータフェッチロジックを分離する
避けるべきアンチパターン
- useQuery と useEffect を併用する:TanStack Query のリフェッチロジックと競合してバグの温床になる
- queryFn の中で useState を呼ぶ:queryFn は純粋な非同期関数にする
- isLoading と isPending を混同する:v5 では
isPendingを使う(isLoading は削除された) - queryKey に毎回新しいオブジェクトを渡す:
queryKey: [{id: userId}]は参照が変わり毎回リフェッチが走る。変数を直接渡すこと
まとめ
TanStack Query v5 は React アプリのサーバー状態管理を劇的にシンプルにしてくれるライブラリです。
- useQuery:データ取得とキャッシュ管理、ローディング・エラー状態の自動ハンドリング
- useMutation:書き込み操作と楽観的更新、成功後のキャッシュ無効化
- useInfiniteQuery:無限スクロールとカーソルベースのページネーション
- useSuspenseQuery:v5 で強化された Suspense 統合でコンポーネントをすっきり記述
- Next.js App Router 統合:prefetchQuery + HydrationBoundary でSSRとのシームレスな連携
「とりあえず useEffect でフェッチ」から卒業して TanStack Query を導入することで、キャッシュの重複排除・自動リフェッチ・楽観的更新といった複雑な機能を宣言的なAPIで扱えるようになります。小さなプロジェクトから大規模なアプリまで、React でデータを扱うならまず検討する価値のあるライブラリです。