TanStack Queryとは｜React Query・SWRとの違いと使い分け

TanStack Queryとは｜サーバー状態を扱うためのライブラリ

結論として、TanStack Queryは「他人のデータを借りて表示する」ための道具です。公式ドキュメントは自らをthe missing data-fetching library for web applicationsと表現し、取得・キャッシュ・同期・更新をシームレスにすると説明しています。

条件として、扱う対象はあくまでサーバーが持っているデータに限られます。例外的に、取得したデータから派生する一時的な値を一緒に持たせることはありますが、それは本来の使い方ではありません。

サーバー状態とクライアント状態は別物

ここが最初のつまずきどころです。Reactの状態管理という言葉は、性質のまったく違う2つを巻き込んで語られがちです。

モーダルが開いているかどうかは、サーバーに聞く必要がありません。一方でユーザー一覧は、自分が見ていない間に他の人が更新しているかもしれない。この「勝手に古くなる」性質こそが、キャッシュと再取得の仕組みを必要にします。

TanStack Queryが引き受けるのは右側の列だけです。左側はuseStateやZustandのようなクライアント状態の道具が担当します。両者を一つのストアに詰め込もうとすると設計が破綻しやすく、分けて考えるのが出発点になります。

React Queryから名前が変わった経緯

もともとはReact専用のReact Queryという名前でした。v4でVue・Svelte・Solidなど他のフレームワークにも同じコアを提供するようになり、フレームワーク非依存を示すTanStack Queryへ改称されています。

実務上の注意点として、npmのパッケージ名は今も@tanstack/react-queryのままです。「React Queryの記事」と「TanStack Queryの記事」が混在して見えるのは、この改称が理由です。ネット上の情報を読むときは、v3以前（react-query）とv4以降（@tanstack/react-query）でimport元が違う点に気をつけてください。

具体的に何を肩代わりしてくれるのか

公式が挙げている課題は、キャッシュ管理、同一データへのリクエストの重複排除、古くなったデータのバックグラウンド更新、ページネーションと遅延読み込み、不要になったデータの破棄です。

自前で書くとどうなるか。読み込み中フラグ、エラー、取得済みデータの3つをuseStateで持ち、useEffectの依存配列を調整し、アンマウント後のsetStateを防ぎ、同じAPIを複数コンポーネントが呼ばないよう調整する。この定型処理が、クエリ1本あたり20〜40行ほど積み上がります。TanStack Queryはそれを数行の宣言に置き換えます。

デフォルト挙動を数字で押さえる

最初に覚えるべきは3つの数字です。公式のImportant Defaultsに明記されています。

staleTime 0の意味

デフォルトでは、データを取得した直後からそのデータは stale（新鮮でない）と判定されます。そして stale なクエリは、次の3つのタイミングで自動的に再取得されます。

1. そのクエリを使う新しいコンポーネントがマウントされたとき

2. ブラウザのウィンドウが再フォーカスされたとき

3. ネットワークが再接続されたとき

つまり、何も設定しないまま使うと、タブを切り替えて戻るたびにAPIが叩かれます。開発中は気づきにくく、本番で通信量やレートリミットの問題として表面化しがちです。

対策はシンプルで、データの性質に応じてstaleTimeを明示的に設定することです。マスタデータのように滅多に変わらないものは長め、リアルタイム性が要るものは短め。staleTimeを一度も設定していないプロジェクトでは、意図しない再取得が起きていないかをまず疑ってください。学習用や画面数の少ないアプリならデフォルトのままでも支障は出にくいものの、本番運用ではデータごとの設計が要ります。

gcTimeとstaleTimeを混同しない

v4まではgcTimeがcacheTimeという名前でした。公式はこの改名の理由を「cacheTimeは『データがキャッシュされる時間』と誤解されやすいが、それは正しくない」と説明しています。

• staleTime：そのデータを「新鮮」とみなす時間。この間は再取得しない

• gcTime：誰も使わなくなったキャッシュを保持しておく時間。デフォルト5分

画面を離れて5分以内に戻れば、キャッシュが残っているので一瞬で描画されます（その裏で再取得は走ります）。5分を超えると破棄され、次回はローディングからやり直しになります。

リトライとエラーの見え方

失敗したクエリは3回まで黙って再試行され、そのあいだエラーは表示されません。指数バックオフなので、3回失敗してエラーが出るまでに数秒かかります。

ユーザーに即座にエラーを見せたい画面では、retryを0や1に下げる判断が要ります。逆に、不安定なネットワークを前提とするモバイル向け画面ではデフォルトのままが有効に働きます。

ミニFAQ：デフォルト設定について

設定はクエリごとに書くのですか？

QueryClientを作るときにdefaultOptionsでアプリ全体の既定値を決め、個別に変えたいクエリだけ上書きするのが実務的です。全クエリに同じ設定をコピーして回ると、変更時に漏れます。

staleTimeを無限にすればAPIを叩かなくなりますか？

自動再取得は止まりますが、更新が反映されなくなります。更新処理のあとに該当クエリを明示的に無効化する設計とセットでなければ、画面が古いまま固まります。

SWRとの違いと選び分け

結論を先に書くと、読み取り中心で軽さを重視するならSWR、更新処理が多く細かい制御が要るならTanStack Queryという分かれ方になります。どちらも「stale-while-revalidate」という同じ発想がベースで、できることの大枠は重なります。

SWRの立ち位置

SWRはVercelが開発・保守しているライブラリで、名前はHTTPキャッシュのstale-while-revalidate戦略（RFC 5861で定義）に由来します。キャッシュされたデータを先に返し、裏で再検証する。この一点に設計を絞り込んでいるのが特徴です。

APIの表面積が小さく、学習コストは低めです。Next.jsと同じVercel製という点も、採用理由に挙がることがあります。

機能と設計思想の比較

採用状況をダウンロード数で見る

実際にどれくらい使われているのかを、npmレジストリが公開しているダウンロード統計APIで取得しました。

母集団と取得条件：2026年11月3日〜11月9日の1週間に、npmレジストリから各パッケージがダウンロードされた回数です。CIでのインストールやミラーからの取得、同一プロジェクトの繰り返しビルドをすべて含むため、採用しているプロジェクト数や開発者数を示す数字ではありません。相対的な規模感の参考としてご覧ください。

@reduxjs/toolkitの数字には、RTK Queryを使っていないRedux Toolkit利用分がすべて含まれます。データ取得ライブラリ同士の比較としてはTanStack QueryとSWRの2つを見るのが妥当で、この期間のダウンロード数では3倍程度の開きがありました。週ごとに変動するため、固定の比率として扱わないでください。

執筆時点（2026年11月11日）でnpmに公開されている最新版は、@tanstack/react-queryが5.107.1、swrが2.5.1でした。バージョンは頻繁に更新されるため、導入前にTanStack Queryのリリース一覧とSWRのリリース一覧で最新安定版を確認してください。

選び分けの目安

判断軸を絞ると次のようになります。

• 更新系の操作が画面の中心か：フォーム送信、インライン編集、ドラッグ&ドロップでの並び替えなどが多いならTanStack Query。楽観的更新と自動ロールバックを自前で書く手間が消えます

• キャッシュの寿命を細かく分けたいか：マスタ系は長く、通知系は短く、といった分離が要るならTanStack Query

• バンドルサイズがシビアか：LPや軽量なWebサイトでキロバイト単位を削りたいならSWR

• チームの習熟度：短期参画でメンバーのReact歴が浅い場合、SWRのほうが立ち上がりは早くなります

どちらを選んでも、「サーバー状態を専用の仕組みで扱う」という構造上の利点は得られます。useEffectで自前実装し続けるより、どちらかを入れる判断のほうが影響は大きいと言えます。

ミニFAQ：SWRとの比較について

同じプロジェクトで両方使えますか？

技術的には動きますが、キャッシュが二重になり、どちらが正かを追えなくなります。移行期間を除いて推奨できません。

SWRからTanStack Queryへ乗り換える価値はありますか？

現状で困っていないなら、乗り換え自体が目的になるのは避けたほうが無難です。楽観的更新の自前実装が膨らんでいる、キャッシュの無効化が複雑になっている、といった具体的な痛みがあるときに検討する順序が合理的です。

RTK Query・Apollo Clientとの棲み分け

TanStack Queryだけが選択肢ではありません。既存プロジェクトに入ると、次の2つに出会うことがあります。

RTK Query（Redux Toolkit）

すでにReduxでクライアント状態を管理しているプロジェクトなら、Redux Toolkitに同梱されているRTK Queryが候補になります。ストアが一本化され、Redux DevToolsで通信も含めて追えるのが利点です。

逆に、Reduxを使っていないプロジェクトにRTK Queryのためだけに導入するのは重くなりがちです。

Apollo Client

APIがGraphQLの場合は、Apollo Clientのようなクライアントが正規化キャッシュ（同じIDのオブジェクトを1か所にまとめて持つ仕組み）を提供します。TanStack Queryはクエリ単位でのキャッシュなので、GraphQLの正規化が欲しい場面では噛み合わないことがあります。

APIの形式そのものの違いについては、GraphQLとは？REST APIとの違い・メリット・案件動向・将来性をフリーランス視点で解説とREST APIとは｜設計原則・HTTPメソッド・GraphQL/gRPCとの違いで整理しています。型安全なAPI層を組むならtRPCとは｜型安全なAPIの仕組み・使い方・GraphQL/RESTとの違いも選択肢に入ります。tRPCはTanStack Queryとの併用を前提にした構成が公式に用意されており、組み合わせて使えます。

