tanstack-query_skill

Overview

This skill helps React developers manage server state with TanStack Query v5. It covers setting up QueryClient, using useQuery/useMutation/useInfiniteQuery, optimistic updates, and v4→v5 migration fixes. Practical tips address renamed options and API changes to avoid common runtime errors.

How this skill works

It configures a centralized QueryClient and wraps your app with QueryClientProvider so hooks can read and update cached server data. The skill demonstrates object-style hook calls (useQuery({queryKey,queryFn})), mutation callbacks (onMutate,onSuccess,onError,onSettled), optimistic updates, and infinite loading via useInfiniteQuery. It also explains key v5 changes like gcTime, isPending, and removed helpers so you can migrate safely.

When to use it

• Setting up data fetching and caching in a new React 18 app
• Migrating a codebase from TanStack Query v4 to v5
• Fixing runtime errors related to object-syntax requirements in hooks
• Implementing optimistic UI for fast mutation feedback
• Adding infinite scroll or paginated queries with useInfiniteQuery
• Tuning cache behavior and refetch policies globally

Best practices

• Always wrap the app with a single QueryClientProvider and include DevTools inside it
• Use object syntax for hooks: useQuery({queryKey,queryFn}) and useMutation({mutationFn,...})
• Prefer sane defaults: set staleTime to avoid excessive refetches and use gcTime (v5) instead of cacheTime
• Use optimistic updates with onMutate/onError/onSettled and snapshot previous cache to allow rollbacks
• Structure query keys as arrays and include params for deterministic cache entries
• Use QueryErrorResetBoundary or React error boundaries to handle query errors gracefully

Example use cases

• Create reusable query hooks for lists and item details: useTodos() and useTodo(id)
• Add a todo with optimistic UI and rollback on failure using useMutation and onMutate
• Migrate existing v4 code: replace cacheTime→gcTime, isLoading→isPending where appropriate, and switch to object syntax
• Implement infinite scrolling for a feed with useInfiniteQuery and getNextPageParam
• Configure QueryClient defaultOptions to control retries, staleTime, refetchOnWindowFocus, and gcTime