description: TanStack Query (React Query v5) data-fetching conventions globs: ["/*.ts", "/*.tsx"] alwaysApply: true
- Use v5 object syntax:
useQuery({ queryKey, queryFn }),useMutation({ mutationFn }). queryFnreturns a promise that resolves data or throws on error (checkres.ok).- Query keys are arrays,
JSON.stringify-serializable, unique:['todo', 5, { preview: true }]. - Include every
queryFnvariable in the key; the key is the dependency array. - Object key props are order-independent; array item order matters.
statusis about data (pending/error/success);fetchStatusis about the function (fetching/paused/idle).- Default
staleTimeis0, defaultgcTimeis 5 min — they're independent; tunestaleTime, 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 })orsetQueryData. - Don't use
useQueryfor non-server state (form/UI/derived) — useuseStateor derive on render.