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

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 orval skill
• For mocking API responses in tests, see test-msw skill
• For React 19 data fetching patterns, see react-19 skill

Full Compiled Document

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