Skip to main content
affpapa.org
RU EN
skill Claude Code CX Codex Cursor GitHub Copilot

tanstack-query-best-practices — Claude Code skill for React Query

A rule set for TanStack Query in React: query keys, caching, mutations, SSR. Installs into Claude Code, Codex, Cursor or Copilot so data fetching follows one pattern across the repo.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-query-best-practices -a claude-code
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-query -a claude-code
Open on GitHub

What tanstack-query-best-practices does

The skill hands the agent a written set of TanStack Query rules: how to shape query keys, how to choose staleTime and gcTime, how to roll back an optimistic update, how to prepare data on the server. The priority table says what each category buys you — the key and cache rules are listed as preventing cache bugs and mismatched data. A separate section lists the triggers: new fetching logic, query configuration, mutations, refactoring existing code.

Inside sits a rules/ folder. Rule names carry prefixes (qk-, cache-, mut-, err-, pf-, inf-, ssr-, parallel-, perf-, offline-), and every file has four parts: why the pattern matters, a bad example, a good example, and when to skip it. Critical categories are worth reading before prefetching and offline support.

Installing takes one command, and there is a wrinkle. In Claude Code the skill is dropped under the short name tanstack-query, so the file lands at ~/.claude/skills/tanstack-query/SKILL.md rather than under the long name in the title. The Codex, Cursor and OpenCode commands use that same short name, so do not go looking for a directory named after the long one.

What it helps with

  • structure query keys as entity → id → filters
  • pick a staleTime that matches how fast the data changes
  • roll back an optimistic update from the onMutate context
  • cut re-renders with select and notifyOnChangeProps
  • wire dehydrate and hydrate into a server-rendered route

Example prompts for the agent

  • Add a `useQuery` for the orders list in `OrdersList` and shape the keys the way tanstack-query-best-practices says.
  • Check the invalidation and rollback after the create-order `useMutation` against tanstack-query-best-practices.
  • Set up server hydration with `dehydrate` and `HydrationBoundary`, and raise `staleTime` on the server as tanstack-query-best-practices describes.

How to install tanstack-query-best-practices

1Skills CLI (Vercel)

npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-query-best-practices -a claude-code
npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-query -a claude-code

2Manually: put the files in place

~/.claude/skills/tanstack-query/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/tanstack-query/

Similar

react-router TanStack A skill that teaches your coding agent the React bindings for TanStack Router: hook reference, components, and a file-based routing setup on Vite. Claude Code CX Codex Cursor +1 546installs wpds WordPress Feeds WordPress Design System docs to your agent through an MCP server, so UI work lands on real components and tokens instead of guesses. Claude Code CX Codex Cursor +1 4,000installs narrow-react-prop-types humanlayer A skill that cuts React component prop types back to the contract your live code actually uses, then makes stories and tests match it instead of weakening it. Claude Code CX Codex Cursor +1 1,200installs senior-frontend Alireza Rezvani This skill supports React and Next.js work, from project scaffolding to bundle checks. Use it when building components, reviewing frontend code, or working on accessibility. Claude Code 1,630installs generate Alireza Rezvani The generate skill writes Playwright tests from a user story, URL, component name or feature description. Useful when an e2e scenario needs covering and you would rather not hand-write it. Claude Code 1,624installs senior-fullstack Alireza Rezvani Scaffolds Next.js, FastAPI, MERN or Django projects and scores your codebase for quality and security issues. Claude Code 1,390installs frontend-design official anthropics This skill guides intentional visual design for new interfaces and redesigns. Use it when a generic generated UI is not enough. Claude Code Claude.ai 1,025,790installs design-taste-frontend Leonxlnx This skill directs the design of public pages and work screens, then checks the result in a browser through screenshots. Use it when an interface feels generic or unfinished. Claude Code CX Codex Cursor +1 673,100installs

Questions about tanstack-query-best-practices

How do I install tanstack-query-best-practices in Claude Code?

Run npx skills add DeckardGer/tanstack-agent-skills --skill tanstack-query-best-practices -a claude-code. The skill file ends up at ~/.claude/skills/tanstack-query/SKILL.md.

What does tanstack-query-best-practices do?

It loads TanStack Query guidance ranked by priority, from query keys and caching down to parallel queries and offline mode. The agent then writes or reviews data fetching code against those rules.

What is in a single rule file?

An explanation of why the pattern matters, the anti-pattern to avoid, a recommended implementation, and the context for when to apply or skip the rule.

Source text

SKILL.md · MIT 
---
name: tanstack-query-best-practices
description: 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.
---

# 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:
1. **Explanation** — Why this pattern matters
2. **Bad Example** — Anti-pattern to avoid
3. **Good Example** — Recommended implementation
4. **Context** — When to apply or skip this rule

## Full Reference

See individual rule files in `rules/` directory for detailed guidance and code examples.

© DeckardGer · MIT · DeckardGer/tanstack-agent-skills

See also

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor