TanStack Query v5 — Review & Coding Standards

Step 2: Run the review checklist

Check every item below. Only report findings that actually exist in the codebase.

Critical Issues (bugs or data integrity problems)

Warnings (anti-patterns and performance issues)

v4 to v5 Migration

Step 3: Generate the report

Produce a structured report in this exact format:

## TanStack Query Review Report

### Summary
- **Critical**: X issues
- **Warnings**: Y issues
- **Migration**: Z items
- **Assessment**: [one-sentence overall assessment]

### Critical Issues

#### [C1] Server state copied to client state
**File:** `src/components/TodoList.tsx:14`
**Issue:** Query data copied to useState via useEffect, creating stale copy that misses background updates.
**Fix:**
[before/after code block showing the fix]

### Warnings
[Same format — ID, file, issue, fix]

### v4 to v5 Migration Opportunities
[Same format — ID, file, v4 pattern found, v5 replacement with code]

### Recommendations
[Prioritized list of suggested improvements, starting with highest-impact changes]

Group findings by severity. Within each group, order by impact. Include file paths with line numbers and concrete before/after code fixes for every finding.

Coding Standards

When writing new TanStack Query code, follow these rules strictly.

QueryClient Setup

• Set a global staleTime above zero (60 seconds is a sensible default for most apps)
• Ensure gcTime >= staleTime always
• Use QueryCache onError for global error handling — never per-component useEffect error toasts
• Create QueryClient outside the component tree for a stable reference
• Include <ReactQueryDevtools> in development

Query Key Factories with queryOptions

All query definitions go through queryOptions factories. Never use inline query key arrays.

import { queryOptions } from '@tanstack/react-query'

export const todoQueries = {
  all: () => ['todos'] as const,

  lists: () =>
    queryOptions({
      queryKey: [...todoQueries.all(), 'list'] as const,
      queryFn: fetchAllTodos,
    }),

  list: (filters: TodoFilters) =>
    queryOptions({
      queryKey: [...todoQueries.all(), 'list', { filters }] as const,
      queryFn: () => fetchTodos(filters),
    }),

  detail: (id: number) =>
    queryOptions({
      queryKey: [...todoQueries.all(), 'detail', id] as const,
      queryFn: () => fetchTodoById(id),
    }),
}

Structure keys from most generic to most specific. Use as const for type-safe keys.

File Organization

src/features/{feature}/
  queries.ts       // queryOptions factories + fetch functions
  mutations.ts     // useMutation hooks (custom hooks ARE appropriate for mutations)
  components/
    FeatureList.tsx
    FeatureDetail.tsx

Data Fetching

• Always check response.ok when using the fetch API as a queryFn. Throw explicitly on 4xx/5xx.
• Use skipToken for conditional fetching (type-safe disabling). Use enabled: false only when you need manual refetch().
• Use select for all data transformations. Keep selectors as stable references (module-level functions or useCallback).
• Use placeholderData: (prev) => prev to keep previous data during key changes (pagination, filtering).
• Never copy query data into useState. Derive everything from data directly.

Mutations

• Callback separation: shared logic (invalidation, cache updates) in useMutation definition, UI logic (navigation, toasts, form resets) in mutate() call-site callbacks.
• Return the invalidation promise from onSuccess to keep the mutation pending until fresh data arrives.
• Invalidate in onSettled (not onSuccess) when using optimistic updates, so the cache corrects on both success and error.
• Never mutate cached data in-place in setQueryData updaters. Always return new references.
• Reserve optimistic updates for high-confidence, instant-feedback interactions (toggles, likes). Avoid for form submissions that navigate away.

Suspense & React 19

• Use useSuspenseQuery (not suspense: true) — data is guaranteed defined.
• Always pair <Suspense> with <ErrorBoundary> (use QueryErrorResetBoundary + react-error-boundary).
• Never use multiple useSuspenseQuery calls in the same component — use useSuspenseQueries for parallel fetches.
• Prefetch in route loaders to avoid waterfalls. Use ensureQueryData for critical (blocking) data, prefetchQuery for non-critical.
• Use startTransition when query keys change (pagination) to keep old UI visible instead of showing the Suspense fallback.

Infinite Queries

• Always provide initialPageParam (required in v5).
• Return undefined from getNextPageParam to signal no more pages.
• Use maxPages to limit stored pages for memory management.
• Combine with IntersectionObserver for infinite scroll.

TypeScript

• Type fetch functions, not hooks. Never provide manual generics to useQuery<T>(). Let inference flow from the queryFn return type.
• Register a global error type via module augmentation (Register interface).
• Use as const on all query key arrays for literal type inference.

Testing

• Create a fresh QueryClient per test with retry: false and gcTime: Infinity.
• Use MSW (Mock Service Worker) over mocking fetch directly.
• Pre-seed cache with queryClient.setQueryData for tests needing immediate data.
• Never share a QueryClient between tests.

Quick Reference: v5 Status Flags

Deep Dive

For the complete TanStack Query v5 reference covering all configuration options, detailed pattern explanations, performance optimization strategies, and the full list of v5 breaking changes, read references/tanstack-query-v5-guide.md.