tanstack-query

name	tanstack-query
description	TanStack Query (React Query) v5 best practices for data fetching, caching, mutations, and server state management. Use when building data-driven React applications, setting up query configurations, implementing mutations/optimistic updates, configuring caching strategies, integrating with SSR, or fixing v4→v5 migration errors.
metadata	{"tags":"tanstack-query, react-query, data-fetching, caching, mutations, server-state, react, typescript"}

TanStack Query v5

Version: @tanstack/react-query@5.90.x Requires: React 18.0+, TypeScript 4.7+

v5 New Features

• useMutationState — cross-component mutation tracking without prop drilling
• Simplified optimistic updates — via variables from pending mutations, no cache manipulation needed
• throwOnError — renamed from useErrorBoundary
• networkMode — offline/PWA support (online | always | offlineFirst)
• useQueries with combine — merge parallel query results into single object
• infiniteQueryOptions — type-safe factory for infinite queries (parallel to queryOptions)
• maxPages — limit pages in cache for infinite queries (requires bi-directional pagination)
• Mutation callback signature change (v5.89+) — onError/onSuccess/onSettled now receive 4 params (added onMutateResult)

Quick Setup

npm install @tanstack/react-query@latest @tanstack/react-query-devtools@latest

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

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5 min
      gcTime: 1000 * 60 * 60,   // 1 hour
      refetchOnWindowFocus: false,
    },
  },
})

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  )
}

Unified Devtools (Recommended with Multiple TanStack Libraries)

If using Query + Router (or other TanStack libraries), use the unified TanStackDevtools shell instead of individual devtools components:

npm install -D @tanstack/react-devtools

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
import { TanStackDevtools } from '@tanstack/react-devtools'

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      <TanStackDevtools
        config={{ position: 'bottom-right' }}
        plugins={[
          { name: 'TanStack Query', render: <ReactQueryDevtoolsPanel /> },
          // Add more plugins: Router, etc.
        ]}
      />
    </QueryClientProvider>
  )
}

Use *Panel variants (ReactQueryDevtoolsPanel, TanStackRouterDevtoolsPanel) when embedding inside TanStackDevtools.

import { useQuery, useMutation, useQueryClient, queryOptions } from '@tanstack/react-query'

const todosQueryOptions = queryOptions({
  queryKey: ['todos'],
  queryFn: async () => {
    const res = await fetch('/api/todos')
    if (!res.ok) throw new Error('Failed to fetch')
    return res.json()
  },
})

function useTodos() {
  return useQuery(todosQueryOptions)
}

function useAddTodo() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (newTodo: { title: string }) => {
      const res = await fetch('/api/todos', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(newTodo),
      })
      if (!res.ok) throw new Error('Failed to add')
      return res.json()
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })
}

Rule Categories

Priority	Category	Rule File	Impact
CRITICAL	Query Keys	rules/qk-query-keys.md	Prevents cache bugs and data inconsistencies
CRITICAL	Caching	rules/cache-configuration.md	Optimizes performance and data freshness
HIGH	Invalidation	rules/cache-invalidation.md	Ensures stale data is properly refreshed
HIGH	Mutations	rules/mut-basics.md	Ensures data integrity after writes
HIGH	Optimistic Updates	rules/mut-optimistic-updates.md	Responsive UI during mutations
HIGH	Error Handling	rules/err-error-handling.md	Prevents poor user experiences
MEDIUM	Prefetching	rules/pf-prefetching.md	Improves perceived performance
MEDIUM	Infinite Queries	rules/inf-infinite-queries.md	Prevents pagination bugs
MEDIUM	SSR/Hydration	rules/ssr-hydration.md	Enables proper server rendering
MEDIUM	Parallel Queries	rules/parallel-queries.md	Dynamic parallel fetching
LOW	Performance	rules/perf-optimization.md	Reduces unnecessary re-renders
LOW	Offline Support	rules/offline-support.md	Enables offline-first patterns

Critical Rules

Always Do

• Object syntax for all hooks: useQuery({ queryKey, queryFn, ...options })
• Array query keys: ['todos'], ['todos', id], ['todos', { filter }]
• Throw errors in queryFn: if (!res.ok) throw new Error('Failed')
• isPending for initial loading: if (isPending) return <Loading />
• Invalidate after mutations: onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] })
• queryOptions factory: reuse across useQuery, useSuspenseQuery, prefetchQuery
• gcTime (not cacheTime): renamed in v5

Never Do

• v4 array/function syntax: useQuery(['todos'], fetchTodos) — removed in v5
• Query callbacks: onSuccess/onError/onSettled removed from queries (still work in mutations) — use useEffect instead
• isLoading for "no data yet": meaning changed in v5 — use isPending
• enabled with useSuspenseQuery: not available — use conditional rendering
• keepPreviousData: removed — use placeholderData: keepPreviousData
• refetch() for changed parameters: include params in queryKey instead, query auto-refetches

v4→v5 Migration Cheatsheet

v4	v5	Notes
useQuery(['key'], fn, opts)	useQuery({ queryKey, queryFn, ...opts })	Object syntax only
cacheTime	gcTime	Renamed
isLoading (no data)	isPending	isLoading = isPending && isFetching
keepPreviousData: true	placeholderData: keepPreviousData	Import keepPreviousData helper
useErrorBoundary	throwOnError	Renamed
onSuccess/onError/onSettled on queries	Removed	Use useEffect for side effects
pageParam = 0 default	initialPageParam: 0	Required for infinite queries
status: 'loading'	status: 'pending'	Renamed
onError(err, vars, ctx)	onError(err, vars, onMutateResult, ctx)	v5.89+ added 4th param

Known Issues (v5.90.x)

• Streaming SSR hydration mismatch — void prefetchQuery + useSuspenseQuery with conditional isFetching render causes hydration errors. Workaround: await prefetch or don't render based on fetchStatus
• useQuery hydration error with prefetching — useQuery + server prefetch can mismatch isLoading between server/client. Use useSuspenseQuery instead
• refetchOnMount ignored for errored queries — errors are always stale. Use retryOnMount: false in addition to refetchOnMount: false
• useMutationState types — mutation.state.variables typed as unknown due to fuzzy matching. Cast explicitly in select callback
• invalidateQueries only refetches active queries — use refetchType: 'all' to include inactive queries
• Readonly query keys break in v5.90.8 — fixed in v5.90.9+

Key Patterns

// Dependent queries (B waits for A)
const { data: user } = useQuery({ queryKey: ['user', id], queryFn: () => fetchUser(id) })
const { data: posts } = useQuery({
  queryKey: ['posts', user?.id],
  queryFn: () => fetchPosts(user!.id),
  enabled: !!user,
})

// Parallel queries
const results = useQueries({
  queries: ids.map(id => ({ queryKey: ['item', id], queryFn: () => fetchItem(id) })),
  combine: (results) => ({ data: results.map(r => r.data), pending: results.some(r => r.isPending) }),
})

// Prefetch on hover
const handleHover = () => queryClient.prefetchQuery({ queryKey: ['item', id], queryFn: () => fetchItem(id) })

// Infinite scroll
useInfiniteQuery({
  queryKey: ['posts'],
  queryFn: ({ pageParam }) => fetchPosts(pageParam),
  initialPageParam: 0,
  getNextPageParam: (lastPage) => lastPage.nextCursor,
})

// Query cancellation
queryFn: async ({ signal }) => {
  const res = await fetch(`/api/search?q=${query}`, { signal })
  return res.json()
}

// Data transformation
useQuery({ queryKey: ['todos'], queryFn: fetchTodos, select: (data) => data.filter(t => t.completed) })