SomtoUgeh TanStack Query Best Practices
Selected 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
Available local rules
This package contains 21 rule files. Consult the official documentation for topics not covered here, matching the installed package version.
- cache-gc-time: Configure gcTime for Inactive Query Retention
- cache-invalidation: Use Targeted Invalidation Over Broad Patterns
- cache-placeholder-vs-initial: Understand Placeholder vs Initial Data
- cache-stale-time: Set Appropriate staleTime Based on Data Volatility
- err-error-boundaries: Use Error Boundaries with useQueryErrorResetBoundary
- inf-page-params: Always Provide getNextPageParam for Infinite Queries
- mut-invalidate-queries: Always Invalidate Related Queries After Mutations
- mut-mutation-state: Use useMutationState for Cross-Component Mutation Tracking
- mut-optimistic-updates: Implement Optimistic Updates for Responsive UI
- network-mode: Configure Network Mode for Offline Support
- parallel-use-queries: Use useQueries for Dynamic Parallel Queries
- perf-select-transform: Use Select to Transform and Filter Data
- persist-queries: Configure Query Persistence for Offline Support
- pf-intent-prefetch: Prefetch on User Intent (Hover, Focus)
- qk-array-structure: Always Use Arrays for Query Keys
- qk-factory-pattern: Use Query Key Factories for Complex Applications
- qk-hierarchical-organization: Organize Keys Hierarchically
- qk-include-dependencies: Include All Variables the Query Depends On
- qk-serializable: Ensure All Key Parts Are JSON-Serializable
- query-cancellation: Implement Query Cancellation Properly
- ssr-dehydration: Use Dehydrate/Hydrate Pattern for SSR
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.