pinia-colada-skilld — скилл для Claude Code: функции и установка
Скилл pinia-colada-skilld добавляет в Claude Code шаблоны и правила работы с @pinia/colada. Помогает настраивать выборку данных, мутации, сброс кэша и работу с SSR во Vue.
MIT 240 установок ★ 186 обновлён 2026-10-10
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/pinia-colada-skilld/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/pinia-colada-skilld/
1Через Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a codex2Вручную: положить файлы
.agents/skills/pinia-colada-skilld/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a cursor2Вручную: положить файлы
.cursor/skills/pinia-colada-skilld/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install skilld-dev/vue-ecosystem-skills skills/pinia-colada-skilld2Вручную: положить файлы
.github/skills/pinia-colada-skilld/SKILL.md1Через Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a gemini-cli2Командой платформы
gemini skills install https://github.com/skilld-dev/vue-ecosystem-skills --path skills/pinia-colada-skilldВручную: положить файлы
.devin/skills/pinia-colada-skilld/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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