@pinia/colada

Pinia Colada

The missing data fetching library for 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: Handle any async state
• 🔌 Plugins: Powerful plugin system
• ✨ Optimistic Updates: Optimistic updates with ease
• 💡 Sensible defaults: Sane defaults with full customization
• 🧩 Out-of-the box plugins: A set of composable functions to handle data fetching
• 📚 Typescript Support: Fully typed with Typescript
• 💨 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

Changelog

0.13.0 (2024-11-26)

⚠ BREAKING CHANGES

• types: placeholderData no longer allows returning null, only undefined. This won't affect most use cases and enables better type inference.

Features

• types: remove undefined with initialData and placeholderData (#114) (6e1863e)