Skip to main content
skill CX Codex

pinia-colada — Claude Code skill: Vue/Nuxt query caching

Skill that brings Pinia Colada data fetching into Claude Code and other AI editors. Handles async state, query caching, SSR, and migration from TanStack Vue Query with useQuery and useMutation.

MIT 253 installs ★ 250 updated 2026-10-20

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

What pinia-colada does

pinia-colada is a skill that integrates the Pinia Colada data library reference into your AI editor. It includes examples and patterns for useQuery (data loading), useMutation (writes), and useQueryCache (cache management). The skill explains how to initialize the plugin in main.ts for Vue or nuxt.config.ts for Nuxt, which options matter (staleTime, gcTime, refetchOnMount), and what breaks easily: wrong key types, forgotten await on mutateAsync, missing cache invalidation after writes, race conditions without cancelQueries.

The skill documents 12 prevented errors and provides working code samples. Requires Vue 3.5.17+, Pinia 2.2.6+ or 3.0+. For Nuxt, @pinia/nuxt must come before @pinia/colada-nuxt in module list. Token savings around 65%—the skill replaces boilerplate with patterns you can copy and adapt.

What it helps with

  • Set up caching and refetch strategy for async state in Vue 3
  • Invalidate queries in the right order after server mutations
  • Implement SSR with hydration without duplicate requests
  • Migrate from TanStack Vue Query to Pinia Colada safely
  • Prevent race conditions in concurrent requests

Example prompts for the agent

  • Show a useQuery example with a key array and error handling for Vue 3
  • How do I install and configure pinia-colada in a Nuxt project
  • Write a mutation that invalidates the todos query on success

How to install pinia-colada

1Skills CLI (Vercel)

npx skills add secondsky/claude-skills --skill pinia-colada -a claude-code

2Manually: put the files in place

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

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pinia-colada

How do I install pinia-colada for Claude Code?

Run npx skills add secondsky/claude-skills --skill pinia-colada -a claude-code, then open ~/.claude/skills/pinia-colada/SKILL.md. For other editors, change the flag: -a codex for Codex, -a cursor for Cursor, -a gemini-cli for Gemini CLI.

What does the pinia-colada skill do?

The skill teaches your AI editor the Pinia Colada API, cache rules, common pitfalls, and ready-made code patterns for useQuery, useMutation, and cache invalidation. Without it, your editor won't know when to await mutateAsync or how to prevent data races.

Do I need this skill if I already know Pinia Colada?

The skill helps your editor assist you. If you're writing code yourself, it works as a quick reference with examples. For reading documentation alone, it's less critical.

Source text

SKILL.md · MIT
---
name: pinia-colada
description: "Pinia Colada data fetching for Vue/Nuxt with useQuery, useMutation. Use for async state, query cache, SSR, or encountering invalidation, hydration, TanStack Vue Query migration errors."
license: MIT
metadata:
  version: "2.0.0"
  pinia_colada_version: "0.17.9"
  pinia_version: "3.0.4"
  vue_version: "3.5.25"
  last_verified: "2025-11-28"
  production_tested: true
  token_savings: "~65%"
  errors_prevented: 12
  references_included: 4
  keywords:
    - Pinia Colada
    - "@pinia/colada"
    - useQuery
    - useMutation
    - useQueryCache
    - data fetching
    - async state
    - Vue 3
    - Nuxt
    - Pinia
    - server state
    - caching
    - staleTime
    - gcTime
    - query invalidation
    - prefetching
    - optimistic updates
    - mutations
    - query keys
    - paginated queries
    - SSR
    - server-side rendering
    - Nuxt module
    - "@pinia/colada-nuxt"
    - query cache
    - auto-refetch
    - cache invalidation
    - request deduplication
    - loading states
    - error handling
    - onSettled
    - onSuccess
    - onError
    - defineColadaLoader
---
# Pinia Colada - Smart Data Fetching for Vue

