17 lines | 1.1 KB

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.