tanstack-query_skill

Overview

This skill captures battle-tested best practices for using TanStack Query (React Query) in data-driven React applications. It focuses on robust query key design, caching, mutations, SSR hydration, and performance patterns to reduce bugs and improve UX. Use it to standardize server-state logic and make data flows predictable across your app.

How this skill works

The skill inspects common patterns and anti-patterns and presents concise rules grouped by priority: Query Keys, Caching, Mutations, Error Handling, Prefetching, SSR, and performance. Each rule includes an explanation, a bad example, a good example, and context for when to apply or skip it. Apply these rules while authoring or refactoring data fetching code to enforce consistency and prevent cache-related bugs.

When to use it

• When designing new data fetching and caching layers for React apps
• While implementing or refactoring mutations and optimistic updates
• During SSR/SSG integration and hydration work
• When configuring global QueryClient defaults and caching strategies
• When diagnosing stale data, cache inconsistencies, or slow UX

Best practices

• Always build query keys as arrays and include every dependent variable to avoid cache collisions
• Set sensible staleTime and gcTime at QueryClient level; prefer targeted invalidation over broad purges
• Invalidate related queries and provide rollback context in onMutate for safe optimistic updates
• Use dehydrate/hydrate and a per-request QueryClient for SSR; increase server staleTime and wrap with HydrationBoundary
• Leverage select, structural sharing, and notifyOnChangeProps to minimize re-renders and transform data cheaply

Example use cases

• Creating a list/detail UI with hierarchical query keys: ['users', userId, { include }]
• Implementing optimistic update for a create/edit mutation with rollback on error
• Prefetching route data on hover and ensuring staleTime is set for preloaded queries
• Hydrating server-fetched queries during SSG/SSR to eliminate loading flashes
• Using useQueries for dynamic parallel fetches and cancelling unused requests