TanStack Query

TanStack Query (formerly React Query) treats data from a server as a fundamentally different problem from client-side UI state: it’s asynchronous, owned by something outside your app, and can go stale the moment you fetch it. Rather than manually wiring loading flags, error state, and cache invalidation into a general-purpose store, TanStack Query gives every query a key, caches the result, and keeps it fresh with configurable staleness windows, background refetching, and automatic retries — so most apps stop hand-rolling this logic entirely.

@tanstack/react-query is the official React binding and by far the most widely used entry point into the project: it wraps the framework-agnostic @tanstack/query-core engine in hooks like useQuery, useMutation, and useInfiniteQuery, with first-class support for Suspense, SSR/RSC hydration in Next.js, and optimistic updates. The same core also ships adapters for Vue, Svelte, Solid, and Angular, plus an official DevTools panel and persistence plugins for offline-first caching.

What You Get

• useQuery / useSuspenseQuery hooks with automatic caching, request deduplication, and background refetch-on-focus or reconnect
• useMutation for create/update/delete flows, with onMutate/onError hooks for optimistic UI updates and automatic rollback
• useInfiniteQuery and useSuspenseInfiniteQuery for cursor- or offset-based pagination and infinite-scroll lists
• A configurable QueryClient controlling staleTime, gcTime, retry/backoff behavior, and global query defaults
• React Query Devtools for inspecting cache contents, query status, and stale/fresh timers in real time
• SSR and React Server Component support via HydrationBoundary and server-side prefetch helpers for Next.js and Remix
• Persistence adapters (@tanstack/react-query-persist-client) for restoring the cache from localStorage or IndexedDB across page loads

Common Use Cases

• Fetching REST or GraphQL data in a dashboard that needs to stay fresh via refetch-on-window-focus without manual polling code
• Building paginated or infinite-scroll feeds where prior pages must stay cached while new ones load
• Applying optimistic UI updates for likes, edits, or reorders that roll back automatically if the mutation fails
• Prefetching and hydrating server state in a Next.js App Router route so the client never re-fetches data the server already has
• Sharing one in-flight request across many components that ask for the same query key at the same time

Under The Hood

Architecture — @tanstack/react-query is a thin binding: useBaseQuery (in packages/react-query/src/useBaseQuery.ts) reads and subscribes to a Query instance held in a framework-agnostic QueryCache via React’s useSyncExternalStore, delegating all fetching, retry, and staleness logic to @tanstack/query-core. Inside core, Query (query.ts) is a small reducer-based state machine — a private #dispatch method runs a switch-statement reducer over actions like fetch, success, failed, and invalidate to produce the next QueryState — built on a shared Subscribable base class that also underlies QueryObserver, QueryClient, and the mutation equivalents. This same core is what lets the Vue, Svelte, Solid, and Angular adapters exist as separate packages with almost no duplicated logic.

Tech Stack — The whole project is TypeScript in an Nx-managed pnpm monorepo (packages/query-core, packages/react-query, plus adapters for five other frameworks and framework-specific devtools/persist-client packages). Builds run through tsup to dual ESM/CJS output, publint and @arethetypeswrong/cli validate published package correctness, size-limit enforces bundle-size budgets, and changesets drives independent per-package versioning and the GitHub-Actions release pipeline.

Code Quality — query-core and react-query alone carry 60+ Vitest test files (src/__tests__) covering the reducer transitions, retry/backoff timing, and hook behavior under Suspense and StrictMode; ESLint runs with a project-specific @tanstack/eslint-config plus the package’s own published eslint-plugin-query (used to lint query-key usage in consumer codebases too). Error handling is explicit throughout the reducer — failed fetches produce a typed error/fetchFailureReason on state rather than throwing past callers unless throwOnError is set.

API Design — The hook surface is deliberately small: useQuery({ queryKey, queryFn }) is enough to get caching, retries, and refetch-on-focus with zero configuration, and the same options object shape carries through useInfiniteQuery, useMutation, and the Suspense variants so switching between them is a rename, not a rewrite. The steeper part of the learning curve is conceptual rather than syntactic — understanding staleTime vs gcTime, and structuring query keys for correct invalidation — which the docs address directly with a dedicated “Important Defaults” and query-key guide.