TanStack Query (React Query) Tutorial: Server State Management

What Is TanStack Query?

TanStack Query (formerly React Query) is the gold standard for managing server state in React applications. Unlike Redux or Zustand which manage client state, TanStack Query is specifically designed for data that lives on a server — fetching it, caching it, keeping it fresh, and synchronizing multiple components that depend on the same data. It eliminates the need to manually manage loading, error, and data states for every API call.

Setting Up TanStack Query

Install with npm install @tanstack/react-query. Wrap your app with QueryClientProvider and create a QueryClient instance. Configure sensible defaults in the QueryClient: staleTime controls when data is considered stale, gcTime controls how long unused data stays in cache. A good starting point is staleTime of 60 seconds for most data and longer for static data like configuration.

useQuery for Data Fetching

The useQuery hook is your primary data fetching tool. Provide a unique queryKey array and a queryFn that returns a promise. TanStack Query handles loading, error, and success states automatically. The queryKey is used for caching — queries with the same key share cached data. Include relevant variables (like user ID or filter parameters) in the key so queries refetch when those change.

useMutation for Data Updates

Use useMutation for POST, PUT, PATCH, and DELETE operations. Provide an onSuccess callback to invalidate related queries with queryClient.invalidateQueries() — this triggers a refetch of stale data after a successful mutation. Use optimistic updates via onMutate for instant UI feedback before the server responds, with rollback on error via onError.

Infinite Queries and Pagination

useInfiniteQuery handles paginated and infinite scroll data. Provide a getNextPageParam function that extracts the next page cursor from each response. Call fetchNextPage() to load more data. The data is available as pages — a nested array of responses. TanStack Query handles deduplication so users who scroll back up see cached previous pages instantly.

DevTools and Debugging

Install @tanstack/react-query-devtools for an in-browser inspector that shows all active queries, their cache status, data, and timing. This is invaluable for debugging stale data issues and understanding cache behavior. In production, queries that fail retry three times by default with exponential backoff — configure retry and retryDelay to match your API's behavior.