TanStack Query の導入

シンプルな fetch でも一覧取得と追加は実装できましたが、コード量が多く、useState と useEffect の組み合わせで「ロード中/エラー/再取得/二重送信防止」を自前で書く必要がありました。同じ処理を TanStack Query で書き直すと、フックの呼び出しだけで大半の状態管理を任せられます。ここでは導入手順から useQuery / useMutation の書き換えまでを進めます。

1. TanStack Queryとは

TanStack Query(旧 React Query)は、Reactでサーバから取得したデータを扱うためのライブラリです。fetch そのものを置き換えるものではなく、fetch で取得したデータの キャッシュ・再取得・ロード状態管理 を統合的に管理してくれる立ち位置になります。公式には「サーバ状態管理ライブラリ」と紹介されており、useState で扱う「クライアント側の一時的な状態」とは別物として扱われます(Overview(TanStack Query公式ドキュメント) に「TanStack Query (formerly known as React Query) is often described as the missing data-fetching library for web applications」と記載があります)。

導入すると、以下のような機能が組み込みで手に入ります。

  • 同じ queryKey に対する取得結果をメモリキャッシュし、複数コンポーネントで共有できる
  • ウィンドウにフォーカスが戻ったタイミングなどで自動的に再取得できる
  • 一定時間キャッシュを鮮度あり(fresh)として扱い、無駄な再取得を減らせる
  • useMutation と invalidateQueries の組み合わせで「更新後に一覧を再取得」を宣言的に書ける

小さな画面では過剰な機能となることもありますが、複数画面で同じデータを共有する規模になると、シンプルな fetch に比べてコードが大幅に読みやすくなります。

2. TanStack Query のインストール

TanStack Queryはnpmパッケージとして配布されているため、プロジェクトに追加するにはまずインストールが必要です。開発サーバは以降のハンズオンでも起動したまま使うので、実行中のターミナルは停止せず、Visual Studio Codeで新しいターミナルを開いてインストールコマンドを実行します。プロジェクト直下で以下のコマンドを実行します。

npm install @tanstack/react-query

インストールが完了すると、package.json の dependencies に以下のように @tanstack/react-query が追加されます。バージョン部分はインストール時点の最新版になるため、値は変わる場合があります。

"dependencies": {
  ...
  "@tanstack/react-query": "^5.62.0"
},

3. QueryClientProvider の用意

TanStack Queryを使うには、アプリケーションのルートで QueryClientProvider を差し込む必要があります。ただし、QueryClientProvider はClient Component専用のため、Server Componentである app/layout.tsx から直接使うとエラーになります。そこで、Providerだけを切り出したClient Component を用意して、layout.tsx から呼び出す形にします。

app/providers.tsx を作成します。Visual Studio Codeのエクスプローラーで app フォルダを右クリックし、「新しいファイル」から providers.tsx を新規作成します。

frontend-fetch-demo
├── app/
│   ├── api/
│   │   └── tasks/
│   │       └── route.ts
│   ├── tasks/
│   │   └── page.tsx
│   ├── layout.tsx
│   ├── page.tsx
│   └── providers.tsx         ← このファイルを作成
└── ...

QueryClientProvider を使うときは、QueryClient を1つ作り、それを QueryClientProvider に渡して配下のコンポーネントを包む形が基本です。書き方は以下のとおりです。

"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        // キャッシュや再取得の初期設定
      },
    },
  }));

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
}

以下は、staleTime を30秒、refetchOnWindowFocus をオフに設定した実装例です。作成した providers.tsx に以下の内容を記述して保存します。

"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 30 * 1000,
            refetchOnWindowFocus: false,
          },
        },
      }),
  );

  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
}

コードを解説します。

"use client";

QueryClientProvider はブラウザで動くContext Providerのため、このファイル全体をClient Componentとしてマークします。

const [queryClient] = useState(
  () =>
    new QueryClient({
      defaultOptions: {
        queries: {
          staleTime: 30 * 1000,
          refetchOnWindowFocus: false,
        },
      },
    }),
);

QueryClient はTanStack Queryのキャッシュ本体です。useState の初期値関数の中で作ることで、コンポーネントが再レンダーされてもインスタンスが1つに保たれます(トップレベルの new QueryClient() はReactの厳格な環境で二重生成される可能性があるため避けます)。

staleTime は「取得したデータが fresh とみなされる期間」で、この間はコンポーネントの再マウントがあってもネットワーク再取得がスキップされます。ここでは動作を追いやすくするために30秒に設定しています。refetchOnWindowFocus は、他のタブから戻ってきたときに自動再取得するかの設定で、この章ではオフにして動きを分かりやすくしています。

続いて、app/layout.tsx から Providers を呼び出します。app/layout.tsx を開き、以下の内容に置き換えます。

import type { Metadata } from "next";
import { Providers } from "./providers";
import "./globals.css";

