Migration API Reference

This section provides a complete reference for APIs and utility functions available when migrating from Vuex to Pinia.

Migration Helpers

createVuexStore()

Creates a Vuex-compatible store wrapper to help with progressive migration.

function createVuexStore<S, G, A, M>(
  options: VuexStoreOptions<S, G, A, M>
): VuexCompatStore<S, G, A, M>

Parameters

• options: VuexStoreOptions<S, G, A, M> - Vuex store configuration options

Return Value

• Type: VuexCompatStore<S, G, A, M>
• Description: A store instance compatible with Vuex API

Example

import { createVuexStore } from 'pinia/migration'

const store = createVuexStore({
  state: {
    count: 0
  },
  mutations: {
    increment(state) {
      state.count++
    }
  },
  actions: {
    incrementAsync({ commit }) {
      setTimeout(() => {
        commit('increment')
      }, 1000)
    }
  },
  getters: {
    doubleCount: state => state.count * 2
  }
})

mapVuexState()

Maps Vuex state to components, compatible with Vuex's mapState.

function mapVuexState<S>(
  namespace?: string,
  states: string[] | Record<string, string | ((state: S) => any)>
): Record<string, ComputedRef>

Parameters

• namespace: string (optional) - Module namespace
• states: string[] | Record<string, string | Function> - States to map

Return Value

• Type: Record<string, ComputedRef>
• Description: Object of mapped computed properties

Example

import { mapVuexState } from 'pinia/migration'

export default {
  computed: {
    // Array syntax
    ...mapVuexState(['count', 'user']),
    
    // Object syntax
    ...mapVuexState({
      localCount: 'count',
      localUser: 'user'
    }),
    
    // With namespace
    ...mapVuexState('counter', ['count'])
  }
}

mapVuexGetters()

Maps Vuex getters to components, compatible with Vuex's mapGetters.

function mapVuexGetters<G>(
  namespace?: string,
  getters: string[] | Record<string, string>
): Record<string, ComputedRef>

Parameters

• namespace: string (optional) - Module namespace
• getters: string[] | Record<string, string> - Getters to map

Return Value

• Type: Record<string, ComputedRef>
• Description: Object of mapped computed properties

Example

import { mapVuexGetters } from 'pinia/migration'

export default {
  computed: {
    // Array syntax
    ...mapVuexGetters(['doubleCount', 'isEven']),
    
    // Object syntax
    ...mapVuexGetters({
      localDouble: 'doubleCount'
    }),
    
    // With namespace
    ...mapVuexGetters('counter', ['doubleCount'])
  }
}

mapVuexActions()

Maps Vuex actions to components, compatible with Vuex's mapActions.

function mapVuexActions<A>(
  namespace?: string,
  actions: string[] | Record<string, string>
): Record<string, Function>

Parameters

• namespace: string (optional) - Module namespace
• actions: string[] | Record<string, string> - Actions to map

Return Value

• Type: Record<string, Function>
• Description: Object of mapped methods

Example

import { mapVuexActions } from 'pinia/migration'

export default {
  methods: {
    // Array syntax
    ...mapVuexActions(['increment', 'decrement']),
    
    // Object syntax
    ...mapVuexActions({
      add: 'increment'
    }),
    
    // With namespace
    ...mapVuexActions('counter', ['increment'])
  }
}

mapVuexMutations()

Maps Vuex mutations to components, compatible with Vuex's mapMutations.

function mapVuexMutations<M>(
  namespace?: string,
  mutations: string[] | Record<string, string>
): Record<string, Function>

Parameters

• namespace: string (optional) - Module namespace
• mutations: string[] | Record<string, string> - Mutations to map

Return Value

• Type: Record<string, Function>
• Description: Object of mapped methods

Example

import { mapVuexMutations } from 'pinia/migration'

export default {
  methods: {
    // Array syntax
    ...mapVuexMutations(['increment', 'decrement']),
    
    // Object syntax
    ...mapVuexMutations({
      add: 'increment'
    }),
    
    // With namespace
    ...mapVuexMutations('counter', ['increment'])
  }
}

Migration Utilities

convertVuexModule()

Converts a Vuex module to a Pinia store definition.

function convertVuexModule<S, G, A, M>(
  module: VuexModule<S, G, A, M>
): StoreDefinition<string, S, G, A>

Parameters

• module: VuexModule<S, G, A, M> - Vuex module to convert

Return Value

• Type: StoreDefinition<string, S, G, A>
• Description: Pinia store definition

Example

import { convertVuexModule } from 'pinia/migration'

const vuexModule = {
  state: () => ({ count: 0 }),
  mutations: {
    increment(state) {
      state.count++
    }
  },
  actions: {
    incrementAsync({ commit }) {
      setTimeout(() => commit('increment'), 1000)
    }
  },
  getters: {
    doubleCount: state => state.count * 2
  }
}

const useCounterStore = convertVuexModule(vuexModule)

createMigrationPlugin()

Creates a Pinia plugin to help with Vuex compatibility during migration.

function createMigrationPlugin(
  options?: MigrationPluginOptions
): PiniaPlugin

Parameters

• options: MigrationPluginOptions (optional) - Plugin configuration

Return Value

• Type: PiniaPlugin
• Description: Pinia plugin for migration support

Example

import { createPinia } from 'pinia'
import { createMigrationPlugin } from 'pinia/migration'

const pinia = createPinia()
pinia.use(createMigrationPlugin({
  enableVuexCompat: true,
  warnOnVuexUsage: true
}))

Type Definitions

VuexStoreOptions

interface VuexStoreOptions<S, G, A, M> {
  state?: S | (() => S)
  getters?: G
  actions?: A
  mutations?: M
  modules?: Record<string, VuexModule>
  plugins?: VuexPlugin[]
  strict?: boolean
  devtools?: boolean
}

VuexCompatStore

interface VuexCompatStore<S, G, A, M> {
  state: S
  getters: G
  dispatch: (type: string, payload?: any) => Promise<any>
  commit: (type: string, payload?: any) => void
  subscribe: (fn: (mutation: any, state: S) => void) => () => void
  subscribeAction: (fn: (action: any, state: S) => void) => () => void
  watch: <T>(getter: (state: S, getters: G) => T, cb: (value: T, oldValue: T) => void) => () => void
  replaceState: (state: S) => void
  registerModule: (path: string | string[], module: VuexModule) => void
  unregisterModule: (path: string | string[]) => void
  hasModule: (path: string | string[]) => boolean
  hotUpdate: (newOptions: VuexStoreOptions<S, G, A, M>) => void
}

MigrationPluginOptions

interface MigrationPluginOptions {
  enableVuexCompat?: boolean
  warnOnVuexUsage?: boolean
  vuexNamespace?: string
  autoConvertModules?: boolean
}

Migration Strategies

Progressive Migration

The migration helpers support progressive migration strategies:

1. Coexistence: Run Vuex and Pinia side by side
2. Module-by-module: Migrate individual Vuex modules
3. Component-by-component: Update components gradually

Best Practices

• Use createVuexStore() for initial compatibility
• Gradually convert modules using convertVuexModule()
• Update component mappings incrementally
• Enable warnings to track migration progress
• Test thoroughly at each migration step

See Also

• Migration Guide
• Vuex Compatibility
• Testing Migration