React Query Best Practices

Important: This guide targets React Query v4. Some patterns may differ in v5.

Comprehensive guide for React Query v4 (TanStack Query) based on TkDodo’s authoritative blog series. Contains 24 rules across 7 categories, prioritized by impact.

When to Apply

Reference these guidelines when:

• Implementing new queries or mutations
• Integrating WebSockets with React Query
• Setting up query invalidation patterns
• Debugging React Query behavior
• Optimizing render performance
• TypeScript integration questions

Rule Categories by Priority

Quick Reference

1. Query Keys & Patterns (CRITICAL)

• query-keys-as-dependencies – Include all queryFn params in queryKey
• query-key-factory – Use factory pattern for consistent key generation
• query-select-transforms – Use select option for data transformations
• query-status-check-order – Check data first, then error, then loading
• query-tracked-properties – Only destructure properties you use
• query-placeholder-vs-initial – Know when to use each approach
• query-dependent-enabled – Use enabled option for dependent queries

2. Mutations & Updates (CRITICAL)

• mutation-prefer-mutate – Use mutate() with callbacks over mutateAsync()
• mutation-invalidation – Invalidate queries after mutations
• mutation-direct-cache-update – Update cache directly when appropriate
• mutation-optimistic-updates – Show success immediately, rollback on failure
• mutation-callback-separation – Query logic in hook, UI effects in component

3. Caching Strategy (HIGH)

• cache-stale-time – Set appropriate staleTime for your domain
• cache-refetch-triggers – Keep refetch triggers enabled in production

4. WebSocket Integration (HIGH)

• websocket-event-invalidation – Use events to trigger invalidation
• websocket-stale-time-infinity – Set staleTime: Infinity for WS-managed data
• websocket-reconnection – Invalidate stale queries on reconnect

5. TypeScript Integration (MEDIUM)

• typescript-infer-dont-specify – Let TypeScript infer, type the queryFn
• typescript-zod-validation – Use Zod for runtime validation

6. Testing Patterns (MEDIUM)

• testing-fresh-client – Create fresh QueryClient per test
• testing-msw-mocking – Use MSW for network mocking

7. Common Pitfalls (MEDIUM)

• troubleshoot-copy-to-state – Never copy query data to local state
• troubleshoot-missing-key-deps – Include all dependencies in query key
• troubleshoot-fetch-not-reject – Handle HTTP errors with fetch

8. Migration to v5 (HIGH)

• migration-cache-time-to-gc-time – cacheTime renamed to gcTime
• migration-query-callbacks-removed – onSuccess/onError/onSettled removed from useQuery
• migration-suspense-hooks – New useSuspenseQuery, useSuspenseInfiniteQuery hooks

Core Mental Model

1. React Query is NOT a data fetching library – it’s an async state manager
2. Server state != Client state – never mix them in global state managers
3. Stale-while-revalidate – show cached data immediately, fetch in background
4. Query keys are dependencies – include all variables used in queryFn

How to Use

Read individual rule files for detailed explanations and code examples:

rules/query-key-factory.md
rules/mutation-invalidation.md
rules/websocket-event-invalidation.md

Each rule file contains:

• Brief explanation of why it matters
• Incorrect code example
• Correct code example

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md