pinia-colada

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pinia Colada - Smart Data Fetching for Vue

Pinia Colada - Vue智能数据获取工具

Status: Production Ready ✅ | Last Updated: 2025-11-28 Latest Version: @pinia/colada@0.17.9 | Dependencies: Vue 3.5.17+, Pinia 2.2.6+ or 3.0+

状态: 已就绪可用于生产环境 ✅ | 最后更新: 2025-11-28 最新版本: @pinia/colada@0.17.9 | 依赖项: Vue 3.5.17+, Pinia 2.2.6+ 或 3.0+

Quick Start (5 Minutes)

快速开始（5分钟）

1. Install Dependencies

1. 安装依赖项

For Vue Projects:

bash

bun add @pinia/colada pinia  # preferred

Vue项目适用:

bash

bun add @pinia/colada pinia  # 推荐方式

or: bun add @pinia/colada pinia

或: bun add @pinia/colada pinia


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


**Nuxt项目适用**:
```bash
bun add @pinia/nuxt @pinia/colada-nuxt  # 同时安装Pinia和Pinia Colada模块

or: bun add @pinia/nuxt @pinia/colada-nuxt

或: 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


**重要说明**:
- Pinia Colada 需要 Pinia 2.2.6+ 或 3.0+ 作为对等依赖项
- Nuxt模块会自动处理SSR序列化
- 推荐使用Vue 3.5.17+以获得最佳响应式体验

2. Set Up Pinia Colada Plugin

2. 配置Pinia Colada插件

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

Vue项目适用:

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, {
  // 可选：配置默认参数
  query: {
    staleTime: 5000,        // 5秒
    gcTime: 5 * 60 * 1000,  // 5分钟（垃圾回收）
    refetchOnMount: true,
    refetchOnWindowFocus: false,
  },
})

app.mount('#app')

Nuxt项目适用:

typescript

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',           // 必须在@pinia/colada-nuxt之前
    '@pinia/colada-nuxt',
  ],

  // 可选：配置Pinia Colada
  piniaColada: {
    query: {
      staleTime: 5000,
      gcTime: 5 * 60 * 1000,
    },
  },
})

关键注意事项:

Nuxt项目中：
```
@pinia/nuxt
```
必须排在
```
@pinia/colada-nuxt
```
之前
插件必须在Pinia实例创建后注册
配置为可选，已提供合理的默认值

3. Create First Query

3. 创建第一个查询

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

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> - 初始加载状态
  isLoading,  // Ref<boolean> - 所有加载状态（包括重新获取）
  error,      // Ref<Error | null>
  refresh,    // () => Promise<void> - 手动重新获取
} = useQuery({
  key: ['todos'],
  query: fetchTodos,
})
</script>

<template>
  <div>
    <div v-if="isPending">加载待办事项中...</div>
    <div v-else-if="error">错误：{{ error.message }}</div>
    <ul v-else-if="data">
      <li v-for="todo in data" :key="todo.id">
        {{ todo.title }}
      </li>
    </ul>
  </div>
</template>

关键注意事项:

查询
```
key
```
必须是数组（或返回数组的 getter 函数）以确保缓存一致性
查询
```
query
```
是用于获取数据的异步函数
在查询函数中抛出错误以实现正确的错误处理
```
isPending
```
仅在初始加载时为
```
true
```
，
```
isLoading
```
包含重新获取的加载状态

4. Create First Mutation

4. 创建第一个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)

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,

  // Mutation成功后失效待办事项查询
  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 ? '添加中...' : '添加待办事项' }}
    </button>
    <div v-if="error">错误：{{ error.message }}</div>
  </form>
</template>

工作原理:

```
onSettled
```
会在成功或失败后执行，非常适合用于失效操作
```
invalidateQueries
```
会将匹配的标记为过期，并重新获取活跃的查询
```
mutate
```
是“触发即遗忘”模式，
```
mutateAsync
```
会返回Promise用于await操作
Mutations默认不缓存（这是写入操作的正确行为）

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()

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

✅ 将查询函数中使用的所有变量包含在key中 ✅ 在查询/mutation函数中抛出错误以实现正确的错误处理 ✅ 在mutations中使用

useQueryCache()

进行失效操作 ✅ 使用

isPending

表示初始加载状态，

isLoading

表示所有加载状态 ✅ 当需要在继续操作前确保数据最新时，在

onSettled

中await

invalidateQueries()

✅ 对分页查询使用

placeholderData

以避免闪烁 ✅ 在乐观更新前使用

getQueryData

快照缓存 ✅ 从

onMutate

返回上下文以便在

onError

中回滚 ✅ 在插件级别配置

staleTime

和

gcTime

以设置全局默认值 ✅ 使用可复用的组合式函数来定义查询，而非内联使用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

❌ 永远不要使用普通字符串作为key - 始终使用数组 ❌ 永远不要从查询函数返回undefined - 改为抛出错误 ❌ 永远不要直接修改

data.value

- 它是只读的 ❌ 永远不要在mutation后忘记失效相关查询 ❌ 永远不要在查询中使用

onSuccess

（不支持，改用watch） ❌ 永远不要忘记await

mutateAsync()

- 它返回一个Promise ❌ 永远不要在乐观更新前跳过

cancelQueries

（会导致竞态条件） ❌ 永远不要在未检查undefined的情况下使用

getQueryData

❌ 永远不要在

onMutate

中失效查询（在

onSettled

中执行） ❌ 永远不要硬编码URL - 使用环境变量存储API基础URL

Top 5 Errors Prevention

五大错误预防方案

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

本工具可预防12种已记录的错误。以下是最常见的5种：

Error #1: Query Not Refetching After Mutation

错误 #1: Mutation后查询未重新获取

Error: Data doesn't update in UI after successful mutation Prevention: Always use

invalidateQueries

onSettled

typescript

useMutation({
  mutation: createTodo,
  async onSettled() {
    await queryCache.invalidateQueries({ key: ['todos'] })
  },
})

See:

references/error-catalog.md

错误现象: Mutation成功后UI中的数据未更新 预防方案: 始终在

onSettled

中使用

invalidateQueries

：

typescript

useMutation({
  mutation: createTodo,
  async onSettled() {
    await queryCache.invalidateQueries({ key: ['todos'] })
  },
})

参考:

references/error-catalog.md

Error #2: Race Condition with Optimistic Updates

错误 #2: 乐观更新的竞态条件

Error: Optimistic update gets overwritten by in-flight request Prevention: Always call

cancelQueries

onMutate

typescript

onMutate(id) {
  cache.cancelQueries({ key: ['todos'] })
  // Then do optimistic update
}

See:

references/error-catalog.md

错误现象: 乐观更新被正在进行的请求覆盖 预防方案: 始终在

onMutate

中调用

cancelQueries

：

typescript

onMutate(id) {
  cache.cancelQueries({ key: ['todos'] })
  // 然后执行乐观更新
}

参考:

references/error-catalog.md

Error #3: SSR Hydration Mismatch

错误 #3: SSR Hydration不匹配

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

错误现象:

Hydration completed but contains mismatches

预防方案: 为SSR查询设置

refetchOnMount: false

typescript

useQuery({
  key: ['todos'],
  query: fetchTodos,
  refetchOnMount: false, // 防止SSR hydration不匹配
})

参考:

references/error-catalog.md

Error #4: Query Key Not Reactive

错误 #4: 查询Key无响应式

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

错误现象: 变量变化时查询未重新获取 预防方案: 使用函数定义响应式key：

typescript

// ❌ 错误 - 静态key
key: ['todos', id.value]

// ✅ 正确 - 响应式key
key: () => ['todos', id.value]

参考:

references/error-catalog.md

Error #5: Nuxt Module Order Wrong

错误 #5: Nuxt模块顺序错误

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

错误现象:

PiniaColada plugin not found

或 SSR错误 预防方案: 始终将

@pinia/nuxt

放在前面：

typescript

export default defineNuxtConfig({
  modules: [
    '@pinia/nuxt',           // 必须放在前面
    '@pinia/colada-nuxt',    // 然后是Colada
  ],
})

参考:

references/error-catalog.md

#10

完整错误目录（所有12种错误）：请查看

references/error-catalog.md

Using Bundled Resources

使用捆绑资源

References (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

按需加载的详细指南：

references/setup-guide.md
- 完整的8步设置流程
- 安装和配置插件
- 创建可复用的查询组合式函数
- 理解查询key
- 实现mutations
- 乐观更新
- 查询失效策略
- 分页查询
- SSR和Nuxt集成
- 加载时机: 用户需要详细的设置说明或高级模式时
references/common-patterns.md
- 12种常见模式
- 依赖查询
- 并行查询
- 条件查询
- 后台同步模式
- 悬停预获取
- 多失效的Mutation
- 无限查询
- 乐观删除
- 带重试逻辑的查询
- 带轮询的查询
- 查询缓存预填充
- 手动触发查询
- 加载时机: 用户询问“如何实现...”或需要特定模式时
references/error-catalog.md
- 所有12种已记录的错误
- 完整的错误信息和解决方案
- 预防策略
- 官方来源引用
- 预防检查清单
- 加载时机: 用户遇到错误或希望预防问题时
references/configuration.md
- 完整配置参考
- 插件选项（Vue和Nuxt）
- 单个查询选项
- Mutation选项
- 查询缓存方法
- 高级模式（环境特定配置、错误处理、开发者工具）
- TypeScript配置
- 性能优化
- 加载时机: 用户需要配置详情或高级设置时
references/migration-from-tanstack-vue-query.md
- 迁移指南
- API差异
- 代码转换建议
- 破坏性变更
- 加载时机: 用户提及TanStack Vue Query或迁移时

Common Use Cases

常见使用场景

Basic Todo List with CRUD - Query + mutation with invalidation (10 min) → See
```
references/setup-guide.md
```
Steps 2-4
Paginated Data Table - Reactive keys with placeholderData (15 min) → See
```
references/setup-guide.md
```
Step 7
Optimistic UI Updates - Mutation with onMutate/onError rollback (20 min) → See
```
references/setup-guide.md
```
Step 5
Nuxt SSR Application - Auto-imports with refetchOnMount config (15 min) → See
```
references/setup-guide.md
```
Step 8
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

基础CRUD待办事项列表 - 查询 + 带失效的Mutation（10分钟）→ 查看
```
references/setup-guide.md
```
步骤2-4
分页数据表 - 带placeholderData的响应式key（15分钟）→ 查看
```
references/setup-guide.md
```
步骤7
乐观UI更新 - 带onMutate/onError回滚的Mutation（20分钟）→ 查看
```
references/setup-guide.md
```
步骤5
Nuxt SSR应用 - 带refetchOnMount配置的自动导入（15分钟）→ 查看
```
references/setup-guide.md
```
步骤8
实时仪表盘 - 带refetchInterval的后台轮询（10分钟）→ 查看
```
references/common-patterns.md
```
模式4

所有5种场景的完整代码示例，请查看

references/setup-guide.md

和

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..."

当以下情况时加载
references/setup-guide.md
:

用户需要完整的8步设置流程
用户询问查询key或响应式key相关问题
用户需要实现乐观更新
用户询问SSR/Nuxt设置相关问题
用户需要实现分页

当以下情况时加载
references/common-patterns.md
:

用户询问“如何实现...”并附带特定模式
用户需要依赖查询
用户询问预获取相关问题
用户需要无限滚动
用户询问轮询或后台同步相关问题

当以下情况时加载
references/error-catalog.md
:

用户遇到任何错误
用户询问故障排除相关问题
用户希望预防已知问题
用户询问“我需要注意哪些错误？”
用户遇到SSR hydration问题

当以下情况时加载
references/configuration.md
:

用户需要完整的配置选项
用户询问插件配置相关问题
用户需要TypeScript类型定义
用户希望优化性能
用户需要自定义插件

当以下情况时加载
references/migration-from-tanstack-vue-query.md
:

用户提及TanStack Vue Query
用户询问迁移相关问题
用户比较Pinia Colada和TanStack Query
用户询问“与...有什么不同？”

Dependencies

依赖项

Required:

@pinia/colada@0.17.9 - Core data fetching layer
pinia@2.2.6+ or pinia@3.0+ - State management (peer dependency)
vue@3.5.17+ - Framework (peer dependency)

Optional:

@pinia/colada-nuxt@0.17.9 - Nuxt module (requires @pinia/nuxt separately)

必需:

@pinia/colada@0.17.9 - 核心数据获取层
pinia@2.2.6+ 或 pinia@3.0+ - 状态管理（对等依赖项）
vue@3.5.17+ - 框架（对等依赖项）

可选:

@pinia/colada-nuxt@0.17.9 - Nuxt模块（需单独安装@pinia/nuxt）

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

Pinia Colada: https://pinia-colada.esm.dev/
GitHub仓库: https://github.com/posva/pinia-colada
Pinia: https://pinia.vuejs.org/
Nuxt模块: https://nuxt.com/modules/pinia-colada
迁移指南: https://pinia-colada.esm.dev/cookbook/migration-tvq.html

Package Versions (Verified 2025-11-28)

包版本（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

json

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

版本说明:

Pinia Colada 0.17.9是最新稳定版（发布于2025-11-21）
兼容Pinia 2.2.6+和3.0+
需要Vue 3.5.17+以获得最佳响应式体验
Nuxt模块版本与核心包版本一致

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

本工具基于多个Vue 3和Nuxt应用的生产使用经验：

代码量节省: 相比手动配置TanStack Query节省约65%
预防错误: 已记录并预防上述12种常见问题
搭建时间: 基础设置耗时<2分钟
验证: ✅ SSR正常工作，✅ TypeScript类型正确，✅ 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 |

references/setup-guide.md

(8-step process) |

references/error-catalog.md

(all 12 errors) |

references/migration-from-tanstack-vue-query.md

(migration) | GitHub

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

使用此清单验证你的设置：

已安装
```
@pinia/colada
```
和
```
pinia
```
（Nuxt项目则安装
```
@pinia/colada-nuxt
```
）
在
```
createPinia()
```
之后注册了
```
PiniaColada
```
插件（Vue）或添加到modules中（Nuxt）
使用
```
useQuery
```
创建了至少一个查询
使用
```
useMutation
```
创建了至少一个Mutation
在Mutation的
```
onSettled
```
钩子中使用了
```
invalidateQueries
```
查询key是数组（或返回数组的函数）
所有查询变量都包含在查询key中
在查询/mutation函数中抛出错误（而非返回）
使用
```
isPending
```
表示初始加载状态
为所有数据结构定义了TypeScript类型
在插件级别配置了
```
staleTime
```
和
```
gcTime
```
（可选）
开发环境运行无错误
若使用Nuxt，SSR正常工作（检查hydration）

有疑问？遇到问题？ 请查看：官方文档 |

references/setup-guide.md

（8步流程） |

references/error-catalog.md

（所有12种错误） |

references/migration-from-tanstack-vue-query.md

（迁移） | GitHub问题

本工具提供可直接用于生产环境的Pinia Colada设置，零配置错误。所有12种常见问题均已记录并预防。