useEffectベースのコードから移行する

既存案件で最も多いのが、このパターンです。

自前実装で起きがちな問題

よくある症状を挙げます。

• 同じAPIを3つのコンポーネントが別々に呼び、画面表示時に3回のリクエストが飛ぶ

• 一覧から詳細へ移動して戻ると、毎回ローディングからやり直しになる

• 更新処理のあと、一覧の再取得を書き忘れて古いデータが残る

• ローディングとエラーの扱いがコンポーネントごとに微妙に違う

• 依存配列の調整ミスで無限ループが起きる

どれも個別には対処できます。ただし対処がコンポーネントごとに散らばるため、人が増えるほど品質がばらつきます。

段階的に移行する手順

一気に置き換える必要はありません。現実的な順番は次の通りです。

1. QueryClientProviderをアプリのルートに追加する（既存コードには影響しません）

2. 最も再利用されているGETのデータ取得を1本だけ置き換える。重複リクエストが消えることをDevtoolsで確認する

3. 同じデータを使う他のコンポーネントを順に置き換える。この時点で重複排除の効果が出ます

4. 更新処理（POST/PUT/DELETE）をmutationに移し、成功時の無効化対象を明示する

5. 残った自前実装を片付ける

移行の初期に効果が出やすいのは、複数画面で使い回されているマスタ系データです。逆に、1画面でしか使わない単発のAPIは後回しで構いません。

短期参画の案件では、2と3まで進めて効果を見せ、残りをチームに引き継ぐ形が現実的なケースもあります。全面置き換えを前提に見積もると、稼働が足りなくなりがちです。

Next.js App Router・RSCの時代でも必要か

結論から書くと、不要になるわけではありませんが、守備範囲は狭くなります。

Next.jsのApp Routerでは、サーバーコンポーネント側でデータを取得してHTMLを返す構成が基本になります。初回表示に必要なデータは、クライアントのキャッシュ機構を通さずに済みます。

条件として、クライアント側でしか成立しない処理は残ります。

• 無限スクロールやページ送りなど、操作に応じた追加取得

• ポーリングやウィンドウ再フォーカスでの更新

• フォーム送信後の楽観的更新と、失敗時の巻き戻し

• ログイン状態に強く依存し、キャッシュを共有できないデータ

逆に、表示するデータがサーバーコンポーネントでの取得だけで完結し、画面上の追加取得や更新操作がほとんどない構成なら、導入しない判断もあり得ます。ブログやコーポレートサイトのような読み取り専用に近いサイトが該当します。

例外として、SPA構成の管理画面やダッシュボード、React Nativeアプリでは従来通りクライアント側のデータ取得が中心になります。この領域ではTanStack Queryの役割は変わりません。

サーバーコンポーネント側の考え方はReact Server Componentsとは｜仕組みとクライアントとの違い、フレームワーク全体の構成はNext.jsとは？React基盤のフレームワークの特徴・できること・年収・将来性をフリーランス視点で解説にまとめています。

v4からv5で変わった点｜既存コードを触る前に

既存プロジェクトに参画すると、v4のままのコードに出会うことがあります。公式の移行ガイドで示されている主な変更点は次の通りです。

特に影響が大きいのはクエリのコールバック削除です。v4でonSuccessに副作用を詰め込んでいたコードは、そのままでは移行できません。レンダリング後の処理として書き直すか、設計を見直す必要があります。

参画前のヒアリングで「バージョンはいくつか」「v5への移行は済んでいるか」を確認しておくと、見積もりの精度が上がります。v4のまま大量のonSuccessが残っているプロジェクトは、移行工数が想定より膨らみやすい箇所です。

フリーランス案件での位置づけ

募集要件での出方

フリーランスエージェント各社が公開しているReact・Next.js案件の募集要項を確認した範囲では、TanStack Query単体が必須スキルとして前面に出るケースは多くありません。多くは「React／TypeScript／Next.js」のセットの中に、使用技術の一つとして併記される形です。非公開案件を含む網羅的な集計ではなく、公開情報を見た範囲での傾向である点はご承知おきください。

この構造は、フリーランス案件の技術スタック組み合わせ｜求人から読む必須セット2026で整理したスタックの束ね方と同じです。個別ライブラリより、組み合わせで評価されると捉えたほうが実態に合います。

面談で効く話し方

ライブラリ名を知っているかどうかより、判断の根拠を語れるかが差になります。

• なぜそのstaleTimeにしたのか（データの更新頻度と、ユーザーが許容できる古さ）

• queryKeyをどう設計したのか（無効化の単位と一致しているか）

