back
loading skill details...
TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React…
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: 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.
don't have the plugin yet? install it then click "run inline in claude" again.