Pinia Colada Integration

Pinia Colada is the data fetching layer for Pinia and Vue. oRPC’s integration with Pinia Colada is lightweight and straightforward - there’s no extra overhead.

WARNING

This documentation assumes you are already familiar with Pinia Colada. If you need a refresher, please review the official Pinia Colada documentation before proceeding.

Installation

npm

npm install @orpc/vue-colada@latest @pinia/colada@latest

yarn

yarn add @orpc/vue-colada@latest @pinia/colada@latest

pnpm

pnpm add @orpc/vue-colada@latest @pinia/colada@latest

bun

bun add @orpc/vue-colada@latest @pinia/colada@latest

deno

deno install npm:@orpc/vue-colada@latest npm:@pinia/colada@latest

Setup

Before you begin, ensure you have already configured a server-side client or a client-side client.

import { createORPCVueColadaUtils } from '@orpc/vue-colada'

export const orpc = createORPCVueColadaUtils(client)

orpc.planet.find.
queryOptions({ input: { id: 123 } })

//

Avoiding Query/Mutation Key Conflicts

Prevent key conflicts by passing a unique base key when creating your utils:

const userORPC = createORPCVueColadaUtils(userClient, {
  path: ['user']
})
const postORPC = createORPCVueColadaUtils(postClient, {
  path: ['post']
})

Query Options Utility

Use .queryOptions to configure queries. Use it with hooks like useQuery, useSuspenseQuery, or prefetchQuery.

const query = useQuery(orpc.planet.find.queryOptions({
  input: { id: 123 }, // Specify input if needed
  context: { cache: true }, // Provide client context if needed
  // additional options...
}))

Mutation Options

Use .mutationOptions to create options for mutations. Use it with hooks like useMutation.

const mutation = useMutation(orpc.planet.create.mutationOptions({
  context: { cache: true }, // Provide client context if needed
  // additional options...
}))

mutation.mutate({ name: 'Earth' })

Query/Mutation Key

Use .key to generate a QueryKey or MutationKey. This is useful for tasks such as revalidating queries, checking mutation status, etc.

const queryCache = useQueryCache()

// Invalidate all planet queries
queryCache.invalidateQueries({
  key: orpc.planet.key(),
})

// Invalidate the planet find query with id 123
queryCache.invalidateQueries({
  key: orpc.planet.find.key({ input: { id: 123 } })
})

Calling Procedure Clients

Use .call to call a procedure client directly. It's an alias for corresponding procedure client.

const result = orpc.planet.find.call({ id: 123 })

Error Handling

Easily manage type-safe errors using our built-in isDefinedError helper.

import { isDefinedError } from '@orpc/client'

const mutation = useMutation(orpc.planet.create.mutationOptions({
  onError: (error) => {
    if (isDefinedError(error)) {
      // Handle the error here
    }
  },
}))

mutation.mutate({ name: 'Earth' })

if (mutation.error.value && isDefinedError(mutation.error.value)) {
  // Handle the error here
}

For more details, see our type-safe error handling guide.