Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 38 ยท Migration from Vuex

Vuex Concepts Mapped to Pinia

Map every Vuex concept to its Pinia equivalent: state, getters, mutations, actions, modules, helpers and subscriptions, with the same app written in both libraries.

If you know Vuex, you already know most of Pinia. Pinia started as an experiment for "what would Vuex 5 look like" and became the official recommended store for Vue. Vuex 4 still works and is in maintenance mode, but new projects should use Pinia, and existing projects can move over gradually. This lesson is the dictionary: for every Vuex idea, what is its Pinia counterpart, and what simply disappears.

The big differences in one table

Vuex Pinia
One root store with modules Many independent stores, each with an id
state state (same idea)
getters getters (same idea; a getter can use this)
mutations (the only way to change state) Gone. Change state in actions or directly
actions that commit mutations actions that change state directly
dispatch('cart/add', item) cart.add(item)
commit('cart/SET', value) cart.value = value or cart.$patch(...)
namespaced: true modules Not needed: every store is its own namespace
rootState, rootGetters Just call another store: useUserStore()
mapState, mapGetters, mapActions mapState, mapActions, mapStores, or storeToRefs
this.$store / useStore() useCartStore()
store.subscribe / subscribeAction store.$subscribe / store.$onAction
store.replaceState store.$state = {...} or $patch
registerModule (dynamic) Stores are dynamic by nature: created on first use
Plugins Pinia plugins

The largest simplification is mutations. In Vuex every change needs two functions (an action and a mutation) and a string name in between. In Pinia an action is a normal function, and you may even write to state outside of one.

flowchart LR
  subgraph Vuex
    V1["component"] -->|"dispatch('add')"| V2["action"]
    V2 -->|"commit('ADD')"| V3["mutation"]
    V3 --> V4["state"]
  end
  subgraph Pinia
    P1["component"] -->|"store.add()"| P2["action"]
    P2 --> P3["state"]
  end

Fewer layers: no mutation step and no string-based dispatching.

The same app in both

Below is a small shopping list. First in Vuex 4 (real Vuex, loaded from a CDN), then in Pinia. Look at the shape of the code more than at the details.

The same list with Vuex 4
The same list with Pinia

Count what changed: the two mutations are gone, commit is gone, the action receives this instead of a context object, and the component calls list.add('eggs') instead of dispatching a string.

Context objects: this instead of { commit, state, getters }

A Vuex action receives a context: { state, getters, commit, dispatch, rootState, rootGetters }. A Pinia action has none of that; this is the store, so it reaches state, getters and other actions directly:

JavaScript
// Vuex
actions: {
  checkout({ state, getters, commit, dispatch, rootState }) {
    if (!rootState.user.loggedIn) return;
    commit("SET_STATUS", "paying");
    return dispatch("payments/charge", getters.total, { root: true });
  },
}
JavaScript
// Pinia
actions: {
  checkout() {
    const user = useUserStore();
    const payments = usePaymentsStore();
    if (!user.loggedIn) return;
    this.status = "paying";
    return payments.charge(this.total);
  },
}

Instead of rootState and { root: true }, you import the other store and call it. Dependencies are explicit, can be traced by your editor and are typed.

Modules become stores

A Vuex module with namespaced: true becomes one Pinia store. The module name becomes the store id:

JavaScript
// Vuex: modules/cart.js   (state read as store.state.cart.items)
export default { namespaced: true, state: ..., getters: ..., mutations: ..., actions: ... };

// Pinia: stores/cart.js   (state read as useCartStore().items)
export const useCartStore = defineStore("cart", { state: ..., getters: ..., actions: ... });

There is no store/index.js that lists all modules. Stores are plain files that components import when they need them. Nested modules (cart/items) become flat stores that may import each other.

Helpers

Components written with the Options API can keep using helpers, now imported from Pinia:

JavaScript
import { mapState, mapActions } from "pinia";
import { useListStore } from "@/stores/list";

export default {
  computed: {
    ...mapState(useListStore, ["items", "count"]),
  },
  methods: {
    ...mapActions(useListStore, ["add", "clear"]),
  },
};

Notice that you pass the store function as the first argument. The lesson on migrating components shows a working example.

What does not carry over

  • Mutation-based devtools time travel works differently: Pinia's DevTools tab records actions and state changes.
  • Strict mode (strict: true, which warns about changes outside mutations) does not exist. Direct state changes are allowed by design.
  • store.watch() is replaced by Vue's watch(() => store.x, ...) or $subscribe.
  • createLogger() becomes a small plugin using $onAction, like the one in Extending Stores from Plugins.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What replaces Vuex mutations in Pinia?

    Pinia has no mutations. Actions (or direct assignment and $patch) change the state.
  2. 2. How does a Pinia action read another module's state, where Vuex used rootState?

    Stores are plain functions; an action just calls useOtherStore().
  3. 3. What does a Vuex namespaced module become?

    Each module maps to one store defined with defineStore(id, ...).
  4. 4. How do you call the Vuex action dispatch('list/add', 'eggs') in Pinia?

    Actions are methods of the store.

Summary

  • Pinia keeps state, getters and actions, drops mutations, namespaces and the root store.
  • Actions use this; to reach other modules call their stores.
  • Vuex modules become Pinia stores; dispatch/commit become method calls.
  • mapState, mapActions still exist, taking a store function.
  • Vuex strict mode and some devtools behavior have no direct equivalent.

Next: Migrating a Vuex Module Step by Step