tanstack-query_skill

Overview

This skill provides practical, up-to-date guidance for using TanStack Query v5 (React Query) to manage server state in React apps. It covers initialization, QueryClient configuration, useQuery/useMutation patterns, optimistic updates, infinite queries, and common v4→v5 migration pitfalls. Use it to implement reliable data fetching, caching, and error handling with modern React (React 18+).

How this skill works

The skill explains how to create and configure a single QueryClient, wrap your app with QueryClientProvider, and define query and mutation hooks using the v5 object syntax. It shows caching controls (staleTime, gcTime), optimistic update flows (onMutate/onError/onSettled), and how to use DevTools, error boundaries, and infinite queries. It highlights v5 breaking changes and practical workarounds for migration from v4.

When to use it

• Initializing TanStack Query in a React 18+ project
• Configuring QueryClient defaults (staleTime, gcTime, retries)
• Creating reusable useQuery/useMutation hooks and optimistic updates
• Implementing pagination with useInfiniteQuery
• Migrating apps from React Query v4 to v5 and resolving breaking changes
• Debugging stale data, cache issues, or query/mutation errors

Best practices

• Create one QueryClient for the whole app and wrap with QueryClientProvider
• Use the v5 object syntax: useQuery({ queryKey, queryFn }) for consistent typing
• Tune staleTime to reduce unnecessary refetches and use gcTime (v5 rename of cacheTime) to control memory
• Implement optimistic updates with onMutate/onError/onSettled and always snapshot previous cache
• Use descriptive, structured query keys (arrays) so invalidation is predictable
• Keep DevTools inside the provider and use them during development to inspect cache and in-flight operations

Example use cases

• Hook pattern: useTodos() returning useQuery({ queryKey:['todos'], queryFn }) for a todo list
• Optimistic add: useMutation with onMutate snapshot, rollback onError, and invalidate onSettled
• Infinite scrolling: useInfiniteQuery for cursor/page-based pagination with initialPageParam
• Migration checklist: replace cacheTime→gcTime, isLoading→isPending semantics, and convert function syntax to object syntax
• Error handling: QueryErrorResetBoundary + useQueryErrorResetBoundary for granular retry/reset behavior