pinia-colada-skilld — Claude Code skill: what it does, how to install
pinia-colada-skilld gives coding assistants patterns and rules for @pinia/colada in Vue. Helps write queries, handle mutations, invalidate cache, and set up SSR.
MIT 240 installs ★ 186 updated 2026-10-10
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a claude-codeWhat pinia-colada-skilld does
This skill provides AI assistants with patterns and rules for @pinia/colada, the data fetching layer built on top of Pinia for Vue. It covers functions like useQuery, useMutation, and infinite queries, showing how to structure query keys as serializable arrays.
It guides the model to use a getter for reactive query keys so updates to route parameters trigger automatic refetches. It also explains optimistic updates, cache invalidation via useQueryCache, and grouping query state for reliable TypeScript narrowing in templates.
Pinia Colada must be registered as a Vue plugin strictly after Pinia itself, and it requires an options object during installation to keep types intact.
What it helps with
- configure data fetching with
useQueryand reactive keys - trigger mutations via
useMutationand invalidate cached entries - handle optimistic UI updates during background requests
- share query state across components using
defineQuery
Example prompts for the agent
- Write a
useQuerycall that fetches user profile data using route params in the key getter - Implement a mutation to update a task and clear the relevant cache entry on completion
- Create a shared query using
defineQueryto reuse todo state across components
How to install pinia-colada-skilld
1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a claude-code2Manually: put the files in place
~/.claude/skills/pinia-colada-skilld/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pinia-colada-skilld/
1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a codex2Manually: put the files in place
.agents/skills/pinia-colada-skilld/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a cursor2Manually: put the files in place
.cursor/skills/pinia-colada-skilld/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install skilld-dev/vue-ecosystem-skills skills/pinia-colada-skilld2Manually: put the files in place
.github/skills/pinia-colada-skilld/SKILL.md1Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a gemini-cli2Platform CLI
gemini skills install https://github.com/skilld-dev/vue-ecosystem-skills --path skills/pinia-colada-skilldManually: put the files in place
.devin/skills/pinia-colada-skilld/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pinia-colada-skilld
How to install pinia-colada-skilld in Claude Code?
Run npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a claude-code. The file will be placed in ~/.claude/skills/pinia-colada-skilld/SKILL.md.
What does pinia-colada-skilld do?
It equips AI assistants with API patterns for @pinia/colada. It guides query key creation, status handling, cache invalidation, and store setup.
Why pass query keys as a getter function?
Passing a getter function allows Pinia Colada to track reactive dependencies such as route parameters. A static array key will not trigger a refetch when underlying values update.
Source text
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