115 lines
4.8 KiB
Markdown
115 lines
4.8 KiB
Markdown
---
|
|
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.
|
|
---
|
|
|
|
# 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.
|