TanStack Query Best Practices
Comprehensive guidelines for implementing TanStack Query (React Query) patterns in React applications. These rules optimize data fetching, caching, mutations, and server state synchronization.
When to Apply
- Creating new data fetching logic
- Setting up query configurations
- Implementing mutations and optimistic updates
- Configuring caching strategies
- Integrating with SSR/SSG
- Refactoring existing data fetching code
Rule Categories by Priority
| Priority | Category | Rules | Impact |
|---|---|---|---|
| CRITICAL | Query Keys | 5 rules | Prevents cache bugs and data inconsistencies |
| CRITICAL | Caching | 5 rules | Optimizes performance and data freshness |
| HIGH | Mutations | 6 rules | Ensures data integrity and UI consistency |
| HIGH | Error Handling | 3 rules | Prevents poor user experiences |
| MEDIUM | Prefetching | 4 rules | Improves perceived performance |
| MEDIUM | Parallel Queries | 2 rules | Enables dynamic parallel fetching |
| MEDIUM | Infinite Queries | 3 rules | Prevents pagination bugs |
| MEDIUM | SSR Integration | 4 rules | Enables proper hydration |
| LOW | Performance | 4 rules | Reduces unnecessary re-renders |
| LOW | Offline Support | 2 rules | Enables offline-first patterns |
Quick Reference
Query Keys (Prefix: qk-)
qk-array-structure— Always use arrays for query keysqk-include-dependencies— Include all variables the query depends onqk-hierarchical-organization— Organize keys hierarchically (entity → id → filters)qk-factory-pattern— Use query key factories for complex applicationsqk-serializable— Ensure all key parts are JSON-serializable
Caching (Prefix: cache-)
cache-stale-time— Set appropriate staleTime based on data volatilitycache-gc-time— Configure gcTime for inactive query retentioncache-defaults— Set sensible defaults at QueryClient levelcache-invalidation— Use targeted invalidation over broad patternscache-placeholder-vs-initial— Understand placeholder vs initial data differences
Mutations (Prefix: mut-)
mut-invalidate-queries— Always invalidate related queries after mutationsmut-optimistic-updates— Implement optimistic updates for responsive UImut-rollback-context— Provide rollback context from onMutatemut-error-handling— Handle mutation errors gracefullymut-loading-states— Use isPending for mutation loading statesmut-mutation-state— Use useMutationState for cross-component tracking
Error Handling (Prefix: err-)
err-error-boundaries— Use error boundaries with useQueryErrorResetBoundaryerr-retry-config— Configure retry logic appropriatelyerr-fallback-data— Provide fallback data when appropriate
Prefetching (Prefix: pf-)
pf-intent-prefetch— Prefetch on user intent (hover, focus)pf-route-prefetch— Prefetch data during route transitionspf-stale-time-config— Set staleTime when prefetchingpf-ensure-query-data— Use ensureQueryData for conditional prefetching
Infinite Queries (Prefix: inf-)
inf-page-params— Always provide getNextPageParaminf-loading-guards— Check isFetchingNextPage before fetching moreinf-max-pages— Consider maxPages for large datasets
SSR Integration (Prefix: ssr-)
ssr-dehydration— Use dehydrate/hydrate pattern for SSRssr-client-per-request— Create QueryClient per requestssr-stale-time-server— Set higher staleTime on serverssr-hydration-boundary— Wrap with HydrationBoundary
Parallel Queries (Prefix: parallel-)
parallel-use-queries— Use useQueries for dynamic parallel queriesquery-cancellation— Implement query cancellation properly
Performance (Prefix: perf-)
perf-select-transform— Use select to transform/filter dataperf-structural-sharing— Leverage structural sharingperf-notify-change-props— Limit re-renders with notifyOnChangePropsperf-placeholder-data— Use placeholderData for instant UI
Offline Support (Prefix: offline-)
network-mode— Configure network mode for offline supportpersist-queries— Configure query persistence for offline support
How to Use
Each rule file in the rules/ directory contains:
- Explanation — Why this pattern matters
- Bad Example — Anti-pattern to avoid
- Good Example — Recommended implementation
- Context — When to apply or skip this rule
Full Reference
See individual rule files in rules/ directory for detailed guidance and code examples.
