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

tanstack-vue-query-skilld — скилл для Claude Code

Скилл tanstack-vue-query-skilld для Claude Code задаёт правила работы с @tanstack/vue-query v5. Помогает писать запросы и мутации в Vue 3 или Vue 2 без типичных ошибок с реактивностью.

MIT 223 установок ★ 186 обновлён 2026-10-10

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

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

Скилл загружает в модель соглашения библиотеки @tanstack/vue-query версии 5.103.2. Внутри собраны правила для useQuery, useMutation и настройки QueryClient. Модель узнаёт, что поля из хуков возвращаются как Ref, поэтому в скриптах к ним нужно обращаться через .value.

В правила заложены тонкости реактивности Vue. Переменная ref передаётся в queryKey напрямую без ручного разворачивания, а для полной реактивности параметров вызывают useQuery(() => ({ ... })). Запросы вручную выполняются через queryClient.query(), так как методы вроде fetchQuery объявлены устаревшими.

Для работы в проекте требуется Vue 3.3+ либо Vue 2.6+ с библиотекой @vue/composition-api. Снаружи setup() или effectScope хуки библиотеки вызовут предупреждение об утечке памяти.

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

  • настроить плагин VueQueryPlugin для SSR с отдельным клиентом
  • связать ref и реактивные параметры внутри queryKey
  • организовать мутацию через useMutation со сбросом кэша
  • перевести вызовы устаревшего fetchQuery на queryClient.query

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

  • Настрой useQuery для получения поста по postId.value без потери реактивности
  • Сделай компонент с useMutation для добавления задачи и сбросом кэша
  • Покажи, как сконфигурировать VueQueryPlugin для приложения с SSR

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

1Через Skills CLI (Vercel)

npx skills add skilld-dev/vue-ecosystem-skills --skill tanstack-vue-query-skilld -a claude-code

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

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

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

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

Вопросы о tanstack-vue-query-skilld

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

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

Что делает tanstack-vue-query-skilld?

Скилл передаёт агенту правила работы с @tanstack/vue-query 5.103.2, предотвращая ошибки при обращении к Ref, разворачивании ключей и вызове хуков.

С какими версиями Vue работает этот скилл?

Описанные правила рассчитаны на Vue 3.3 и выше, а для Vue 2 поддерживается версия от 2.6 при наличии пакета @vue/composition-api.

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

SKILL.md · MIT
---
name: tanstack-vue-query-skilld
description: "Hooks for managing, caching and syncing asynchronous and remote data in Vue. ALWAYS use when writing code importing \"@tanstack/vue-query\". Consult for debugging, best practices, or modifying @tanstack/vue-query, tanstack/vue-query, tanstack vue-query, tanstack vue query, query."
license: MIT
---

# @tanstack/[email protected]

Async data hooks for Vue. Version 5.103.2, prepared source at `input/source`.
Peer deps: `vue ^2.6.0 || ^3.3.0`; Vue 2 needs `@vue/composition-api` (optional peer) (`package.json:56-59`).
Re-exports everything from `@tanstack/query-core` 5.103.2, so `keepPreviousData`, `skipToken`, `focusManager`, `onlineManager`, hydration utils, and observer classes import from `@tanstack/vue-query` directly (`src/index.ts:1`).

## Setup

Install the plugin once per app. It creates (or accepts) a `QueryClient`, provides it app-wide, and mounts/unmounts it (`src/vueQueryPlugin.ts:74-154`):

```ts
import { createApp } from 'vue'
import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query'

const app = createApp(App)

// Option A: pass your own client (required for SSR — one fresh client per request)
const queryClient = new QueryClient()
app.use(VueQueryPlugin, { queryClient })

// Option B: let the plugin build one with your defaults
app.use(VueQueryPlugin, {
  queryClientConfig: { defaultOptions: { queries: { staleTime: 5 * 1000 } } },
})
```

`VueQueryPluginOptions`: `queryClient` or `queryClientConfig` (one or the other), `queryClientKey` (only when installing multiple clients), `clientPersister` + `clientPersisterOnSuccess` (persisted cache restore), `enableDevtoolsV6Plugin` (`src/vueQueryPlugin.ts:11-38`). The client is not mounted on the server (`src/vueQueryPlugin.ts:87-89`).

`useQueryClient(id?)` throws outside an injection context or without the plugin (`src/useQueryClient.ts:27-44`).

## Basic query

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useQuery } from '@tanstack/vue-query'

const postId = ref(1)
const { status, data, error, refetch } = useQuery({
  queryKey: ['post', postId],          // ref inside the key: tracked, no .value
  queryFn: () => fetchPost(postId.value),
})
</script>

<template>
  <span v-if="status === 'pending'">Loading...</span>
  <span v-else-if="status === 'error'">Error: {{ error!.message }}</span>
  <h1 v-else>{{ data!.title }}</h1>
</template>
```

## Basic mutation

```vue
<script setup lang="ts">
import { useMutation, useQueryClient } from '@tanstack/vue-query'

const queryClient = useQueryClient()
const addMutation = useMutation({
  mutationFn: addTodo,
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})

function onAdd() {
  addMutation.mutate('Item', {
    onError: (error) => console.error('Failed:', error),
  })
}
</script>

<template>
  <button @click="onAdd">Add</button>
