Pinia Colada

Pinia Colada is a smart data-fetching layer for Vue built on top of Pinia. Silgi provides createColadaUtils, a utility that generates type-safe queryOptions and mutationOptions from your client — with full Vue reactivity support.

Prerequisites

You need a Silgi client set up. The Pinia Colada integration wraps this client.

Setup

import { createColadaUtils } from 'silgi/pinia-colada'
import { client } from './client' // your Silgi client

const utils = createColadaUtils(client)

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

const { data, status } = useQuery(
  utils.users.list.queryOptions({
    input: { limit: 10 },
  }),
)
</script>

<template>
  <p v-if="status === 'loading'">Loading...</p>
  <ul v-else>
    <li v-for="user in data" :key="user.id">{{ user.name }}</li>
  </ul>
</template>

Queries

queryOptions returns everything useQuery needs — a reactive computed key and the fetch function:

const options = utils.users.list.queryOptions({
  input: { limit: 10 },
})

// options contains:
// - key: computed(() => [["users", "list"], { type: "query", input: { limit: 10 } }])
// - query: ({ signal }) => client.users.list({ limit: 10 }, { signal })

Reactive inputs

Both input and context accept Vue reactive values — ref, computed, or getter functions:

import { ref, computed } from 'vue'

const limit = ref(10)

const options = utils.users.list.queryOptions({
  input: computed(() => ({ limit: limit.value })),
})

When the reactive value changes, the query key updates automatically, which triggers a refetch.

Mutations

mutationOptions returns everything useMutation needs:

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

const queryCache = useQueryCache()

const { mutate, isLoading } = useMutation({
  ...utils.users.create.mutationOptions(),
  onSuccess: () => {
    queryCache.invalidateQueries({
      key: utils.users.key(),
    })
  },
})
</script>

<template>
  <button @click="mutate({ name: 'Alice' })" :disabled="isLoading">
    {{ isLoading ? 'Creating...' : 'Create User' }}
  </button>
</template>

Cache invalidation

Every level of the utils tree has a key() method for generating cache keys:

import { useQueryCache } from '@pinia/colada'

const queryCache = useQueryCache()

// Invalidate all queries under "users"
queryCache.invalidateQueries({
  key: utils.users.key(),
})

// Invalidate a specific query with specific input
queryCache.invalidateQueries({
  key: utils.users.list.key({ type: 'query', input: { limit: 10 } }),
})

// Invalidate everything
queryCache.invalidateQueries({
  key: utils.key(),
})

Direct calls

Each procedure util has a call property that is the original client function:

const users = await utils.users.list.call({ limit: 10 })

Available methods

Each procedure-level util provides:

Each router-level util provides:

What's next?

• Client — set up the Silgi client that powers the colada utils
• TanStack Query — if you prefer TanStack Query over Pinia Colada
• Typed Errors — handle errors from your queries and mutations