@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.12.0 (2024-11-06)

⚠ BREAKING CHANGES

• transformError was never fully implemented so they are being removed and might come back if they is a real-word use case for them
• If you were using the delayLoadingRef util, use the @pinia/colada-plugin-delay instead.
• Renaming Error to defaultError allows to differentiate the property from the existing global Error class. Upgrading should be straightforward.

Features

• add initial delay plugin (42c8760)
• add track and untrack actions for plugins (8902ba3)
• allow dynamic values for auto refetches (63d2fd0)
• allow extending useQuery return (ef06628)
• expose more types (4447d6d)
• plugins: pass scope for added variables (a3b666f)
• work without the plugin (696f88e)

Bug Fixes

• avoid broken reactivity in defineQuery (4c48abc)
• dedupe pinia colada (6ace8e8)
• keep data if signal is aborted (de5cde5)
• pass onMutate context (618312b), closes #95
• remove queryCache from mutation hooks (3f1119a)
• run create in ssr too (1a6fa4a)
• ssr: throw on error in query (58b7f69)
• upgrade to new cache format (03e1683)

Code Refactoring

• query: remove unused transformError and setup options (de0cb48)
• remove delayLoadingRef helper in favor of the plugins (4c9b4cb)
• rename the global Error property in TypesConfig to (0021426)