Agent Native

tanstack-query-best-practices

This skill provides TanStack Query best practices for React applications, covering query keys, caching strategies, mutations, error handling, prefetching…

by DeckardGerCommunityNot reviewed

Community author

Agents
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, claude.ai and API
License
MIT (permissive)
Pin
b2fc14cpinned Oct 9, 2026
Context cost
about 1,100 tokenswhen the skill loads
GitHub stars
222on deckardger/tanstack-agent-skills
Scripts
None found

What it does

“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.”
The author's description, from SKILL.md

Generated summary from the skill's own text

This skill provides TanStack Query best practices for React applications, covering query keys, caching strategies, mutations, error handling, prefetching, infinite queries, SSR integration, and performance optimization. It includes 40+ rules organized by priority that guide proper implementation of server state management patterns and prevent common pitfalls.

When to use it

  • Building React applications with server state and data fetching requirements
  • Setting up query configurations, caching strategies, or mutation patterns
  • Implementing SSR or integrating server-side rendering with client state
  • Refactoring existing data fetching code to use TanStack Query patterns

When not to

  • Projects not using React or TanStack Query libraries
  • Client-side only state management unrelated to server data
  • Simple applications with minimal or static data fetching needs

Install

These commands install from the publisher's repository and need no account.

skills CLI

npx skills add deckardger/tanstack-agent-skills --skill tanstack-query-best-practices

Installs from the repository's default branch, which may have changed since the commit we checked.

GitHub CLI 2.90 or later

gh skill install deckardger/tanstack-agent-skills tanstack-query-best-practices@b2fc14c974b2ca09b38de09c28237f240175205b

Installs the commit we checked (b2fc14c).

Copy by hand

Download the folder at b2fc14c and put it in .claude/skills/tanstack-query-best-practices for Claude Code and in .agents/skills/tanstack-query-best-practices for Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode.

Skill folder on GitHub at b2fc14c

Copy for your agent

A prompt for any coding agent. It installs this skill from GitHub at the pinned commit, copies the files as they are, and runs nothing unless you ask.

Prompt

Install the agent skill "tanstack-query-best-practices" by DeckardGer.

Source, pinned to commit b2fc14c974b2ca09b38de09c28237f240175205b:
https://github.com/deckardger/tanstack-agent-skills/tree/b2fc14c974b2ca09b38de09c28237f240175205b/skills/tanstack-query

1. Download that folder at exactly this commit. Do not use the default branch.
2. Copy every file unchanged, keeping the folder structure, into .claude/skills/tanstack-query-best-practices/ for Claude Code and .agents/skills/tanstack-query-best-practices/ for Codex, Cursor, Gemini CLI, GitHub Copilot and OpenCode. Create the folders if they do not exist.
3. Do not edit the files, and do not run any script in the folder unless I ask you to.
4. When you are done, list the files you copied and where you put them.

Listing and checks: https://www.agentnative.dev/skills/deckardger/tanstack-query-best-practices

SKILL.md at the pin

---
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.

From deckardger/tanstack-agent-skills at b2fc14c, shown as plain text under its license: MIT (permissive). The license text is in LICENSE.

View SKILL.md on GitHub at b2fc14c

Files

39 files, 125 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.

Skill folder on GitHub at b2fc14c
All Frontend and design skills

Related in Frontend and design

  • react-email

    React Email lets agents build HTML email templates as React components and render them to HTML or plain text.

    by ResendOfficial publisher

    Claude Code, Codex, Cursor +4 · about 3.4K tokens · pinned 6 days ago

  • apollo-client

    This skill guides building React applications with Apollo Client 4.x for managing GraphQL queries, mutations, and state.

    by Apollo GraphQLOfficial publisher

    Claude Code, Codex, Cursor +4 · about 1.7K tokens · pinned 6 days ago

  • stitch::code-to-design

    This skill converts existing frontend code (React, Vue, Angular, etc.) into a Stitch Design by extracting HTML, analyzing design systems, and uploading both…

    by GoogleOfficial publisher

    Claude Code, Codex, Cursor +4 · about 760 tokens · pinned 6 days ago

  • stitch::extract-design-md

    Extracts a comprehensive design system document (DESIGN.md) by analyzing frontend source code including component files, stylesheets, Tailwind configs, and…

    by GoogleOfficial publisher

    Claude Code, Codex, Cursor +4 · about 3.3K tokens · pinned 6 days ago

  • stitch::extract-static-html

    This skill extracts a self-contained static HTML file from a running web application or React components by inlining all CSS and images as base64 data.

    by GoogleOfficial publisher

    Contains scripts

    Claude Code, Codex, Cursor +3 · about 2.6K tokens · pinned 6 days ago

  • frontend-design

    This skill builds production-grade frontend interfaces and web components with distinctive, intentional design aesthetics.

    by SnykOfficial publisher

    Claude Code, Codex, Cursor +4 · about 990 tokens · pinned 6 days ago

The skills listed here are third-party software, collected from public GitHub repositories as a catalog of recent skills and provided as is. Agent Native does not write or control them and is not responsible for any harm, loss or damage caused by installing or using them. Labels and checks describe what we saw at one commit and are not a guarantee. Read a skill's files before you run it. Terms of use