Pinia Colada

The missing data fetching layer for Vue. Built on top of Pinia

Pinia Colada makes data fetching in Vue applications a breeze. It's built on top of Pinia and takes away all of the complexity and boilerplate that comes with fetching data. It's fully typed and tree-shakeable, and it's built with the same principles as Pinia and Vue: It's approachable, flexible, powerful and can be progressively adopted.

[!TIP] This is a feature-complete version of the exercises from Mastering Pinia. If you would like to learn how it started and become an expert in Vue state management, check it out!

Features

• ⚡️ Automatic caching: Smart client-side caching with request deduplication
• 🗄️ Async State: Simplified async state management
• 🔌 Plugins: Powerful plugin system
• ✨ Optimistic Updates: UI that updates before the server responds
• 💡 Sensible defaults: Works well out of the box while remaining fully configurable
• 🧩 Out-of-the box plugins: Auto refetch, delay loading, and more
• 📚 Typescript Support: Best-in-class TypeScript support
• 💨 Small Bundle Size: A baseline of ~2kb and fully tree-shakeable
• 📦 Zero Dependencies: No dependencies other than Pinia
• ⚙️ SSR: Out of the box server-side rendering support

[!NOTE] Pinia Colada is always trying to improve and evolve. Feedback regarding new and existing options and features is very welcome! Contribution to documentation, issues, and pull requests are highly appreciated.

Installation

npm install pinia @pinia/colada

Install the plugins for the features you need:

import { createPinia } from 'pinia'
import { PiniaColada } from '@pinia/colada'

app.use(createPinia())
// install after pinia
app.use(PiniaColada, {
  // optional options
})

Usage

The core of Pinia Colada is the useQuery and useMutation functions. They are used to read data and write it respectively. Here's a simple example:

<script lang="ts" setup>
import { useRoute } from 'vue-router'
import { useMutation, useQuery, useQueryCache } from '@pinia/colada'
import { patchContact, getContactById } from '~/api/contacts'

const route = useRoute()
const queryCache = useQueryCache()

const { data: contact, isPending } = useQuery({
  // unique key for the query in the cache
  key: () => ['contacts', route.params.id],
  query: () => getContactById(route.params.id),
})

const { mutate: updateContact, isLoading } = useMutation({
  mutation: patchContact,
  async onSettled({ id }) {
    // invalidate the query to refetch the data of the query above
    await queryCache.invalidateQueries({ key: ['contacts', id], exact: true })
  },
})
</script>

<template>
  <section>
    <p v-if="isPending">Loading...</p>
    <ContactCard
      v-else
      :key="contact.id"
      :contact="contact"
      :is-updating="isLoading"
      @update:contact="updateContact"
    />
  </section>
</template>

Learn more about the core concepts and how to use them in the documentation.

License

MIT