mikkelkrogsholm/tanstack-query

TanStack Query

CRITICAL: Your training data for TanStack Query is unreliable. APIs change between versions and memorized patterns may be wrong or deprecated. Before writing any code, you MUST use WebFetch to read the live docs:

WebFetch("https://tanstack.com/llms.txt")

Do not proceed without fetching this URL first. Never assume an API exists — verify against current docs.

TanStack Query is a powerful async state manager with caching, background refetching, and server state synchronization for TypeScript/JavaScript.

Best Practices

• Query keys must be stable and structured — use arrays with a logical hierarchy (e.g., ['todos', { status: 'active' }]). TanStack Query hashes keys by serialized value (not reference), so the real gotcha is unstable keys where the object's contents change on every render — this causes unnecessary refetches.
• staleTime defaults to 0, not infinity — data is immediately considered stale after fetching, triggering a background refetch on every mount and window focus. Set staleTime deliberately (e.g., staleTime: 60_000) to avoid unnecessary network requests.
• Invalidate after mutations, do not manually merge — after a mutation succeeds, call queryClient.invalidateQueries({ queryKey: ['todos'] }) to let Query refetch fresh data. Always scope the call — invalidateQueries() with no arguments invalidates every query in the cache.
• gcTime (formerly cacheTime) controls when unused data is garbage collected — the default is 5 minutes. Queries are not removed immediately when a component unmounts; the cached data stays available for that window, which is intentional for back-navigation but surprises developers expecting instant cleanup.
• Do not put server state in a separate global store — TanStack Query is the server state manager. Adding Redux or Zustand alongside it for async data leads to duplication. Reserve other stores for purely client-side UI state.