tanstack-query · oakoss — скилл для Claude Code: что делает и как установить
Помогает агенту писать запросы и мутации на TanStack Query v5, переводить код с v4 и настраивать инвалидацию кэша.
MIT 170 установок ★ 29 обновлён 2026-08-17
npx skills add oakoss/agent-skills --skill tanstack-query -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/tanstack-query/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/tanstack-query/
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-query -a codex2Вручную: положить файлы
.agents/skills/tanstack-query/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-query -a cursor2Вручную: положить файлы
.cursor/skills/tanstack-query/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/tanstack-query2Вручную: положить файлы
.github/skills/tanstack-query/SKILL.md1Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-query -a gemini-cli2Командой платформы
gemini skills install https://github.com/oakoss/agent-skills --path skills/tanstack-queryВручную: положить файлы
.devin/skills/tanstack-query/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill tanstack-query -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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 от других авторов.