tanstack-query

name	tanstack-query
description	Expert patterns for TanStack Query v5 (React Query). Caching, mutations, query key factories, and performance optimization.

TanStack Query (React Query) v5

You are an expert in asynchronous state management using TanStack Query v5. You understand the nuances of the "Query" vs "Server State" paradigm and how to efficiently sync your UI with the server.

Triggers

• Files with @tanstack/react-query imports.
• Use of useQuery, useMutation, useInfiniteQuery, or useSuspenseQuery.
• Data fetching in React components.

Core Principles

1. Query Key Management

Always use a Query Key Factory to maintain consistency and avoid typos.

const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: string) => [...todoKeys.details(), id] as const,
}

2. v5 Hook Signatures

TanStack Query v5 uses a single object signature.

• ✅ useQuery({ queryKey, queryFn })
• ❌ useQuery(queryKey, queryFn)

3. Caching vs. Stale Time

• staleTime: How long the data is considered "fresh". Default is 0. Set it higher for data that doesn't change often.
• gcTime: How long inactive data stays in cache before being garbage collected. Default is 5 minutes.

4. Mutations & Optimistic Updates

Always handle onMutate, onError, and onSettled for a smooth UX.

useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    await queryClient.cancelQueries({ queryKey: todoKeys.detail(newTodo.id) })
    const previousTodo = queryClient.getQueryData(todoKeys.detail(newTodo.id))
    queryClient.setQueryData(todoKeys.detail(newTodo.id), newTodo)
    return { previousTodo }
  },
  onError: (err, newTodo, context) => {
    queryClient.setQueryData(todoKeys.detail(newTodo.id), context.previousTodo)
  },
  onSettled: (newTodo) => {
    queryClient.invalidateQueries({ queryKey: todoKeys.all })
  },
})

5. Suspense Support

Use useSuspenseQuery or useSuspenseInfiniteQuery for better integration with React Suspense boundaries. These hooks return data directly (no isLoading check needed at the hook level).

Anti-Patterns

• ❌ useEffect for fetching: Use TanStack Query hooks instead.
• ❌ Manual state for loading: Use isPending or isLoading from the hook.
• ❌ Inline query functions: Extract them for testability and reuse.
• ❌ Over-fetching: Use select to transform or filter data from the response.