</template>
```

`mutate` swallows rejection by design; per-call callbacks fire only for the latest call. Use `mutateAsync` for a promise per call (`src/useMutation.ts:262-270`).

## Rules that catch Vue developers

- **Returns are `Ref`s.** Every result field of `useQuery`/`useInfiniteQuery`/`useMutation` is a `Ref` (`data.value` in script, auto-unwrapped in template), except the functions `refetch`, `fetchNextPage`, `fetchPreviousPage`, `mutate`, `mutateAsync`, `reset`, plus `suspense()` (`src/useBaseQuery.ts:27-40`, `src/useMutation.ts:53-68`).
- **`useQueries` returns one `Ref`** of the whole result array (or the `combine` value), not a reactive array (`src/useQueries.ts:357-376`).
- **Never unwrap refs for the query key.** Put the `ref` itself into `queryKey` and read `.value` inside `queryFn` (`src/utils.ts:84-111`).
- **Only `queryKey` and `enabled` accept reactive getters.** A function anywhere else is the real callback (`queryFn`, `select`, ...). To make any option reactive, pass a whole-options getter `useQuery(() => ({ ... }))` (`src/queryOptions.ts:67-76`, `src/useQuery.ts:225-227`).
- **`initialData` is not reactive**; it is read once (`src/queryOptions.ts:136-148`).
- **Call composables in `setup()` or an `effectScope`.** Outside a scope, dev mode warns about memory leaks (`src/useBaseQuery.ts:82-88`).
- **Imperative fetches go through `queryClient.query()` / `queryClient.infiniteQuery()`.** `fetchQuery`, `prefetchQuery`, `fetchInfiniteQuery`, `prefetchInfiniteQuery`, `ensureQueryData` are deprecated and slated for removal (`src/queryClient.ts:251-253`, `src/queryClient.ts:311-313`).
- **Declare shared queries with `queryOptions()`** so the key carries its data type for `getQueryData`, `invalidateQueries`, and prefetch reuse (`src/queryOptions.ts:244-251`).

## Environment limits

- Prepared source: `@tanstack/vue-query` 5.103.2 with `@tanstack/query-core` 5.103.2 (`package.json:2,45`). Docs match v5; v4 APIs may appear in old examples.
- Vue 3.3+ for Vue 3; Vue 2.6+ with `@vue/composition-api`, or Vue 2.7 native (`package.json:52-59`).
- ESM-first dual build (`build/modern`, `build/legacy`); `sideEffects: false` (`package.json:21-35`).

## References

- [references/api.md](./references/api.md) — every export, its signature, and where it lives in the source.
- [references/reactivity.md](./references/reactivity.md) — refs, getters, `skipToken`, `queryOptions` getters, `shallow`.
- [references/query-client.md](./references/query-client.md) — Vue `QueryClient`, reactive args, invalidation timing, SSR, multiple clients.
- [references/mutations.md](./references/mutations.md) — mutations, `mutationOptions`, `useMutationState`, optimistic updates.
- [references/migration.md](./references/migration.md) — v5 breaking changes and version-specific rules since 5.90.

Official docs: https://tanstack.com/query/latest/docs/framework/vue/overview

© skilld-dev · MIT · skilld-dev/vue-ecosystem-skills

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

Все скиллы по теме «Фронтенд и UI» →
tanstack-query-best-practices DeckardGer Скилл tanstack-query-best-practices для Claude Code собирает правила TanStack Query для React: ключи запросов, кеш, мутации и SSR. Включается при работе над загрузкой данных, чтобы соблюдать одну схему. CX Codex +1 13 400установок tanstack-query tanstack-skills Скилл подсказывает агенту, как работать с TanStack Query v5: кэширование, инвалидация, мутации и оптимистичные обновления. CX Codex +1 10 500установок 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установок router-query TanStack Скилл router-query связывает TanStack Router с TanStack Query для предзагрузки данных в лоадерах, кэширования через useSuspenseQuery и изоляции QueryClient при SSR. CX Codex +1 448установок

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

Весь набор →
vuetify-skilld Скилл vuetify-skilld настраивает агента на разработку с Vuetify 4.x под Vue 3. Помогает подключить компоненты, разрулить CSS-слои и мигрировать проект с третьей версии. CX Codex +1 421установок pinia-skilld Скилл pinia-skilld для ИИ-агентов, который подсказывает верные API Pinia 4.x: хранилища, геттеры, действия, SSR и миграцию с v2 и v3. CX Codex +1 349установок vue-router-skilld Скилл vue-router-skilld для Claude Code содержит правила настройки [email protected]: типизированная маршрутизация, data loaders и файловые роуты без устаревшего API. CX Codex +1 324установок pinia-colada-skilld Скилл pinia-colada-skilld добавляет в Claude Code шаблоны и правила работы с @pinia/colada. Помогает настраивать выборку данных, мутации, сброс кэша и работу с SSR во Vue. CX Codex +1 240установок vueuse-core-skilld Скилл vueuse-core-skilld с полным API @vueuse/core 15.0.0: новые composables, правила миграции с v14, устаревшие функции и требования окружения. CX Codex +1 219установок vee-validate-skilld Скилл vee-validate-skilld помогает писать, проверять и отлаживать формы Vue 3 с vee-validate 4.15.x. Даёт актуальные примеры Composition API, паттерны схем валидации, интеграцию typed-schema и решение типичных ошибок. CX Codex +1 188установок primevue-skilld Скилл primevue-skilld помогает писать и обновлять код для PrimeVue v5: настраивать библиотеку, заменять устаревшие API и собирать компоненты из частей. Пригодится в проекте на Vue 3. CX Codex +1 187установок shadcn-vue-skilld Скилл shadcn-vue-skilld для Claude Code, Codex, Cursor и других агентов, покрывающий CLI shadcn-vue 2.8.2 для Vue и Nuxt. Знает точные флаги всех команд — от init до mcp, конфигурацию components.json и правила разрешения имён компонентов. CX Codex +1 174установок

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

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