TanStack Query skill for Claude Code

Server state is a cache of someone else’s data. Do it well and every query has a structured key from one factory, a staleTime chosen on purpose, mutations invalidate exactly the keys they affect, optimistic updates roll back on error, and SSR hands the cache to the client so nothing refetches on hydration.

Step 0 — inspect before changing

npm ls @tanstack/react-query @tanstack/react-query-devtools   # v5 expected (5.x)
grep -rn "new QueryClient" src app | head
grep -rn "queryKey:" src app | head -30                          # how keys are built today
grep -rn "useEffect" src app | grep -i fetch | head              # hand-rolled fetching to replace

v4 → v5 renames to watch for in existing code: cacheTime → gcTime, isLoading (for first load) → isPending, keepPreviousData: true → placeholderData: keepPreviousData, single-object signature only (useQuery({ queryKey, queryFn })), onSuccess/onError removed from useQuery. TanStack ships a v5 codemod (remove-overloads); take the exact jscodeshift command from the official v5 migration guide and review its diff by hand.

QueryClient defaults

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 30_000,             // default 0 = refetch on every mount/focus; rarely what you want
      retry: (count, err) => !(err instanceof HttpError && err.status < 500) && count < 2,
      refetchOnWindowFocus: true,    // keep; it is cheap with a sane staleTime
    },
  },
});

Create the client once per app in the browser (useState(() => new QueryClient()) or module scope in an SPA) and once per request on the server. A module-level client on a server shares one user’s data with the next request.

staleTime by data type

Data	staleTime	Notes
Reference data (countries, plans, feature config)	Infinity or hours	Invalidate on deploy or explicit change
User profile, settings	5 min	Invalidate on the user’s own edits
Lists users edit collaboratively	10–30 s	Plus invalidation after mutations
Dashboards, prices, inventory	0–10 s, maybe refetchInterval	Pause polling when tab hidden (default)
Search-as-you-type results	60 s	Keyed by query term so back/forward is instant

gcTime (default 5 min) is how long an unused cache entry survives. Raise it only for data users navigate back to often.

Query key factory

// src/features/projects/queries.ts
import { queryOptions, infiniteQueryOptions } from "@tanstack/react-query";

export const projectKeys = {
  all: ["projects"] as const,
  lists: () => [...projectKeys.all, "list"] as const,
  list: (filters: ProjectFilters) => [...projectKeys.lists(), filters] as const,
  details: () => [...projectKeys.all, "detail"] as const,
  detail: (id: string) => [...projectKeys.details(), id] as const,
};

export const projectQuery = (id: string) =>
  queryOptions({
    queryKey: projectKeys.detail(id),
    queryFn: ({ signal }) => api.get<Project>(`/projects/${id}`, { signal }),
    staleTime: 60_000,
  });

export const projectsQuery = (filters: ProjectFilters) =>
  queryOptions({
    queryKey: projectKeys.list(filters),
    queryFn: ({ signal }) => api.get<Project[]>("/projects", { params: filters, signal }),
  });

• Every variable the queryFn uses must be in the key. Missing one is the top cause of “shows the wrong user’s/filter’s data”.
• Keys go general → specific so invalidateQueries({ queryKey: projectKeys.lists() }) hits every filter combination at once.
• queryOptions gives type inference for useQuery, prefetchQuery, getQueryData, and setQueryData from one definition. Reuse it everywhere; never retype keys inline.
• Pass signal to fetch so superseded requests are aborted.

Reading data

const { data, isPending, isError, error, isFetching } = useQuery(projectQuery(id));
if (isPending) return <Skeleton />;
if (isError) return <ErrorState error={error} />;
return <ProjectView project={data} refreshing={isFetching} />;

Pattern	How
Dependent query	enabled: !!userId (or skipToken as queryFn for type-safe disabling)
Parallel, dynamic count	useQueries({ queries: ids.map(projectQuery) })
Paginated table without flashing empty	placeholderData: keepPreviousData
Infinite scroll	useInfiniteQuery with initialPageParam and getNextPageParam
Derived/selected slice	select: (d) => d.items.filter(...) (memoize the selector if expensive)
Suspense	useSuspenseQuery(projectQuery(id)) inside <Suspense> + error boundary
Prefetch on hover/intent	queryClient.prefetchQuery(projectQuery(id))
Seed detail from list	initialData: () => getQueryData(lists)?.find(...), with initialDataUpdatedAt

Never copy query data into useState to edit it; keep the form state separate and initialize it from data once (key the form component by id).

Mutations

Default: invalidate, which is simple and correct.

