Vuex to Pinia Migration: The Complete 2026 Guide (With Code Examples)

# npm
npm install pinia

# yarn
yarn add pinia

# pnpm
pnpm add pinia

// main.ts (or main.js)
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const app = createApp(App)

// Create Pinia instance
const pinia = createPinia()

// Use Pinia (can coexist with Vuex during migration)
app.use(pinia)

// If you still have Vuex stores to migrate:
// app.use(store)

app.mount('#app')

// store/modules/user.js (Vuex)
export default {
  namespaced: true,

  state: () => ({
    user: null,
    isAuthenticated: false,
    loading: false,
    error: null
  }),

  getters: {
    fullName: (state) => {
      if (!state.user) return ''
      return `${state.user.firstName} ${state.user.lastName}`
    },
    isAdmin: (state) => {
      return state.user?.role === 'admin'
    }
  },

  mutations: {
    SET_USER(state, user) {
      state.user = user
      state.isAuthenticated = !!user
    },
    SET_LOADING(state, loading) {
      state.loading = loading
    },
    SET_ERROR(state, error) {
      state.error = error
    },
    CLEAR_USER(state) {
      state.user = null
      state.isAuthenticated = false
    }
  },

  actions: {
    async login({ commit }, credentials) {
      commit('SET_LOADING', true)
      commit('SET_ERROR', null)
      try {
        const response = await api.login(credentials)
        commit('SET_USER', response.data.user)
        return response.data
      } catch (error) {
        commit('SET_ERROR', error.message)
        throw error
      } finally {
        commit('SET_LOADING', false)
      }
    },

    async logout({ commit }) {
      await api.logout()
      commit('CLEAR_USER')
    },

    async fetchCurrentUser({ commit }) {
      commit('SET_LOADING', true)
      try {
        const response = await api.getCurrentUser()
        commit('SET_USER', response.data.user)
      } catch (error) {
        commit('SET_ERROR', error.message)
      } finally {
        commit('SET_LOADING', false)
      }
    }
  }
}

// stores/user.ts (Pinia)
import { defineStore } from 'pinia'
import { api } from '@/services/api'

interface User {
  id: number
  firstName: string
  lastName: string
  email: string
  role: 'user' | 'admin'
}

interface UserState {
  user: User | null
  loading: boolean
  error: string | null
}

export const useUserStore = defineStore('user', {
  state: (): UserState => ({
    user: null,
    loading: false,
    error: null
  }),

  getters: {
    isAuthenticated: (state) => !!state.user,
    fullName: (state) => {
      if (!state.user) return ''
      return `${state.user.firstName} ${state.user.lastName}`
    },
    isAdmin: (state) => state.user?.role === 'admin'
  },

  actions: {
    async login(credentials: { email: string; password: string }) {
      this.loading = true
      this.error = null
      try {
        const response = await api.login(credentials)
        this.user = response.data.user  // Direct mutation!
        return response.data
      } catch (error: any) {
        this.error = error.message
        throw error
      } finally {
        this.loading = false
      }
    },

    async logout() {
      await api.logout()
      this.$reset()  // Built-in reset to initial state!
    },

    async fetchCurrentUser() {
      this.loading = true
      try {
        const response = await api.getCurrentUser()
        this.user = response.data.user
      } catch (error: any) {
        this.error = error.message
      } finally {
        this.loading = false
      }
    }
  }
})

// stores/cart.ts
import { defineStore } from 'pinia'
import { useUserStore } from './user'
import { useProductsStore } from './products'

export const useCartStore = defineStore('cart', {
  state: () => ({
    items: []
  }),

  actions: {
    addToCart(productId: number) {
      // Access other stores directly
      const userStore = useUserStore()
      const productsStore = useProductsStore()

      if (!userStore.isAuthenticated) {
        throw new Error('Must be logged in to add to cart')
      }

      const product = productsStore.getProductById(productId)
      this.items.push({ product, quantity: 1 })
    }
  }
})

// stores/products.ts
import { defineStore } from 'pinia'

interface Product {
  id: number
  name: string
  price: number
  inStock: boolean
}

export const useProductsStore = defineStore('products', {
  state: () => ({
    products: [] as Product[],  // Type annotation
    selectedId: null as number | null
  }),

  getters: {
    // Return type is inferred automatically
    selectedProduct(state) {
      return state.products.find(p => p.id === state.selectedId)
    },

    // Or be explicit if you prefer
    inStockProducts(state): Product[] {
      return state.products.filter(p => p.inStock)
    },

    // Getters can use other getters with `this`
    selectedProductName(): string {
      return this.selectedProduct?.name ?? 'None selected'
    }
  },

  actions: {
    // Parameters are typed, `this` is fully typed
    async fetchProducts() {
      const response = await api.get<Product[]>('/products')
      this.products = response.data
    },

    selectProduct(id: number) {
      this.selectedId = id
    }
  }
})

// stores/counter.ts (Setup Syntax)
import { defineStore } from 'pinia'
import { ref, computed } from 'vue'

export const useCounterStore = defineStore('counter', () => {
  // State = refs
  const count = ref(0)

  // Getters = computed
  const doubleCount = computed(() => count.value * 2)

  // Actions = functions
  function increment() {
    count.value++
  }

  async function incrementAsync() {
    await new Promise(r => setTimeout(r, 1000))
    count.value++
  }

  // Must return all state, getters, and actions
  return { count, doubleCount, increment, incrementAsync }
})

// stores/user.spec.ts
import { setActivePinia, createPinia } from 'pinia'
import { useUserStore } from './user'
import { vi, describe, it, expect, beforeEach } from 'vitest'

describe('User Store', () => {
  beforeEach(() => {
    // Create a fresh Pinia instance for each test
    setActivePinia(createPinia())
  })

  it('starts with no user', () => {
    const store = useUserStore()
    expect(store.user).toBeNull()
    expect(store.isAuthenticated).toBe(false)
  })

  it('logs in a user', async () => {
    const store = useUserStore()
    
    // Mock the API
    vi.spyOn(api, 'login').mockResolvedValue({
      data: { user: { id: 1, firstName: 'John', lastName: 'Doe' } }
    })

    await store.login({ email: 'john@example.com', password: 'secret' })

    expect(store.user).toEqual({ id: 1, firstName: 'John', lastName: 'Doe' })
    expect(store.isAuthenticated).toBe(true)
    expect(store.fullName).toBe('John Doe')
  })

  it('resets state on logout', async () => {
    const store = useUserStore()
    store.user = { id: 1, firstName: 'John', lastName: 'Doe' }

    await store.logout()

    expect(store.user).toBeNull()
  })
})

// components/UserProfile.spec.ts
import { mount } from '@vue/test-utils'
import { createTestingPinia } from '@pinia/testing'
import UserProfile from './UserProfile.vue'

it('displays user name', () => {
  const wrapper = mount(UserProfile, {
    global: {
      plugins: [
        createTestingPinia({
          initialState: {
            user: {
              user: { firstName: 'John', lastName: 'Doe' }
            }
          }
        })
      ]
    }
  })

  expect(wrapper.text()).toContain('John Doe')
})