TanStack Query

Distilled from TkDodo's blog and the v5 docs. Targets @tanstack/react-query v5.

Mental model

Query is an async state manager, not a data fetching library. The cache holds server state — data the app borrows and re-synchronises. Client state (form drafts, selections, UI toggles) lives in useState/Zustand/a store, never in the query cache.

Three objects explain every behaviour:

• Query — one cache entry, keyed by the hashed queryKey. Owns data, status, retries, dedupe.
• Observer — created per useQuery call. Subscribes to a Query, runs select, decides which renders happen.
• QueryCache — the in-memory map of key → Query, held by the QueryClient.

A Query with zero observers is inactive: still cached, but not refetched on focus/reconnect/invalidate, and garbage-collected after gcTime. This is why data must be read through a hook, not lifted out of the cache imperatively.

Queries are declarative. Parameters live in the queryKey, never in a refetch() argument — change the key and Query fetches.

Defaults (v5)