tanstack-query-best-practices

# 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 keys - `qk-include-dependencies` — Include all variables the query depends on - `qk-hierarchical-organization` — Organize keys hierarchically (entity → id → filters) - `qk-factory-pattern` — Use query key factories for complex applications - `qk-serializable` — Ensure all key parts are JSON-serializable ### Caching (Prefix: `cache-`) - `cache-stale-time` — Set appropriate staleTime based on data volatility - `cache-gc-time` — Configure gcTime for inactive query retention - `cache-defaults` — Set sensible defaults at QueryClient level - `cache-invalidation` — Use targeted invalidation over broad patterns - `cache-placeholder-vs-initial` — Understand placeholder vs initial data differences ### Mutations (Prefix: `mut-`) - `mut-invalidate-queries` — Always invalidate related queries after mutations - `mut-optimistic-updates` — Implement optimistic updates for responsive UI - `mut-rollback-context` — Provide rollback context from onMutate - `mut-error-handling` — Handle mutation errors gracefully - `mut-loading-states` — Use isPending for mutation loading states - `mut-mutation-state` — Use useMutationState for cross-component tracking ### Error Handling (Prefix: `err-`) - `err-error-boundaries` — Use error boundaries with useQueryErrorResetBoundary - `err-retry-config` — Configure retry logic appropriately - `err-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 transitions - `pf-stale-time-config` — Set staleTime when prefetching - `pf-ensure-query-data` — Use ensureQueryData for conditional prefetching ### Infinite Queries (Prefix: `inf-`) - `inf-page-params` — Always provide getNextPageParam - `inf-loading-guards` — Check isFetchingNextPage before fetching more - `inf-max-pages` — Consider maxPages for large datasets ### SSR Integration (Prefix: `ssr-`) - `ssr-dehydration` — Use dehydrate/hydrate pattern for SSR - `ssr-client-per-request` — Create QueryClient per request - `ssr-stale-time-server` — Set higher staleTime on server - `ssr-hydration-boundary` — Wrap with HydrationBoundary ### Parallel Queries (Prefix: `parallel-`) - `parallel-use-queries` — Use useQueries for dynamic parallel queries - `query-cancellation` — Implement query cancellation properly ### Performance (Prefix: `perf-`) - `perf-select-transform` — Use select to transform/filter data - `perf-structural-sharing` — Leverage structural sharing - `perf-notify-change-props` — Limit re-renders with notifyOnChangeProps - `perf-placeholder-data` — Use placeholderData for instant UI ### Offline Support (Prefix: `offline-`) - `network-mode` — Configure network mode for offline support - `persist-queries` — Configure query persistence for offline support ## How to Use Each rule file in the `rules/` directory contains: 1. **Explanation** — Why this pattern matters 2. **Bad Example** — Anti-pattern to avoid 3. **Good Example** — Recommended implementation 4. **Context** — When to apply or skip this rule ## Full Reference See individual rule files in `rules/` directory for detailed guidance and code examples.