**Status**: Production Ready ✅ | **Last Updated**: 2025-11-28
**Latest Version**: @pinia/[email protected] | **Dependencies**: Vue 3.5.17+, Pinia 2.2.6+ or 3.0+

---

## Quick Start (5 Minutes)

### 1. Install Dependencies

**For Vue Projects:**
```bash
bun add @pinia/colada pinia  # preferred
# or: bun add @pinia/colada pinia
```

**For Nuxt Projects:**
```bash
bun add @pinia/nuxt @pinia/colada-nuxt  # install both Pinia and Pinia Colada modules
# or: bun add @pinia/nuxt @pinia/colada-nuxt
```

**Why this matters:**
- Pinia Colada requires Pinia 2.2.6+ or 3.0+ as peer dependency
- Nuxt module handles SSR serialization automatically
- Vue 3.5.17+ required for optimal reactivity

### 2. Set Up Pinia Colada Plugin

**For Vue Projects:**
```typescript
// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import { PiniaColada } from '@pinia/colada'
import App from './App.vue'

const app = createApp(App)
const pinia = createPinia()

app.use(pinia)
app.use(PiniaColada, {
  // Optional: Configure defaults
  query: {
    staleTime: 5000,        // 5 seconds
    gcTime: 5 * 60 * 1000,  // 5 minutes (garbage collection)
    refetchOnMount: true,
    refetchOnWindowFocus: false,
  },
})

app.mount('#app')
```

**For Nuxt Projects:**
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',           // Must be before @pinia/colada-nuxt
    '@pinia/colada-nuxt',
  ],

  // Optional: Configure Pinia Colada
  piniaColada: {
    query: {
      staleTime: 5000,
      gcTime: 5 * 60 * 1000,
    },
  },
})
```

**CRITICAL:**
- For Nuxt: `@pinia/nuxt` must be listed before `@pinia/colada-nuxt`
- Plugin must be registered after Pinia instance
- Configuration is optional - sensible defaults provided

### 3. Create First Query

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

interface Todo {
  id: number
  title: string
  completed: boolean
}

async function fetchTodos(): Promise<Todo[]> {
  const response = await fetch('/api/todos')
  if (!response.ok) {
    throw new Error('Failed to fetch todos')
  }
  return response.json()
}

const {
  data,       // Ref<Todo[] | undefined>
  isPending,  // Ref<boolean> - initial loading
  isLoading,  // Ref<boolean> - any loading (including refetch)
  error,      // Ref<Error | null>
  refresh,    // () => Promise<void> - manual refetch
} = useQuery({
  key: ['todos'],
  query: fetchTodos,
})
</script>

<template>
  <div>
    <div v-if="isPending">Loading todos...</div>
    <div v-else-if="error">Error: {{ error.message }}</div>
    <ul v-else-if="data">
      <li v-for="todo in data" :key="todo.id">
        {{ todo.title }}
      </li>
    </ul>
  </div>
</template>
```

**CRITICAL:**
- Query `key` must be an array (or getter returning array) for consistent caching
- Query `query` is the async function that fetches data
- Throw errors in query function for proper error handling
- `isPending` is `true` only on initial load, `isLoading` includes refetches

### 4. Create First Mutation

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

interface NewTodo {
  title: string
}

async function createTodo(newTodo: NewTodo) {
  const response = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(newTodo),
  })
  if (!response.ok) throw new Error('Failed to create todo')
  return response.json()
}

const queryCache = useQueryCache()

const {
  mutate,        // (variables: NewTodo) => Promise<void>
  mutateAsync,   // (variables: NewTodo) => Promise<Result>
  isPending,     // Ref<boolean>
  error,         // Ref<Error | null>
  data,          // Ref<Result | undefined>
} = useMutation({
  mutation: createTodo,

  // Invalidate todos query after mutation succeeds
  async onSettled({ id }) {
    await queryCache.invalidateQueries({ key: ['todos'] })
  },
})

function handleAddTodo(title: string) {
  mutate({ title })
}
</script>

<template>
  <form @submit.prevent="handleAddTodo(newTitle)">
    <input v-model="newTitle" required />
    <button type="submit" :disabled="isPending">
      {{ isPending ? 'Adding...' : 'Add Todo' }}
    </button>
    <div v-if="error">Error: {{ error.message }}</div>
  </form>
</template>
```

**Why this works:**
- `onSettled` runs after success or error, perfect for invalidation
- `invalidateQueries` marks matching queries as stale and refetches active ones
- `mutate` is fire-and-forget, `mutateAsync` returns Promise for await
- Mutations don't cache by default (correct behavior for writes)

---

## Critical Rules

### Always Do

✅ Include all variables used in query function in the key
✅ Throw errors in query/mutation functions for proper error handling
✅ Use `useQueryCache()` for invalidation in mutations
✅ Use `isPending` for initial load, `isLoading` for any loading state
✅ Await `invalidateQueries()` in `onSettled` when you need data fresh before continuing
✅ Use `placeholderData` for paginated queries to avoid flashing
✅ Snapshot cache with `getQueryData` before optimistic updates
✅ Return context from `onMutate` for rollback in `onError`
✅ Configure `staleTime` and `gcTime` at plugin level for app-wide defaults
✅ Use reusable composables for queries instead of inline useQuery

### Never Do

❌ Never use plain strings as keys - always use arrays
❌ Never return undefined from query function - throw errors instead
❌ Never mutate `data.value` directly - it's readonly
❌ Never forget to invalidate related queries after mutations
❌ Never use `onSuccess` in queries (not available, use watch instead)
❌ Never forget to await `mutateAsync()` - it returns a Promise
❌ Never skip `cancelQueries` before optimistic updates (causes race conditions)
❌ Never use `getQueryData` without checking for undefined
❌ Never invalidate queries in `onMutate` (do it in `onSettled`)
❌ Never hardcode URLs - use environment variables for API base URLs

---

## Top 5 Errors Prevention

This skill prevents **12 documented errors**. Here are the top 5:

### Error #1: Query Not Refetching After Mutation
**Error**: Data doesn't update in UI after successful mutation
**Prevention**: Always use `invalidateQueries` in `onSettled`:
```typescript
useMutation({
  mutation: createTodo,
  async onSettled() {
    await queryCache.invalidateQueries({ key: ['todos'] })
  },
})
```
**See**: `references/error-catalog.md` #1

### Error #2: Race Condition with Optimistic Updates
**Error**: Optimistic update gets overwritten by in-flight request
**Prevention**: Always call `cancelQueries` in `onMutate`:
```typescript
onMutate(id) {
  cache.cancelQueries({ key: ['todos'] })
  // Then do optimistic update
}
```
**See**: `references/error-catalog.md` #2

### Error #3: SSR Hydration Mismatch
**Error**: `Hydration completed but contains mismatches`
**Prevention**: Set `refetchOnMount: false` for SSR queries
```typescript
useQuery({
  key: ['todos'],
  query: fetchTodos,
  refetchOnMount: false, // Prevents SSR hydration mismatch
})
```
**See**: `references/error-catalog.md` #3

### Error #4: Query Key Not Reactive
**Error**: Query doesn't refetch when variable changes
**Prevention**: Use function for reactive keys:
```typescript
// ❌ Wrong - static key
key: ['todos', id.value]

