Master TanStack Query for React Apps

This skill acts as a production-grade TanStack Query (formerly React Query) expert for React and Next.js, treating it as an asynchronous state manager rather than just a data-fetching library - it handles caching, background updates, request deduplication, pagination, and loading/error states out of the box, with the rule of thumb "never use useEffect to fetch data if TanStack Query is available." Its core pattern is abstracting every useQuery call into a custom hook that encapsulates the fetcher, types, and query key:

export const useUser = (userId: string) => {
  return useQuery({
    queryKey: ['users', userId],
    queryFn: () => fetchUser(userId),
    staleTime: 1000 * 60 * 5,
    enabled: !!userId,
  });
};

Use it when setting up or refactoring data-fetching logic away from useEffect/useState, designing array-based typed query keys, configuring global or per-query staleTime/gcTime/retry, writing useMutation hooks for POST/PUT/DELETE, invalidating the cache after a mutation, implementing optimistic updates for instant UX feedback, or integrating with Next.js App Router Server Components and client-boundary hydration.

Query keys must be arrays where order matters, with a factory pattern recommended for larger apps (issueKeys.all, .lists(), .list(filters), .detail(id)) to avoid misspelling ['users'] vs ['user'] across files. Mutations call queryClient.invalidateQueries on success to mark related data stale. Optimistic updates follow a three-step onMutate/onError/onSettled pattern: cancel outgoing refetches and snapshot the previous value in onMutate, roll back to that snapshot in onError, and always invalidate in onSettled to resync with the server. Next.js App Router integration covers initializing a QueryClientProvider in a client component with staleTime and refetchOnWindowFocus: false set, and server-side prefetching via queryClient.prefetchQuery wrapped in dehydrate/HydrationBoundary so a client component's useQuery reads instantly from the dehydrated cache with no network request on mount. Best practices: use query key factories, set a non-zero global staleTime since the default is 0 (triggering a background refetch on every remount), prefer invalidateQueries over direct setQueryData in most cases, and never sync query data into local React state with a useEffect - derive it during render instead.

Built specifically for React and Next.js App Router, using @tanstack/react-query's QueryClient, QueryClientProvider, dehydrate, and HydrationBoundary for server/client cache handoff. Two troubleshooting cases are documented: an infinite fetch loop traced to an unhandled exception in queryFn combined with the default 3-retry behavior (fixed by setting retry: false while debugging), and staleTime vs gcTime confusion - if gcTime is shorter than staleTime, data is garbage-collected before it even goes stale.

React and Next.js developers building or refactoring asynchronous data-fetching layers who want production patterns for query keys, mutations with cache invalidation, optimistic UI, and SSR hydration rather than ad-hoc useEffect fetching.