TanStack Query v5 実践ガイド【2026年最新】— 型安全なキャッシュ設計・楽観的更新・Next.js App Router 連携

onMutate:  (variables, context) => onMutateResult | Promise<onMutateResult | void>
onSuccess: (data, variables, onMutateResult, context) => unknown
onError:   (error, variables, onMutateResult, context) => unknown
onSettled: (data, error, variables, onMutateResult, context) => unknown

// 旧来の書き方（今も動く）
const queryClient = useQueryClient();
useMutation({
  mutationFn: updateTodo,
  onSettled: () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
});

// 新シグネチャ：useQueryClient 不要、context.client を使う
useMutation({
  mutationFn: updateTodo,
  onSettled: (_data, _err, _vars, _onMutateResult, context) =>
    context.client.invalidateQueries({ queryKey: ["todos"] }),
});

// lib/todos/queries.ts
import { queryOptions } from "@tanstack/react-query";
import { fetchTodos, fetchTodo } from "./api";
import type { Todo, TodoFilters } from "./types";

// クエリキーファクトリ：キーの命名を一元管理し、タイポと不整合を排除する
export const todoKeys = {
  all: ["todos"] as const,
  lists: () => [...todoKeys.all, "list"] as const,
  list: (filters: TodoFilters) => [...todoKeys.lists(), filters] as const,
  details: () => [...todoKeys.all, "detail"] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
};

// queryOptions に定義を集約。戻り値は型情報を保持する
export const todoListOptions = (filters: TodoFilters) =>
  queryOptions({
    queryKey: todoKeys.list(filters),
    queryFn: () => fetchTodos(filters),
    staleTime: 60_000,
  });

export const todoDetailOptions = (id: number) =>
  queryOptions({
    queryKey: todoKeys.detail(id),
    queryFn: () => fetchTodo(id),
  });

import { useQuery, useQueryClient } from "@tanstack/react-query";
import { todoListOptions, todoKeys } from "@/lib/todos/queries";

function TodoList({ filters }: { filters: TodoFilters }) {
  const { data } = useQuery(todoListOptions(filters)); // data: Todo[] | undefined（自動推論）
  // ...
}

// キャッシュ直接読み取りも型安全
const queryClient = useQueryClient();
const cached = queryClient.getQueryData(todoListOptions(filters).queryKey);
//    ^? Todo[] | undefined  — ジェネリクス指定なしで型がつく

// プレフィックス一致：["todos"] で始まるすべて
queryClient.invalidateQueries({ queryKey: todoKeys.all });

// 変数まで指定：特定フィルタのリストだけ
queryClient.invalidateQueries({ queryKey: todoKeys.list({ type: "done" }) });

// 完全一致：そのキー自身のみ（子孫は対象外）
queryClient.invalidateQueries({ queryKey: todoKeys.all, exact: true });

// predicate：各クエリインスタンスを評価する最も柔軟な方法
queryClient.invalidateQueries({
  predicate: (query) =>
    query.queryKey[0] === "todos" &&
    typeof query.queryKey[1] === "object" &&
    (query.queryKey[1] as { version?: number }).version! >= 10,
});

// 定義側：meta でドメインの意味づけを付与
export const useSensitiveTodos = () =>
  useQuery({
    queryKey: todoKeys.list({ type: "sensitive" }),
    queryFn: fetchSensitiveTodos,
    meta: { cacheType: "sensitive" },
  });

// ログアウト時：meta が sensitive のクエリだけを無効化
function handleLogout() {
  queryClient.invalidateQueries({
    predicate: (query) => query.meta?.cacheType === "sensitive",
  });
}

// 設定更新後、非表示のダッシュボードも裏で温めておく（遷移時のスピナーを消す）
queryClient.invalidateQueries({ queryKey: ["dashboard"], refetchType: "all" });

function AddTodo() {
  const { mutate, isPending, variables, isError } = useMutation({
    mutationFn: (text: string) => createTodo(text),
    onSettled: () =>
      queryClient.invalidateQueries({ queryKey: todoKeys.lists() }),
  });

  return (
    <>
      <ul>
        {todos.map((t) => (
          <li key={t.id}>{t.text}</li>
        ))}
        {/* 送信中は variables を半透明で仮表示。失敗時は再送ボタンを出す */}
        {isPending && <li style={{ opacity: 0.5 }}>{variables}</li>}
        {isError && (
          <li style={{ color: "red" }}>
            {variables}{" "}
            <button onClick={() => mutate(variables!)}>再試行</button>
          </li>
        )}
      </ul>
      <button onClick={() => mutate("新しいタスク")}>追加</button>
    </>
  );
}

const pendingTexts = useMutationState<string>({
  filters: { mutationKey: ["addTodo"], status: "pending" },
  select: (mutation) => mutation.state.variables as string,
});

// lib/todos/mutations.ts
import { useMutation } from "@tanstack/react-query";
import { updateTodo } from "./api";
import { todoKeys } from "./queries";
import type { Todo, UpdateTodoInput } from "./types";

export const useToggleTodo = () =>
  useMutation({
    mutationFn: (input: UpdateTodoInput) => updateTodo(input),

    // ① Mutation 実行直前。context.client から QueryClient にアクセス
    onMutate: async (input, context) => {
      const key = todoKeys.lists();

      // 1-1. 進行中の再フェッチを止める（楽観更新がサーバー応答で上書きされるのを防ぐ）
      await context.client.cancelQueries({ queryKey: key });

      // 1-2. ロールバック用に現在のキャッシュを退避
      const previousTodos = context.client.getQueryData<Todo[]>(key);

      // 1-3. キャッシュをイミュータブルに楽観更新
      context.client.setQueryData<Todo[]>(key, (old) =>
        (old ?? []).map((todo) =>
          todo.id === input.id ? { ...todo, ...input } : todo,
        ),
      );

      // 1-4. 戻り値は onMutateResult として onError / onSettled に渡る
      return { previousTodos };
    },

    // ② 失敗時：退避しておいたスナップショットへ確実に戻す
    onError: (_err, _input, onMutateResult, context) => {
      if (onMutateResult?.previousTodos) {
        context.client.setQueryData(todoKeys.lists(), onMutateResult.previousTodos);
      }
    },

    // ③ 成否に関わらず、最後はサーバーの「正」と同期する
    onSettled: (_data, _err, _input, _onMutateResult, context) => {
      context.client.invalidateQueries({ queryKey: todoKeys.lists() });
    },
  });

import { arrayMove } from "@dnd-kit/sortable";
import type { DragEndEvent } from "@dnd-kit/core";

function handleDragEnd(event: DragEndEvent) {
  const { active, over } = event;
  if (!over || active.id === over.id) return;

  // updater 関数を渡し、必ずイミュータブルに新しい配列を返す
  queryClient.setQueryData<Todo[]>(todoKeys.lists(), (old) => {
    if (!old) return old;
    const from = old.findIndex((t) => t.id === active.id);
    const to = old.findIndex((t) => t.id === over.id);
    return arrayMove(old, from, to); // 非破壊的に並び替え
  });
}

// app/get-query-client.ts
import { isServer, QueryClient } from "@tanstack/react-query";

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      // ハイドレーション直後の即時再フェッチを防ぐ。SSR では実質必須
      queries: { staleTime: 60 * 1000 },
    },
  });
}

let browserQueryClient: QueryClient | undefined;

export function getQueryClient() {
  if (isServer) return makeQueryClient(); // リクエストごとに新規生成
  if (!browserQueryClient) browserQueryClient = makeQueryClient();
  return browserQueryClient; // ブラウザでは使い回す
}

// app/todos/page.tsx（Server Component）
import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
import { getQueryClient } from "@/app/get-query-client";
import { todoListOptions } from "@/lib/todos/queries";
import { TodoList } from "./todo-list";

export default async function TodosPage() {
  const queryClient = getQueryClient();

  // 同じ queryOptions を使い回す（DRY）
  await queryClient.prefetchQuery(todoListOptions({ type: "done" }));

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <TodoList />
    </HydrationBoundary>
  );
}

// app/todos/todo-list.tsx（Client Component）
"use client";
import { useQuery } from "@tanstack/react-query";
import { todoListOptions } from "@/lib/todos/queries";

export function TodoList() {
  // プリフェッチ済みのキャッシュから即座に描画される
  const { data } = useQuery(todoListOptions({ type: "done" }));
  return (
    <ul>
      {data?.map((t) => (
        <li key={t.id}>{t.text}</li>
      ))}
    </ul>
  );
}

// get-query-client.ts の defaultOptions に追加
import { defaultShouldDehydrateQuery } from "@tanstack/react-query";

dehydrate: {
  shouldDehydrateQuery: (query) =>
    defaultShouldDehydrateQuery(query) || query.state.status === "pending",
}

"use client";
import { useSuspenseQuery } from "@tanstack/react-query";
import { todoListOptions } from "@/lib/todos/queries";

function TodoList({ filters }: { filters: TodoFilters }) {
  // data は Todo[]（undefined ではない）。isPending / error の分岐は不要
  const { data } = useSuspenseQuery(todoListOptions(filters));
  return (
    <ul>
      {data.map((t) => (
        <li key={t.id}>{t.text}</li>
      ))}
    </ul>
  );
}