Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 38 ยท Migration from Vuex

Migrating Components and Running Vuex Beside Pinia

Move a Vue app from Vuex to Pinia without a big-bang rewrite: install both, migrate leaf modules first, convert components with map helpers and bridge the two stores.

Rewriting all state management in one pull request is risky and rarely necessary. Vuex and Pinia can live in the same app at the same time, so you can move one module at a time, keep the app shippable after every step and delete Vuex only when nothing uses it. This lesson gives you the plan, shows components in both styles and runs a real app with both libraries together.

The incremental plan

  1. Install Pinia next to Vuex: app.use(store).use(pinia).
  2. Pick a leaf module: one that few others depend on (settings, UI flags, notifications), not the central user module.
  3. Rewrite that module as a Pinia store (see the walkthrough) and delete the Vuex module.
  4. Update every component that used it.
  5. Bridge where an old module still needs the new store or the other way round.
  6. Repeat until Vuex is empty, then remove the package and store/index.js.
flowchart LR
  A["Vuex only"] --> B["Both installed"]
  B --> C["Leaf modules in Pinia"]
  C --> D["Core modules in Pinia"]
  D --> E["Remove Vuex"]

Every step leaves the app working.

Commit after each module. If something breaks, you know exactly which module caused it.

Updating components

The store is reachable in three styles of component. Here is the conversion table for each.

Composition API (<script setup>)

JavaScript
// before
import { useStore } from "vuex";
const store = useStore();
const total = computed(() => store.getters["cart/total"]);
const add = (p) => store.dispatch("cart/addItem", p);

// after
import { storeToRefs } from "pinia";
import { useCartStore } from "@/stores/cart";
const cart = useCartStore();
const { total } = storeToRefs(cart);     // keeps reactivity
const { addItem } = cart;                 // actions can be destructured directly

Remember: destructuring state and getters needs storeToRefs; destructuring actions does not.

Options API with helpers

JavaScript
// before
import { mapGetters, mapActions } from "vuex";
computed: { ...mapGetters("cart", ["total", "count"]) },
methods: { ...mapActions("cart", ["addItem"]) },

// after
import { mapState, mapActions } from "pinia";
import { useCartStore } from "@/stores/cart";
computed: { ...mapState(useCartStore, ["total", "count"]) },
methods: { ...mapActions(useCartStore, ["addItem"]) },

mapState is read-only. For two-way v-model use mapWritableState:

JavaScript
computed: { ...mapWritableState(useSettingsStore, ["theme"]) }

Options API with this.$store

If a component reaches into this.$store directly, mapStores gives a replacement. It adds a property named <id>Store for each store:

JavaScript
import { mapStores } from "pinia";

computed: { ...mapStores(useCartStore, useUserStore) },
methods: {
  buy() { this.cartStore.addItem(this.product); },   // this.userStore also exists
},

Bridging the two stores

During the migration the old and the new world need each other. Because both libraries are plain JavaScript, bridging is just importing.

A Pinia store reads a Vuex module, via the exported Vuex store instance:

JavaScript
import legacy from "@/store";          // the old Vuex store

export const useCartStore = defineStore("cart", {
  getters: {
    total() { return this.subtotal * (1 - legacy.state.user.discount); },
  },
});

A Vuex action uses a Pinia store: this works once Pinia is installed on the app, because installing sets the active pinia:

JavaScript
actions: {
  logout({ commit }) {
    commit("CLEAR_SESSION");
    useCartStore().$reset();           // Pinia store from inside a Vuex action
  },
},

Treat bridges as temporary. Each one is a reminder of a module still to migrate; remove them as you go.

A running example with both libraries

The page below installs real Vuex and real Pinia on the same app. user is still a Vuex module (the old world). cart is already a Pinia store that reads the user's discount through a bridge. One component uses Options API helpers from Pinia, the other uses $store for the remaining Vuex state. Change the discount through Vuex and watch the Pinia total follow.

Vuex and Pinia in one app

Notice the single source of truth for each piece of data: the discount lives in Vuex only, the cart only in Pinia. The bridge reads; it does not copy. Copying state between stores is a bug factory.

Pitfalls while mixing

  • Two reactive systems, one app. They are both built on Vue reactivity, so reading Vuex state inside a Pinia getter stays reactive, as the example shows.
  • DevTools show both: Vuex in its own panel and Pinia in the Pinia tab.
  • Circular dependencies appear when two stores import each other at module level. Call useOtherStore() inside actions and getters, never at the top of the file.
  • Tests. Component tests for migrated components should provide a testing pinia, as in Testing Components with createTestingPinia; unmigrated ones still need Vuex.
  • Types. In TypeScript the Pinia stores are typed automatically from their definition, which is one of the best rewards for finishing the migration.

Finishing

When no file imports vuex:

  1. Delete store/index.js and the Vuex plugins.
  2. Remove app.use(store).
  3. npm uninstall vuex.
  4. Search for $store, mapGetters, useStore from vuex and any "/ action strings. Zero results means done.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which module should you migrate first?

    Leaf modules have few callers to update, so the change is small and safe; core modules come later.
  2. 2. Which Pinia helper replaces mapGetters('cart', ['total'])?

    mapState takes the store function and a list of state or getter names.
  3. 3. Why must a Pinia getter read legacy Vuex state instead of copying it?

    Having the same data in two stores means two places to update. Bridge by reading the single source.
  4. 4. When can you destructure a store's action directly?

    Actions can be destructured safely; only state and getters need storeToRefs to stay reactive.

Summary

  • Install Pinia beside Vuex and migrate module by module, leaf modules first.
  • Convert components with storeToRefs, mapState, mapActions, mapWritableState and mapStores.
  • Bridge by importing: Pinia reads the Vuex store; Vuex actions can call Pinia stores.
  • Keep one source of truth per piece of data and remove bridges as you go.
  • Remove Vuex only when nothing imports it.

Next: Project: A Todo App with Filters