AGENTS.md — TanStack Query (v5)

Conventions for @tanstack/react-query v5. Grounded in the official docs.

• Use the v5 object syntax: useQuery({ queryKey, queryFn }), useMutation({ mutationFn }).
• A query = a unique key + a function returning a promise that resolves data or throws on error.
• fetch doesn't throw on HTTP errors — check res.ok and throw, or the query won't enter the error state.
• Query keys are arrays, JSON.stringify-serializable, and unique to the data: ['todos'], ['todo', 5, { preview: true }].
• Put every variable the queryFn uses in the key; changing it refetches automatically. The key is the dependency array.
• Object key props are hashed order-independently; array item order matters.
• status (pending/error/success) is about data; fetchStatus (fetching/paused/idle) is about the running function. Use both.
• Default staleTime is 0 (stale immediately); stale queries refetch on mount, window focus, and reconnect. Tune staleTime instead of disabling refetch flags.
• Default gcTime is 5 minutes for inactive queries. Freshness (staleTime) and retention (gcTime) are independent.
• Failed queries retry 3 times with exponential backoff by default — don't disable retries blindly.
• Results are structurally shared (stable references for unchanged data); don't re-memoize data.
• Use useMutation for create/update/delete; trigger with mutate(variables).
• After a successful mutation, queryClient.invalidateQueries({ queryKey }) (in onSuccess/onSettled) or setQueryData.
• Callback order: onMutate → onSuccess/onError → onSettled. Use mutateAsync only when you need to await at the call site.
• Don't use TanStack Query for non-server state (form/UI/derived values) — that belongs in useState or derived on render.