Migrating from @tanstack/vue-query to @pinia/colada

This guide will help you migrate from @tanstack/vue-query to @pinia/colada. The two libraries have similar function names and API options, so it should be mostly a matter of updating the imports and adjusting the function names but there are still a couple of differences to be aware of.

NOTE

This guide is a work in progress and may not cover all the differences between the two libraries. Please, help us improve it by contributing if you find any missing information.

Different status values

• fetchStatus is named asyncStatus
• asyncStatus values are idle and loading instead of idle and fetching
• Mutations also have an asyncStatus property and they match the query status values instead of having two different conventions

Different defaults

Most of the sensible defaults from @tanstack/vue-query are kept in @pinia/colada, but there are a few differences to be aware of:

• Default staleTime is 5 seconds instead of 0

Different option names

• queryFn is named query
• queryKey is named key
• mutationFn is named mutation

API Differences

TanStack Vue Query Equivalent	Pinia Colada	Comment
refetch({ cancelRefetch: false })	refresh()	See Refetching Queries
refetch({ throwOnError: true })	refetch(true)	Same for refresh()

Differences in philosophy

These differences are a bit more subtle and span across multiple layers of the library.

Structural sharing

TanStack implements a few rendering optimizations that are crucial in React but unnecessary in Vue. Pinia Colada does not implement these optimizations and instead relies on Vue's great reactivity system. The most notable difference is Structural sharing which is explained in their React docs but barely mentioned in the Vue docs. In short, TanStack query partially updates parts of the object based on what is changed. This means that if your query returns the same data as before and you use a watcher on the data, it will not trigger the watcher. This is not the case in Pinia Colada as it uses Shallow Refs to store data to get the best performance and simply replaces the value after each successful query. In Vue apps, this is rarely a problem, but if it is, you will need to avoid the watcher code by comparing the values yourself:

const { data } = useQuery({
  key: ['todos'],
  query: fetchTodos,
})

watch(data, (newData, oldData) => {
  if (!isSameData(newData, oldData)) {
    // do something with the new data
  }
})