TanStack Query Pro -- Data Fetching for Next.js 16

When to Use

Trigger on any mention of: tanstack query, react query, useQuery, useMutation, useSuspenseQuery, prefetch, dehydrate, HydrationBoundary, cache invalidation, optimistic updates, infinite scroll, staleTime, gcTime.

Reference Files

Load the relevant reference file(s) based on what the user needs:

File	Description
`references/setup.md`	Version compatibility (TQ v5.90+ / React 19 / Next.js 16), v4-to-v5 breaking changes (14 entries), migration codemod, installation, QueryClientProvider with `useState` pattern, DevTools setup
`references/ssr-patterns.md`	3 SSR approaches: Prefetch+Dehydrate (recommended), StreamedHydration, Streaming Prefetch (v5.40+). When-to-use decision table
`references/queries.md`	useQuery, useSuspenseQuery, queryOptions helper, skipToken, query key factory, parallel queries, dependent queries
`references/mutations.md`	useMutation, mutate vs mutateAsync, optimistic updates (UI-based and cache-based), invalidation strategies (5 methods)
`references/infinite-queries.md`	useInfiniteQuery, Intersection Observer auto-load, traditional page-number pagination, keepPreviousData
`references/caching.md`	staleTime/gcTime strategies by data type, global defaults, cache lifecycle diagram (FRESH -> STALE -> INACTIVE -> GC)
`references/performance.md`	select transforms, placeholderData, hover/focus prefetching, structural sharing, query cancellation with AbortSignal
`references/typescript.md`	Type inference patterns, custom error types, queryOptions for type-safe sharing, skipToken conditional queries, mutation type safety
`references/testing.md`	Test wrapper/utilities, renderHook for hooks, mutation testing, component testing with renderWithQuery
`references/errors.md`	18 documented errors (TQ-001 through TQ-018) with exact messages, causes, and fixes
`references/cviet-patterns.md`	CViet project setup (as-is), expanded query key factory, AI enhancement caching, dashboard SSR prefetch, CV auto-save with debounce, billing/plan hooks
`references/quick-reference.md`	Query status flags table, hook quick reference, QueryClient methods, common import patterns, all sources

Error Quick Lookup

ID	Error	Fix
TQ-001	No QueryClient set	Wrap in QueryClientProvider, use `useState` for client
TQ-002	Missing queryFn	Always provide queryFn to useQuery
TQ-003	Hydration mismatch	Ensure same data on server/client with dehydrate
TQ-004	Query data undefined	queryFn must return a value, check `res.ok` and throw
TQ-005	Stale data after mutation	`queryClient.invalidateQueries({ queryKey })`
TQ-006	Infinite re-renders	Move queryFn outside component, stable queryKey
TQ-007	undefined.length in infinite	Use distinct keys for useQuery vs useInfiniteQuery
TQ-008	Data disappears on nav	Create QueryClient in `useState`, raise gcTime
TQ-009	gcTime 0 hydration error	Use `gcTime: 2000` minimum
TQ-010	fetch no throw on 4xx/5xx	Custom fetch wrapper that throws on error status
TQ-011	QueryKey type error	Use `as const` on query key arrays
TQ-012	Rendered more hooks	Use `enabled` or `skipToken`, never conditional hooks
TQ-013	Refetch overwrites optimistic	Cancel queries in `onMutate` before setting cache
TQ-014	Suspense hydration error	Prefetch on server or use ReactQueryStreamedHydration
TQ-015	Module-level QueryClient	Create inside `useState` callback, not module scope
TQ-016	DevTools missing in prod	Intentional; import from devtools/production if needed
TQ-017	isLoading always false	Renamed in v5: use `isPending` instead
TQ-018	cacheTime not valid	Renamed in v5: use `gcTime` instead

Key Patterns

SSR Prefetch (Recommended)

// Server Component
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'

export default async function DashboardPage() {
  const queryClient = new QueryClient()
  await queryClient.prefetchQuery({ queryKey: ['cvs'], queryFn: fetchCVs })
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <CVList />
    </HydrationBoundary>
  )
}

Query Key Factory

export const cvKeys = {
  all: ['cvs'] as const,
  lists: () => [...cvKeys.all, 'list'] as const,
  detail: (id: string) => [...cvKeys.all, 'detail', id] as const,
}

Optimistic Update (Cache-Based)

onMutate: async (newData) => {
  await queryClient.cancelQueries({ queryKey: ['cvs'] })
  const previous = queryClient.getQueryData(['cvs'])
  queryClient.setQueryData(['cvs'], (old) => /* update */)
  return { previous }
},
onError: (err, vars, ctx) => queryClient.setQueryData(['cvs'], ctx.previous),
onSettled: () => queryClient.invalidateQueries({ queryKey: ['cvs'] }),

tanstack-query-pro