@pinia/colada

Pinia Colada

The missing data fetching library for Pinia

This is a more complete and production-ready (not yet!) version of the exercises from Mastering Pinia.

[!NOTE] Pinia Colada is in active development not ready for production. New versions might introduce breaking changes. Feedback regarding new and existing options and features is welcome! Documentation is a work in progress and contributions are welcome.

Pinia Colada is an opinionated yet flexible data fetching layer on top of Pinia. It's built as a set of pinia plugins, stores and composables to benefit from Pinia's features and ecosystem. Pinia Colada has:

• ⚡️ Automatic caching: Smart client-side caching with request deduplication
• 🗄️ Async State: Handle any async state
• 📚 Typescript Support: Fully typed with Typescript
• 💨 Bundle Size: Small bundle size (<2kb) and fully tree-shakeable
• 📦 Zero Dependencies: No dependencies other than Pinia
• ⚙️ SSR: Server-side rendering support
• 🔌 Plugins: Powerful plugin system

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

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

const route = useRoute()
const caches = useQueryCache()

const { data: contact, isLoading } = useQuery({
  // recognizes this query as ['contacts', id]
  key: () => ['contacts', route.params.id],
  query: () => getContactById(route.params.id),
})

const { mutate: updateContact } = useMutation({
  mutation: _updateContact,
  onSettled({ id }) {
    caches.invalidateQueries({ key: ['contacts', id], exact: true })
  },
})
</script>

<template>
  <section>
    <ContactCard
      :key="contact.id"
      :contact="contact"
      :is-updating="isLoading"
      @update:contact="updateContact"
    />
  </section>
</template>

License

MIT

Changelog

0.11.0 (2024-10-25)

⚠ BREAKING CHANGES

• mutations: This wasn't needed as instead, one can use useQueryCache() outside. It could be added back if needed but it's more pragmatic to start without it.
• query: The queryCache.cancelQuery() is renamed to queryCache.cancel() to better match the other functions naming. A new function queryCache.cancelQueries() is added to actually cancel one or multiple queries instead of just one.
• plugins: In plugins, cache is renamed to queryCache for consistency.
• This makes it clearer that queryCache is the result of useQueryCache().

Features

• add mutation store (#47) (7954f83)
• hmr: warn against bugs (7bb44a0)
• nuxt: add auto imports (964bce2)
• nuxt: support colada.options (57a0430)
• predicate in filter (2fc62b7)
• query: add cancelQueries (a374ee2)
• run defined mutations in effect scope (86ff5ed)

Bug Fixes

• nuxt: plugins (fd95add)

Performance Improvements

• tree shake unused stores (e0ede7e)

Code Refactoring

• mutations: Remove queryCache from the context (d9c2509)
• plugins: rename cache to queryCache (c97639b)
• rename caches to queryCache (e514d33)