TanStack Query Best Practices

Patterns and conventions for TanStack Query v5 data fetching, caching, and mutations in React/TypeScript projects.

Core Mental Model

Server state vs client state — TanStack Query manages server state (data from APIs). Do not duplicate it into useState or Redux; use those only for client state (UI state, form drafts).
Stale-while-revalidate — Cached data is served immediately, then validated in the background. Users see data fast; freshness happens transparently.
Query keys = dependency arrays — Every variable that affects fetching belongs in the key. When the key changes, TanStack Query refetches automatically.
Declarative over imperative — Drive refetching by changing key values (state, filters, IDs), not by calling refetch() with new parameters.
Cache is the single source of truth — The query cache is the authoritative store for all server state. Read from it; never copy it elsewhere.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'