// TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state.
TanStack Start best practices for full-stack React applications. Server functions, middleware, SSR, authentication, and deployment patterns. Activate when building full-stack apps with TanStack Start.
Best practices for integrating TanStack Query with TanStack Router and TanStack Start. Patterns for full-stack data flow, SSR, and caching coordination.
TanStack Router best practices for type-safe routing, data loading, search params, and navigation. Activate when building React applications with complex routing needs.
| name | tanstack-query-best-practices |
| description | TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state. |
Comprehensive guidelines for implementing TanStack Query (React Query) patterns in React applications. These rules optimize data fetching, caching, mutations, and server state synchronization.
| 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 |
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-serializablecache-)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 differencesmut-)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 trackingerr-)err-error-boundaries — Use error boundaries with useQueryErrorResetBoundaryerr-retry-config — Configure retry logic appropriatelyerr-fallback-data — Provide fallback data when appropriatepf-)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 prefetchinginf-)inf-page-params — Always provide getNextPageParaminf-loading-guards — Check isFetchingNextPage before fetching moreinf-max-pages — Consider maxPages for large datasetsssr-)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 HydrationBoundaryparallel-)parallel-use-queries — Use useQueries for dynamic parallel queriesquery-cancellation — Implement query cancellation properlyperf-)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 UIoffline-)network-mode — Configure network mode for offline supportpersist-queries — Configure query persistence for offline supportEach rule file in the rules/ directory contains:
See individual rule files in rules/ directory for detailed guidance and code examples.