``` ## Pattern: Suspense Queries ```tsx 'use client'; import { useSuspenseQuery } from '@tanstack/react-query'; export function ProjectDetails({ id }: { id: string }) { const { data } = useSuspenseQuery({ queryKey: ['project', id], queryFn: () => fetch(`/api/projects/${id}`).then(r => r.json()), }); // data is guaranteed non-null return

{data.name}

; } // parent component }> ``` `useSuspenseQuery` integrates with React Suspense. Cleaner than handling `isLoading`. Pair with error boundaries: ```tsx }> }> ``` ## Pattern: Query Keys — Organize Them ```ts // lib/queryKeys.ts export const queryKeys = { projects: { all: ['projects'] as const, list: (filters: ProjectFilters) => [...queryKeys.projects.all, 'list', filters] as const, detail: (id: string) => [...queryKeys.projects.all, 'detail', id] as const, }, user: { me: ['user', 'me'] as const, settings: ['user', 'settings'] as const, }, }; // usage useQuery({ queryKey: queryKeys.projects.list({ status: 'active' }), queryFn: ... }); // invalidate all project queries: qc.invalidateQueries({ queryKey: queryKeys.projects.all }); // invalidate only one specific filter: qc.invalidateQueries({ queryKey: queryKeys.projects.list({ status: 'active' }) }); ``` Hierarchical query keys = surgical invalidation. The factory makes it type-safe. ## Pattern: Polling / Background Refetch ```tsx useQuery({ queryKey: ['notifications'], queryFn: fetchNotifications, refetchInterval: 30_000, // poll every 30s while mounted refetchIntervalInBackground: false, // pause when tab hidden (default) }); ``` For real-time SSE/WebSocket data, skip polling — use `setQueryData` from the socket handler to push updates into the cache. ## Pattern: Dependent Queries ```ts const { data: user } = useQuery({ queryKey: ['user'], queryFn: getUser }); const { data: projects } = useQuery({ queryKey: ['projects', user?.teamId], queryFn: () => fetchProjects(user!.teamId), enabled: !!user?.teamId, // wait for user to load }); ``` `enabled: false` blocks the query until the condition is true. ## Pattern: Manual Cache Updates When you know the result of a mutation, write directly to the cache instead of refetching: ```ts const mutation = useMutation({ mutationFn: updateProject, onSuccess: (updated) => { qc.setQueryData(['projects', updated.id], updated); qc.setQueryData(['projects'], (old: Project[] = []) => old.map(p => p.id === updated.id ? updated : p) ); }, }); ``` Saves a round-trip and feels instant. Combine with `invalidate` if the server might have computed extra fields. ## Using with Next.js - Provider lives in a `'use client'` component imported by `app/layout.tsx`. - `QueryClient` must be a per-request instance on the server (see `getQueryClient`). - `HydrationBoundary` lets server-prefetched data flow into the client cache. - Server Actions can be called from `mutationFn` directly. - For initial RSC data without TanStack: pass it as `initialData` to `useQuery`: ```tsx useQuery({ queryKey, queryFn, initialData: serverData }); ``` - React 19 `use()` hook + Suspense covers single-fetch cases without TanStack overhead. ## Examples ### Example 1: Admin table with filters URL params drive filters; query key includes filter object; click filter → URL updates → query re-runs → cached pages stay warm if returning to same filter. ### Example 2: Optimistic todo toggle Click checkbox → optimistically flip in cache → mutation runs → on error rollback → on success invalidate. Feels instant. ### Example 3: Infinite chat feed `useInfiniteQuery` with cursor pagination. Scroll up → load older messages. New messages via WebSocket → `setQueryData` prepends to first page. ## Troubleshooting ### Hydration mismatch on server-prefetched data Cause: server-rendered HTML doesn't match the first client render (e.g. relative time formatting). Fix: format times in client component only via `useEffect`, or use `suppressHydrationWarning` strategically. Ensure `staleTime > 0` on the server-prefetched query so client doesn't refetch immediately. ### "No QueryClient set" error Cause: component using a hook isn't inside ``. Fix: confirm `` wraps your app in `layout.tsx`. The provider must be a client component. ### Query refetches on every navigation Cause: per-request `QueryClient` on the server, no client-side singleton, or `staleTime: 0`. Fix: use the `getQueryClient` pattern with the browser singleton. Bump `staleTime` to e.g. 60s. ### Optimistic update flickers / wrong rollback Cause: race between mutation and concurrent refetch. Fix: always `cancelQueries` in `onMutate` before `setQueryData`. Snapshot must be done after cancel. ### "Cannot read 'pages' of undefined" on infinite query Cause: accessing `data.pages` before query loads. Fix: handle `isLoading` state. Pages array is undefined until first fetch returns. ### Devtools doesn't show in production By design — `` no-ops in production. To enable, gate manually: `{process.env.NODE_ENV !== 'production' && }`. ### Server prefetched data not used by client Cause: missing `HydrationBoundary` or `dehydrate(queryClient)`. Fix: wrap the client component subtree with ``. Make sure server `queryKey` exactly matches the client `queryKey`. ### Invalidation doesn't trigger refetch Cause: query is inactive (no mounted observer), or matcher doesn't match. Fix: `invalidateQueries` only refetches *active* queries by default. Pass `refetchType: 'all'` to also refetch inactive ones. ### Mutation returns success but UI stays stale Cause: forgot to invalidate or write to cache. Fix: in `onSuccess`, either `invalidateQueries` or `setQueryData`. Without either, cached data is untouched. ### Server Action throws but mutation shows success Cause: action returns `{ ok: false }` instead of throwing — mutation only sees rejection if `mutationFn` throws. Fix: in the mutationFn wrapper, throw when `result.ok === false`. ### Heavy bundle size Cause: importing devtools in production. Fix: lazy-load devtools via `dynamic(() => import('@tanstack/react-query-devtools').then(m => m.ReactQueryDevtools), { ssr: false })`. Devtools v5 is small (< 10KB) but every byte counts. ### "Query data cannot be undefined" Cause: `queryFn` returned undefined (e.g. forgot `return`, or fetch failed without throwing). Fix: throw on error (`if (!res.ok) throw new Error(...)`). Never return undefined from a queryFn — return `null` if you need to express absence.