tanstack-query

TanStack Query (React Query) Skill

Summary

TanStack Query (formerly React Query) is a powerful asynchronous state management library for React that handles server-state fetching, caching, synchronization, and updates. It eliminates the need for manual data fetching boilerplate and provides built-in features like background refetching, optimistic updates, pagination, and intelligent cache management.

When to Use

Use TanStack Query when:

• Fetching data from REST APIs, GraphQL, or tRPC endpoints
• Need automatic background refetching and cache invalidation
• Building real-time dashboards with polling or websocket data
• Implementing infinite scroll or pagination
• Require optimistic UI updates for mutations
• Managing complex server-state synchronization
• Need offline support with cache persistence
• Building applications with frequent data updates

TanStack Query excels at:

• Server-state management (API data, external state)
• Request deduplication and caching
• Stale-while-revalidate patterns
• Loading and error state management
• Prefetching and eager loading
• Parallel and dependent query orchestration

Avoid TanStack Query for:

• Pure client-side state (use Zustand, Jotai, or Context)
• Form state management (use React Hook Form, Formik)
• Simple one-time fetches without caching needs

Quick Start

Installation

npm install @tanstack/react-query
# DevTools (optional but recommended)
npm install @tanstack/react-query-devtools

Basic Setup

// app/providers.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { useState } from 'react';

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // 1 minute
        refetchOnWindowFocus: false,
      },
    },
  }));

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}