blog.dopana

戻る

ReactにおけるTanStack Queryのシンプルな理解と実践的な活用法、特にクライアントサイドキャッシュについて書きます。

TL;DR: @tanstack/react-queryは単なるAPI呼び出しライブラリではありません。クライアントサイドのサーバーステートキャッシュとして機能し、APIデータのキャッシュ、重複リクエストの回避、必要に応じた自動refetch、loading/error状態の便利な管理を実現します。

課題:重複するAPIリクエスト#

Reactアプリケーションを構築する際、よくある問題に直面します:

APIがデータを返したのに、次回もAPIを呼ぶ必要があるの?

例えば、あるページにこんなAPIがあるとします:

GET /api/users/123
text

コンポーネントAがこのAPIを呼び、その後コンポーネントBもユーザー123の情報を必要とする場合、従来の方法では両方のコンポーネントがAPIを呼んでしまう可能性があります。

コンポーネントAGET /api/users/123コンポーネントBGET /api/users/123

これが冗長なリクエストを生みます。

一つの解決策は自前のキャッシュを作ることです:

cache.ts
const cache = new Map()
ts

しかしアプリが大きくなると、自前でキャッシュを管理するのはすぐに複雑になります。

そこでTanStack Queryが役に立ちます。

TanStack Queryとは?#

TanStack Queryは、以前React Queryとして知られていた、フロントエンドでサーバーステートを管理するためのライブラリです。

React用のパッケージは:

terminal
npm install @tanstack/react-query
bash

重要なポイントは:

TanStack Queryは単なるfetch() APIライブラリではない。

以下の仕組みを提供します:

  • データ取得
  • データキャッシュ
  • リクエストの重複排除
  • データのrefetch
  • リクエストのリトライ
  • loading/error管理
  • キャッシュのinvalidate
  • optimistic update
  • ページネーション
  • infinite query
  • バックグラウンドrefetch

Server StateとClient Stateの違い#

TanStack Queryを理解する上で最も重要な概念です。

Client State#

UI/アプリケーションに属するstateです。

例えば:

ThemeToggle.tsx
const [isOpen, setIsOpen] = useState(false)
tsx

あるいは:

ThemeToggle.tsx
const [theme, setTheme] = useState("dark")
tsx

このデータはフロントエンドに属します。

Server State#

バックエンドから来るデータです。

例えば:

user.json
{
  "id": 123,
  "name": "John",
  "email": "john@example.com"
}
json

フロントエンドはこのデータを本当の意味で所有していません。

データの正本はバックエンドにあります。

APIServer(正本)TanStack QueryCacheコンポーネントAコンポーネントB

TanStack Queryは主にこの種のstateを解決するために設計されています。

[!NOTE] ELI5で説明すると:Client Stateは家の電気のスイッチのようなもの — 自分で自由にオン/オフできます。Server Stateは外の天気のようなもの — 窓(API)越しに「見る」ことしかできず、所有もできませんし、いつでも変わる可能性があります。

TanStack QueryをReduxと混同しない#

シンプルな理解はこうです:

Redux/Zustand
    ↓
Client State

TanStack Query
    ↓
Server State
text

例えば:

ui-store.ts
{
  sidebarOpen: true,
  theme: "dark"
}
ts

はZustand/Reduxに適しています。

一方で:

server-state.ts
{
  users: [...],
  posts: [...],
  products: [...],
  profile: {...}
}
ts

がAPI由来のデータなら、TanStack Queryの方が適していることが多いです。

もちろん、両方のstateが一つのアプリに共存できます。

キャッシュはどう動くのか?#

例えば:

UserProfile.tsx
const { data } = useQuery({
  queryKey: ["user", userId],
  queryFn: () => fetchUser(userId),
})
tsx

TanStack Queryは:

queryKey
ts

を使って、どのデータがキャッシュされているかを識別します。

例えば:

["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を作ります。

App.tsx
import {
  QueryClient,
  QueryClientProvider,
} from "@tanstack/react-query"

const queryClient = new QueryClient()

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <MyApp />
    </QueryClientProvider>
  )
}
tsx

次にqueryを使います:

注目点は:

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} />
tsx

TanStack Queryは:

["user", 123]
text

がQuery Cacheに既に存在することを知っています。

そのためコンポーネントBは真っ白なローディング画面の代わりに、既存のデータを即座に表示できます。

コンポーネントA先にマウントQuery Cache['user', 123]コンポーネントB後にマウントAPI Request(必要なときのみ)

これはTanStack Queryの大きな強みの一つです。

[!NOTE] デフォルトでstaleTimeは0、つまりキャッシュデータは即座にstaleと見なされます。コンポーネントBは古いデータを一瞬で表示し(ローディングなし)、同時にTanStack Queryが裏でrefetchします — このパターンをstale-while-revalidateと呼びます。