• 自前実装から移行したときに、何がどう改善したのか

「使ったことがあります」で終わらず、どの問題をどう解いたかを1つ具体で持っておくと、技術選定に関与するポジションの話につながりやすくなります。

単価への効き方

TanStack Queryを使えること自体が単価を押し上げるというより、Reactまわりの設計判断ができる人材かどうかの材料として見られます。フロントエンドの単価レンジそのものはReactフリーランス単価相場｜案件動向・スキル別レンジ・獲得の実務とフロントエンドエンジニアのフリーランス単価相場｜経験別・技術別レンジと動向で整理しています。

自分のスキルセットでどのくらいの単価を狙えるか知りたい場合は、無料のフリーランスエンジニア単価診断で市場単価の目安を確認できます。案件そのものを探すならReact案件の一覧から条件を絞るのが早道です。

どの案件を選ぶかの優先順位づけについては、案件の選び方｜フリーランスエンジニアが単価・稼働・スキルで決める優先順位に判断の軸をまとめてあります。

つまずきやすいポイントと対策

queryKeyの設計が雑になる

queryKeyはキャッシュの住所であり、無効化の単位でもあります。ここが雑だと、あとから「一覧だけ更新したいのに全部消える」「消したいのに消えない」という事態になります。

リソース名から始めて、絞り込み条件を配列で足していく形が扱いやすくなります。検索条件をキーに含めておけば、条件違いが別キャッシュとして並びます。

更新後の無効化漏れ

mutationが成功したあと、どのクエリを古い扱いにするかを明示しない限り、画面は更新されません。自前実装のときに再取得を書き忘れたのと同じ問題が、形を変えて出てきます。

対策は、mutationを書くときに「このデータが変わると、どの一覧・どの詳細が影響を受けるか」をコメントではなくコードで列挙しておくことです。

すべてをTanStack Queryに寄せてしまう

フォームの入力途中の値やモーダルの開閉まで押し込むと、かえって複雑になります。サーバー状態とクライアント状態の線引きに戻ってください。

Devtoolsを入れずに悩む

公式のDevtoolsを入れると、どのクエリがいつfetchされ、どのキーでキャッシュされているかが一覧で見えます。再取得が多すぎる、キーが意図と違う、といった問題の多くはこれで一目でわかります。導入していないまま推測でデバッグするのは遠回りです。

導入前チェックリスト

新しくプロジェクトへ入るとき、あるいは自分で導入を決めるときに確認する項目です。

• 扱うデータがサーバー状態か、クライアント状態かを分類した

• バージョンがv4かv5かを確認した（v4ならonSuccessの使用箇所を洗い出した）

• QueryClientのdefaultOptionsでstaleTimeを明示した

• データの性質ごとにstaleTimeを分ける方針を決めた（マスタ系は長め、通知系は短め）

• retryの既定値3回が、対象画面のUXとして妥当か検討した

• queryKeyの命名規則をチームで決めた

• mutation成功時に無効化するクエリを列挙した

• Devtoolsを開発環境に入れた

• SWRやRTK Queryが既に入っていないか確認した（二重管理の回避）

• Next.jsのApp Router構成なら、サーバー側取得とクライアント側取得の境界を決めた

まとめ

TanStack Queryは、サーバーから取得したデータのキャッシュ・再取得・失効管理を肩代わりするライブラリで、useEffectによる自前実装の定型処理を置き換えるための道具です。 SWRとは設計思想の違いで選び分け、更新処理が多いならTanStack Query、軽さ優先ならSWRという判断になります。

要点を整理します。

• サーバー状態とクライアント状態を分けて考える。前者だけがTanStack Queryの守備範囲

• デフォルトはstaleTime 0・gcTime 5分・リトライ3回。本番運用では、データの性質に応じてstaleTimeを明示的に設定する

• 旧名はReact Query。パッケージ名は@tanstack/react-queryのまま

• SWRとの差は機能量と制御の細かさ。両方を同時に入れる構成は避ける

• v4からv5ではクエリのコールバックが削除された。既存案件に入る前にバージョンを確認する

• App Router時代でも、追加取得・ポーリング・楽観的更新の領域では役割が残る

• 案件では単体スキルより、React・TypeScriptとのセットで評価されやすい

次のステップとしては、手元のプロジェクトで最も重複呼び出しが多いGET処理を1本だけ置き換え、Devtoolsで変化を確認してみてください。効果が数字で見えれば、チームへの提案材料にもなります。

参照した一次情報は以下の通りです。

• TanStack Query 公式ドキュメント（Overview）

• TanStack Query 公式ドキュメント（Important Defaults）

• TanStack Query 公式ドキュメント（Migrating to v5）

• SWR 公式ページ（Vercel OSS）