Skip to content
Tutorials Center
My learning

Topics

Lesson 72 of 87 ยท Performance, Security and Ecosystem

Migrating from Vue 2 and Vuex

Migrate a Vue 2 app to Vue 3: breaking changes (filters, event bus, v-model, global API), the @vue/compat migration build, Options to Composition API and moving from Vuex to Pinia, step by step.

Vue 2 reached end of life on December 31, 2023. It still runs, and many production apps use it, but it no longer receives fixes, and the ecosystem (libraries, UI kits, tooling) has moved to Vue 3. If you maintain such an app, you have a migration ahead. The good news: Vue 3 kept the core ideas (templates, components, directives, reactivity), the Options API still works, and there is an official migration build that lets you upgrade in steps instead of one risky leap.

This lesson is a practical map. First the plan, then the breaking changes you will actually meet, then the two biggest moves: replacing global APIs and the event bus, and replacing Vuex with Pinia. Shell commands and project files are read-only, because the site cannot run a build. The runnable examples show the new code side by side with the old in comments.

The plan

A rewrite-from-scratch is almost never right. Work in this order:

flowchart TD
    A["1. Audit: Vue version, router, Vuex, UI library, test tools"] --> B["2. Upgrade to Vue 2.7 and fix its deprecation warnings"]
    B --> C["3. Replace libraries with Vue 3 versions<br/>Router 4, Pinia or Vuex 4, UI kit, Test Utils 2"]
    C --> D["4. Switch to @vue/compat and fix warnings one by one"]
    D --> E["5. Remove compat: plain Vue 3"]
    E --> F["6. Optional: Composition API, script setup, Vite"]

Each step leaves the app working. Ship after every step, not only at the end.

  • Vue 2.7 is the last Vue 2 release. It backports the Composition API, <script setup> and defineComponent, so you can start writing Vue 3 style code inside the old app, and its warnings point at what will break.
  • Libraries first. The app can only move as far as its slowest dependency. List every plugin, mixin library and UI kit and check whether a Vue 3 version exists. Vue Router 3 becomes Router 4, vue-test-utils 1 becomes Test Utils 2, Vuetify 2 becomes Vuetify 3, and so on. A dependency with no Vue 3 version is a decision: replace, fork or drop it.
  • The build tool is a separate decision. Do not switch from webpack to Vite and from Vue 2 to Vue 3 in the same week (legacy setups).
  • The migration build, @vue/compat, is Vue 3 with a layer that behaves like Vue 2 for most features and prints a warning for each use of a removed API. You alias vue to @vue/compat in your bundler, set compilerOptions.compatConfig = { MODE: 2 }, and clear the warnings in the console one at a time. A component can opt in to full Vue 3 behaviour with compatConfig: { MODE: 3 } when it is clean. Some things cannot be emulated (for example libraries that use Vue 2 internals), which is why the library audit comes first.
  • Tests are your safety net. Before you start, make sure key flows have tests (testing overview). Without tests, every warning fix is a guess.

Breaking changes you will actually meet

Vue 2 Vue 3
new Vue({ render }).$mount("#app") createApp(App).mount("#app")
Vue.use(plugin), Vue.component(...), Vue.directive(...), Vue.mixin(...) (global, shared by all apps) app.use(...), app.component(...), app.directive(...), app.mixin(...) on one app instance
Vue.prototype.$http = ... app.config.globalProperties.$http = ... (or better, provide/inject or a module)
Vue.set(obj, key, v), Vue.delete Not needed: proxies detect new keys and index writes (reactivity pitfalls)
Filters {{ price | currency }} Removed. Use a method, a computed property or a plain function
$on, $off, $once (event bus: new Vue() as a hub) Removed from instances. Use a small emitter library, a store or provide/inject
value prop and input event for v-model modelValue prop and update:modelValue event
.sync modifier (:title.sync="t") v-model:title="t"
.native modifier on component listeners Removed. Declare the events in emits; undeclared listeners fall through to the root element
$listeners Merged into $attrs (attrs and inheritance)
beforeDestroy, destroyed beforeUnmount, unmounted
data could be an object on a root instance data must always be a function
<template v-for>: the key goes on each child The key goes on the <template> tag
v-for has higher priority than v-if v-if has higher priority than v-for (list rendering)
Transition classes v-enter, v-leave v-enter-from, v-leave-from (transitions)
Single root element per template Multiple roots (fragments) allowed
@keyup.13 (key codes) Use key names: @keyup.enter
functional: true components Functional components are plain functions
Async component () => import("./X.vue") defineAsyncComponent(() => import("./X.vue"))
Vue Router 3: new VueRouter, catch-all * Router 4: createRouter, createWebHistory, catch-all /:pathMatch(.*)* (Vue Router)
$refs inside v-for filled an array automatically Use a function ref or an array ref, and note that the order is not guaranteed (template refs)
Plugins written with Vue.extend or global state Use app in install(app, options) (plugins)

