accelint-tanstack-query-best-practices
This skill covers expert patterns for TanStack Query in modern React with Next.js App Router, including QueryClient configuration, query key factories, cache invalidation, and optimistic updates. Learn critical anti-patterns to avoid—like singleton QueryClients on servers, unstable query keys, and N observers per list item—plus decision matrices for cache configuration and mutation strategies.
accelint-tanstack-query-best-practices teaches proven patterns and critical anti-patterns for TanStack Query in React and Next.js applications.
AI-generated summary based on this skill's SKILL.md
Install
gohypergiant/agent-skills/accelint-tanstack-query-best-practices · repository language: TypeScript
git clone https://github.com/gohypergiant/agent-skills
cp -r agent-skills/skills/accelint-tanstack-query-best-practices ~/.claude/skills/accelint-tanstack-query-best-practicesFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What are tanstack query best practices for Next.js?
accelint-tanstack-query-best-practices teaches expert patterns for TanStack Query in modern React with Next.js App Router. Key practices include: creating separate QueryClient instances per request on the server (never singletons), using stable query key factories to prevent unnecessary re-renders, configuring staleTime and gcTime appropriately for your data freshness needs, and implementing proper cache invalidation strategies. The skill also covers hydration boundaries to sync server and client caches, and avoiding anti-patterns like N observers per list item that degrade performance.
How should I configure QueryClient and set up server-client caching layers?
accelint-tanstack-query-best-practices covers QueryClient setup across server and client boundaries in Next.js. On the server, create a new QueryClient per request rather than reusing a singleton. Configure staleTime (how long data is fresh) and gcTime (garbage collection time) based on your data volatility. Use hydration to serialize server-fetched data into the client QueryClient, preventing duplicate requests. The skill includes decision matrices for cache configuration and demonstrates multi-layer caching patterns that respect the App Router's server/client component split.
What patterns should I use for useSuspenseQuery, useQuery, and useMutation?
accelint-tanstack-query-best-practices explains when to use each hook. useSuspenseQuery throws a promise during fetch, integrating with React Suspense for cleaner code—ideal for server components or when you want boundary-level loading states. useQuery is the standard for data fetching with built-in caching and background refetching. useMutation handles side effects with pessimistic or optimistic update patterns. The skill teaches decision matrices for choosing between them and demonstrates both update strategies: optimistic (update UI immediately, rollback on error) and pessimistic (wait for server confirmation).
How do I build query hooks with proper key factories and invalidation strategy?
accelint-tanstack-query-best-practices emphasizes stable query key factories to prevent cache misses and unnecessary renders. Create a keys object with nested functions that return consistent arrays—e.g., keys.users.list() always returns ['users', 'list']. Use invalidateQueries with partial matching to invalidate related queries after mutations: invalidateQueries({ queryKey: ['users'] }) clears all user queries. The skill covers dependent queries (enabled guard pattern) and cache invalidation strategies that balance freshness against request overhead, with examples for common scenarios like list updates and detail mutations.
What are common tanstack query mistakes and anti-patterns to avoid?
accelint-tanstack-query-best-practices identifies critical anti-patterns: singleton QueryClients on servers (causes data leakage between requests), unstable query keys that change on every render (defeats caching), creating N observers per list item (kills performance), and incorrect staleTime/gcTime tuples that either stale data too fast or hold garbage too long. The skill teaches how to debug observer counts with DevTools, recognize structural sharing issues with large datasets, and avoid query cancellation mistakes. It also covers hydration boundary errors and pessimistic vs. optimistic update pitfalls.
How can I debug performance issues and optimize observer behavior?
accelint-tanstack-query-best-practices covers performance debugging using TanStack Query DevTools to monitor observer counts, cache hits, and refetch patterns. Optimize by reducing observers (avoid N per list item), using proper query key scoping, and tuning staleTime and gcTime. The skill teaches structural sharing optimization for large datasets and query cancellation with AbortController to prevent memory leaks. Learn to identify polling issues (refetch intervals), unnecessary background refetches, and cache invalidation cascades that trigger excessive requests. Includes decision matrices for cache configuration tuned to your data freshness and performance constraints.
SKILL.md
rendered from the published skill — quoted content, verbatim
TanStack Query Best Practices
Expert patterns for TanStack Query in modern React applications with Next.js App Router and Server Components.
NEVER Do With TanStack Query
- NEVER use a singleton QueryClient on the server - Creates data leakage between users and race conditions. Each request must get its own isolated QueryClient instance to prevent cached data from one user appearing for another.
- NEVER synchronize query data to useState - Background refetches, invalidations, and optimistic updates all modify the cache. Local state copies become stale immediately, causing "my save didn't work" bugs. Use query data directly or derive with
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 10 files
skills/accelint-tanstack-query-best-practices/SKILL.md
skills/accelint-tanstack-query-best-practices/assets/output-report-template.md
skills/accelint-tanstack-query-best-practices/assets/query-client.ts
skills/accelint-tanstack-query-best-practices/references/caching-strategy.md
skills/accelint-tanstack-query-best-practices/references/fundamentals.md
skills/accelint-tanstack-query-best-practices/references/mutations-and-updates.md
skills/accelint-tanstack-query-best-practices/references/patterns-and-pitfalls.md
skills/accelint-tanstack-query-best-practices/references/query-client-setup.md
skills/accelint-tanstack-query-best-practices/references/query-keys.md
skills/accelint-tanstack-query-best-practices/references/server-integration.md