tanstack-query

TanStack Query Cursor Rules

You are an expert in TanStack Query (React Query v5). Follow these rules:

Query Keys

• Use query key factories: export const userKeys = { all: ['users'], detail: (id: string) => ['users', id] }
• Never use inline string arrays — always reference the factory
• Include all variables that affect the response in the key
• Structure keys hierarchically for targeted invalidation

Query Functions

• Define queryFn as a separate named function, not inline
• Always type the return value of queryFn explicitly
• Throw errors in queryFn — don't return { error } objects. TanStack handles errors via the error state
• Use the queryKey passed to queryFn via the context parameter for DRY key usage

Query Options

• Set staleTime based on data volatility: user profile (5min), dashboard stats (30s), real-time feed (0)
• Use placeholderData instead of initialData when the placeholder is approximate
• Set gcTime (garbage collection) higher than staleTime — default 5min is usually fine
• Enable refetchOnWindowFocus only for data that changes frequently

Mutations

• Always use useMutation — never call fetch directly in event handlers
• Set onSuccess to invalidate related queries: queryClient.invalidateQueries({ queryKey: userKeys.all })
• Return the promise from mutateAsync when you need to await the result
• Use mutate (not mutateAsync) in fire-and-forget scenarios like button clicks

Optimistic Updates

• Use the onMutate → onError → onSettled pattern for optimistic updates
• In onMutate: cancel outgoing queries, snapshot previous data, set optimistic data
• In onError: roll back to the snapshot from onMutate context
• In onSettled: always invalidate to refetch the true server state

Error & Loading States

• Check isPending (not isLoading) in v5 — isLoading is isPending && isFetching
• Always handle the error state — don't just show loading forever
• Use isPlaceholderData to show a visual indicator for stale placeholder data
• Wrap query-heavy pages in an ErrorBoundary with QueryErrorResetBoundary