Not on the list because it is not a break: the Options API, methods, computed, watch, lifecycle hooks (except the two renamed), mixins (still work, though composables are better), v-model on native inputs, and slots (the slot="name" attribute syntax was already deprecated in 2.6; use v-slot / #name).

Filters, v-model and .sync in practice

Filters were Vue 2's way to format text in templates. In Vue 3 you call a function, which is clearer and works in any expression. Custom form components change their v-model contract. This example shows the Vue 3 forms, with the Vue 2 versions in comments:

Filters, v-model and .sync after migration

Type into the fields: the parent's refs update, and the formatted price follows. v-model:title and v-model:author on one component replace .sync and allow several models per component (component v-model). In a migration, the mechanical part is searching your codebase for | filter pipes in templates, .sync, $emit("input", value props that back v-model, .native and $listeners. The compat build warns about each of them, so you rarely have to hunt blindly.

Replacing $on and the event bus

A common Vue 2 trick was creating an empty new Vue() and using bus.$emit("saved") and bus.$on("saved", fn) for communication between distant components. Vue 3 removed $on, $off and $once from instances ($emit remains, but only for parent-child events). The hub pattern is still fine in some cases; you replace it with a tiny emitter (for example the mitt package, about 200 bytes) or, usually better, with shared state (state sharing).

Vuex to Pinia

Vuex was Vue's official store, and Vuex 4 works with Vue 3, so you can migrate the framework first and the store later. But Pinia is the recommended store now (Pinia basics), and it is simpler:

Vuex Pinia
state state (or ref in a setup store)
getters getters (or computed)
mutations (the only way to change state, synchronous) Gone: change state directly or in actions
actions (commit mutations, can be async) actions (change state, can be async)
modules, namespaced One store per module, namespaced by its id automatically
this.$store.state.cart.items, mapState, mapGetters const cart = useCartStore(), storeToRefs(cart)
this.$store.commit("add", item), dispatch("load") cart.add(item), cart.load()

A good migration order: move one module at a time. Vuex 4 and Pinia can live in the same app, and components switch store by store. Delete mutations as you go: every commit becomes the logic of an action.

The example puts the two styles next to each other. Both are small stand-ins (neither is the real library), written so you can compare the shape of the code, plus a mitt-style emitter for the bus.

Vuex shape versus Pinia shape, and an event bus replacement

Both stores do the same work. The Vuex-shaped one needs a mutation (ADD) for every state change and an action wrapper to do anything asynchronous; the Pinia-shaped one is a few functions. Real Pinia adds DevTools, plugins and server-side support on top. In a real migration the commit("ADD", name) calls in components become cart.add(name).

Options API to Composition API (optionally)

Because Vue 3 keeps the Options API, you do not have to convert components. Convert when you touch them: a component that is hard to understand because its logic is spread over data, computed, watch and methods is a good candidate, and logic that you want to share becomes a composable (composables). <script setup> (script setup) is the shortest way to write the result. A mixin becomes a composable that returns exactly the refs and functions it provides, which fixes the old problem of invisible name clashes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the recommended first step before moving a large Vue 2 app to Vue 3?

    Your app can only move as far as its dependencies. Vue 2.7 gives you Composition API and warnings, and you can then use the @vue/compat build to move step by step.
  2. 2. What replaces <my-input :value="x" @input="x = $event"> when the component supports v-model in Vue 3?

    Vue 3 v-model on a component uses the modelValue prop and update:modelValue event (and v-model:name for extra models, replacing .sync).
  3. 3. Vue 3 removed filters. How do you format a value in a template now?

    A function call such as {{ currency(price) }} does the same job and works in any expression.
  4. 4. What happened to Vuex mutations in Pinia?

    Pinia has state, getters and actions. Actions can be synchronous or asynchronous and change state directly.
  5. 5. Which API can you no longer use on component instances for a global event bus?

    Instance event listeners ($on, $off, $once) were removed. Use a tiny emitter library or shared state instead.

Summary

  • Vue 2 is end of life; migrate in steps: audit, Vue 2.7, library upgrades, the @vue/compat build, then plain Vue 3.
  • Main breaking changes: createApp and app.* instead of global Vue.*, no filters, no $on/$off/$once, modelValue and update:modelValue, v-model:name instead of .sync, renamed lifecycle hooks and transition classes, v-if over v-for.
  • Replace the event bus with a small emitter or shared state, and filters with functions.
  • Vuex 4 works with Vue 3, but Pinia is simpler: no mutations, one store per module, and storeToRefs instead of map helpers.
  • The Options API still works; convert to the Composition API where it pays off, one component at a time.

Next: put your skills into practice with a complete app, Project: Todo App.