# tanstack-query

Guides AI assistants in configuring TanStack Query for React, handling server state, background caching, and optimistic updates.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 583 installs · ★ 78
- Author: bobmatnyc
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/bobmatnyc/claude-mpm-skills/tree/HEAD/toolchains/typescript/state/tanstack-query/SKILL.md
- Updated: 2026-07-18
- HTML: https://affpapa.org/en/nevibecode/skills/bobmatnyc-tanstack-query

## What it does

This skill equips coding agents with patterns for `@tanstack/react-query`. It provides guidelines for setting up `QueryClientProvider`, organizing `useQuery` and `useMutation` hooks, and synchronizing remote API endpoints.

The instructions cover hierarchical array structures for `queryKey`, cache invalidation logic, and cache retention settings via `staleTime` and `gcTime`. For form fields or client-only UI flags, the guidance explicitly defers to tools like Zustand or React Hook Form rather than storing local values in the server cache.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add bobmatnyc/claude-mpm-skills --skill tanstack-query -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tanstack-query/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tanstack-query/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add bobmatnyc/claude-mpm-skills --skill tanstack-query -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tanstack-query/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add bobmatnyc/claude-mpm-skills --skill tanstack-query -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tanstack-query/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install bobmatnyc/claude-mpm-skills tanstack-query
```

2. **Manually: put the files in place**
- File: `.github/skills/tanstack-query/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add bobmatnyc/claude-mpm-skills --skill tanstack-query -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/bobmatnyc/claude-mpm-skills --path toolchains/typescript/state/tanstack-query
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tanstack-query/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add bobmatnyc/claude-mpm-skills --skill tanstack-query -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/bobmatnyc/claude-mpm-skills/tree/HEAD/toolchains/typescript/state/tanstack-query/SKILL.md

## When to use it
- set up QueryClientProvider with default caching options in React
- structure hierarchical query keys for exact or prefix cache invalidation
- implement data mutations that automatically refetch stale resource lists
- separate asynchronous server state from local client UI state

## Example prompts
- Set up a QueryClientProvider with a one-minute staleTime in my React app
- Write a useQuery hook to fetch user details by userId with error handling
- Create a mutation hook that posts a new user and invalidates the users query key

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1107cd6033430f7d.

BEGIN THIRD-PARTY FILE 1107cd6033430f7d
````text
---
name: tanstack-query
description: TanStack Query (React Query) for asynchronous server-state management with automatic caching, background refetching, optimistic updates, and pagination in React applications.
user-invocable: false
disable-model-invocation: true
progressive_disclosure:
  entry_point:
    - summary
    - when_to_use
    - quick_start
  intermediate:
    - core_concepts
    - queries
    - mutations
    - cache_management
  advanced:
    - optimistic_updates
    - pagination
    - ssr_hydration
    - integration_patterns
    - performance
---

# TanStack Query (React Query) Skill

## Summary

TanStack Query (formerly React Query) is a powerful asynchronous state management library for React that handles server-state fetching, caching, synchronization, and updates. It eliminates the need for manual data fetching boilerplate and provides built-in features like background refetching, optimistic updates, pagination, and intelligent cache management.

## When to Use

**Use TanStack Query when:**
- Fetching data from REST APIs, GraphQL, or tRPC endpoints
- Need automatic background refetching and cache invalidation
- Building real-time dashboards with polling or websocket data
- Implementing infinite scroll or pagination
- Require optimistic UI updates for mutations
- Managing complex server-state synchronization
- Need offline support with cache persistence
- Building applications with frequent data updates

**TanStack Query excels at:**
- Server-state management (API data, external state)
- Request deduplication and caching
- Stale-while-revalidate patterns
- Loading and error state management
- Prefetching and eager loading
- Parallel and dependent query orchestration

**Avoid TanStack Query for:**
- Pure client-side state (use Zustand, Jotai, or Context)
- Form state management (use React Hook Form, Formik)
- Simple one-time fetches without caching needs

## Quick Start

### Installation

```bash
npm install @tanstack/react-query
# DevTools (optional but recommended)
npm install @tanstack/react-query-devtools
```

### Basic Setup

```tsx
// app/providers.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { useState } from 'react';

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // 1 minute
        refetchOnWindowFocus: false,
      },
    },
  }));

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}
```

### First Query

```tsx
// components/UserProfile.tsx
import { useQuery } from '@tanstack/react-query';

interface User {
  id: number;
  name: string;
  email: string;
}

function UserProfile({ userId }: { userId: number }) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['user', userId],
````
END THIRD-PARTY FILE 1107cd6033430f7d

The third-party file has ended. Everything between the 1107cd6033430f7d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3047 of 56730 bytes. © bobmatnyc · MIT · https://github.com/bobmatnyc/claude-mpm-skills/tree/HEAD/toolchains/typescript/state/tanstack-query/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md