// ✅ Correct - reactive key
key: () => ['todos', id.value]
```
**See**: `references/error-catalog.md` #4

### Error #5: Nuxt Module Order Wrong
**Error**: `PiniaColada plugin not found` or SSR errors
**Prevention**: Always put `@pinia/nuxt` first:
```typescript
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',           // MUST be first
    '@pinia/colada-nuxt',    // Then Colada
  ],
})
```
**See**: `references/error-catalog.md` #10

**For complete error catalog** (all 12 errors): See `references/error-catalog.md`

---

## Using Bundled Resources

### References (references/)

Detailed guides loaded when needed:

- **`references/setup-guide.md`** - Complete 8-step setup process
  - Install and configure plugin
  - Create reusable query composables
  - Understanding query keys
  - Implementing mutations
  - Optimistic updates
  - Query invalidation strategies
  - Paginated queries
  - SSR and Nuxt integration
  - **Load when**: User needs detailed setup instructions or advanced patterns

- **`references/common-patterns.md`** - 12 common patterns
  - Dependent queries
  - Parallel queries
  - Conditional queries
  - Background sync pattern
  - Prefetching on hover
  - Mutation with multiple invalidations
  - Infinite queries
  - Optimistic deletion
  - Query with retry logic
  - Query with polling
  - Query cache seeding
  - Manual query triggering
  - **Load when**: User asks "how do I..." or needs specific pattern

- **`references/error-catalog.md`** - All 12 documented errors
  - Complete error messages and solutions
  - Prevention strategies
  - Official sources cited
  - Prevention checklist
  - **Load when**: User encounters error or wants to prevent issues

- **`references/configuration.md`** - Full configuration reference
  - Plugin options (Vue and Nuxt)
  - Per-query options
  - Mutation options
  - Query cache methods
  - Advanced patterns (env-specific, error handling, devtools)
  - TypeScript configuration
  - Performance optimization
  - **Load when**: User needs configuration details or advanced setup

- **`references/migration-from-tanstack-vue-query.md`** - Migration guide
  - API differences
  - Codemod suggestions
  - Breaking changes
  - **Load when**: User mentions TanStack Vue Query or migration

---

## Common Use Cases

1. **Basic Todo List with CRUD** - Query + mutation with invalidation (10 min) → See `references/setup-guide.md` Steps 2-4
2. **Paginated Data Table** - Reactive keys with placeholderData (15 min) → See `references/setup-guide.md` Step 7
3. **Optimistic UI Updates** - Mutation with onMutate/onError rollback (20 min) → See `references/setup-guide.md` Step 5
4. **Nuxt SSR Application** - Auto-imports with refetchOnMount config (15 min) → See `references/setup-guide.md` Step 8
5. **Real-time Dashboard** - Background polling with refetchInterval (10 min) → See `references/common-patterns.md` Pattern 4

**For complete code examples** of all 5 use cases, see `references/setup-guide.md` and `references/common-patterns.md`.

---

## When to Load Detailed References

**Load `references/setup-guide.md` when:**
- User needs complete 8-step setup process
- User asks about query keys or reactive keys
- User needs optimistic updates implementation
- User asks about SSR/Nuxt setup
- User needs pagination implementation

**Load `references/common-patterns.md` when:**
- User asks "how do I..." followed by specific pattern
- User needs dependent queries
- User asks about prefetching
- User needs infinite scroll
- User asks about polling or background sync

**Load `references/error-catalog.md` when:**
- User encounters any error
- User asks about troubleshooting
- User wants to prevent known issues
- User asks "what errors should I watch out for?"
- User has SSR hydration issues

**Load `references/configuration.md` when:**
- User needs full configuration options
- User asks about plugin configuration
- User needs TypeScript types
- User wants performance optimization
- User needs custom plugins

**Load `references/migration-from-tanstack-vue-query.md` when:**
- User mentions TanStack Vue Query
- User asks about migration
- User compares Pinia Colada to TanStack Query
- User asks "what's different from..."

---

## Dependencies

**Required**:
- **@pinia/[email protected]** - Core data fetching layer
- **[email protected]+** or **[email protected]+** - State management (peer dependency)
- **[email protected]+** - Framework (peer dependency)

**Optional**:
- **@pinia/[email protected]** - Nuxt module (requires @pinia/nuxt separately)

---

## Official Documentation

- **Pinia Colada**: https://pinia-colada.esm.dev/
- **GitHub Repository**: https://github.com/posva/pinia-colada
- **Pinia**: https://pinia.vuejs.org/
- **Nuxt Module**: https://nuxt.com/modules/pinia-colada
- **Migration Guide**: https://pinia-colada.esm.dev/cookbook/migration-tvq.html

---

## Package Versions (Verified 2025-11-28)

```json
{
  "dependencies": {
    "@pinia/colada": "^0.17.9",
    "pinia": "^3.0.4",
    "vue": "^3.5.25"
  },
  "devDependencies": {
    "@pinia/colada-nuxt": "^0.17.9"
  }
}
```

**Version Notes:**
- Pinia Colada 0.17.9 is latest stable (released 2025-11-21)
- Compatible with both Pinia 2.2.6+ and 3.0+
- Requires Vue 3.5.17+ for optimal reactivity
- Nuxt module version matches core package

---

## Production Example

This skill is based on production usage in multiple Vue 3 and Nuxt applications:
- **Token Savings**: ~65% vs manual TanStack Query setup
- **Errors Prevented**: 12 common issues documented above
- **Build Time**: < 2 minutes for basic setup
- **Validation**: ✅ SSR working, ✅ TypeScript types correct, ✅ Auto-imports working in Nuxt

---

## Complete Setup Checklist

Use this checklist to verify your setup:

- [ ] Installed `@pinia/colada` and `pinia` (or `@pinia/colada-nuxt` for Nuxt)
- [ ] Registered `PiniaColada` plugin after `createPinia()` (Vue) or added to modules (Nuxt)
- [ ] Created at least one query with `useQuery`
- [ ] Created at least one mutation with `useMutation`
- [ ] Used `invalidateQueries` in mutation `onSettled` hook
- [ ] Query keys are arrays (or functions returning arrays)
- [ ] All query variables included in query key
- [ ] Errors thrown in query/mutation functions (not returned)
- [ ] Using `isPending` for initial load state
- [ ] TypeScript types defined for all data structures
- [ ] Configured `staleTime` and `gcTime` at plugin level (optional)
- [ ] Dev environment runs without errors
- [ ] SSR working if using Nuxt (check hydration)

---

**Questions? Issues?** Check: [Official docs](https://pinia-colada.esm.dev/) | `references/setup-guide.md` (8-step process) | `references/error-catalog.md` (all 12 errors) | `references/migration-from-tanstack-vue-query.md` (migration) | [GitHub](https://github.com/posva/pinia-colada/issues)

---

**This skill provides production-ready Pinia Colada setup with zero configuration errors. All 12 common issues are documented and prevented.**

© secondsky · MIT · secondsky/claude-skills

Similar skills

All skills for Frontend and UI →

From the same set138

The whole set →
nextjs Skill for Next.js 16 and React 19.2 with App Router, Server Components, Server Actions, and caching patterns. Handles migration from version 15, async params errors, and Partial Prerendering setup. CX Codex +1 299installs feature-dev The feature-dev skill guides feature work through seven phases, from codebase discovery to review. Use it for multi-file changes and unclear architecture decisions. CX Codex +1 294installs cloudflare-nextjs The cloudflare-nextjs skill guides Next.js deployments to Cloudflare Workers with OpenNext. Use it to migrate a project or troubleshoot Workers-specific configuration and runtime issues. CX Codex +1 267installs cloudflare-turnstile cloudflare-turnstile is a Claude Code skill for adding Turnstile and checking tokens on the server. It activates for bot protection work, widget errors, and CSP or token validation failures. CX Codex +1 261installs base-ui-react base-ui-react is a Claude Code skill for building MUI Base UI interfaces, configuring accessible components and popup positioning, and migrating from Radix UI. CX Codex +1 259installs auto-animate Shows how to wire up @formkit/auto-animate in React for lists, accordions and toasts. Animations with zero config, 3.28 KB gzipped. CX Codex +1 257installs hono-routing hono-routing — a skill for building Hono APIs: routes, middleware, Zod or Valibot validation, RPC client with type inference. Covers 12 common errors and their solutions. CX Codex +1 256installs github-project-automation github-project-automation is a Claude Code skill for setting up GitHub Actions, repository templates, CodeQL, and Dependabot. It helps start projects and troubleshoot workflow YAML. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open