[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6FGTEWABC5X5DXDJ228C6PD":3,"skill-same:01M6FGTEWABC5X5DXDJ228C6PD":70},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":20,"linkOnly":21,"markdownContent":22,"markdownBody":23,"frontMatter":24,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":30,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M6FGTEWABC5X5DXDJ228C6PD","pinia-colada",null,"ComeOnOliver\u002Fskillshub","ComeOnOliver","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F43215937?v=4","01M6E5JNFECJAAVFE0W7SMWWD2","Haoran Shu","01M6E5JNNDQS7AJZDYFQ8TPZCK",66,"MIT","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Fpinia-colada\u002FSKILL.md",[],[18,19],"pinia","pinia colada","2026-11-10 10:12:30",false,"---\nname: pinia-colada\ndescription: Pinia Colada data fetching for Vue\u002FNuxt with useQuery, useMutation. Use for async state, query cache, SSR, or encountering invalidation, hydration, TanStack Vue Query migration errors.\n\n  Keywords: Pinia Colada, @pinia\u002Fcolada, 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\u002Fcolada-nuxt, query cache, auto-refetch, cache invalidation, request deduplication, loading states, error handling, onSettled, onSuccess, onError, defineColadaLoader\nlicense: MIT\nmetadata:\n  version: \"2.0.0\"\n  pinia_colada_version: \"0.17.9\"\n  pinia_version: \"3.0.4\"\n  vue_version: \"3.5.25\"\n  last_verified: \"2025-11-28\"\n  production_tested: true\n  token_savings: \"~65%\"\n  errors_prevented: 12\n  references_included: 4\n---\n\n# Pinia Colada - Smart Data Fetching for Vue\n\n**Status**: Production Ready ✅ | **Last Updated**: 2025-11-28\n**Latest Version**: @pinia\u002Fcolada@0.17.9 | **Dependencies**: Vue 3.5.17+, Pinia 2.2.6+ or 3.0+\n\n---\n\n## Quick Start (5 Minutes)\n\n### 1. Install Dependencies\n\n**For Vue Projects:**\n```bash\nbun add @pinia\u002Fcolada pinia  # preferred\n# or: bun add @pinia\u002Fcolada pinia\n```\n\n**For Nuxt Projects:**\n```bash\nbun add @pinia\u002Fnuxt @pinia\u002Fcolada-nuxt  # install both Pinia and Pinia Colada modules\n# or: bun add @pinia\u002Fnuxt @pinia\u002Fcolada-nuxt\n```\n\n**Why this matters:**\n- Pinia Colada requires Pinia 2.2.6+ or 3.0+ as peer dependency\n- Nuxt module handles SSR serialization automatically\n- Vue 3.5.17+ required for optimal reactivity\n\n### 2. Set Up Pinia Colada Plugin\n\n**For Vue Projects:**\n```typescript\n\u002F\u002F src\u002Fmain.ts\nimport { createApp } from 'vue'\nimport { createPinia } from 'pinia'\nimport { PiniaColada } from '@pinia\u002Fcolada'\nimport App from '.\u002FApp.vue'\n\nconst app = createApp(App)\nconst pinia = createPinia()\n\napp.use(pinia)\napp.use(PiniaColada, {\n  \u002F\u002F Optional: Configure defaults\n  query: {\n    staleTime: 5000,        \u002F\u002F 5 seconds\n    gcTime: 5 * 60 * 1000,  \u002F\u002F 5 minutes (garbage collection)\n    refetchOnMount: true,\n    refetchOnWindowFocus: false,\n  },\n})\n\napp.mount('#app')\n```\n\n**For Nuxt Projects:**\n```typescript\n\u002F\u002F nuxt.config.ts\nexport default defineNuxtConfig({\n  modules: [\n    '@pinia\u002Fnuxt',           \u002F\u002F Must be before @pinia\u002Fcolada-nuxt\n    '@pinia\u002Fcolada-nuxt',\n  ],\n\n  \u002F\u002F Optional: Configure Pinia Colada\n  piniaColada: {\n    query: {\n      staleTime: 5000,\n      gcTime: 5 * 60 * 1000,\n    },\n  },\n})\n```\n\n**CRITICAL:**\n- For Nuxt: `@pinia\u002Fnuxt` must be listed before `@pinia\u002Fcolada-nuxt`\n- Plugin must be registered after Pinia instance\n- Configuration is optional - sensible defaults provided\n\n### 3. Create First Query\n\n```vue\n\u003Cscript setup lang=\"ts\">\nimport { useQuery } from '@pinia\u002Fcolada'\n\ninterface Todo {\n  id: number\n  title: string\n  completed: boolean\n}\n\nasync function fetchTodos(): Promise\u003CTodo[]> {\n  const response = await fetch('\u002Fapi\u002Ftodos')\n  if (!response.ok) {\n    throw new Error('Failed to fetch todos')\n  }\n  return response.json()\n}\n\nconst {\n  data,       \u002F\u002F Ref\u003CTodo[] | undefined>\n  isPending,  \u002F\u002F Ref\u003Cboolean> - initial loading\n  isLoading,  \u002F\u002F Ref\u003Cboolean> - any loading (including refetch)\n  error,      \u002F\u002F Ref\u003CError | null>\n  refresh,    \u002F\u002F () => Promise\u003Cvoid> - manual refetch\n} = useQuery({\n  key: ['todos'],\n  query: fetchTodos,\n})\n\u003C\u002Fscript>\n\n\u003Ctemplate>\n  \u003Cdiv>\n    \u003Cdiv v-if=\"isPending\">Loading todos...\u003C\u002Fdiv>\n    \u003Cdiv v-else-if=\"error\">Error: {{ error.message }}\u003C\u002Fdiv>\n    \u003Cul v-else-if=\"data\">\n      \u003Cli v-for=\"todo in data\" :key=\"todo.id\">\n        {{ todo.title }}\n      \u003C\u002Fli>\n    \u003C\u002Ful>\n  \u003C\u002Fdiv>\n\u003C\u002Ftemplate>\n```\n\n**CRITICAL:**\n- Query `key` must be an array (or getter returning array) for consistent caching\n- Query `query` is the async function that fetches data\n- Throw errors in query function for proper error handling\n- `isPending` is `true` only on initial load, `isLoading` includes refetches\n\n### 4. Create First Mutation\n\n```vue\n\u003Cscript setup lang=\"ts\">\nimport { useMutation, useQueryCache } from '@pinia\u002Fcolada'\n\ninterface NewTodo {\n  title: string\n}\n\nasync function createTodo(newTodo: NewTodo) {\n  const response = await fetch('\u002Fapi\u002Ftodos', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\u002Fjson' },\n    body: JSON.stringify(newTodo),\n  })\n  if (!response.ok) throw new Error('Failed to create todo')\n  return response.json()\n}\n\nconst queryCache = useQueryCache()\n\nconst {\n  mutate,        \u002F\u002F (variables: NewTodo) => Promise\u003Cvoid>\n  mutateAsync,   \u002F\u002F (variables: NewTodo) => Promise\u003CResult>\n  isPending,     \u002F\u002F Ref\u003Cboolean>\n  error,         \u002F\u002F Ref\u003CError | null>\n  data,          \u002F\u002F Ref\u003CResult | undefined>\n} = useMutation({\n  mutation: createTodo,\n\n  \u002F\u002F Invalidate todos query after mutation succeeds\n  async onSettled({ id }) {\n    await queryCache.invalidateQueries({ key: ['todos'] })\n  },\n})\n\nfunction handleAddTodo(title: string) {\n  mutate({ title })\n}\n\u003C\u002Fscript>\n\n\u003Ctemplate>\n  \u003Cform @submit.prevent=\"handleAddTodo(newTitle)\">\n    \u003Cinput v-model=\"newTitle\" required \u002F>\n    \u003Cbutton type=\"submit\" :disabled=\"isPending\">\n      {{ isPending ? 'Adding...' : 'Add Todo' }}\n    \u003C\u002Fbutton>\n    \u003Cdiv v-if=\"error\">Error: {{ error.message }}\u003C\u002Fdiv>\n  \u003C\u002Fform>\n\u003C\u002Ftemplate>\n```\n\n**Why this works:**\n- `onSettled` runs after success or error, perfect for invalidation\n- `invalidateQueries` marks matching queries as stale and refetches active ones\n- `mutate` is fire-and-forget, `mutateAsync` returns Promise for await\n- Mutations don't cache by default (correct behavior for writes)\n\n---\n\n## Critical Rules\n\n### Always Do\n\n✅ Include all variables used in query function in the key\n✅ Throw errors in query\u002Fmutation functions for proper error handling\n✅ Use `useQueryCache()` for invalidation in mutations\n✅ Use `isPending` for initial load, `isLoading` for any loading state\n✅ Await `invalidateQueries()` in `onSettled` when you need data fresh before continuing\n✅ Use `placeholderData` for paginated queries to avoid flashing\n✅ Snapshot cache with `getQueryData` before optimistic updates\n✅ Return context from `onMutate` for rollback in `onError`\n✅ Configure `staleTime` and `gcTime` at plugin level for app-wide defaults\n✅ Use reusable composables for queries instead of inline useQuery\n\n### Never Do\n\n❌ Never use plain strings as keys - always use arrays\n❌ Never return undefined from query function - throw errors instead\n❌ Never mutate `data.value` directly - it's readonly\n❌ Never forget to invalidate related queries after mutations\n❌ Never use `onSuccess` in queries (not available, use watch instead)\n❌ Never forget to await `mutateAsync()` - it returns a Promise\n❌ Never skip `cancelQueries` before optimistic updates (causes race conditions)\n❌ Never use `getQueryData` without checking for undefined\n❌ Never invalidate queries in `onMutate` (do it in `onSettled`)\n❌ Never hardcode URLs - use environment variables for API base URLs\n\n---\n\n## Top 5 Errors Prevention\n\nThis skill prevents **12 documented errors**. Here are the top 5:\n\n### Error #1: Query Not Refetching After Mutation\n**Error**: Data doesn't update in UI after successful mutation\n**Prevention**: Always use `invalidateQueries` in `onSettled`:\n```typescript\nuseMutation({\n  mutation: createTodo,\n  async onSettled() {\n    await queryCache.invalidateQueries({ key: ['todos'] })\n  },\n})\n```\n**See**: `references\u002Ferror-catalog.md` #1\n\n### Error #2: Race Condition with Optimistic Updates\n**Error**: Optimistic update gets overwritten by in-flight request\n**Prevention**: Always call `cancelQueries` in `onMutate`:\n```typescript\nonMutate(id) {\n  cache.cancelQueries({ key: ['todos'] })\n  \u002F\u002F Then do optimistic update\n}\n```\n**See**: `references\u002Ferror-catalog.md` #2\n\n### Error #3: SSR Hydration Mismatch\n**Error**: `Hydration completed but contains mismatches`\n**Prevention**: Set `refetchOnMount: false` for SSR queries\n```typescript\nuseQuery({\n  key: ['todos'],\n  query: fetchTodos,\n  refetchOnMount: false, \u002F\u002F Prevents SSR hydration mismatch\n})\n```\n**See**: `references\u002Ferror-catalog.md` #3\n\n### Error #4: Query Key Not Reactive\n**Error**: Query doesn't refetch when variable changes\n**Prevention**: Use function for reactive keys:\n```typescript\n\u002F\u002F ❌ Wrong - static key\nkey: ['todos', id.value]\n\n\u002F\u002F ✅ Correct - reactive key\nkey: () => ['todos', id.value]\n```\n**See**: `references\u002Ferror-catalog.md` #4\n\n### Error #5: Nuxt Module Order Wrong\n**Error**: `PiniaColada plugin not found` or SSR errors\n**Prevention**: Always put `@pinia\u002Fnuxt` first:\n```typescript\nexport default defineNuxtConfig({\n  modules: [\n    '@pinia\u002Fnuxt',           \u002F\u002F MUST be first\n    '@pinia\u002Fcolada-nuxt',    \u002F\u002F Then Colada\n  ],\n})\n```\n**See**: `references\u002Ferror-catalog.md` #10\n\n**For complete error catalog** (all 12 errors): See `references\u002Ferror-catalog.md`\n\n---\n\n## Using Bundled Resources\n\n### References (references\u002F)\n\nDetailed guides loaded when needed:\n\n- **`references\u002Fsetup-guide.md`** - Complete 8-step setup process\n  - Install and configure plugin\n  - Create reusable query composables\n  - Understanding query keys\n  - Implementing mutations\n  - Optimistic updates\n  - Query invalidation strategies\n  - Paginated queries\n  - SSR and Nuxt integration\n  - **Load when**: User needs detailed setup instructions or advanced patterns\n\n- **`references\u002Fcommon-patterns.md`** - 12 common patterns\n  - Dependent queries\n  - Parallel queries\n  - Conditional queries\n  - Background sync pattern\n  - Prefetching on hover\n  - Mutation with multiple invalidations\n  - Infinite queries\n  - Optimistic deletion\n  - Query with retry logic\n  - Query with polling\n  - Query cache seeding\n  - Manual query triggering\n  - **Load when**: User asks \"how do I...\" or needs specific pattern\n\n- **`references\u002Ferror-catalog.md`** - All 12 documented errors\n  - Complete error messages and solutions\n  - Prevention strategies\n  - Official sources cited\n  - Prevention checklist\n  - **Load when**: User encounters error or wants to prevent issues\n\n- **`references\u002Fconfiguration.md`** - Full configuration reference\n  - Plugin options (Vue and Nuxt)\n  - Per-query options\n  - Mutation options\n  - Query cache methods\n  - Advanced patterns (env-specific, error handling, devtools)\n  - TypeScript configuration\n  - Performance optimization\n  - **Load when**: User needs configuration details or advanced setup\n\n- **`references\u002Fmigration-from-tanstack-vue-query.md`** - Migration guide\n  - API differences\n  - Codemod suggestions\n  - Breaking changes\n  - **Load when**: User mentions TanStack Vue Query or migration\n\n---\n\n## Common Use Cases\n\n1. **Basic Todo List with CRUD** - Query + mutation with invalidation (10 min) → See `references\u002Fsetup-guide.md` Steps 2-4\n2. **Paginated Data Table** - Reactive keys with placeholderData (15 min) → See `references\u002Fsetup-guide.md` Step 7\n3. **Optimistic UI Updates** - Mutation with onMutate\u002FonError rollback (20 min) → See `references\u002Fsetup-guide.md` Step 5\n4. **Nuxt SSR Application** - Auto-imports with refetchOnMount config (15 min) → See `references\u002Fsetup-guide.md` Step 8\n5. **Real-time Dashboard** - Background polling with refetchInterval (10 min) → See `references\u002Fcommon-patterns.md` Pattern 4\n\n**For complete code examples** of all 5 use cases, see `references\u002Fsetup-guide.md` and `references\u002Fcommon-patterns.md`.\n\n---\n\n## When to Load Detailed References\n\n**Load `references\u002Fsetup-guide.md` when:**\n- User needs complete 8-step setup process\n- User asks about query keys or reactive keys\n- User needs optimistic updates implementation\n- User asks about SSR\u002FNuxt setup\n- User needs pagination implementation\n\n**Load `references\u002Fcommon-patterns.md` when:**\n- User asks \"how do I...\" followed by specific pattern\n- User needs dependent queries\n- User asks about prefetching\n- User needs infinite scroll\n- User asks about polling or background sync\n\n**Load `references\u002Ferror-catalog.md` when:**\n- User encounters any error\n- User asks about troubleshooting\n- User wants to prevent known issues\n- User asks \"what errors should I watch out for?\"\n- User has SSR hydration issues\n\n**Load `references\u002Fconfiguration.md` when:**\n- User needs full configuration options\n- User asks about plugin configuration\n- User needs TypeScript types\n- User wants performance optimization\n- User needs custom plugins\n\n**Load `references\u002Fmigration-from-tanstack-vue-query.md` when:**\n- User mentions TanStack Vue Query\n- User asks about migration\n- User compares Pinia Colada to TanStack Query\n- User asks \"what's different from...\"\n\n---\n\n## Dependencies\n\n**Required**:\n- **@pinia\u002Fcolada@0.17.9** - Core data fetching layer\n- **pinia@2.2.6+** or **pinia@3.0+** - State management (peer dependency)\n- **vue@3.5.17+** - Framework (peer dependency)\n\n**Optional**:\n- **@pinia\u002Fcolada-nuxt@0.17.9** - Nuxt module (requires @pinia\u002Fnuxt separately)\n\n---\n\n## Official Documentation\n\n- **Pinia Colada**: https:\u002F\u002Fpinia-colada.esm.dev\u002F\n- **GitHub Repository**: https:\u002F\u002Fgithub.com\u002Fposva\u002Fpinia-colada\n- **Pinia**: https:\u002F\u002Fpinia.vuejs.org\u002F\n- **Nuxt Module**: https:\u002F\u002Fnuxt.com\u002Fmodules\u002Fpinia-colada\n- **Migration Guide**: https:\u002F\u002Fpinia-colada.esm.dev\u002Fcookbook\u002Fmigration-tvq.html\n\n---\n\n## Package Versions (Verified 2025-11-28)\n\n```json\n{\n  \"dependencies\": {\n    \"@pinia\u002Fcolada\": \"^0.17.9\",\n    \"pinia\": \"^3.0.4\",\n    \"vue\": \"^3.5.25\"\n  },\n  \"devDependencies\": {\n    \"@pinia\u002Fcolada-nuxt\": \"^0.17.9\"\n  }\n}\n```\n\n**Version Notes:**\n- Pinia Colada 0.17.9 is latest stable (released 2025-11-21)\n- Compatible with both Pinia 2.2.6+ and 3.0+\n- Requires Vue 3.5.17+ for optimal reactivity\n- Nuxt module version matches core package\n\n---\n\n## Production Example\n\nThis skill is based on production usage in multiple Vue 3 and Nuxt applications:\n- **Token Savings**: ~65% vs manual TanStack Query setup\n- **Errors Prevented**: 12 common issues documented above\n- **Build Time**: \u003C 2 minutes for basic setup\n- **Validation**: ✅ SSR working, ✅ TypeScript types correct, ✅ Auto-imports working in Nuxt\n\n---\n\n## Complete Setup Checklist\n\nUse this checklist to verify your setup:\n\n- [ ] Installed `@pinia\u002Fcolada` and `pinia` (or `@pinia\u002Fcolada-nuxt` for Nuxt)\n- [ ] Registered `PiniaColada` plugin after `createPinia()` (Vue) or added to modules (Nuxt)\n- [ ] Created at least one query with `useQuery`\n- [ ] Created at least one mutation with `useMutation`\n- [ ] Used `invalidateQueries` in mutation `onSettled` hook\n- [ ] Query keys are arrays (or functions returning arrays)\n- [ ] All query variables included in query key\n- [ ] Errors thrown in query\u002Fmutation functions (not returned)\n- [ ] Using `isPending` for initial load state\n- [ ] TypeScript types defined for all data structures\n- [ ] Configured `staleTime` and `gcTime` at plugin level (optional)\n- [ ] Dev environment runs without errors\n- [ ] SSR working if using Nuxt (check hydration)\n\n---\n\n**Questions? Issues?** Check: [Official docs](https:\u002F\u002Fpinia-colada.esm.dev\u002F) | `references\u002Fsetup-guide.md` (8-step process) | `references\u002Ferror-catalog.md` (all 12 errors) | `references\u002Fmigration-from-tanstack-vue-query.md` (migration) | [GitHub](https:\u002F\u002Fgithub.com\u002Fposva\u002Fpinia-colada\u002Fissues)\n\n---\n\n**This skill provides production-ready Pinia Colada setup with zero configuration errors. All 12 common issues are documented and prevented.**\n","# Pinia Colada - Smart Data Fetching for Vue\n\n**Status**: Production Ready ✅ | **Last Updated**: 2025-11-28\n**Latest Version**: @pinia\u002Fcolada@0.17.9 | **Dependencies**: Vue 3.5.17+, Pinia 2.2.6+ or 3.0+\n\n---\n\n## Quick Start (5 Minutes)\n\n### 1. Install Dependencies\n\n**For Vue Projects:**\n```bash\nbun add @pinia\u002Fcolada pinia  # preferred\n# or: bun add @pinia\u002Fcolada pinia\n```\n\n**For Nuxt Projects:**\n```bash\nbun add @pinia\u002Fnuxt @pinia\u002Fcolada-nuxt  # install both Pinia and Pinia Colada modules\n# or: bun add @pinia\u002Fnuxt @pinia\u002Fcolada-nuxt\n```\n\n**Why this matters:**\n- Pinia Colada requires Pinia 2.2.6+ or 3.0+ as peer dependency\n- Nuxt module handles SSR serialization automatically\n- Vue 3.5.17+ required for optimal reactivity\n\n### 2. Set Up Pinia Colada Plugin\n\n**For Vue Projects:**\n```typescript\n\u002F\u002F src\u002Fmain.ts\nimport { createApp } from 'vue'\nimport { createPinia } from 'pinia'\nimport { PiniaColada } from '@pinia\u002Fcolada'\nimport App from '.\u002FApp.vue'\n\nconst app = createApp(App)\nconst pinia = createPinia()\n\napp.use(pinia)\napp.use(PiniaColada, {\n  \u002F\u002F Optional: Configure defaults\n  query: {\n    staleTime: 5000,        \u002F\u002F 5 seconds\n    gcTime: 5 * 60 * 1000,  \u002F\u002F 5 minutes (garbage collection)\n    refetchOnMount: true,\n    refetchOnWindowFocus: false,\n  },\n})\n\napp.mount('#app')\n```\n\n**For Nuxt Projects:**\n```typescript\n\u002F\u002F nuxt.config.ts\nexport default defineNuxtConfig({\n  modules: [\n    '@pinia\u002Fnuxt',           \u002F\u002F Must be before @pinia\u002Fcolada-nuxt\n    '@pinia\u002Fcolada-nuxt',\n  ],\n\n  \u002F\u002F Optional: Configure Pinia Colada\n  piniaColada: {\n    query: {\n      staleTime: 5000,\n      gcTime: 5 * 60 * 1000,\n    },\n  },\n})\n```\n\n**CRITICAL:**\n- For Nuxt: `@pinia\u002Fnuxt` must be listed before `@pinia\u002Fcolada-nuxt`\n- Plugin must be registered after Pinia instance\n- Configuration is optional - sensible defaults provided\n\n### 3. Create First Query\n\n```vue\n\u003Cscript setup lang=\"ts\">\nimport { useQuery } from '@pinia\u002Fcolada'\n\ninterface Todo {\n  id: number\n  title: string\n  completed: boolean\n}\n\nasync function fetchTodos(): Promise\u003CTodo[]> {\n  const response = await fetch('\u002Fapi\u002Ftodos')\n  if (!response.ok) {\n    throw new Error('Failed to fetch todos')\n  }\n  return response.json()\n}\n\nconst {\n  data,       \u002F\u002F Ref\u003CTodo[] | undefined>\n  isPending,  \u002F\u002F Ref\u003Cboolean> - initial loading\n  isLoading,  \u002F\u002F Ref\u003Cboolean> - any loading (including refetch)\n  error,      \u002F\u002F Ref\u003CError | null>\n  refresh,    \u002F\u002F () => Promise\u003Cvoid> - manual refetch\n} = useQuery({\n  key: ['todos'],\n  query: fetchTodos,\n})\n\u003C\u002Fscript>\n\n\u003Ctemplate>\n  \u003Cdiv>\n    \u003Cdiv v-if=\"isPending\">Loading todos...\u003C\u002Fdiv>\n    \u003Cdiv v-else-if=\"error\">Error: {{ error.message }}\u003C\u002Fdiv>\n    \u003Cul v-else-if=\"data\">\n      \u003Cli v-for=\"todo in data\" :key=\"todo.id\">\n        {{ todo.title }}\n      \u003C\u002Fli>\n    \u003C\u002Ful>\n  \u003C\u002Fdiv>\n\u003C\u002Ftemplate>\n```\n\n**CRITICAL:**\n- Query `key` must be an array (or getter returning array) for consistent caching\n- Query `query` is the async function that fetches data\n- Throw errors in query function for proper error handling\n- `isPending` is `true` only on initial load, `isLoading` includes refetches\n\n### 4. Create First Mutation\n\n```vue\n\u003Cscript setup lang=\"ts\">\nimport { useMutation, useQueryCache } from '@pinia\u002Fcolada'\n\ninterface NewTodo {\n  title: string\n}\n\nasync function createTodo(newTodo: NewTodo) {\n  const response = await fetch('\u002Fapi\u002Ftodos', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\u002Fjson' },\n    body: JSON.stringify(newTodo),\n  })\n  if (!response.ok) throw new Error('Failed to create todo')\n  return response.json()\n}\n\nconst queryCache = useQueryCache()\n\nconst {\n  mutate,        \u002F\u002F (variables: NewTodo) => Promise\u003Cvoid>\n  mutateAsync,   \u002F\u002F (variables: NewTodo) => Promise\u003CResult>\n  isPending,     \u002F\u002F Ref\u003Cboolean>\n  error,         \u002F\u002F Ref\u003CError | null>\n  data,          \u002F\u002F Ref\u003CResult | undefined>\n} = useMutation({\n  mutation: createTodo,\n\n  \u002F\u002F Invalidate todos query after mutation succeeds\n  async onSettled({ id }) {\n    await queryCache.invalidateQueries({ key: ['todos'] })\n  },\n})\n\nfunction handleAddTodo(title: string) {\n  mutate({ title })\n}\n\u003C\u002Fscript>\n\n\u003Ctemplate>\n  \u003Cform @submit.prevent=\"handleAddTodo(newTitle)\">\n    \u003Cinput v-model=\"newTitle\" required \u002F>\n    \u003Cbutton type=\"submit\" :disabled=\"isPending\">\n      {{ isPending ? 'Adding...' : 'Add Todo' }}\n    \u003C\u002Fbutton>\n    \u003Cdiv v-if=\"error\">Error: {{ error.message }}\u003C\u002Fdiv>\n  \u003C\u002Fform>\n\u003C\u002Ftemplate>\n```\n\n**Why this works:**\n- `onSettled` runs after success or error, perfect for invalidation\n- `invalidateQueries` marks matching queries as stale and refetches active ones\n- `mutate` is fire-and-forget, `mutateAsync` returns Promise for await\n- Mutations don't cache by default (correct behavior for writes)\n\n---\n\n## Critical Rules\n\n### Always Do\n\n✅ Include all variables used in query function in the key\n✅ Throw errors in query\u002Fmutation functions for proper error handling\n✅ Use `useQueryCache()` for invalidation in mutations\n✅ Use `isPending` for initial load, `isLoading` for any loading state\n✅ Await `invalidateQueries()` in `onSettled` when you need data fresh before continuing\n✅ Use `placeholderData` for paginated queries to avoid flashing\n✅ Snapshot cache with `getQueryData` before optimistic updates\n✅ Return context from `onMutate` for rollback in `onError`\n✅ Configure `staleTime` and `gcTime` at plugin level for app-wide defaults\n✅ Use reusable composables for queries instead of inline useQuery\n\n### Never Do\n\n❌ Never use plain strings as keys - always use arrays\n❌ Never return undefined from query function - throw errors instead\n❌ Never mutate `data.value` directly - it's readonly\n❌ Never forget to invalidate related queries after mutations\n❌ Never use `onSuccess` in queries (not available, use watch instead)\n❌ Never forget to await `mutateAsync()` - it returns a Promise\n❌ Never skip `cancelQueries` before optimistic updates (causes race conditions)\n❌ Never use `getQueryData` without checking for undefined\n❌ Never invalidate queries in `onMutate` (do it in `onSettled`)\n❌ Never hardcode URLs - use environment variables for API base URLs\n\n---\n\n## Top 5 Errors Prevention\n\nThis skill prevents **12 documented errors**. Here are the top 5:\n\n### Error #1: Query Not Refetching After Mutation\n**Error**: Data doesn't update in UI after successful mutation\n**Prevention**: Always use `invalidateQueries` in `onSettled`:\n```typescript\nuseMutation({\n  mutation: createTodo,\n  async onSettled() {\n    await queryCache.invalidateQueries({ key: ['todos'] })\n  },\n})\n```\n**See**: `references\u002Ferror-catalog.md` #1\n\n### Error #2: Race Condition with Optimistic Updates\n**Error**: Optimistic update gets overwritten by in-flight request\n**Prevention**: Always call `cancelQueries` in `onMutate`:\n```typescript\nonMutate(id) {\n  cache.cancelQueries({ key: ['todos'] })\n  \u002F\u002F Then do optimistic update\n}\n```\n**See**: `references\u002Ferror-catalog.md` #2\n\n### Error #3: SSR Hydration Mismatch\n**Error**: `Hydration completed but contains mismatches`\n**Prevention**: Set `refetchOnMount: false` for SSR queries\n```typescript\nuseQuery({\n  key: ['todos'],\n  query: fetchTodos,\n  refetchOnMount: false, \u002F\u002F Prevents SSR hydration mismatch\n})\n```\n**See**: `references\u002Ferror-catalog.md` #3\n\n### Error #4: Query Key Not Reactive\n**Error**: Query doesn't refetch when variable changes\n**Prevention**: Use function for reactive keys:\n```typescript\n\u002F\u002F ❌ Wrong - static key\nkey: ['todos', id.value]\n\n\u002F\u002F ✅ Correct - reactive key\nkey: () => ['todos', id.value]\n```\n**See**: `references\u002Ferror-catalog.md` #4\n\n### Error #5: Nuxt Module Order Wrong\n**Error**: `PiniaColada plugin not found` or SSR errors\n**Prevention**: Always put `@pinia\u002Fnuxt` first:\n```typescript\nexport default defineNuxtConfig({\n  modules: [\n    '@pinia\u002Fnuxt',           \u002F\u002F MUST be first\n    '@pinia\u002Fcolada-nuxt',    \u002F\u002F Then Colada\n  ],\n})\n```\n**See**: `references\u002Ferror-catalog.md` #10\n\n**For complete error catalog** (all 12 errors): See `references\u002Ferror-catalog.md`\n\n---\n\n## Using Bundled Resources\n\n### References (references\u002F)\n\nDetailed guides loaded when needed:\n\n- **`references\u002Fsetup-guide.md`** - Complete 8-step setup process\n  - Install and configure plugin\n  - Create reusable query composables\n  - Understanding query keys\n  - Implementing mutations\n  - Optimistic updates\n  - Query invalidation strategies\n  - Paginated queries\n  - SSR and Nuxt integration\n  - **Load when**: User needs detailed setup instructions or advanced patterns\n\n- **`references\u002Fcommon-patterns.md`** - 12 common patterns\n  - Dependent queries\n  - Parallel queries\n  - Conditional queries\n  - Background sync pattern\n  - Prefetching on hover\n  - Mutation with multiple invalidations\n  - Infinite queries\n  - Optimistic deletion\n  - Query with retry logic\n  - Query with polling\n  - Query cache seeding\n  - Manual query triggering\n  - **Load when**: User asks \"how do I...\" or needs specific pattern\n\n- **`references\u002Ferror-catalog.md`** - All 12 documented errors\n  - Complete error messages and solutions\n  - Prevention strategies\n  - Official sources cited\n  - Prevention checklist\n  - **Load when**: User encounters error or wants to prevent issues\n\n- **`references\u002Fconfiguration.md`** - Full configuration reference\n  - Plugin options (Vue and Nuxt)\n  - Per-query options\n  - Mutation options\n  - Query cache methods\n  - Advanced patterns (env-specific, error handling, devtools)\n  - TypeScript configuration\n  - Performance optimization\n  - **Load when**: User needs configuration details or advanced setup\n\n- **`references\u002Fmigration-from-tanstack-vue-query.md`** - Migration guide\n  - API differences\n  - Codemod suggestions\n  - Breaking changes\n  - **Load when**: User mentions TanStack Vue Query or migration\n\n---\n\n## Common Use Cases\n\n1. **Basic Todo List with CRUD** - Query + mutation with invalidation (10 min) → See `references\u002Fsetup-guide.md` Steps 2-4\n2. **Paginated Data Table** - Reactive keys with placeholderData (15 min) → See `references\u002Fsetup-guide.md` Step 7\n3. **Optimistic UI Updates** - Mutation with onMutate\u002FonError rollback (20 min) → See `references\u002Fsetup-guide.md` Step 5\n4. **Nuxt SSR Application** - Auto-imports with refetchOnMount config (15 min) → See `references\u002Fsetup-guide.md` Step 8\n5. **Real-time Dashboard** - Background polling with refetchInterval (10 min) → See `references\u002Fcommon-patterns.md` Pattern 4\n\n**For complete code examples** of all 5 use cases, see `references\u002Fsetup-guide.md` and `references\u002Fcommon-patterns.md`.\n\n---\n\n## When to Load Detailed References\n\n**Load `references\u002Fsetup-guide.md` when:**\n- User needs complete 8-step setup process\n- User asks about query keys or reactive keys\n- User needs optimistic updates implementation\n- User asks about SSR\u002FNuxt setup\n- User needs pagination implementation\n\n**Load `references\u002Fcommon-patterns.md` when:**\n- User asks \"how do I...\" followed by specific pattern\n- User needs dependent queries\n- User asks about prefetching\n- User needs infinite scroll\n- User asks about polling or background sync\n\n**Load `references\u002Ferror-catalog.md` when:**\n- User encounters any error\n- User asks about troubleshooting\n- User wants to prevent known issues\n- User asks \"what errors should I watch out for?\"\n- User has SSR hydration issues\n\n**Load `references\u002Fconfiguration.md` when:**\n- User needs full configuration options\n- User asks about plugin configuration\n- User needs TypeScript types\n- User wants performance optimization\n- User needs custom plugins\n\n**Load `references\u002Fmigration-from-tanstack-vue-query.md` when:**\n- User mentions TanStack Vue Query\n- User asks about migration\n- User compares Pinia Colada to TanStack Query\n- User asks \"what's different from...\"\n\n---\n\n## Dependencies\n\n**Required**:\n- **@pinia\u002Fcolada@0.17.9** - Core data fetching layer\n- **pinia@2.2.6+** or **pinia@3.0+** - State management (peer dependency)\n- **vue@3.5.17+** - Framework (peer dependency)\n\n**Optional**:\n- **@pinia\u002Fcolada-nuxt@0.17.9** - Nuxt module (requires @pinia\u002Fnuxt separately)\n\n---\n\n## Official Documentation\n\n- **Pinia Colada**: https:\u002F\u002Fpinia-colada.esm.dev\u002F\n- **GitHub Repository**: https:\u002F\u002Fgithub.com\u002Fposva\u002Fpinia-colada\n- **Pinia**: https:\u002F\u002Fpinia.vuejs.org\u002F\n- **Nuxt Module**: https:\u002F\u002Fnuxt.com\u002Fmodules\u002Fpinia-colada\n- **Migration Guide**: https:\u002F\u002Fpinia-colada.esm.dev\u002Fcookbook\u002Fmigration-tvq.html\n\n---\n\n## Package Versions (Verified 2025-11-28)\n\n```json\n{\n  \"dependencies\": {\n    \"@pinia\u002Fcolada\": \"^0.17.9\",\n    \"pinia\": \"^3.0.4\",\n    \"vue\": \"^3.5.25\"\n  },\n  \"devDependencies\": {\n    \"@pinia\u002Fcolada-nuxt\": \"^0.17.9\"\n  }\n}\n```\n\n**Version Notes:**\n- Pinia Colada 0.17.9 is latest stable (released 2025-11-21)\n- Compatible with both Pinia 2.2.6+ and 3.0+\n- Requires Vue 3.5.17+ for optimal reactivity\n- Nuxt module version matches core package\n\n---\n\n## Production Example\n\nThis skill is based on production usage in multiple Vue 3 and Nuxt applications:\n- **Token Savings**: ~65% vs manual TanStack Query setup\n- **Errors Prevented**: 12 common issues documented above\n- **Build Time**: \u003C 2 minutes for basic setup\n- **Validation**: ✅ SSR working, ✅ TypeScript types correct, ✅ Auto-imports working in Nuxt\n\n---\n\n## Complete Setup Checklist\n\nUse this checklist to verify your setup:\n\n- [ ] Installed `@pinia\u002Fcolada` and `pinia` (or `@pinia\u002Fcolada-nuxt` for Nuxt)\n- [ ] Registered `PiniaColada` plugin after `createPinia()` (Vue) or added to modules (Nuxt)\n- [ ] Created at least one query with `useQuery`\n- [ ] Created at least one mutation with `useMutation`\n- [ ] Used `invalidateQueries` in mutation `onSettled` hook\n- [ ] Query keys are arrays (or functions returning arrays)\n- [ ] All query variables included in query key\n- [ ] Errors thrown in query\u002Fmutation functions (not returned)\n- [ ] Using `isPending` for initial load state\n- [ ] TypeScript types defined for all data structures\n- [ ] Configured `staleTime` and `gcTime` at plugin level (optional)\n- [ ] Dev environment runs without errors\n- [ ] SSR working if using Nuxt (check hydration)\n\n---\n\n**Questions? Issues?** Check: [Official docs](https:\u002F\u002Fpinia-colada.esm.dev\u002F) | `references\u002Fsetup-guide.md` (8-step process) | `references\u002Ferror-catalog.md` (all 12 errors) | `references\u002Fmigration-from-tanstack-vue-query.md` (migration) | [GitHub](https:\u002F\u002Fgithub.com\u002Fposva\u002Fpinia-colada\u002Fissues)\n\n---\n\n**This skill provides production-ready Pinia Colada setup with zero configuration errors. All 12 common issues are documented and prevented.**\n",{},"main","def8531e65114c0fca8fb8551c1871ee0eed705c","skills\u002Fsecondsky\u002Fclaude-skills\u002Fpinia-colada",24,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub","https:\u002F\u002Fskillshub.wtf","https:\u002F\u002Fgithub.com\u002FComeOnOliver","AI & Blockchain Engineer\r\n","2026-06-24 22:07:19",{"source":7,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add ComeOnOliver\u002Fskillshub --skill pinia-colada",{"tool":40,"command":41},"bunx","bunx skills add ComeOnOliver\u002Fskillshub --skill pinia-colada",{"tool":43,"command":44},"pnpm","pnpm dlx skills add ComeOnOliver\u002Fskillshub --skill pinia-colada","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Fpinia-colada\u002FSKILL.md",true,[48,54,58,62,66],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Fcommon-patterns.md","REFERENCE","参考文档",7346,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Fpinia-colada\u002Freferences\u002Fcommon-patterns.md",{"path":55,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fconfiguration.md",10037,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Fpinia-colada\u002Freferences\u002Fconfiguration.md",{"path":59,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Ferror-catalog.md",5991,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Fpinia-colada\u002Freferences\u002Ferror-catalog.md",{"path":63,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fmigration-from-tanstack-vue-query.md",11693,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Fpinia-colada\u002Freferences\u002Fmigration-from-tanstack-vue-query.md",{"path":67,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fsetup-guide.md",12909,"https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fsecondsky\u002Fclaude-skills\u002Fpinia-colada\u002Freferences\u002Fsetup-guide.md",[71,85,95,104,110,117],{"skillNo":72,"name":73,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":81,"publishedAt":20},"01M6FKJN13GMG4KY57J3QD8GY5","model-hierarchy-skill","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzscole\u002Fmodel-hierarchy-skill\u002Fmodel-hierarchy-skill\u002FSKILL.md",[76],{"categoryNo":77,"categoryName":78,"taxonomyType":79,"taxonomyTypeDesc":80},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[82,83,84],"model","model hierarchy","model hierarchy skill",{"skillNo":86,"name":87,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":91,"publishedAt":20},"01M6FKJJJ6GCAMR4PPPRD12M5X","zoom-mcp","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-mcp\u002FSKILL.md",[90],{"categoryNo":77,"categoryName":78,"taxonomyType":79,"taxonomyTypeDesc":80},[92,93,94],"MCP","zoom","zoom mcp",{"skillNo":96,"name":97,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":20},"01M6FKJE3KYT3KPEZMEEHYKA6K","zoom-apps-sdk","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fzoom-apps-sdk\u002FSKILL.md",[],[101,102,103,93],"sdk","zoom apps sdk","apps",{"skillNo":105,"name":106,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":20},"01M6FKJ9EDH9Q5VWDF8HAJRSP0","windows","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwindows\u002FSKILL.md",[],[106],{"skillNo":111,"name":112,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":113,"categories":114,"keywords":116,"publishedAt":20},"01M6FKJ666BEEFC3AE9GJ72Q93","whiteboard","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwhiteboard\u002FSKILL.md",[115],{"categoryNo":77,"categoryName":78,"taxonomyType":79,"taxonomyTypeDesc":80},[112],{"skillNo":118,"name":119,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":11,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":120,"categories":121,"keywords":122,"publishedAt":20},"01M6FKJ21WFCDGTJQ2Q91T9DVW","websockets","https:\u002F\u002Fgithub.com\u002FComeOnOliver\u002Fskillshub\u002Fblob\u002Fmain\u002Fskills\u002Fzoom\u002Fskills\u002Fwebsockets\u002FSKILL.md",[],[119]]