Request Deduplication#

よくある状況です:

コンポーネントA ─┐
                 │
コンポーネントB ─┼──→ GET /api/user/123
                 │
コンポーネントC ─┘
text

3つのコンポーネントがほぼ同時にマウントしても、こう送りたくはありません:

GET /api/user/123
GET /api/user/123
GET /api/user/123
text

TanStack Queryはquery keyに基づいてリクエストを共有/重複排除する仕組みを持っています。

概念図:

コンポーネントAQuery Cache['user', 123]コンポーネントBコンポーネントCAPI Requestは1回だけ

staleTime — データが古くなるまでの時間#

とても重要なオプションです。

例えば:

UsersList.tsx
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になる
text

staleTimeはキャッシュ削除時間ではない#

とてもよくある誤解です。

例えば:

staleTime: 60_000
ts

はこういう意味ではありません:

60秒後にキャッシュが削除される。

意味はこうです:

60秒後にデータがstaleと見なされる。

データはキャッシュに残り続けることがあります。

[!WARNING] TanStack Query学習時の一番あるあるな誤解:staleTimeは「データが新鮮な期間」であり、「キャッシュの寿命」ではありません。staleTimeが切れてもデータは古いとマークされるだけ — 次の利用時に裏でrefetchされますが、キャッシュは削除されません。

gcTime#

TanStack Queryにはさらに:

gcTime
ts

があります。以前は:

cacheTime
text

と呼ばれていました。

使われなくなったデータをガベージコレクトするまでの保持時間に関係します。

例えば:

UsersList.tsx
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の例:

ProductsList.tsx
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

フロントエンドのキャッシュはまだこうかもしれません:

John
text

つまりクライアントサイドキャッシュには常にトレードオフがあります:

Performance
    ↕
Freshness
text

APIリクエストを減らしたい:

staleTime ↑
text

データを頻繁に更新したい:

staleTime ↓
text

データのrefetch#

TanStack Queryは様々な状況でrefetchできます。

例えばユーザーがブラウザタブに戻ってきたとき:

UsersList.tsx
useQuery({
  queryKey: ["users"],
  queryFn: fetchUsers,
  refetchOnWindowFocus: true,
})
tsx

概念図:

ユーザーがタブを離れるサーバーデータが変わるユーザーがタブに戻るTanStack Queryが自動refetch

開発者が自前でイベントリスナーを書かなくても、アプリが常に最新に感じられます。

[!NOTE] refetchOnWindowFocusのデフォルトはtrueです — 初心者を驚かせる”important defaults”の一つです:タブを行き来するだけでアプリが勝手にAPIを呼びます。DevToolsに「謎の」リクエストが出たら、こいつが犯人の可能性大です。

キャッシュのInvalidate#

CRUDをするときに非常に便利な機能です。

例えば:

GET /users
POST /users
text

ユーザー作成後:

api.ts
await createUser(data)
ts

こうinvalidateできます:

UsersList.tsx
queryClient.invalidateQueries({
  queryKey: ["users"],
})
ts

するとTanStack Queryはクエリ:

["users"]
text

がstaleになったと判断し、refetchできます。

フロー:

POST /users作成成功invalidate ['users']queryがstaleになるrefetchUI更新

Mutation#

TanStack QueryにはuseMutation()もあります。

CreateUser.tsx
const mutation = useMutation({
  mutationFn: createUser,
})
tsx

使い方:

CreateUser.tsx
mutation.mutate({
  name: "John",
})
tsx

完全な例:

UsersList.tsx
const queryClient = useQueryClient()

const mutation = useMutation({
  mutationFn: createUser,

  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ["users"],
    })
  },
})
tsx

よくあるパターンです:

MutationInvalidateRefetchUpdate UI

Optimistic Update#

さらに高度な機能がOptimistic Updateです。

例えばユーザーがクリック:

❤️ Like
text

こうする代わりに:

Click
 ↓
API request
 ↓
Server response
 ↓
Update UI
text

こうできます:

Click
 ↓
即座にUI更新
 ↓
API request
 ↓
Success → そのまま
Failure → ロールバック
text

ユーザーはアプリが速く感じます。

例えば:

ユーザーがLikeをクリック10 → 11に即時更新POST /likesuccess → そのままerror → 10にロールバック

自前のキャッシュ/state管理が一気に複雑になるユースケースの一つです。

TanStack QueryはLocalStorageにキャッシュするの?#

デフォルトでは:

しません。

クエリキャッシュは主にメモリ上にあります。

例えば:

Browser
   └─JavaScript Memory
           └─TanStack Query Cache
text

ページリロード:

F5
 ↓
JavaScriptメモリ消失
 ↓
Queryキャッシュ消失
text

キャッシュを永続化したい場合、TanStack Queryはこんな仕組みと組み合わせられます:

localStorage
IndexedDB
text

リロード後/オフラインでも一部のサーバーステートを保持したいアプリに適しています。

TanStack QueryはHTTPキャッシュなの?#

この2つを混同してはいけません。

少なくとも2つの異なるキャッシュ層があります:

Browser / HTTP Cache
        ↓
HTTPレスポンスのキャッシュ

TanStack Query
        ↓
アプリケーションレベルのサーバーステートキャッシュ
text

例えば:

React ComponentTanStack Query Cachefetch()Browser HTTP CacheNetworkBackend

TanStack Queryが理解するのは:

queryKey
staleTime
invalidation
mutation
query state
ts

一方HTTPキャッシュはこんなHTTPの仕組みに基づきます:

Cache-Control
ETag
Last-Modified
Age
text

2つの仕組みは共存できます。

自前キャッシュとの比較#

TanStack Queryなし:

cache.ts
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アーキテクチャでは両方使えます:

React AppClient StateZustand — UI stateServer StateTanStack Query — API cache

Zustandの例:

ui-store.ts
{
  sidebarOpen: true,
  selectedTheme: "dark"
}
ts

TanStack Query:

server-state.ts
{
  users: [...],
  posts: [...],
  profile: {...}
}
ts

どちらか選ぶ必要はありません。

TanStack Query vs SWR#

React/Next.jsのもう一つの人気選択肢はSWRです。

両者のコンセプトはかなり似ています:

React
 ├─TanStack Query
 └─SWR
text

両方とも解決するのは:

  • fetching
  • caching
  • revalidation
  • server state

TanStack Queryはより広範なquery/mutationシステムとサーバーステート管理能力を提供する一方、SWRはかなりミニマルなAPIです。

なのでアプリにこういう要素が多いなら:

CRUD
Mutation
Pagination
Infinite Query
Optimistic Update
Cache Invalidation
Complex Server State
text

TanStack Queryは検討に値します。

いつTanStack Queryを使うべき?#

TanStack Queryが特に適しているのは:

Dashboard
Admin panel
E-commerce
CRM
SaaS
Social network
Healthcare application
Education platform
text

特にAPIが多いアプリケーションです。

例えば:

/users
/users/:id
/courses
/courses/:id
/students
/students/:id
/reports
/notifications
text

各コンポーネントが自前で管理する代わりに:

fetch
loading
error
cache
refetch
text

サーバーステートはTanStack Queryに任せられます。

TanStack Queryが必ずしも要らないとき#

アプリが極めてシンプルな場合:

SimpleData.tsx
const [data, setData] = useState()

useEffect(() => {
  fetch("/api/data")
    .then(...)
}, [])
tsx

APIリクエストが数個だけなら、ライブラリ追加のメリットは少ないかもしれません。

同様に、フレームワークが強力なサーバーデータ取得/キャッシュ機構を既に提供し、アプリが主に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.ts
text

例えば:

queries/users.ts
// queries/users.ts

export const usersQuery = () => ({
  queryKey: ["users"],
  queryFn: fetchUsers,
})
ts

コンポーネント:

UserList.tsx
const { data, isPending } = useQuery(
  usersQuery()
)
tsx

APIロジックが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=john
text

query keyの設計が一貫しているほど:

invalidateQueries()
ts

とキャッシュ管理が楽になります。

[!TIP] query keyは総称から詳細へ階層的に設計しましょう:["users"] → ["users", id] → ["users", { page, search }]。そうすればinvalidateQueries({ queryKey: ["users"] })で配下全体をinvalidateできます — ファイルを一つずつ消す代わりにフォルダごと消すようなものです。

完全な例#

フローは明確です:

ComponentuseQuery()Query CacheAPI → ServerMutationPOST /usersinvalidate ['users']refetchQuery Cache → UI updated

まとめ#

ReactでAPIデータのクライアントサイドキャッシュが目的なら、@tanstack/react-queryは検討に値する選択肢です。

覚えておくべき最重要ポイントはこうではありません:

“TanStack Queryはfetch APIライブラリだ。”

こうです:

TanStack Queryはサーバーステート管理とクライアント側キャッシュのシステムだ。

APIが増え始め、こんな問題が出てきたときに特に有効です:

API request duplication
        +
Caching
        +
Stale data
        +
Refetch
        +
Mutation
        +
Cache invalidation
        +
Optimistic update
text

useEffect + useState + Mapで全部自作する代わりに、サーバーステート部分はTanStack Queryに任せられます。

モダンなReactアーキテクチャはこう単純化できます:

UI stateZustand / useStateServer stateTanStack QueryHTTP cacheBrowser / CDNPersistent dataBackend / Database

APIデータをむやみにRedux/Zustandに入れなくて済む考え方でもあります。

参考文献#