ZenStack Pinia Colada

Pinia Colada client for ZenStack - The Smart Data Fetching Layer for Vue 3.

Features

- 🔐 Type-safe - Full TypeScript support with automatic type inference
- ⚡️ Automatic caching - Smart caching powered by Pinia Colada
- 🔄 Optimistic updates - Update UI before server responds
- 🎯 Automatic invalidation - Cache invalidation based on data relationships
- 📦 Zero config - Works out of the box with your ZenStack schema
- 🌳 Tree-shakeable - Only bundle what you use

Installation

``bash
npm install zenstack-pinia-colada @pinia/colada pinia


or

pnpm add zenstack-pinia-colada @pinia/colada pinia

or

yarn add zenstack-pinia-colada @pinia/colada pinia
`

Prerequisites

1. You need a ZenStack project set up (v3.0.0 or higher). See ZenStack documentation for details.
2. Generate your ZenStack schema using npx zenstack generate

Note: This library requires ZenStack v3 to be installed in your project. The library will use your installed version of ZenStack packages.

Quick Start

$3

`typescript
// 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)
app.mount('#app')
`

$3

`vue


`

$3

`vue



`

API Reference

$3

Each model in your schema gets the following query hooks:

- useFindUnique(args, options) - Find a unique record
- useFindFirst(args, options) - Find the first matching record
- useFindMany(args, options) - Find multiple records
- useInfiniteFindMany(args, options) - Paginated query with infinite loading
- useCount(args, options) - Count records
- useAggregate(args, options) - Aggregate data
- useGroupBy(args, options) - Group records

Query Return Values:

`typescript
{
data: Ref, // Query data
error: Ref, // Error if query failed
status: Ref<'pending' | 'success' | 'error'>, // Query status
refresh: () => Promise, // Manually refetch
// ... and more from Pinia Colada
}
`

$3

Each model gets these mutation hooks:

- useCreate(options) - Create a record
- useCreateMany(options) - Create multiple records
- useCreateManyAndReturn(options) - Create and return multiple records
- useUpdate(options) - Update a record
- useUpdateMany(options) - Update multiple records
- useUpdateManyAndReturn(options) - Update and return multiple records
- useUpsert(options) - Create or update a record
- useDelete(options) - Delete a record
- useDeleteMany(options) - Delete multiple records

Mutation Return Values:

`typescript
{
mutate: (variables: T) => void, // Trigger mutation
mutateAsync: (variables: T) => Promise, // Async mutation
status: Ref<'pending' | 'success' | 'error' | 'idle'>,
data: Ref, // Mutation result
error: Ref, // Error if mutation failed
// ... and more from Pinia Colada
}
`

Advanced Features

$3

Pinia Colada automatically tracks reactive dependencies in your queries. When using reactive values (refs, computed), wrap your query arguments in a getter function:

`typescript
import { ref, computed } from 'vue'

const userId = ref('123')
const includeDeleted = ref(false)

// ✅ Correct: Use a getter function
const { data: posts } = queries.post.useFindMany(() => ({
where: {
authorId: userId.value, // Unwrap refs inside the getter
deletedAt: includeDeleted.value ? undefined : null
},
}))

// When userId or includeDeleted changes, the query automatically re-runs!
`

Why use a getter function?

The getter function () => ({...}) allows Pinia Colada to track when your reactive values change and automatically re-fetch the query. Inside the getter, unwrap refs with .value.

Alternative patterns:

`typescript
// Using computed (also works)
const queryArgs = computed(() => ({
where: { authorId: userId.value }
}))
const { data } = queries.post.useFindMany(queryArgs)

// Static queries (no reactivity needed)
const { data } = queries.post.useFindMany({
where: { published: true } // No getter needed for static values
})
`

$3

Optimistic updates allow the UI to update immediately before the server responds:

`typescript
const updatePost = queries.post.useUpdate({
optimisticUpdate: true, // Enable optimistic updates
})

updatePost.mutate({
where: { id: '1' },
data: { title: 'New Title' },
})
// UI updates immediately, then syncs with server response
`

$3

Pinia Colada provides many options to customize query behavior:

`typescript
const { data } = queries.post.useFindMany(
{ where: { published: true } },
{
staleTime: 5000, // Consider data fresh for 5 seconds
gcTime: 300000, // Garbage collection time (default: 5 minutes)
refetchOnMount: true,
refetchOnWindowFocus: true,
enabled: computed(() => isReady.value), // Conditionally enable
}
)
`

$3

For paginated data with infinite scrolling:

`typescript
const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = queries.post.useInfiniteFindMany(
{ take: 10, where: { published: true } },
{
getNextPageParam: (lastPage, pages) => {
// Return the cursor for the next page
return lastPage.length === 10 ? pages.length * 10 : undefined
},
}
)
`

$3

By default, mutations automatically invalidate related queries. You can disable this:

`typescript
const createPost = queries.post.useCreate({
invalidateQueries: false, // Don't auto-invalidate related queries
})
`

Type Safety

All hooks are fully typed based on your ZenStack schema:

`typescript
// TypeScript knows the exact shape of User
const { data: user } = queries.user.useFindUnique({
where: { id: '1' },
select: { id: true, name: true, email: true },
})

// user is typed as: { id: string; name: string; email: string } | null
`

Comparison with TanStack Query

If you're familiar with @zenstackhq/tanstack-query, the Pinia Colada client offers:

- 🎯 Vue-first design - Built specifically for Vue 3 composition API
- 📦 Smaller bundle - Tree-shakeable ESM-only package
- 🔧 Simpler API - Less configuration, sensible defaults
- 🏪 Pinia integration - Works seamlessly with your Pinia store
- ⚡️ Better performance - Optimized for Vue's reactivity system

Key API Differences:

- Returns Vue Ref objects instead of plain values
- Uses status instead of separate isLoading, isSuccess flags
- refresh() instead of refetch()` for manual updates
- Direct integration with Pinia's state management

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Links

- ZenStack Documentation
- Pinia Colada Documentation
- GitHub Repository