How to migrate Vue 2 to Vue 3

1. Take an inventory of breaking changes

Run vueleap at the root of the project. It reads .vue, JavaScript, TypeScript and style files plus package.json, skips node_modules, dist and anything in .gitignore, and groups findings by rule.

# run it once, nothing to install
npx vueleap

# or add it to the project
npm install --save-dev vueleap

# run it once, nothing to install
pnpm dlx vueleap

# or add it to the project
pnpm add --save-dev vueleap

# run it once, nothing to install
yarn dlx vueleap

# or add it to the project
yarn add --dev vueleap

# run it once, nothing to install
bunx vueleap

# or add it to the project
bun add --dev vueleap

Add --html report.html to also get a shareable report.

Every finding has a severity: error breaks at compile time or runtime, warning changes behavior, info deserves a review. The summary ends with an effort score to compare projects or track progress.

2. Upgrade the build tooling

Vue 3 single file components are compiled by @vue/compiler-sfc, which ships with vue. Remove vue-template-compiler, use vue-loader 17 with webpack or Vue CLI 5, or @vitejs/plugin-vue with Vite. vueleap reports these under vue2-tooling.

3. Install Vue 3 with the migration build

npm install vue@^3.5 @vue/compat@^3.5
npm uninstall vue-template-compiler

Alias vue to @vue/compat and enable compat mode in the template compiler. vueleap prints this configuration with only the flags your project needs, running everything else in Vue 3 mode (MODE: 3):

// vite.config.js
import vue from '@vitejs/plugin-vue'

export default {
  resolve: { alias: { vue: '@vue/compat' } },
  plugins: [
    vue({
      template: {
        compilerOptions: {
          compatConfig: { MODE: 3, COMPILER_FILTERS: true, COMPILER_V_BIND_SYNC: true },
        },
      },
    }),
  ],
}

// main.js
import { configureCompat } from 'vue'

configureCompat({
  MODE: 3,
  GLOBAL_MOUNT: true,
  INSTANCE_EVENT_EMITTER: true,
  FILTERS: true,
})

Read @vue/compat build flags explained for what each flag does.

4. Apply the safe automatic fixes

Some changes are pure renames. vueleap rewrites them while preserving formatting, and shows a diff first:

npx vueleap --fix           # preview
npx vueleap --fix --write   # apply

That covers beforeDestroy and destroyed, custom directive hooks, $scopedSlots, transition class names, keyCode modifiers with a single key name, .sync to v-model:prop, @hook: events and Vue.config.productionTip.

5. Fix the rest, rule by rule

1. Replace new Vue() with createApp() and move Vue.use, Vue.component, Vue.directive and Vue.prototype to the app instance.
2. Remove filters and replace the event bus.
3. Update components used with v-model to modelValue and update:modelValue.
4. Rewrite render functions to import h from vue, and replace $listeners and $children.

The breaking changes checklist links every rule to the official guide.

6. Upgrade the ecosystem

Move to vue-router 4 and to Vuex 4 or Pinia. Replace Vue 2 only UI libraries: BootstrapVue with bootstrap-vue-next, Vuetify 2 with Vuetify 3, Element UI with Element Plus. vueleap lists them from package.json with the suggested successor.

7. Turn compat off and keep it off

Remove each compat flag once vueleap no longer reports the matching rule. When the list is empty, drop the alias and @vue/compat. Then keep the codebase clean in CI:

npx vueleap --fail-on error

Frequently asked questions

More guides