TanStack Query Best Practices
Comprehensive performance optimization guide for TanStack Query v5 applications. Contains 40 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
- •Writing new queries, mutations, or data fetching logic
- •Implementing caching strategies (staleTime, gcTime)
- •Reviewing code for performance issues or request waterfalls
- •Refactoring existing TanStack Query code
- •Implementing infinite queries, Suspense, or optimistic updates
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Query Key Structure | CRITICAL | tquery- |
| 2 | Caching Configuration | CRITICAL | cache- |
| 3 | Mutation Patterns | HIGH | mutation- |
| 4 | Prefetching & Waterfalls | HIGH | prefetch- |
| 5 | Infinite Queries | MEDIUM | infinite- |
| 6 | Suspense Integration | MEDIUM | suspense- |
| 7 | Error & Retry Handling | MEDIUM | error- |
| 8 | Render Optimization | LOW-MEDIUM | render- |
Quick Reference
1. Query Key Structure (CRITICAL)
- •
tquery-key-factories- Use centralized query key factories - •
tquery-hierarchical-keys- Structure keys from generic to specific - •
tquery-always-arrays- Always use array query keys - •
tquery-serializable-objects- Use serializable objects in keys - •
tquery-options-pattern- Use queryOptions for type-safe sharing - •
tquery-colocate-keys- Colocate query keys with features
2. Caching Configuration (CRITICAL)
- •
cache-staletime-gctime- Understand staleTime vs gcTime - •
cache-global-defaults- Configure global defaults appropriately - •
cache-placeholder-vs-initial- Use placeholderData vs initialData correctly - •
cache-invalidation-precision- Invalidate with precision - •
cache-refetch-triggers- Control automatic refetch triggers - •
cache-enabled-option- Use enabled for conditional queries
3. Mutation Patterns (HIGH)
- •
mutation-optimistic-updates- Implement optimistic updates with rollback - •
mutation-invalidate-onsettled- Invalidate in onSettled, not onSuccess - •
mutation-cancel-queries- Cancel queries before optimistic updates - •
mutation-setquerydata- Use setQueryData for immediate cache updates - •
mutation-avoid-parallel- Avoid parallel mutations on same data
4. Prefetching & Waterfalls (HIGH)
- •
prefetch-avoid-waterfalls- Avoid request waterfalls - •
prefetch-on-hover- Prefetch on hover for perceived speed - •
prefetch-in-queryfn- Prefetch dependent data in queryFn - •
prefetch-server-components- Prefetch in Server Components - •
prefetch-flatten-api- Flatten API to reduce waterfalls
5. Infinite Queries (MEDIUM)
- •
infinite-max-pages- Limit infinite query pages with maxPages - •
infinite-flatten-pages- Flatten pages for rendering - •
infinite-refetch-behavior- Understand infinite query refetch behavior - •
infinite-loading-states- Handle infinite query loading states correctly
6. Suspense Integration (MEDIUM)
- •
suspense-use-suspense-hooks- Use Suspense hooks for simpler loading states - •
suspense-error-boundaries- Always pair Suspense with Error Boundaries - •
suspense-parallel-queries- Combine Suspense queries with useSuspenseQueries - •
suspense-boundaries-placement- Place Suspense boundaries strategically
7. Error & Retry Handling (MEDIUM)
- •
error-retry-config- Configure retry with exponential backoff - •
error-conditional-retry- Use conditional retry based on error type - •
error-global-handler- Use global error handler for common errors - •
error-display-patterns- Display errors appropriately - •
error-throw-on-error- Use throwOnError with Error Boundaries
8. Render Optimization (LOW-MEDIUM)
- •
render-select-memoize- Memoize select functions - •
render-select-derived- Use select to derive data and reduce re-renders - •
render-notify-props- Use notifyOnChangeProps to limit re-renders - •
render-structural-sharing- Understand structural sharing - •
render-tracked-props- Avoid destructuring all properties
How to Use
Read individual reference files for detailed explanations and code examples:
- •Section definitions - Category structure and impact levels
- •Reference files:
references/{prefix}-{slug}.md
Each reference file contains:
- •Brief explanation of why it matters
- •Incorrect code example with explanation
- •Correct code example with explanation
- •Additional context and references
Related Skills
- •For generating type-safe query hooks, see
orvalskill - •For mocking API responses in tests, see
test-mswskill - •For React 19 data fetching patterns, see
react-19skill
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md