---
description: TanStack Query (React Query v5) data-fetching conventions
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---

- Use v5 object syntax: `useQuery({ queryKey, queryFn })`, `useMutation({ mutationFn })`.
- `queryFn` returns a promise that resolves data or **throws** on error (check `res.ok`).
- Query keys are arrays, `JSON.stringify`-serializable, unique: `['todo', 5, { preview: true }]`.
- Include every `queryFn` variable in the key; the key is the dependency array.
- Object key props are order-independent; array item order matters.
- `status` is about data (`pending`/`error`/`success`); `fetchStatus` is about the function (`fetching`/`paused`/`idle`).
- Default `staleTime` is `0`, default `gcTime` is 5 min — they're independent; tune `staleTime`, don't disable refetch flags reflexively.
- Default retry is 3 with exponential backoff; don't disable retries blindly.
- After a successful mutation, `queryClient.invalidateQueries({ queryKey })` or `setQueryData`.
- Don't use `useQuery` for non-server state (form/UI/derived) — use `useState` or derive on render.