К основному содержанию
скилл CX Codex

tanstack-query · oakoss — скилл для Claude Code: что делает и как установить

Помогает агенту писать запросы и мутации на TanStack Query v5, переводить код с v4 и настраивать инвалидацию кэша.

MIT 170 установок ★ 29 обновлён 2026-08-17

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add oakoss/agent-skills --skill tanstack-query -a claude-code
Открыть на GitHub

Что делает tanstack-query

Скилл содержит правила работы с библиотекой TanStack Query версии 5 в React. Он подсказывает агенту корректный синтаксис: объектные параметры вместо позиционных аргументов, свойство gcTime вместо устаревшего cacheTime, а также статус isPending вместо isLoading.

В инструкциях собраны частые ошибки при работе с хуками. Например, useSuspenseQuery не поддерживает параметр enabled, а бесконечные запросы useInfiniteQuery в пятой версии требуют обязательный initialPageParam.

Файл помечен как user-invocable: false, поэтому агент подтягивает правила сам, когда видит задачи на получение данных, гидратацию SSR или настройку оптимистичных обновлений.

Какие задачи решает

  • перевести проект с React Query v4 на TanStack Query v5
  • настроить бесконечную прокрутку через useInfiniteQuery
  • реализовать откат оптимистичных обновлений в useMutation
  • исправить расхождения гидратации при серверном рендеринге

Примеры запросов агенту

  • Обнови хук загрузки профиля с синтаксиса v4 на TanStack Query v5
  • Настрой пагинацию списка заказов через useInfiniteQuery с initialPageParam
  • Добавь оптимистичное обновление списка задач при отправке формы

Как установить tanstack-query

1Через Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill tanstack-query -a claude-code

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/tanstack-query/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о tanstack-query

Как установить tanstack-query в Claude Code?

Выполните команду npx skills add oakoss/agent-skills --skill tanstack-query -a claude-code в терминале.

Что делает этот скилл?

Он обучает кодинг-агента паттернам TanStack Query v5: правильному вызову хуков, обработке ошибок, инвалидации кэша и отказу от устаревших API четвёртой версии.

Какие ключевые отличия v5 от v4 учитывает скилл?

Инструкция требует объектную форму для useQuery, замену cacheTime на gcTime, обязательный initialPageParam для бесконечных списков и использование throwOnError вместо useErrorBoundary.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →

Сначала — tanstack-query от других авторов.

tanstack-query tanstack-skills Скилл подсказывает агенту, как работать с TanStack Query v5: кэширование, инвалидация, мутации и оптимистичные обновления. CX Codex +1 10 500установок tanstack-query Mindrally Скилл tanstack-query задаёт агенту правила работы с серверным состоянием в React: ключи запросов, queryOptions, мутации и переход с v4 на v5. CX Codex +1 766установок tanstack-query community Скилл tanstack-query для Claude Code и редакторов с поддержкой ИИ-агентов, содержащий правила оптимизации загрузки данных. Помогает настраивать кеш и предотвращать лишние сетевые запросы. CX Codex +1 587установок tanstack-query secondsky Скилл помогает агенту работать с TanStack Query v5: получать данные, настраивать кэш, мутации и разбирать ошибки миграции с v4. CX Codex +1 314установок tanstack-query bobmatnyc Учит ИИ-ассистента настраивать TanStack Query в React: работать с серверным состоянием, кешированием, пагинацией и оптимистичными обновлениями. CX Codex +1 601установок safe-action-tanstack-query next-safe-action Скилл safe-action-tanstack-query помогает связывать next-safe-action с TanStack Query: мутации, ошибки, optimistic updates и очистка клиентского кэша. Нужен при работе с React Query. CX Codex +1 458установок tanstack-query-setup patricio0312rev Скилл tanstack-query-setup ставит TanStack Query в React-проект: провайдер QueryClient, хуки на useQuery, мутации и правила кеша. Агент получает готовые шаблоны и подставляет в них ваш код. CX Codex +1 267установок tanstack-query-expert davila7 Скилл tanstack-query-expert помогает проектировать работу TanStack Query в React и Next.js: от запросов и кеша до мутаций и серверной гидратации. Пригодится при настройке или переработке загрузки данных. CX Codex +1 196установок tanstack-query-v5-cursorrules-prompt-file PatrickJS Правило tanstack-query-v5-cursorrules-prompt-file для Cursor задаёт рекомендации по TanStack Query v5 в React-проектах. Оно охватывает запросы, мутации, кеш и загрузку данных. CX Codex +1 ★ 41 178звёзд репо react-tanstack-router-query PatrickJS Правило react-tanstack-router-query настраивает связку TanStack Router v1 и TanStack Query v5 в React-проектах для загрузки данных в роутере без спиннеров ожидания. CX Codex +1 ★ 41 178звёзд репо tanstack-query-best-practices DeckardGer Скилл tanstack-query-best-practices для Claude Code собирает правила TanStack Query для React: ключи запросов, кеш, мутации и SSR. Включается при работе над загрузкой данных, чтобы соблюдать одну схему. CX Codex +1 13 400установок

Из того же набора106

Весь набор →
mermaid-diagrams Скилл mermaid-diagrams помогает создавать Mermaid-диаграммы в Markdown: от блок-схем и ERD до графиков, mindmap и архитектурных схем. CX Codex +1 177установок motion Скилл обучает ИИ-агента правильно применять библиотеку Motion (framer-motion) в React и Next.js. Помогает настроить жесты, скролл-эффекты и избежать просадок FPS. CX Codex +1 176установок shadcn-ui Учит агента работать с shadcn/ui: добавлять компоненты через CLI, настраивать темы на oklch и собирать формы с проверкой через Zod. CX Codex +1 176установок local-first Скилл local-first помогает решить, нужна ли веб-приложению локальная база с синхронизацией, и выбрать движок и стратегию разрешения конфликтов. CX Codex +1 173установок threejs Помогает создавать 3D-сцены на Three.js, подключать WebGPU и React Three Fiber. Помогает настраивать шейдеры, загружать модели и повышать производительность. CX Codex +1 167установок accessibility Скилл accessibility помогает создавать и проверять интерфейсы по WCAG 2.2 AA: от семантической HTML-разметки до клавиатурной навигации и поддержки скринридеров. CX Codex +1 164установок react-performance Скилл react-performance для Claude Code собирает паттерны оптимизации React и включается автоматически в задачах о скорости приложения. CX Codex +1 163установок design-system Скилл design-system для Claude Code собирает дизайн-систему с токенами, темами и архитектурой компонентов. Задаёт структуру для dark mode, CVA-вариантов и доступности. CX Codex +1 160установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой