TanStack Query Development

Use this capability whenever you write or review code that reads or writes server state — data another system owns, which the client holds only as a cache. It owns how that data is organized: where a query or mutation is defined, what identifies it in the cache, when it refetches, what invalidates it, how a failure surfaces, and how all of it is tested.

Server state is not application state. It goes stale on its own, it can be refetched, and two components asking for it should get one request. That is the whole reason this layer exists, and the rules below follow from it.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Baseline and Scope

TanStack Query v5 is the baseline, verified against 5.101.4 on 2026-08-02 against the React adapter's documentation. React 18 and TypeScript 5.4 are the minimums. Types ship as patch releases rather than majors, so a project should pin the patch version and expect type changes between them.

The React adapter is the only one in scope. The Vue, Svelte, Solid, Angular, Lit, and Preact adapters version independently of it and are out of scope entirely — no rule, no comparison.

Both web and React Native are in scope. Native needs wiring the browser gets for free; react-native.md covers it, and skipping it silently disables two defaults rather than failing loudly.

Two references are conditional. server-rendering.md applies only where the host renders on a server or uses React Server Components; offline-persistence.md applies only where the host's requirements call for offline continuity. Load neither by default.

Version-sensitive claims name their version. Behaviour has moved inside v5 — the mutation callback signatures gained an onMutateResult and a context argument, and staleTime: 'static', subscribed, and environmentManager are all recent additions. Treat an unversioned claim about this library, here or anywhere else, as suspect and check it against the installed version's documentation.