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.

Quick Setup

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