secondsky/claude-skills / plugins/pinia-colada/skills/pinia-colada
pinia-colada
VerifiedPinia 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.1 KB |
| references/common-patterns.md | markdown | 7.2 KB |
| references/configuration.md | markdown | 9.8 KB |
| references/error-catalog.md | markdown | 5.9 KB |
| references/migration-from-tanstack-vue-query.md | markdown | 11.4 KB |
| references/setup-guide.md | markdown | 12.6 KB |
references/migration-from-tanstack-vue-query.md
View on GitHub# Migration Guide: TanStack Vue Query → Pinia Colada
**Last Updated**: 2025-11-11
**Source**: https://pinia-colada.esm.dev/cookbook/migration-tvq.html
---
## Why Migrate to Pinia Colada?
Pinia Colada is specifically designed for Vue.js with:
- Better Vue 3 Composition API integration
- Built on Pinia (official Vue state management)
- Smaller bundle size (~2kb baseline vs ~10kb+)
- First-class TypeScript support
- Better SSR integration with Nuxt
- Simpler API with fewer concepts to learn
---
## Package Migration
### Install Pinia Colada
```bash
# Remove TanStack Vue Query
bun remove @tanstack/vue-query
# Install Pinia Colada
bun add @pinia/colada pinia
# For Nuxt
bun add @pinia/nuxt @pinia/colada-nuxt
```
### Update Plugin Setup
**Before (TanStack Vue Query):**
```typescript
// main.ts
import { VueQueryPlugin } from '@tanstack/vue-query'
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 5000,
},
},
})
app.use(VueQueryPlugin, { queryClient })
```
**After (Pinia Colada):**
```typescript
// main.ts
import { createPinia } from 'pinia'
import { PiniaColada } from '@pinia/colada'
const pinia = createPinia()
app.use(pinia)
app.use(PiniaColada, {
query: {
staleTime: 5000,
},
})
```
---
## API Differences
### Query Hooks
| TanStack Vue Query | Pinia Colada | Notes |
|-------------------|--------------|-------|
| `useQuery({ queryKey, queryFn })` | `useQuery({ key, query })` | Property names changed |
| `queryKey: ['todos']` | `key: ['todos']` | Same array format |
| `queryFn: fetchTodos` | `query: fetchTodos` | Name changed |
| `isLoading` | `isPending` for initial, `isLoading` for any | More granular states |
| `data` | `data` | Same |
| `error` | `error` | Same |
| `refetch()` | `refresh()` | Method renamed |
| `isFetching` | `isLoading` | Simplified |
| `isInitialLoading` | `isPending` | Renamed |
### Mutation Hooks
| TanStack Vue Query | Pinia Colada | Notes |
|-------------------|--------------|-------|
| `useMutation({ mutationFn })` | `useMutation({ mutation })` | Property name changed |
| `mutationFn: createTodo` | `mutation: createTodo` | Name changed |
| `mutate()` | `mutate()` | Same |
| `mutateAsync()` | `mutateAsync()` | Same |
| `isLoading` | `isPending` | Renamed |
| Callbacks in `useMutation` | Callbacks in `useMutation` | Same pattern |
### Query Client / Cache
| TanStack Vue Query | Pinia Colada | Notes |
|-------------------|--------------|-------|
| `useQueryClient()` | `useQueryCache()` | Renamed |
| `queryClient.invalidateQueries()` | `cache.invalidateQueries()` | Same API |
| `queryClient.setQueryData()` | `cache.setQueryData()` | Same API |
| `queryClient.getQueryData()` | `cache.getQueryData()` | Same API |
| `queryClient.prefetchQuery()` | `cache.prefetchQuery()` | Same API |
| `queryClient.cancelQueries()` | `cache.cancelQueries()` | Same API |
---
## Code Migration Examples
### Example 1: Basic Query
**Before (TanStack Vue Query):**
```vue
<script setup lang="ts">
import { useQuery } from '@tanstack/vue-query'
const { data, isLoading, error } = useQuery({
queryKey: ['todos'],
queryFn: async () => {
const res = await fetch('/api/todos')
return res.json()
},
})
</script>
```
**After (Pinia Colada):**
```vue
<script setup lang="ts">
import { useQuery } from '@pinia/colada'
const { data, isPending, error } = useQuery({
key: ['todos'],
query: async () => {
const res = await fetch('/api/todos')
return res.json()
},
})
</script>
<template>
<!-- Change isLoading to isPending -->
<div v-if="isPending">Loading...</div>
</template>
```
**Changes Required:**
1. Import from `@pinia/colada` instead of `@tanstack/vue-query`
2. Change `queryKey` → `key`
3. Change `queryFn` → `query`
4. Change `isLoading` → `isPending` (for initial load)
### Example 2: Query with Parameters
**Before:**
```typescript
const todoId = ref(1)
const { data } = useQuery({
queryKey: ['todo', todoId],
queryFn: () => fetchTodo(todoId.value),
})
```
**After:**
```typescript
const todoId = ref(1)
const { data } = useQuery({
key: () => ['todo', todoId.value],
query: () => fetchTodo(todoId.value),
})
```
**Changes Required:**
1. Make `key` a function that returns array (for reactivity)
2. Change `queryKey` → `key`, `queryFn` → `query`
### Example 3: Mutation with Invalidation
**Before:**
```typescript
import { useMutation, useQueryClient } from '@tanstack/vue-query'
const queryClient = useQueryClient()
const { mutate } = useMutation({
mutationFn: createTodo,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['todos'] })
},
})
```
**After:**
```typescript
import { useMutation, useQueryCache } from '@pinia/colada'
const cache = useQueryCache()
const { mutate } = useMutation({
mutation: createTodo,
async onSettled() {
await cache.invalidateQueries({ key: ['todos'] })
},
})
```
**Changes Required:**
1. Import `useQueryCache` instead of `useQueryClient`
2. Change `mutationFn` → `mutation`
3. Prefer `onSettled` over `onSuccess` (runs on both success and error)
4. Change `queryKey` → `key` in invalidation
### Example 4: Optimistic Updates
**Before:**
```typescript
const { mutate } = useMutation({
mutationFn: updateTodo,
onMutate: async (newTodo) => {
await queryClient.cancelQueries({ queryKey: ['todos'] })
const previous = queryClient.getQueryData(['todos'])
queryClient.setQueryData(['todos'], (old) => [...old, newTodo])
return { previous }
},
onError: (err, newTodo, context) => {
queryClient.setQueryData(['todos'], context.previous)
},
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['todos'] })
},
})
```
**After:**
```typescript
const { mutate } = useMutation({
mutation: updateTodo,
onMutate(newTodo) {
cache.cancelQueries({ key: ['todos'] })
const previous = cache.getQueryData(['todos'])
cache.setQueryData(['todos'], [...previous, newTodo])
return { previous }
},
onError(err, newTodo, context) {
cache.setQueryData(['todos'], context.previous)
},
async onSettled() {
await cache.invalidateQueries({ key: ['todos'] })
},
})
```
**Changes Required:**
1. Use `cache` instead of `queryClient`
2. Change `queryKey` → `key`
3. Change `mutationFn` → `mutation`
4. Remove `async/await` from `onMutate` (not needed)
5. Use direct array instead of callback in `setQueryData`
### Example 5: Nuxt Integration
**Before (TanStack Vue Query):**
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@tanstack/vue-query-nuxt'],
})
// plugins/vue-query.ts
export default defineNuxtPlugin((nuxt) => {
const queryClient = new QueryClient({
defaultOptions: { queries: { staleTime: 5000 } }
})
nuxt.vueApp.use(VueQueryPlugin, { queryClient })
})
```
**After (Pinia Colada):**
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: [
'@pinia/nuxt', // Required first
'@pinia/colada-nuxt',
],
piniaColada: {
query: {
staleTime: 5000,
},
},
})
// No plugin file needed - auto-configured!
```
**Changes Required:**
1. Replace module with `@pinia/colada-nuxt`
2. Add `@pinia/nuxt` before it
3. Remove plugin file - configuration handled in nuxt.config
4. Auto-imports work out of the box
---
## Breaking Changes to Watch For
### 1. Query Callbacks Removed
**TanStack Vue Query** had query callbacks (`onSuccess`, `onError` in `useQuery`).
**Pinia Colada** removed these. Use `watch` instead:
```typescript
const { data } = useQuery({ key: ['todos'], query: fetchTodos })
// Instead of onSuccess callback
watch(data, (newData) => {
if (newData) {
console.log('Query succeeded:', newData)
}
})
```
### 2. `enabled` Option Behavior
Both support `enabled`, but Pinia Colada requires a function:
**Before:**
```typescript
const enabled = ref(false)
useQuery({ queryKey: ['todos'], queryFn: fetchTodos, enabled })
```
**After:**
```typescript
const enabled = ref(false)
useQuery({ key: ['todos'], query: fetchTodos, enabled: () => enabled.value })
```
### 3. `placeholderData` vs `initialData`
**TanStack Vue Query** has both `placeholderData` and `initialData`.
**Pinia Colada** has:
- `placeholderData` - shows while loading, not cached
- No `initialData` (use `placeholderData` instead)
### 4. `gcTime` Replaces `cacheTime`
**Before:**
```typescript
queryClient.setDefaultOptions({
queries: { cacheTime: 5 * 60 * 1000 },
})
```
**After:**
```typescript
app.use(PiniaColada, {
query: { gcTime: 5 * 60 * 1000 },
})
```
---
## Migration Checklist
- [ ] Install `@pinia/colada` and `pinia`
- [ ] Remove `@tanstack/vue-query`
- [ ] Update plugin setup in `main.ts` or `nuxt.config.ts`
- [ ] Replace all `useQuery` imports
- [ ] Change `queryKey` → `key`, `queryFn` → `query`
- [ ] Change `isLoading` → `isPending` for initial load state
- [ ] Replace `useQueryClient` → `useQueryCache`
- [ ] Change `mutationFn` → `mutation` in mutations
- [ ] Update all `queryKey` → `key` in cache operations
- [ ] Convert query callbacks to `watch` statements
- [ ] Make `enabled` option a function if used
- [ ] Change `cacheTime` → `gcTime`
- [ ] Update Nuxt integration if using Nuxt
- [ ] Test all queries, mutations, and invalidations
- [ ] Verify SSR hydration if using SSR
---
## Feature Parity
| Feature | TanStack Vue Query | Pinia Colada | Status |
|---------|-------------------|--------------|--------|
| Basic queries | ✅ | ✅ | Full parity |
| Query keys | ✅ | ✅ | Full parity |
| Mutations | ✅ | ✅ | Full parity |
| Cache management | ✅ | ✅ | Full parity |
| Optimistic updates | ✅ | ✅ | Full parity |
| Query invalidation | ✅ | ✅ | Full parity |
| Prefetching | ✅ | ✅ | Full parity |
| SSR support | ✅ | ✅ | Full parity (better in Nuxt) |
| Paginated queries | ✅ | ✅ | Full parity |
| Infinite queries | ✅ | ⚠️ | Use paginated queries pattern |
| Query cancellation | ✅ | ✅ | Full parity |
| DevTools | ✅ | ✅ | Built-in Vue DevTools support |
| Suspense | ✅ | ❌ | Not yet supported |
| Query callbacks | ✅ | ❌ | Use `watch` instead |
| Retry logic | ✅ | ✅ | Full parity |
| Background refetch | ✅ | ✅ | Full parity |
---
## Common Migration Mistakes
### Mistake 1: Forgetting to Make Key a Function
```typescript
// ❌ Wrong - won't be reactive
const id = ref(1)
useQuery({ key: ['todo', id.value], query: () => fetchTodo(id.value) })
// ✅ Correct - reactive
useQuery({ key: () => ['todo', id.value], query: () => fetchTodo(id.value) })
```
### Mistake 2: Using `isLoading` for Initial State
```typescript
// ❌ Wrong - isLoading is true during refetches too
const { data, isLoading } = useQuery({ key: ['todos'], query: fetchTodos })
// ✅ Correct - use isPending for initial load
const { data, isPending } = useQuery({ key: ['todos'], query: fetchTodos })
```
### Mistake 3: Not Awaiting `invalidateQueries`
```typescript
// ❌ Wrong - mutation resolves before refetch completes
onSuccess() {
cache.invalidateQueries({ key: ['todos'] })
closeModal() // Might see stale data
}
// ✅ Correct - wait for refetch
async onSettled() {
await cache.invalidateQueries({ key: ['todos'] })
closeModal() // Data is fresh
}
```
---
## Need Help?
- **Official Migration Guide**: https://pinia-colada.esm.dev/cookbook/migration-tvq.html
- **Pinia Colada Docs**: https://pinia-colada.esm.dev/
- **GitHub Issues**: https://github.com/posva/pinia-colada/issues
- **Pinia Colada Skill**: See [SKILL.md](../SKILL.md) for complete documentation
---
**Happy migrating!** Pinia Colada provides a simpler, more Vue-native experience. 🍹
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |