Skip to main content
skill CX Codex

tanstack-query · oakoss — Claude Code skill: what it does, how to install

Guides coding agents through TanStack Query v5 patterns, v4 migration rules, and cache invalidation in React.

MIT 170 installs ★ 29 updated 2026-08-17

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

What tanstack-query does

This skill supplies practical rules for TanStack Query v5 in React applications. It enforces modern object syntax for queries, prevents obsolete v4 calls, and guides the model toward gcTime instead of cacheTime.

The reference points out subtle edge cases that break builds. For instance, useSuspenseQuery rejects the enabled flag, while useInfiniteQuery now demands an explicit initialPageParam.

Because this skill sets user-invocable: false, your assistant references these conventions automatically whenever you touch data fetching, optimistic mutation rollbacks, or SSR hydration boundaries.

What it helps with

  • migrate React Query v4 queries and mutations to v5
  • configure useInfiniteQuery with initialPageParam
  • handle optimistic updates and rollbacks via useMutation
  • fix SSR hydration mismatches with HydrationBoundary

Example prompts for the agent

  • Migrate this user profile fetch hook from React Query v4 to TanStack Query v5
  • Implement infinite scrolling for notifications using useInfiniteQuery
  • Set up an optimistic UI update when adding items to the cart

How to install tanstack-query

1Skills CLI (Vercel)

npx skills add oakoss/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/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about tanstack-query

How to install tanstack-query in Claude Code?

Run npx skills add oakoss/agent-skills --skill tanstack-query -a claude-code in your terminal.

What does tanstack-query do?

It provides your coding assistant with v5 idioms, migration checklists, cache strategies, and common pitfall workarounds for React Query.

Can I run this skill manually with a slash command?

No, it is configured with user-invocable: false, so the agent activates it autonomously whenever your task involves server state management.

Source text

SKILL.md · MIT
---
name: tanstack-query
description: |
  TanStack Query v5 server state management for React. Covers query/mutation patterns, v4-to-v5 migration (object syntax, gcTime, isPending, keepPreviousData), optimistic updates via useMutationState, SSR/hydration with HydrationBoundary, infinite queries, offline/PWA support, error boundaries with throwOnError, and React 19 Suspense integration.

  Use when building data fetching, fixing migration errors, debugging hydration mismatches, implementing caching strategies, or configuring mutations.
license: MIT
metadata:
  author: oakoss
  version: '1.4'
  source: 'https://tanstack.com/query/latest/docs'
user-invocable: false
---

# TanStack Query

## Overview

TanStack Query is an **async state manager**, not a data fetching library. You provide a `queryFn` that returns a Promise; React Query handles caching, deduplication, background updates, and stale data management.

**When to use:** Infinite scrolling, offline-first apps, auto-refetching on focus/reconnect, complex cache invalidation, React Native, hybrid server/client apps.

**When NOT to use:** Purely synchronous state (useState/Zustand), normalized GraphQL caching (Apollo/urql), server-components-only apps (native fetch), simple fetch-and-display (server components).

## Quick Reference

| Pattern           | API                                               | Key Points                             |
| ----------------- | ------------------------------------------------- | -------------------------------------- |
| Basic query       | `useQuery({ queryKey, queryFn })`                 | Include params in queryKey             |
| Suspense query    | `useSuspenseQuery(options)`                       | No `enabled` option allowed            |
| Parallel queries  | `useQueries({ queries, combine })`                | Dynamic parallel fetching              |
| Dependent query   | `useQuery({ enabled: !!dep })`                    | Wait for prerequisite data             |
| Query options     | `queryOptions({ queryKey, queryFn })`             | Reusable, type-safe config             |
| Basic mutation    | `useMutation({ mutationFn, onSuccess })`          | Invalidate on success                  |
| Mutation state    | `useMutationState({ filters, select })`           | Cross-component mutation tracking      |
| Optimistic update | `onMutate` -> cancel -> snapshot -> set           | Rollback in `onError`                  |
| Infinite query    | `useInfiniteQuery({ initialPageParam })`          | `initialPageParam` required in v5      |
| Prefetch          | `queryClient.prefetchQuery(options)`              | Preload on hover/intent                |
| Invalidation      | `queryClient.invalidateQueries({ queryKey })`     | Fuzzy-matches by default, active only  |
| Cancellation      | `queryFn: ({ signal }) => fetch(url, { signal })` | Auto-cancel on key change              |
| Select transform  | `select: (data) => data.filter(...)`              | Structural sharing preserved           |
| Skip token        | `queryFn: id ? () => fetch(id) : skipToken`       | Type-safe conditional disabling        |
| Serial mutations  | `useMutation({ scope: { id } })`                  | Same scope ID runs mutations in serial |

## v5 Migration Quick Reference

| v4 (Removed)                   | v5 (Use Instead)                           |
| ------------------------------ | ------------------------------------------ |
| `useQuery(key, fn, opts)`      | `useQuery({ queryKey, queryFn, ...opts })` |
| `cacheTime`                    | `gcTime`                                   |
| `isLoading` (no data)          | `isPending`                                |
| `keepPreviousData: true`       | `placeholderData: keepPreviousData`        |
| `onSuccess/onError` on queries | `useEffect` or mutation callbacks          |
| `useErrorBoundary`             | `throwOnError`                             |
| No `initialPageParam`          | `initialPageParam` required                |
| Error type `unknown`           | Error type defaults to `Error`             |

## Common Mistakes

