Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add skilld-dev/vue-ecosystem-skills --skill pinia-colada-skilld -a claude-code
Open on GitHub

What 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 useQuery and reactive keys
  • trigger mutations via useMutation and invalidate cached entries
  • handle optimistic UI updates during background requests
  • share query state across components using defineQuery

Example prompts for the agent

  • Write a useQuery call 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 defineQuery to 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-code

2Manually: put the files in place

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

Copy the whole skill folder; for one project use .claude/skills/pinia-colada-skilld/

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

Similar skills

All skills for Frontend and UI →

From the same set32

The whole set →
vue-skilld vue-skilld guides coding agents through Vue 3.6 development. Useful when creating composables, setting up Vapor Mode, or migrating code from Vue 3.4 and 3.5. CX Codex +1 434installs vuetify-skilld vuetify-skilld directs AI assistants on configuring and debugging Vuetify 4.x with Vue 3. Helps handle tree-shaking, Vite integration, and v3 to v4 migration. CX Codex +1 421installs pinia-skilld pinia-skilld — a skill that feeds your coding agent the correct Pinia 4.x APIs: stores, getters, actions, SSR hydration, testing and v2/v3 migration notes. CX Codex +1 349installs vue-router-skilld vue-router-skilld guides AI coding agents through [email protected] conventions. Covers typed routes, experimental data loaders, and file-based routing without deprecated patterns. CX Codex +1 324installs tanstack-vue-query-skilld tanstack-vue-query-skilld guides AI assistants on @tanstack/vue-query v5 conventions. It prevents reactivity bugs with query keys and SSR setup in Vue projects. CX Codex +1 223installs vueuse-core-skilld vueuse-core-skilld — a skill with the full @vueuse/core 15.0.0 API: new composables, v14 migration rules, deprecated functions and environment requirements. CX Codex +1 219installs vee-validate-skilld vee-validate-skilld — a skill for writing, reviewing, and debugging Vue 3 forms with vee-validate 4.15.x. Covers Composition API, validation schema patterns, typed-schema integration, version-specific changes since 4.9, and common pitfalls. CX Codex +1 188installs primevue-skilld primevue-skilld is a Claude Code skill that guides PrimeVue v5 setup, current component APIs, and theming in Vue 3 projects. CX Codex +1 187installs

Project sponsors

Companies that keep this analytics open