pinia vs vuex
Maintaining a Vuex Store or Migrating to Pinia
piniavuex

Maintaining a Vuex Store or Migrating to Pinia

Vuex offers an established mutation/action store model, while Pinia is the Vue project's recommended choice for new state-management work. Compare the supported Vue version and migration contract instead of treating the packages as identical stores.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
pinia7,829,61114,771195 kB28a month agoMIT
vuex2,261,59128,281271 kB144-MIT

Existing state contracts determine the migration cost

Vuex organizes a centralized store through state, getters, mutations, actions and modules. Pinia defines stores through a different API and does not preserve those call contracts by changing an import. Inventory component access, action dispatches, mutation commits, plugins and persisted data before making a migration plan.

Both approaches can support shared application state, but the appropriate amount of shared state remains an application decision. A small component interaction may not justify either store. For server-rendered applications, isolate state per request rather than treating a module-level singleton as harmless.

Check the actual major versions

The checked versions are Vuex 4.1.0 and Pinia 4.1.0. Vuex declares Vue ^3.2.0, while current Pinia declares Vue ^3.5.11. A project that satisfies Vuex's peer range therefore does not automatically satisfy Pinia's current one.

Vuex's official README recommends Pinia for new Vue projects while explicitly retaining maintenance of Vuex 3 and 4. Its historical description of Pinia supporting Vue 2 must not be applied to the present Pinia 4 artifact.

Migrate behavior rather than names

Map state ownership, derived values and asynchronous actions deliberately. Verify how the application subscribes to changes and exposes store values to components, as well as what its plugins expect. If saved state or an external event depends on the old shape, design that transition separately.

Choose Pinia when its current ecosystem and API offer a concrete maintenance benefit. Keep an established Vuex application when a migration would add cost without solving a real problem. Neither downloads nor a generic claim about less boilerplate proves a better design for every application.

How to Choose: pinia vs vuex

  • pinia:

    Choose Pinia for a new compatible Vue application or a planned move to its store model. Current Pinia 4 requires Vue ^3.5.11; do not borrow Vue 2 compatibility claims from an older major.

  • vuex:

    Keep Vuex when its existing modules, plugins and component contracts remain useful. Vuex 4 targets Vue 3 and is still maintained; the recommendation to use Pinia for new projects is not an npm deprecation notice.

README for pinia

Pinia logo


npm package build status


Pinia

Intuitive, type safe and flexible Store for Vue

  • πŸ’‘ Intuitive
  • πŸ”‘ Type Safe
  • βš™οΈ Devtools support
  • πŸ”Œ Extensible
  • πŸ— Modular by design
  • πŸ“¦ Extremely light
  • ⛰️ Nuxt Module

The latest version of pinia works with Vue 3. See the branch v2 for a version that works with Vue 2.

Pinia is the most similar English pronunciation of the word pineapple in Spanish: piΓ±a. A pineapple is in reality a group of individual flowers that join together to create a multiple fruit. Similar to stores, each one is born individually, but they are all connected at the end. It's also a delicious tropical fruit indigenous to South America.

πŸ‘‰ Demo with Vue 3 on StackBlitz

πŸ‘‰ Demo with Nuxt 3 on StackBlitz

Help me keep working on this project πŸ’š

Gold Sponsors

CodeRabbit

Silver Sponsors

VueMastery Controla SendCloud

Bronze Sponsors

RTVision Storyblok


FAQ

A few notes about the project and possible questions:

Q: Is Pinia the successor of Vuex?

A: Yes

Q: What about dynamic modules?

A: Dynamic modules are not type safe, so instead we allow creating different stores that can be imported anywhere

Installation

# or pnpm or yarn
npm install pinia @vue/devtools-api

Usage

Install the plugin

Create a pinia (the root store) and pass it to app:

// Vue 3
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const pinia = createPinia()
const app = createApp(App)

app.use(pinia)
app.mount('#app')

For more detailed instructions, including Nuxt configuration, check the Documentation.

Create a Store

You can create as many stores as you want, and they should each exist in different files:

import { defineStore } from 'pinia'

// main is the name of the store. It is unique across your application
// and will appear in devtools
export const useMainStore = defineStore('main', {
  // a function that returns a fresh state
  state: () => ({
    counter: 0,
    name: 'Eduardo',
  }),
  // optional getters
  getters: {
    // getters receive the state as first parameter
    doubleCounter: (state) => state.counter * 2,
    // use getters in other getters
    doubleCounterPlusOne(): number {
      return this.doubleCounter + 1
    },
  },
  // optional actions
  actions: {
    reset() {
      // `this` is the store instance
      this.counter = 0
    },
  },
})

defineStore returns a function that has to be called to get access to the store:

import { useMainStore } from '@/stores/main'
import { storeToRefs } from 'pinia'

export default defineComponent({
  setup() {
    const main = useMainStore()

    // extract specific store properties
    const { counter, doubleCounter } = storeToRefs(main)

    return {
      // gives access to the whole store in the template
      main,
      // gives access only to specific state or getter
      counter,
      doubleCounter,
    }
  },
})

Documentation

To learn more about Pinia, check its documentation.

License

MIT