TanStack QueryによるReact Client-side Cache
TanStack Queryをクライアント側サーバーステートキャッシュとして活用:APIキャッシュ、重複排除、自動refetch、loading/error管理。
ReactにおけるTanStack Queryのシンプルな理解と実践的な活用法、特にクライアントサイドキャッシュについて書きます。
TL;DR: @tanstack/react-queryは単なるAPI呼び出しライブラリではありません。クライアントサイドのサーバーステートキャッシュとして機能し、APIデータのキャッシュ、重複リクエストの回避、必要に応じた自動refetch、loading/error状態の便利な管理を実現します。
課題:重複するAPIリクエスト#
Reactアプリケーションを構築する際、よくある問題に直面します:
APIがデータを返したのに、次回もAPIを呼ぶ必要があるの?
例えば、あるページにこんなAPIがあるとします:
GET /api/users/123textコンポーネントAがこのAPIを呼び、その後コンポーネントBもユーザー123の情報を必要とする場合、従来の方法では両方のコンポーネントがAPIを呼んでしまう可能性があります。
これが冗長なリクエストを生みます。
一つの解決策は自前のキャッシュを作ることです:
const cache = new Map()tsしかしアプリが大きくなると、自前でキャッシュを管理するのはすぐに複雑になります。
そこでTanStack Queryが役に立ちます。
TanStack Queryとは?#
TanStack Queryは、以前React Queryとして知られていた、フロントエンドでサーバーステートを管理するためのライブラリです。
React用のパッケージは:
npm install @tanstack/react-querybash重要なポイントは:
TanStack Queryは単なる
fetch()APIライブラリではない。
以下の仕組みを提供します:
- データ取得
- データキャッシュ
- リクエストの重複排除
- データのrefetch
- リクエストのリトライ
- loading/error管理
- キャッシュのinvalidate
- optimistic update
- ページネーション
- infinite query
- バックグラウンドrefetch
Server StateとClient Stateの違い#
TanStack Queryを理解する上で最も重要な概念です。
Client State#
UI/アプリケーションに属するstateです。
例えば:
const [isOpen, setIsOpen] = useState(false)tsxあるいは:
const [theme, setTheme] = useState("dark")tsxこのデータはフロントエンドに属します。
Server State#
バックエンドから来るデータです。
例えば:
{
"id": 123,
"name": "John",
"email": "john@example.com"
}jsonフロントエンドはこのデータを本当の意味で所有していません。
データの正本はバックエンドにあります。
TanStack Queryは主にこの種のstateを解決するために設計されています。
[!NOTE] ELI5で説明すると:Client Stateは家の電気のスイッチのようなもの — 自分で自由にオン/オフできます。Server Stateは外の天気のようなもの — 窓(API)越しに「見る」ことしかできず、所有もできませんし、いつでも変わる可能性があります。
TanStack QueryをReduxと混同しない#
シンプルな理解はこうです:
Redux/Zustand
↓
Client State
TanStack Query
↓
Server Statetext例えば:
{
sidebarOpen: true,
theme: "dark"
}tsはZustand/Reduxに適しています。
一方で:
{
users: [...],
posts: [...],
products: [...],
profile: {...}
}tsがAPI由来のデータなら、TanStack Queryの方が適していることが多いです。
もちろん、両方のstateが一つのアプリに共存できます。
キャッシュはどう動くのか?#
例えば:
const { data } = useQuery({
queryKey: ["user", userId],
queryFn: () => fetchUser(userId),
})tsxTanStack Queryは:
queryKeytsを使って、どのデータがキャッシュされているかを識別します。
例えば:
["user", 123]textと:
["user", 456]textは異なるキャッシュエントリです。
こんなイメージです:
Query Cache
"user", 123
↓
{ id: 123, name: "John" }
"user", 456
↓
{ id: 456, name: "Alice" }
"posts", 123
↓
[ ... ]text[!TIP]
queryKeyはスーパーのロッカー番号のようなものだと考えてください:各キーが正確に一つのデータ収納を開けます。キーが違えば収納も違い、混ざることはありません。
基本例#
まずQueryClientを作ります。
import {
QueryClient,
QueryClientProvider,
} from "@tanstack/react-query"
const queryClient = new QueryClient()
export function App() {
return (
<QueryClientProvider client={queryClient}>
<MyApp />
</QueryClientProvider>
)
}tsx次にqueryを使います:
import { useQuery } from "@tanstack/react-query"
function UserProfile({ userId }: { userId: number }) {
const { data, isPending, error } = useQuery({
queryKey: ["user", userId],
queryFn: () => fetch(`/api/users/${userId}`).then(res => res.json()),
})
if (isPending) {
return <div>Loading...</div>
}
if (error) {
return <div>Error</div>
}
return <div>{data.name}</div>
}tsx注目点は:
queryKey: ["user", userId]tsこれこそがキャッシュのidentityです。
[!NOTE] TanStack Query v5以降、初期ローディング状態は
isPending(v4のisLoadingに代わるもの)になり、cacheTimeはgcTimeに改名されました。本記事の例はv5のAPIを使っています。
2つ目のコンポーネントが同じAPIを呼ぶとき#
コンポーネントAにこうあるとします:
<UserProfile userId={123} />tsxその後コンポーネントBもこう使います:
<UserProfile userId={123} />tsxTanStack Queryは:
["user", 123]textがQuery Cacheに既に存在することを知っています。
そのためコンポーネントBは真っ白なローディング画面の代わりに、既存のデータを即座に表示できます。
これはTanStack Queryの大きな強みの一つです。
[!NOTE] デフォルトで
staleTimeは0、つまりキャッシュデータは即座にstaleと見なされます。コンポーネントBは古いデータを一瞬で表示し(ローディングなし)、同時にTanStack Queryが裏でrefetchします — このパターンをstale-while-revalidateと呼びます。
Request Deduplication#
よくある状況です:
コンポーネントA ─┐
│
コンポーネントB ─┼──→ GET /api/user/123
│
コンポーネントC ─┘text3つのコンポーネントがほぼ同時にマウントしても、こう送りたくはありません:
GET /api/user/123
GET /api/user/123
GET /api/user/123textTanStack Queryはquery keyに基づいてリクエストを共有/重複排除する仕組みを持っています。
概念図:
staleTime — データが古くなるまでの時間#
とても重要なオプションです。
例えば:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
})tsxこれはデータが60秒間freshと見なされるという意味です。
その間、別のコンポーネントが:
["users"]tsを使っても、TanStack Queryは即座にrefetchせず現在のキャッシュを使えます。
例えば:
00秒 API request
↓
cache
10秒 コンポーネントB
↓
キャッシュを使う
30秒 コンポーネントC
↓
キャッシュを使う
60秒 キャッシュがstaleになるtextstaleTimeはキャッシュ削除時間ではない#
とてもよくある誤解です。
例えば:
staleTime: 60_000tsはこういう意味ではありません:
60秒後にキャッシュが削除される。
意味はこうです:
60秒後にデータがstaleと見なされる。
データはキャッシュに残り続けることがあります。
[!WARNING] TanStack Query学習時の一番あるあるな誤解:
staleTimeは「データが新鮮な期間」であり、「キャッシュの寿命」ではありません。staleTimeが切れてもデータは古いとマークされるだけ — 次の利用時に裏でrefetchされますが、キャッシュは削除されません。
gcTime#
TanStack Queryにはさらに:
gcTimetsがあります。以前は:
cacheTimetextと呼ばれていました。
使われなくなったデータをガベージコレクトするまでの保持時間に関係します。
例えば:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
gcTime: 5 * 60_000,
})tsxシンプルに理解すると:
staleTime
↓
データがfreshと見なされる期間は?
gcTime
↓
inactiveなキャッシュを保持する期間は?textこの2つの概念は異なります。
[!NOTE] デフォルト値:
staleTimeは0(即stale)、gcTimeは5分(最後のコンポーネントがアンマウントされてからinactiveキャッシュを5分保持)。初心者が出会う「不思議な」挙動のほとんどは、この2つの数字で説明できます。
実践的な設定#
商品APIの例:
const productsQuery = useQuery({
queryKey: ["products"],
queryFn: fetchProducts,
staleTime: 5 * 60 * 1000,
gcTime: 30 * 60 * 1000,
})tsx意味はこうです:
5分
↓
dataがfreshと見なされる
30分
↓
inactiveキャッシュがガベージコレクトされうるtextあまり変わらないデータに特に有効です。
例えば:
- 国リスト
- カテゴリ
- 学校リスト
- 設定
- 商品カタログ
- マスタデータ
[!TIP] 経験則:データの変更頻度が低いほど
staleTimeを長く。国リストならstaleTime: InfinityでもOK。リアルタイム価格ボードなら数秒かrefetch intervalを使いましょう。
キャッシュはデータが常に新しいという意味ではない#
とても重要なポイントです。
仮に:
Backend
↓
User name = "John"textフロントエンドのキャッシュ:
User name = "John"textその後サーバーが変更:
Backend
↓
User name = "Mike"textフロントエンドのキャッシュはまだこうかもしれません:
Johntextつまりクライアントサイドキャッシュには常にトレードオフがあります:
Performance
↕
FreshnesstextAPIリクエストを減らしたい:
staleTime ↑textデータを頻繁に更新したい:
staleTime ↓textデータのrefetch#
TanStack Queryは様々な状況でrefetchできます。
例えばユーザーがブラウザタブに戻ってきたとき:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchOnWindowFocus: true,
})tsx概念図:
開発者が自前でイベントリスナーを書かなくても、アプリが常に最新に感じられます。
[!NOTE]
refetchOnWindowFocusのデフォルトはtrueです — 初心者を驚かせる”important defaults”の一つです:タブを行き来するだけでアプリが勝手にAPIを呼びます。DevToolsに「謎の」リクエストが出たら、こいつが犯人の可能性大です。
キャッシュのInvalidate#
CRUDをするときに非常に便利な機能です。
例えば:
GET /users
POST /userstextユーザー作成後:
await createUser(data)tsこうinvalidateできます:
queryClient.invalidateQueries({
queryKey: ["users"],
})tsするとTanStack Queryはクエリ:
["users"]textがstaleになったと判断し、refetchできます。
フロー:
Mutation#
TanStack QueryにはuseMutation()もあります。
const mutation = useMutation({
mutationFn: createUser,
})tsx使い方:
mutation.mutate({
name: "John",
})tsx完全な例:
const queryClient = useQueryClient()
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
})
},
})tsxよくあるパターンです:
Optimistic Update#
さらに高度な機能がOptimistic Updateです。
例えばユーザーがクリック:
❤️ Liketextこうする代わりに:
Click
↓
API request
↓
Server response
↓
Update UItextこうできます:
Click
↓
即座にUI更新
↓
API request
↓
Success → そのまま
Failure → ロールバックtextユーザーはアプリが速く感じます。
例えば:
自前のキャッシュ/state管理が一気に複雑になるユースケースの一つです。
TanStack QueryはLocalStorageにキャッシュするの?#
デフォルトでは:
しません。
クエリキャッシュは主にメモリ上にあります。
例えば:
Browser
└─JavaScript Memory
└─TanStack Query Cachetextページリロード:
F5
↓
JavaScriptメモリ消失
↓
Queryキャッシュ消失textキャッシュを永続化したい場合、TanStack Queryはこんな仕組みと組み合わせられます:
localStorage
IndexedDBtextリロード後/オフラインでも一部のサーバーステートを保持したいアプリに適しています。
TanStack QueryはHTTPキャッシュなの?#
この2つを混同してはいけません。
少なくとも2つの異なるキャッシュ層があります:
Browser / HTTP Cache
↓
HTTPレスポンスのキャッシュ
TanStack Query
↓
アプリケーションレベルのサーバーステートキャッシュtext例えば:
TanStack Queryが理解するのは:
queryKey
staleTime
invalidation
mutation
query statets一方HTTPキャッシュはこんなHTTPの仕組みに基づきます:
Cache-Control
ETag
Last-Modified
Agetext2つの仕組みは共存できます。
自前キャッシュとの比較#
TanStack Queryなし:
const cache = new Map()
async function getUser(id: number) {
if (cache.has(id)) {
return cache.get(id)
}
const data = await fetch(`/api/users/${id}`)
.then(res => res.json())
cache.set(id, data)
return data
}ts最初はシンプルに見えます。
でもその後こんな問題を解かなければなりません:
❓ どれくらいキャッシュする?
❓ いつstaleになる?
❓ いつrefetchする?
❓ Retry?
❓ Loading?
❓ Error?
❓ Deduplicate?
❓ Mutation?
❓ Invalidate?
❓ Pagination?
❓ Infinite scroll?
❓ Optimistic update?
❓ Garbage collection?
❓ Concurrent request?
❓ Offline?textこうなると最初のシンプルなMap()は完全なキャッシュシステムに変貌しています。
TanStack Queryはその大半を解決します。
TanStack Query vs Zustand#
一般的なReactアーキテクチャでは両方使えます:
Zustandの例:
{
sidebarOpen: true,
selectedTheme: "dark"
}tsTanStack Query:
{
users: [...],
posts: [...],
profile: {...}
}tsどちらか選ぶ必要はありません。
TanStack Query vs SWR#
React/Next.jsのもう一つの人気選択肢はSWRです。
両者のコンセプトはかなり似ています:
React
├─TanStack Query
└─SWRtext両方とも解決するのは:
- fetching
- caching
- revalidation
- server state
TanStack Queryはより広範なquery/mutationシステムとサーバーステート管理能力を提供する一方、SWRはかなりミニマルなAPIです。
なのでアプリにこういう要素が多いなら:
CRUD
Mutation
Pagination
Infinite Query
Optimistic Update
Cache Invalidation
Complex Server StatetextTanStack Queryは検討に値します。
いつTanStack Queryを使うべき?#
TanStack Queryが特に適しているのは:
Dashboard
Admin panel
E-commerce
CRM
SaaS
Social network
Healthcare application
Education platformtext特にAPIが多いアプリケーションです。
例えば:
/users
/users/:id
/courses
/courses/:id
/students
/students/:id
/reports
/notificationstext各コンポーネントが自前で管理する代わりに:
fetch
loading
error
cache
refetchtextサーバーステートはTanStack Queryに任せられます。
TanStack Queryが必ずしも要らないとき#
アプリが極めてシンプルな場合:
const [data, setData] = useState()
useEffect(() => {
fetch("/api/data")
.then(...)
}, [])tsxAPIリクエストが数個だけなら、ライブラリ追加のメリットは少ないかもしれません。
同様に、フレームワークが強力なサーバーデータ取得/キャッシュ機構を既に提供し、アプリが主にserver componentsを使うなら、クライアントサイドのqueryライブラリを追加する前に全体アーキテクチャを検討すべきです。
実践的なアーキテクチャ#
大きなReact SPAではこう整理できます:
src/
├─api/
│ ├─users.ts
│ ├─courses.ts
│ └─reports.ts
├─queries/
│ ├─users.ts
│ ├─courses.ts
│ └─reports.ts
├─components/
│ ├─UserList.tsx
│ └─CourseList.tsx
└─query-client.tstext例えば:
// queries/users.ts
export const usersQuery = () => ({
queryKey: ["users"],
queryFn: fetchUsers,
})tsコンポーネント:
const { data, isPending } = useQuery(
usersQuery()
)tsxAPIロジックがUIと混ざりすぎなくなります。
重要なパターン:Query Key#
TanStack Queryを使うときは、構造化されたquery keyを設計しましょう。
例えば:
["users"]ts["users", userId]ts["users", { page: 1, search: "john" }]tsイメージはこうです:
users
├─users/123
├─users/456
└─users?page=1&search=johntextquery keyの設計が一貫しているほど:
invalidateQueries()tsとキャッシュ管理が楽になります。
[!TIP] query keyは総称から詳細へ階層的に設計しましょう:
["users"]→["users", id]→["users", { page, search }]。そうすればinvalidateQueries({ queryKey: ["users"] })で配下全体をinvalidateできます — ファイルを一つずつ消す代わりにフォルダごと消すようなものです。
完全な例#
function UserList() {
const queryClient = useQueryClient()
const usersQuery = useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60_000,
})
const createMutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
})
},
})
if (usersQuery.isPending) {
return <div>Loading...</div>
}
if (usersQuery.isError) {
return <div>Something went wrong</div>
}
return (
<>
{usersQuery.data.map(user => (
<div key={user.id}>
{user.name}
</div>
))}
<button
onClick={() =>
createMutation.mutate({
name: "John",
})
}
>
Add user
</button>
</>
)
}tsxフローは明確です:
まとめ#
ReactでAPIデータのクライアントサイドキャッシュが目的なら、@tanstack/react-queryは検討に値する選択肢です。
覚えておくべき最重要ポイントはこうではありません:
“TanStack Queryはfetch APIライブラリだ。”
こうです:
TanStack Queryはサーバーステート管理とクライアント側キャッシュのシステムだ。
APIが増え始め、こんな問題が出てきたときに特に有効です:
API request duplication
+
Caching
+
Stale data
+
Refetch
+
Mutation
+
Cache invalidation
+
Optimistic updatetextuseEffect + useState + Mapで全部自作する代わりに、サーバーステート部分はTanStack Queryに任せられます。
モダンなReactアーキテクチャはこう単純化できます:
APIデータをむやみにRedux/Zustandに入れなくて済む考え方でもあります。