const qc = useQueryClient();
const rename = useMutation({
  mutationFn: (v: { id: string; name: string }) => api.patch(`/projects/${v.id}`, { name: v.name }),
  onSuccess: (updated, v) => {
    qc.setQueryData(projectQuery(v.id).queryKey, updated);         // we have the fresh entity
    return qc.invalidateQueries({ queryKey: projectKeys.lists() }); // returned promise keeps isPending until refetch done
  },
});

Optimistic update when latency is visible and the outcome is near-certain (toggles, reorder, rename):

const toggle = useMutation({
  mutationFn: (v: { id: string; done: boolean }) => api.patch(`/todos/${v.id}`, v),
  onMutate: async (v) => {
    const key = todoKeys.list(filters);
    await qc.cancelQueries({ queryKey: key });                       // stop in-flight refetch overwriting us
    const previous = qc.getQueryData<Todo[]>(key);
    qc.setQueryData<Todo[]>(key, (old) => old?.map((t) => (t.id === v.id ? { ...t, done: v.done } : t)));
    return { previous, key };
  },
  onError: (_err, _v, ctx) => ctx && qc.setQueryData(ctx.key, ctx.previous),   // roll back
  onSettled: (_d, _e, _v, ctx) => qc.invalidateQueries({ queryKey: ctx?.key ?? todoKeys.lists() }),
});

For a single component that only needs to show the pending item, skip cache surgery: render toggle.variables while toggle.isPending (or read across components with useMutationState).

Decision table:

Situation	Approach
Server response returns the full updated entity	setQueryData for detail + invalidate lists
Mutation affects many queries in unknown ways	invalidateQueries({ queryKey: ["projects"] })
Create/delete in a visible list, fast feedback needed	Optimistic insert/remove with rollback
Rapid repeated mutations (typing, sliders)	Debounce the mutate call; set mutationKey and scope to serialize
Mutation result must be confirmed before UI changes (payments)	No optimism; disable button with isPending

SSR hydration

Pattern for every framework: create a request-scoped client, prefetchQuery with the same queryOptions, dehydrate, wrap the client tree in HydrationBoundary, and set staleTime > 0 so the client does not refetch immediately.

// Next.js App Router server component
export default async function Page({ params }: PageProps<"/projects/[id]">) {
  const { id } = await params;
  const qc = getQueryClient();                      // new client per request on the server
  await qc.prefetchQuery(projectQuery(id));
  return (
    <HydrationBoundary state={dehydrate(qc)}>
      <ProjectClient id={id} />
    </HydrationBoundary>
  );
}

Framework specifics (Next.js streaming with pending queries, React Router loaders, Nuxt/Vue, getQueryClient with isServer) are in references/ssr-hydration.md — read it whenever the task involves server rendering.

Gotchas

• isPending vs isFetching: pending means no data yet; fetching means any request in flight including background refetch. Show skeletons on pending, a subtle indicator on fetching.
• Keys are hashed deterministically (object property order does not matter), but they must be JSON-serializable: convert Dates, Maps and class instances to strings first.
• invalidateQueries refetches only active queries by default; inactive ones are marked stale and refetch on next mount. That is usually right.
• Throwing in queryFn is required for errors; fetch does not reject on 4xx/5xx — check res.ok and throw.
• enabled: false queries ignore invalidateQueries; call refetch() explicitly.
• Devtools: <ReactQueryDevtools initialIsOpen={false} /> from @tanstack/react-query-devtools — tree-shaken out of production builds.
• Do not mirror query data into Redux/Zustand. If a client store needs it, read it from the query cache with useQuery and select.

Verification

1. Open React Query Devtools: each screen shows the expected keys, fresh/stale status matches the chosen staleTime, and no duplicate keys for the same resource.
2. Network tab: navigating back to a screen within staleTime makes no request; focus refetch happens only for stale queries.
3. Force a mutation error (devtools offline or a 500 mock) and confirm optimistic changes roll back and an error is shown.
4. SSR: view source shows data in HTML, and the first client render makes no request for prefetched keys.
5. Tests: wrap components in a fresh QueryClient per test with retry: false.

Report format

**Keys:** projectKeys factory (all → lists → list(filters) → detail(id))
**staleTime:** projects 60 s, plans Infinity, dashboard 5 s + refetchInterval 30 s
**Mutations:** rename → setQueryData detail + invalidate lists; toggleTodo optimistic w/ rollback
**SSR:** /projects/[id] prefetched + HydrationBoundary; no client refetch on load
**Verified:** devtools keys, offline rollback test, network tab back-navigation