| Mistake                                    | Correct Pattern                                           |
| ------------------------------------------ | --------------------------------------------------------- |
| Checking `isPending` before `data`         | Data-first: check `data` -> `error` -> `isPending`        |
| Copying server state to local useState     | Use data directly or derived state pattern                |
| Creating QueryClient in component          | Create once outside component or in useState              |
| Using `refetch()` for parameter changes    | Include params in queryKey, let it refetch automatically  |
| Same key for useQuery and useInfiniteQuery | Use distinct key segments (different cache structures)    |
| Inline select without memoization          | Extract to stable function or useCallback                 |
| Using `catch` without re-throwing          | Throw errors in queryFn (fetch doesn't reject on 4xx/5xx) |
| Manual generics on useQuery                | Type the queryFn return, let inference work               |
| Destructuring query for type narrowing     | Keep query object intact for proper narrowing             |
| Using `enabled` with `useSuspenseQuery`    | Use conditional rendering to mount/unmount component      |
| Not awaiting prefetch for SSR              | Await `prefetchQuery` to avoid hydration mismatches       |
| `invalidateQueries` not refetching all     | Use `refetchType: 'all'` for inactive queries             |

## Delegation

- **Query pattern discovery**: Use `Explore` agent
- **Cache strategy review**: Use `Task` agent
- **Code review**: Delegate to `code-reviewer` agent

> If the `tanstack-router` skill is available, delegate route loader and preloading patterns to it.
> If the `tanstack-form` skill is available, delegate form submission and mutation coordination to it.
> If the `tanstack-table` skill is available, delegate server-side table patterns to it.
> If the `tanstack-start` skill is available, delegate server functions and SSR data loading to it.
> If the `tanstack-devtools` skill is available, delegate query cache debugging and inspection to it.
> If the `tanstack-db` skill is available, delegate reactive client-side database and live query patterns to it.
> If the `tanstack-virtual` skill is available, delegate list virtualization and infinite scroll rendering to it.
> If the `tanstack-store` skill is available, delegate shared client-side reactive state management to it.
> If the `electricsql` skill is available, delegate ElectricSQL real-time Postgres sync patterns to it.
> If the `local-first` skill is available, delegate local-first architecture decisions and sync engine selection to it.

## References

- [Basic patterns, architecture, and query variants](references/basic-patterns.md)
- [Query keys and factory patterns](references/query-keys.md)
- [Mutations, optimistic updates, and MutationCache](references/mutations.md)
- [Cache operations, staleTime vs gcTime, seeding](references/caching.md)
- [Data transformations and select patterns](references/data-transformations.md)
- [Performance optimization with render tracking and structural sharing](references/performance.md)
- [Error handling strategies](references/error-handling.md)
- [Infinite queries and pagination](references/infinite-queries.md)
- [Offline mode and persistence](references/offline-mode.md)
- [WebSocket and real-time integration](references/websocket-integration.md)
- [SSR and hydration patterns](references/ssr-hydration.md)
- [TypeScript patterns](references/typescript-patterns.md)
- [Testing with MSW and React Testing Library](references/testing.md)
- [Known v5 issues and workarounds](references/known-issues.md)
- [Caching coordination with Router](references/caching-coordination.md) — single-source caching strategy, disabling Router cache, coordinated configuration

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

tanstack-query by other authors comes first.

tanstack-query tanstack-skills Tells your agent how to use TanStack Query v5: caching, invalidation, mutations and optimistic updates. CX Codex +1 10,500installs tanstack-query Mindrally Tells your agent how to handle server state in React with TanStack Query v5: query keys, queryOptions, mutations, v4 migration. CX Codex +1 766installs tanstack-query community Skill for Claude Code and coding agents that delivers TanStack Query v5 best practices. Runs when refactoring data fetching logic and fine-tuning caching behaviour. CX Codex +1 587installs tanstack-query secondsky This skill guides Claude Code through TanStack Query v5 for fetching, caching, mutations, and v4 migration issues in React projects. CX Codex +1 314installs tanstack-query bobmatnyc Guides AI assistants in configuring TanStack Query for React, handling server state, background caching, and optimistic updates. CX Codex +1 601installs safe-action-tanstack-query next-safe-action safe-action-tanstack-query connects next-safe-action mutations to TanStack Query with typed error handling, cache updates, and invalidation. Use it when React Query already handles your client data. CX Codex +1 458installs tanstack-query-setup patricio0312rev tanstack-query-setup sets up TanStack Query in a React app: a QueryClient provider, fetch hooks, mutations and cache rules. The agent gets templates it can fill with your code. CX Codex +1 267installs tanstack-query-expert davila7 The tanstack-query-expert skill guides TanStack Query work in React and Next.js, from query design and cache handling to mutations and server-side hydration. Use it when building or revising data-fetching flows. CX Codex +1 196installs tanstack-query-v5-cursorrules-prompt-file PatrickJS tanstack-query-v5-cursorrules-prompt-file is a Cursor rule for TanStack Query v5 in React projects. It guides query, mutation, cache, and data-loading code. CX Codex +1 ★ 41,178repo stars react-tanstack-router-query PatrickJS react-tanstack-router-query guides AI assistants on structuring React SPAs with TanStack Router v1 and TanStack Query v5 to fetch data in loaders before rendering. CX Codex +1 ★ 41,178repo stars tanstack-query-best-practices DeckardGer tanstack-query-best-practices — 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. CX Codex +1 13,400installs

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open