React Query

When to use

Use when writing, reviewing, or upgrading code that touches TanStack Query. It covers auditing existing data-fetching code, replacing useEffect/useState fetching, cache invalidation, optimistic updates, prefetching, infinite scroll, Suspense integration, auth/token-refresh wiring, and MSW test setup.

How it works

Every rule is cited to a page in the TanStack Query v5 docs or explicitly flagged as a community practice. The docs win on conflict — the skill tells you to fetch the cited URL and verify rather than trust its own summary.

SKILL.md stays small and routes to eight reference files: review-checklist.md, coding-standards.md, v5-migration.md, setup.md, query-patterns.md, mutations.md, auth.md, and testing.md.

Modes

The three modes compose — an upgraded v4 project typically wants migration first, then a review pass.

Review

Maps the surface area (imports, QueryClient defaults, every hook call site, queryOptions factories vs. inline keys), then runs a numbered checklist: critical issues C1–C6, warnings W1–W14, and v4→v5 migrations M1–M12. Output is a fixed report format with file:line, a v5 doc URL per finding, and before/after fixes. It will not invent findings to pad the report.

Migrate

Full v4→v5 change list, including the official remove-overloads jscodeshift codemod and the manual renames it does not cover — cacheTime → gcTime, keepPreviousData → placeholderData: keepPreviousData, suspense: true → useSuspenseQuery, useErrorBoundary → throwOnError, <Hydrate> → <HydrationBoundary>, status === 'loading' → 'pending', required initialPageParam, and the removal of onSuccess/onError/onSettled from query configs.

Code

Opinionated rules for new v5 code: global staleTime > 0 with gcTime >= staleTime, module-scope QueryClient, queryOptions factories with generic→specific keys, queryKey treated as a dependency array, response.ok checks in every fetch-based queryFn, select instead of copying to state, skipToken for conditional fetching, returning the invalidateQueries promise from mutation onSuccess, invalidating in onSettled for optimistic updates, useSuspenseQueries for parallel Suspense reads, and a fresh QueryClient per test.

Invoke

/react-query:react-query

Also auto-triggers on imports from @tanstack/react-query or its devtools, and on hooks like useQuery, useMutation, useSuspenseQuery, useInfiniteQuery, useQueries, queryOptions, or skipToken.