Migrating from Vuex to Pinia: A Practical Guide

Pinia is the state management library that ships as the default in Vue 3 land. If you are still on Vuex, the migration is not urgent — Vuex 4 still works — but it is worth doing. The mental model is simpler, the TypeScript story is better, and the API is half the size.

What changes

Pinia drops the namespace and module concept that Vuex had. Each store is a flat file with state, getters, and actions. There are no mutations — actions mutate state directly. You define a store with defineStore() and import it in any component that needs it.

Migrate store by store

Both libraries can coexist in a project. Install Pinia alongside Vuex, then convert one store at a time. The order I usually pick: smallest, most isolated stores first (settings, UI state); largest, most-coupled stores last (auth, user, cart).

For each store, port the state and getters first (they translate almost directly), then the actions. Mutations collapse into actions — you do not need a separate concept for synchronous changes.

Updating components

ts// Vuex
this.$store.dispatch('cart/addItem', item)
this.$store.getters['cart/itemCount']

// Pinia
import { useCartStore } from '@/stores/cart'
const cart = useCartStore()
cart.addItem(item)
cart.itemCount

The Pinia version is more direct — and far better for TypeScript inference. Methods on cart are typed; in Vuex, this.$store.dispatch is mostly stringly-typed and your editor cannot help much.

What to leave alone

If a Vuex store is large, well-tested, and not actively changing, migration is busywork. Migrate the stores you actively touch and leave the rest until they need changes. Pinia's compatibility is fine for years of dual existence.