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

pinia-colada-skilld — скилл для Claude Code: функции и установка

Скилл pinia-colada-skilld добавляет в Claude Code шаблоны и правила работы с @pinia/colada. Помогает настраивать выборку данных, мутации, сброс кэша и работу с SSR во Vue.

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

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

Что делает pinia-colada-skilld

Скилл снабжает ассистента контекстом по библиотеке @pinia/colada для управления запросами и кэшем в приложениях на Vue. Он подсказывает сигнатуры функций, разделение состояний данных и фоновой загрузки, а также подходы к типизации ответов через фабрики параметров.

Внутри собраны правила использования useQuery, useMutation и бесконечных списков. Для реактивных ключей скилл требует передавать геттер, иначе запрос не отследит изменение параметров маршрута. Мутации оформляются с очисткой кэша через useQueryCache, а оптимистичные обновления откатываются при возникновении ошибок.

Плагин @pinia/colada нужно регистрировать строго после создания pinia, передавая объект настроек. Без этого типы в приложении не свяжутся корректно.

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

  • настроить получение данных через useQuery с реактивными ключами
  • реализовать мутации через useMutation с очисткой кэша
  • добавить оптимистичное обновление состояния при отправке данных
  • изолировать запросы в разделяемые хранилища с помощью defineQuery

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

  • Покажи пример загрузки списка задач через useQuery с правильной обработкой состояния ошибки
  • Сделай мутацию для добавления контакта с инвалидацией кэша в onSettled
  • Напиши общий запрос через defineQuery с параметром поиска

Как установить pinia-colada-skilld

1Через Skills CLI (Vercel)

npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a claude-code

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

~/.claude/skills/pinia-colada-skilld/SKILL.md

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

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

Вопросы о pinia-colada-skilld

Как установить pinia-colada-skilld в Claude Code?

Выполните команду npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a claude-code. Файл навыка запишется в ~/.claude/skills/pinia-colada-skilld/SKILL.md.

Что делает pinia-colada-skilld?

Скилл обучает ассистента API библиотеки @pinia/colada для Vue. Он объясняет, как объявлять ключи запросов, разделять статусы выполнения, сбрасывать кэш и связывать данные с Pinia.

Почему в useQuery ключи нужно передавать через функцию-геттер?

Геттер нужен для реактивности: когда меняются параметры маршрута или связанные переменные, повторный запрос выполнится только при таком объявлении ключа. Обычный массив не отследит изменения зависимостей.

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

SKILL.md · MIT
---
name: pinia-colada-skilld
description: Data fetching layer for Vue built on Pinia. Use when writing, debugging, or reviewing code that imports @pinia/colada (pinia colada), including useQuery, useMutation, useInfiniteQuery, defineQuery, query cache invalidation, optimistic updates, plugins, SSR, or migrating from older versions. Provides current 1.4.x APIs, patterns, and migration rules.
license: MIT
---

# @pinia/colada 1.4.5

The smart data fetching layer for Vue.js, built on Pinia. Queries read and cache
data (`useQuery`), mutations write data (`useMutation`), everything lives in
Pinia stores (`useQueryCache`, `useMutationCache`).

- Docs: https://pinia-colada.esm.dev
- API types: `dist/index.d.mts` in the prepared package source
- Runtime exports: `dist/index.mjs:1487`
- Peers: `vue ^3.5.41`, `pinia ^2.2.6 || ^3.0.0 || ^4.0.2` (pinia 4 allowed since 1.4.1, `package.json:91-94`)
- Bundled codemods: `codemods/rules/*.yaml` in the package

## Setup

```sh
npm install pinia @pinia/colada
```

```ts
import { createPinia } from 'pinia'
import { PiniaColada } from '@pinia/colada'

const app = createApp(App)
app.use(createPinia())
// install after pinia; the options object is required for correct typing
app.use(PiniaColada, {
  queryOptions: { staleTime: 60_000 },
  plugins: [],
})
```

Global options go under `queryOptions` / `mutationOptions` (`dist/index.d.mts:1601-1618`).

## Mental model

- A query is identified by its `key`: a JSON-serializable array
  (`EntryKey`, `dist/index.d.mts:119`). Keys are hierarchical: `{ key: ['todos'] }`
  also matches `['todos', { filter: 'done' }]` when filtering.