export const metadata: Metadata = {
  title: "frontend-fetch-demo",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ja">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

コードを解説します。

import { Providers } from "./providers";

先ほど作成した Providers コンポーネントを読み込みます。layout.tsx と providers.tsx は同じ app/ 直下にあるため、相対パスの ./providers でimportできます。

<body>
  <Providers>{children}</Providers>
</body>

<body> の直下で children を <Providers> で包んでいます。これで配下のすべてのページから useQuery / useMutation が使えるようになります。layout.tsx そのものはServer Componentのままにできるので、"use client" は書きません。Providerだけを切り出したClient Componentを噛ませる のがApp RouterでTanStack Queryを使うときの定番パターンです。

4. useQueryによる一覧取得の書き換え

Providerが差し込めたので、実際のページ側でも useState + useEffect の組み合わせを useQuery / useMutation に置き換えて、TanStack Queryの書き方を体験します。一覧取得と作成の両方をまとめて書き換え、シンプルな fetch で書いていた状態管理コードがどれだけ減るかを見比べられる形にします。

useQuery は取得系、useMutation は書き込み系に使います。書き方は以下のとおりです。

// 取得系: useQuery
const { data, isPending, isError, error } = useQuery({
  queryKey: ["キャッシュキー"],
  queryFn: 取得関数,
});

// 書き込み系: useMutation
const mutation = useMutation({
  mutationFn: (引数) => 書き込み関数(引数),
  onSuccess: () => {
    // 成功時の処理(例: invalidateQueriesで再取得を促す)
  },
});
mutation.mutate(引数);

以下は、/api/tasks に対する一覧取得と追加を useQuery / useMutation で書き直した実装例です。app/tasks/page.tsx を、TanStack Queryを使った以下の内容に置き換えます。

"use client";

import {
  useMutation,
  useQuery,
  useQueryClient,
} from "@tanstack/react-query";
import { useState } from "react";

type Task = {
  id: number;
  title: string;
  done: boolean;
};

async function fetchTasks(): Promise<Task[]> {
  const res = await fetch("/api/tasks");
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

async function createTask(title: string): Promise<Task> {
  const res = await fetch("/api/tasks", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ title }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

export default function TasksPage() {
  const queryClient = useQueryClient();
  const [title, setTitle] = useState("");

  const {
    data: tasks,
    isPending,
    isError,
    error,
  } = useQuery({
    queryKey: ["tasks"],
    queryFn: fetchTasks,
  });

  const createMutation = useMutation({
    mutationFn: (newTitle: string) => createTask(newTitle),
    onSuccess: () => {
      setTitle("");
      queryClient.invalidateQueries({ queryKey: ["tasks"] });
    },
  });

  const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    if (!title.trim()) return;
    createMutation.mutate(title);
  };

  return (
    <main style={{ padding: 24 }}>
      <h1>タスク一覧</h1>

      <form onSubmit={handleSubmit} style={{ marginBottom: 16 }}>
        <input
          type="text"
          value={title}
          onChange={(e) => setTitle(e.target.value)}
          placeholder="新しいタスクを入力"
          disabled={createMutation.isPending}
        />
        <button
          type="submit"
          disabled={createMutation.isPending || !title.trim()}
        >
          {createMutation.isPending ? "送信中..." : "追加"}
        </button>
      </form>

      {isPending && <p>読み込み中...</p>}
      {isError && <p>エラー: {error.message}</p>}

      <ul>
        {tasks?.map((task) => (
          <li key={task.id}>
            {task.title} {task.done ? "(完了)" : ""}
          </li>
        ))}
      </ul>
    </main>
  );
}

コードを解説します。

async function fetchTasks(): Promise<Task[]> {
  const res = await fetch("/api/tasks");
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

TanStack Query自体はHTTP通信を行いません。「データを取ってくる関数」を自分で用意して、それを useQuery に渡す形になります。fetch を素で使うのはこれまでと同じで、useQuery が担うのはその結果の管理です。

const {
  data: tasks,
  isPending,
  isError,
  error,
} = useQuery({
  queryKey: ["tasks"],
  queryFn: fetchTasks,
});

useQuery にキャッシュのキー(queryKey)と、取得関数(queryFn)を渡します。queryKey は文字列や数値の配列で、同じキーで呼ばれたクエリは1つのキャッシュを共有します。返り値の data が成功時のデータ、isPending がロード中フラグ、isError / error がエラー情報です。 useState + useEffect で書いていた3つの状態が、フック1個の戻り値になっているのが分かります。

const createMutation = useMutation({
  mutationFn: (newTitle: string) => createTask(newTitle),
  onSuccess: () => {
    setTitle("");
    queryClient.invalidateQueries({ queryKey: ["tasks"] });
  },
});

書き込み系の処理は useMutation を使います。mutationFn に「実行する関数」を渡し、成功時の処理を onSuccess に書きます。queryClient.invalidateQueries({ queryKey: ["tasks"] }) は「tasks キーのキャッシュを古いものとしてマークし、再取得を促す」動きになります。これで useQuery 側は自動的に再取得 され、一覧が最新化されます。シンプルな fetch では loadTasks() を明示的に呼び直していた部分が、宣言的な invalidateQueries に置き換わりました。

createMutation.mutate(title);

useMutation の実行は .mutate(引数) で行います。 .mutate は結果を待たずに戻るため、状態は createMutation.isPending などから拾います。.mutateAsync(...) を使うとPromiseとして待つこともできますが、通常は .mutate で十分です。

5. ブラウザでの動作確認

ブラウザで http://localhost:3000/tasks を開くと、初回表示で「読み込み中...」と表示された後、初期表示の2件のタスクが並んだ状態になります。

入力欄に 新規Task と入力して「追加」ボタンを押します。

送信が完了すると、入力したタスクが一覧の末尾に追加されます。この動きが確認できれば、TanStack Query による取得・送信が正しく動いています。

シンプルな fetch 版と比べて、コンポーネントのコード量が減り、状態管理のロジックがフックの呼び出しにまとまっているのが体感できるはずです。

💡 ポイント
staleTime: 30 * 1000 の効果で、30秒以内に別のページから戻ってきても再取得は走りません。挙動を試したい場合は、staleTime を 0 に落とすと、コンポーネントがマウントされるたびに再取得されるようになります。設定値ひとつで挙動を切り替えられるのが TanStack Query の魅力の一つです。