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 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