- `status` is the data status: `'pending' | 'success' | 'error'`.
  `asyncStatus` is the operation status: `'idle' | 'loading'`. They are separate
  on purpose (https://pinia-colada.esm.dev/guide/queries.md).
- Defaults: `staleTime: 5000`, `gcTime: 300_000`, `refetchOnMount`,
  `refetchOnWindowFocus`, `refetchOnReconnect`, `enabled: true`
  (`dist/index.mjs:92-97`). Mutation `gcTime` default is `60_000`
  (`dist/index.d.mts:1379`).

## Core patterns

### Basic query

```vue
<script setup lang="ts">
import { useQuery } from '@pinia/colada'

const { state, asyncStatus } = useQuery({
  key: ['todos'],
  query: () => fetch('/api/todos').then(res => res.json()),
})
</script>

<template>
  <div v-if="state.status === 'pending'">Loading...</div>
  <div v-else-if="state.status === 'error'">{{ state.error.message }}</div>
  <ul v-else>
    <li v-for="todo in state.data" :key="todo.id">{{ todo.text }}</li>
  </ul>
</template>
```

Use the grouped `state` object for type narrowing in templates. TypeScript
cannot narrow separate `data` / `error` refs from `status`
(https://pinia-colada.esm.dev/guide/queries.md).

### Reactive keys: pass a getter

Everything the `query` function reads (route params, refs) must be in the `key`.
Pass `key` as a getter so the query refetches when dependencies change:

```ts
const { data } = useQuery({
  key: () => ['contacts', route.params.id as string],
  query: () => fetch(`/api/contacts/${route.params.id}`).then(r => r.json()),
})
```

### Guard queries with `enabled`

Prevent invalid fetches when a required param is absent (common in stores and
global queries):

```ts
useQuery({
  key: () => ['decks', route.params.deckId],
  query: () => fetchDeck(route.params.deckId as string),
  enabled: () => 'deckId' in route.params,
})
```

### Type-safe shared options: `defineQueryOptions`

```ts
export const todoOptions = defineQueryOptions((id: string) => ({
  key: ['todos', id],
  query: () => fetchTodo(id),
}))

// single-function form; the returned key is tagged so queryCache infers TData
const { data } = useQuery(() => todoOptions(route.params.id as string))
const todo = queryCache.getQueryData(todoOptions('1').key) // typed
```

`useQuery` accepts options or a getter returning options
(`dist/index.d.mts:733`). Since 1.0 the two-parameter form
`useQuery(options, paramsGetter)` is removed; see
[references/migration.md](./references/migration.md).

### Shared query state: `defineQuery`

Wrap queries used by multiple components so refs are created once, like a tiny
Pinia store. The setup function must be synchronous:

```ts
export const useFilteredTodos = defineQuery(() => {
  const search = ref('')
  const query = useQuery({
    key: () => ['todos', { search: search.value }],
    query: () => fetchTodos(search.value),
  })
  return { ...query, search }
})
```

Details: [references/queries.md](./references/queries.md).

### Mutation + invalidation

```ts
const queryCache = useQueryCache()

const { mutate, isLoading } = useMutation({
  mutation: (text: string) => createTodo(text),
  async onSettled() {
    await queryCache.invalidateQueries({ key: ['todos'] })
  },
})
```

- `mutate(vars)` never rejects; use it in templates and event handlers.
- `mutateAsync(vars)` returns a promise and rejects on failure.
- Put `onMutate` before `mutation` in the options object so its returned
  context is inferred in later hooks (`dist/index.d.mts:1410-1433`).
- Optimistic updates: write to the cache in `onMutate`, roll back in `onError`
  only if the cache still holds your optimistic value. Full pattern in
  [references/mutations.md](./references/mutations.md).

### Queries have no `onSuccess`/`onError`

This is intentional: a query can have many watchers. Use `watch(data, ...)`,
or global hooks via `PiniaColadaQueryHooksPlugin`
(https://pinia-colada.esm.dev/plugins/official/query-hooks.md).

## Version-critical rules (1.x)

- `useQuery(setup, paramsGetter)` and `useQueryState(setup, paramsGetter)` were
  removed in 1.0.0. Migrate with the shipped codemod:
  `ast-grep scan -r node_modules/@pinia/colada/codemods/rules/migration-0-21-to-1-0.yaml -i src`
  (https://github.com/posva/pinia-colada/blob/main/CHANGELOG.md).
- `useQueryState(key)` reads query state without fetching; the key is the only
  argument (`dist/index.d.mts:920-926`).
- `initialData` changes query state to `success`; `placeholderData` does not
  change the cache (`dist/index.d.mts:558-600`).
- To reset an entry's state manually use `queryCache.setEntryState(entry, state)`;
  setting data to `undefined` via `setQueryData()` no longer resets state.
- Infinite query data is `{ pages, pageParams }`; use `setInfiniteQueryData()`
  (added 1.2.0), not `setQueryData()`, to prime infinite entries.
- Devtools are a separate package: `@pinia/colada-devtools`.
- Nuxt: install the `@pinia/colada-nuxt` module; it handles SSR serialization
  automatically.

## References

- [queries.md](./references/queries.md): `useQuery` API, options, return values,
  `useQueryState`, `defineQuery`, `defineQueryOptions`, key factories
- [mutations.md](./references/mutations.md): `useMutation` API, hooks and
  context, optimistic updates, `defineMutation`, `defineMutationOptions`
- [infinite-queries.md](./references/infinite-queries.md): `useInfiniteQuery`,
  `defineInfiniteQueryOptions`, `setInfiniteQueryData`, `maxPages`
- [query-cache.md](./references/query-cache.md): cache stores, invalidation,
  filters, manual cache writes, error codes
- [plugins.md](./references/plugins.md): plugin API, `PiniaColadaQueryHooksPlugin`,
  `TypesConfig` augmentation, official plugin packages
- [ssr.md](./references/ssr.md): serialization and hydration, lazy queries,
  `PiniaColadaSSRNoGc`
- [migration.md](./references/migration.md): 0.x to 1.x changes and codemods

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

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

Все скиллы по теме «Фронтенд и UI» →
pinia-colada secondsky Скилл pinia-colada для управления асинхронным состоянием в Vue и Nuxt через useQuery и useMutation. Помогает при кешировании, SSR, инвалидации кеша и миграции с TanStack Vue Query. CX Codex +1 253установок pinia Anthony Fu Загружает документацию Pinia v4.0.3 прямо в контекст агента. Агент начинает правильно определять сторы, работать с storeToRefs() и настраивать SSR-гидратацию. CX Codex +1 20 600установок unit-test-vue-pinia официальный github Скилл unit-test-vue-pinia для GitHub Copilot — помогает писать и проверять юнит-тесты для Vue 3, TypeScript, Vitest и Pinia. Держит тесты на публичных входах, не проваливаясь во внутренности компонентов. CX Codex +1 1 800установок vue-pinia-cursorrules-prompt-file PatrickJS Правило vue-pinia-cursorrules-prompt-file задаёт стандарты работы с Pinia и TypeScript во Vue 3: разделение состояния, синтаксис setup-хранилищ, типизацию, SSR и правила персистентности. CX Codex +1 ★ 41 178звёзд репо vue-pinia-best-practices github.com/vuejs-ai Скилл vue-pinia-best-practices с лучшими практиками Pinia: как избежать ошибок при настройке хранилищ, сохранить реактивность и правильно организовать state management в Vue-проекте. CX Codex +1 18 500установок vue sanjeed5 Задаёт строгие стандарты для Vue 3: синтаксис <script setup>, Composition API, Pinia и чистые вычисляемые свойства. Применяется к файлам .vue, .js и .ts. CX Codex +1 ★ 3 589звёзд репо

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

Весь набор →
vue-skilld Скилл vue-skilld помогает писать компоненты и композаблы на Vue 3.6. Направляет агента при переходе на Vapor Mode, настройке SSR и обновлении кода с версий 3.4–3.5. CX Codex +1 434установок 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установок tanstack-vue-query-skilld Скилл tanstack-vue-query-skilld для Claude Code задаёт правила работы с @tanstack/vue-query v5. Помогает писать запросы и мутации в Vue 3 или Vue 2 без типичных ошибок с реактивностью. CX Codex +1 223установок 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установок

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

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