Agent skill · writing content · deckardger
tanstack-query-best-practices
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.
Why this skill is useful
Provides specific best practices for implementing TanStack Query that enhance data fetching and state management in React applications.
What it needs
About 3k tokens when loaded. Last updated 2026-04-03. 205 stars on the source repository.
What this skill does
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 …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills deckardger/tanstack-query