TanStack Query
Knowledge base from the official TanStack Query (React Query) v5 documentation — server-state fetching, caching, and mutation library for React. Use when building or debugging data fetching with useQuery/useMutation/useInfiniteQuery, caching/invalidation strategy, optimistic updates, SSR/hydration with Next.js or Remix, Suspense integration, or migrating from React Query v3/v4.
TanStack Query
Package: @tanstack/react-query | Chapters: 80 (34 Guides + 8 Overview + 3 Migrations + ESLint + 5 Persisters + 10 Core API + 19 React API) | Generated: 2026-08-25
How to Use This Skill
- Without arguments — load Core Patterns below for the read/write/invalidate mental model shared across the whole library
- With a concept name — ask about
optimistic updates,infinite queries,SSR,useMutation, etc.; I find and read the matching chapter - With a chapter — ask for
ch030; I load that specific chapter - Browse — ask "what chapters do you have?" to see the full index
When you ask about a topic not covered in Core Patterns below, I will read the relevant chapter file before answering.
Core Patterns & Conventions
Server state, not client state. This library exists for data owned by a server that can go stale — not a replacement for useState/Redux/Zustand for purely local UI state.
The read → write → invalidate loop is the whole mental model. useQuery reads a cache entry keyed by queryKey; useMutation performs a write; queryClient.invalidateQueries({ queryKey }) from the mutation's onSuccess tells stale reads to refresh. Nearly every advanced feature (optimistic updates, infinite queries, prefetching) is a variation on this loop.
Query keys are the dependency array of the fetcher. Every value a queryFn closes over that can change must be in queryKey, or the cache can't tell requests apart. The exhaustive-deps ESLint rule enforces this automatically.
status answers "do we have data?"; fetchStatus answers "is the fetcher running?" They combine independently — a query can be pending and paused (offline, first mount) at once. Use isLoading (not isPending) for "show a spinner because this is genuinely fetching right now."
Defaults are aggressive on purpose. staleTime: 0 (stale immediately), gcTime 5 minutes, retry: 3 with backoff for queries but retry: 0 for mutations — know these before debugging "why does it refetch so much."
Every dependent query is a request waterfall. Prefer flattening the backend API (a combined endpoint) over accepting a chained enabled: !!x fetch when performance matters.
Suspense queries side by side in one component serialize, not parallelize. Reach for useSuspenseQueries/useSuspenseInfiniteQuery combinations the moment more than one lives together.
SSR needs a per-request QueryClient, never a module-scoped one. Prefetch in a loader → dehydrate() → <HydrationBoundary> on the client, with a non-zero staleTime to avoid an immediate refetch.
Install @tanstack/eslint-plugin-query's flat/recommended from day one. It automates enforcement of most of the gotchas above (exhaustive-deps, stable-query-client, no-rest-destructuring, no-void-query-fn, and more).
Chapter Index
Overview / Get Started
| # | Title | Key Concepts |
|---|---|---|
| ch001 | Overview | server state vs. client state, core primitives |
| ch002 | Installation | npm/CDN install, ESLint plugin |
| ch003 | Quick Start | read → write → invalidate loop |
| ch004 | Devtools | Floating/Embedded mode, production lazy-load |
| ch005 | Comparison | vs. SWR, Apollo, RTK Query |
| ch006 | TypeScript | inference, Register, queryOptions |
| ch007 | GraphQL | queryFn as any Promise-returning client |
| ch008 | React Native | onlineManager, focusManager, AppState |
Guides
| # | Title | Key Concepts |
|---|---|---|
| ch009 | Important Defaults | staleTime, gcTime, retry, structural sharing |
| ch010 | Queries | status, fetchStatus |
| ch011 | Query Keys | dependency rule, hashing |
| ch012 | Query Functions | QueryFunctionContext, error contract |
| ch013 | Query Options | queryOptions helper |
| ch014 | Network Mode | online/always/offlineFirst |
| ch015 | Parallel Queries | manual vs. useQueries |
| ch016 | Dependent Queries | enabled, waterfalls |
| ch017 | Background Fetching Indicators | isFetching, useIsFetching |
| ch018 | Window Focus Refetching | focusManager |
| ch019 | Polling | refetchInterval |
| ch020 | Disabling/Pausing Queries | enabled, skipToken, lazy queries |
| ch021 | Query Retries | retry, retryDelay, failureReason |
| ch022 | Paginated / Lagged Queries | keepPreviousData |
| ch023 | Infinite Queries | fetchNextPage, maxPages |
| ch024 | Initial Query Data | initialData, initialDataUpdatedAt |
| ch025 | Placeholder Query Data | placeholderData, isPlaceholderData |
| ch026 | Mutations | mutate/mutateAsync, callbacks, scope |
| ch027 | Query Invalidation | invalidateQueries matching |
| ch028 | Invalidations from Mutations | onSuccess pattern |
| ch029 | Updates from Mutation Responses | setQueryData, immutability |
| ch030 | Optimistic Updates | via UI vs. via cache, rollback |
| ch031 | Query Cancellation | AbortSignal, cancelQueries |
| ch032 | Scroll Restoration | cache stability |
| ch033 | Filters | QueryFilters, MutationFilters |
| ch034 | Performance & Request Waterfalls | serial vs. parallel |
| ch035 | Prefetching & Router Integration | queryClient.query(), router loaders |
| ch036 | Server Rendering & Hydration | dehydrate/HydrationBoundary |
| ch037 | Advanced Server Rendering | Server Components, streaming |
| ch038 | Caching Examples | full cache lifecycle walkthrough |
| ch039 | Render Optimizations | tracked properties, select |
| ch040 | Default Query Function | key-only queries |
| ch041 | Suspense | useSuspenseQuery, error boundaries |
| ch042 | Testing | renderHook, mocking network calls |
Migrations
| # | Title | Key Concepts |
|---|---|---|
| ch043 | Migrating to React Query 3 | QueryClient split |
| ch044 | Migrating to React Query 4 | @tanstack scope, array keys |
| ch045 | Migrating to TanStack Query v5 | gcTime, isPending, object signature |
ESLint Plugin
| # | Title | Key Concepts |
|---|---|---|
| ch046 | ESLint Plugin Query | all 8 rules, flat/recommended |
Plugins (Persisters)
| # | Title | Key Concepts |
|---|---|---|
| ch047 | persistQueryClient | dehydrate/hydrate, gcTime/maxAge |
| ch048 | createSyncStoragePersister | deprecated, localStorage |
| ch049 | createAsyncStoragePersister | recommended, AsyncStorage |
| ch050 | broadcastQueryClient (Experimental) | cross-tab sync |
| ch051 | experimental_createQueryPersister | per-query persistence |
Core API
| # | Title | Key Concepts |
|---|---|---|
| ch052 | QueryClient | bulk operations, defaults |
| ch053 | QueryCache | global callbacks, find/findAll |
| ch054 | MutationCache | global callbacks |
| ch055 | QueryObserver, InfiniteQueryObserver & QueriesObserver | framework-agnostic layer |
| ch056 | streamedQuery (Experimental) | AsyncIterable, chat UIs |
| ch057 | FocusManager | setEventListener, setFocused |
| ch058 | OnlineManager | connectivity detection |
| ch059 | environmentManager | server/client detection |
| ch060 | NotifyManager | batching, scheduling |
| ch061 | TimeoutManager | custom timer providers |
React API
| # | Title | Key Concepts |
|---|---|---|
| ch062 | useQuery | full option/return reference |
| ch063 | useQueries | combine option |
| ch064 | useInfiniteQuery | full option/return reference |
| ch065 | useMutation | full option/return reference |
| ch066 | useIsFetching | app-wide loading indicator |
| ch067 | useIsMutating | app-wide loading indicator |
| ch068 | useMutationState | cross-component mutation access |
| ch069 | useSuspenseQuery | guaranteed-defined data |
| ch070 | useSuspenseInfiniteQuery | Suspense + infinite |
| ch071 | useSuspenseQueries | parallel Suspense fix |
| ch072 | QueryClientProvider | context setup |
| ch073 | useQueryClient | imperative client access |
| ch074 | queryOptions | type-preserving helper |
| ch075 | infiniteQueryOptions | type-preserving helper |
| ch076 | mutationOptions | type-preserving helper |
| ch077 | usePrefetchQuery | Suspense-safe prefetch |
| ch078 | usePrefetchInfiniteQuery | Suspense-safe prefetch |
| ch079 | QueryErrorResetBoundary & useQueryErrorResetBoundary | resettable error boundaries |
| ch080 | Hydration API — dehydrate, hydrate, HydrationBoundary | low-level SSR primitives |
Topic Index
- Caching lifecycle (staleTime/gcTime) → ch009, ch038, ch062
- Devtools → ch004
- ESLint rules → ch046
- Infinite queries → ch023, ch064, ch070, ch075, ch078
- Migration (v3→v4→v5) → ch043, ch044, ch045
- Mutations → ch026, ch028, ch029, ch065, ch068, ch076
- Network/offline handling → ch008, ch014, ch044, ch058
- Optimistic updates → ch030, ch068
- Performance / waterfalls → ch034, ch035, ch039
- Persistence (storage/cross-tab) → ch047–ch051
- Query keys → ch011, ch046
- Render optimizations (select, tracked properties) → ch013, ch039, ch046
- Server rendering / hydration → ch036, ch037, ch080
- Suspense → ch041, ch069–ch071, ch077, ch078, ch079
- Testing → ch042
- TypeScript → ch006, ch013, ch063
Supporting Files
- glossary.md — key terms with definitions
- patterns.md — common implementation patterns and trade-offs
- cheatsheet.md — decision rules, defaults table, migration renames
Scope & Limits
This skill covers the official TanStack Query v5 documentation (React adapter, @tanstack/react-query) as of the fetch date in the source — the framework-agnostic core (@tanstack/query-core) is covered only through the React-facing surface documented here. Other framework adapters (Vue, Solid, Svelte, Angular) are not covered.
The historical v3/v4 migration chapters (ch043, ch044) are condensed — they summarize the major renames and breaking changes rather than reproducing every codemod command and code diff, since most projects on this skill's stack (Next.js/React) are already on v5 or migrating directly to it.
tanstack-query-examples.txt (60 aggregated example READMEs/entry points from the TanStack Query GitHub repo) was used to sanity-check and enrich the Mutations/Optimistic Updates guidance above, not turned into its own chapters — it was mostly minimal per-example boilerplate without much unique conceptual content beyond what the main docs already cover.
Related skills: react-hook-form-docs — a common integration pairing (forms + server-state cache). react-docs, if present in this library, covers the underlying React hooks/rendering model this library builds on.