Upgrade to Vue 3

Vue 2 is end of life, so the Vue 3 upgrade is no longer optional for maintained apps. The risk concentrates in app initialization (createApp), global API changes, removed features (filters, the event bus, $children), and ecosystem packages — not in rewriting every component.

Version upgradeDifficulty: hardEffort: 1–4 weeks depending on app size and plugin counthigh risk

Last verified May 20, 2026 · Updated May 22, 2026

Vue 2 reached end of life on 2023-12-31 and gets no further security patches, so maintained apps must move to Vue 3. The @vue/compat migration build lets you run on the Vue 3 runtime with Vue 2 behavior and migrate incrementally. Most breakage is in app initialization, the global API, removed features, and ecosystem packages.

Who should upgrade

Every maintained Vue 2 app — Vue 2 is EOL and receives no security patches.
Apps wanting Teleport, fragments (multiple root nodes), and the Composition API.
Teams ready to move from Vuex to Pinia and from Vue CLI to Vite.

Who should wait

Apps blocked by a critical third-party plugin with no Vue 3-compatible release.
Apps mid-feature-freeze, where the @vue/compat incremental path should be scheduled deliberately rather than rushed.

What changed

App init: `createApp(App)` replaces `new Vue({ render })`; global config/plugins attach to the app instance.
v-model on components changed: default prop/event renamed and multiple v-models are supported.
Components can have multiple root nodes (fragments); Teleport renders content to another DOM location.
Removed: filters, the global event bus ($on/$off/$once), and `$children`.
@vue/compat: run on the Vue 3 runtime with Vue 2 behavior plus per-feature deprecation warnings.

Vue 2 is end of life

Vue 2 stopped receiving updates, including security patches, on 2023-12-31. Staying on Vue 2 means shipping unpatched dependencies. Treat the Vue 3 upgrade as a security item, and use @vue/compat to make it incremental rather than a blocking rewrite.

Recommended upgrade path

Incremental path using the @vue/compat migration build

# 1. Install the Vue 3 runtime and the migration build$ npm install vue@3 @vue/compat@3# 2. Alias vue to @vue/compat in your build config, then run the app#    and read the deprecation warnings it emits$ npm run dev# 3. Upgrade the ecosystem packages$ npm install vue-router@4 pinia

App initialization

new Vue vs createApp

// Vue 2
import Vue from 'vue'
import App from './App.vue'
new Vue({ render: (h) => h(App) }).$mount('#app')

// Vue 3
import { createApp } from 'vue'
import App from './App.vue'
const app = createApp(App)
app.use(router)
app.mount('#app')

Ecosystem migration matrix

Concern	Vue 2	Vue 3
Router	Vue Router 3	Vue Router 4
State management	Vuex 3/4	Pinia (recommended)
Build tooling	Vue CLI (webpack)	Vite
Filters	Supported	Removed — use methods/computed
Event bus	$on / $off / $once	Removed — use mitt or props/emit
$children	Available	Removed — use refs / provide-inject

Migration executionAI-assisted migration workflow

Upgrade this app to Vue 3 incrementally. First install @vue/compat and alias vue to it so the app runs on the Vue 3 runtime with Vue 2 behavior. Then switch the entry point to createApp, move global registrations onto the app instance, and clear compat warnings by category (filters, event bus, $children, .sync). Upgrade Vue Router 3 to 4 and Vuex to Pinia. Run lint, tests, and build after each step and report before continuing. Remove @vue/compat only once no deprecation warnings remain.

Safety: Incremental edits only. Pause for review after the createApp switch and after clearing each warning category. Do not convert components to the Composition API in this pass.

PR review checklist

vue is pinned to a single 3.x version in the lockfile
Entry point uses createApp; globals attach to the app instance
No filters, event bus ($on/$off/$once), or $children remain
Vue Router is on 4.x and the store is on Pinia (or Vuex 4)
No @vue/compat deprecation warnings remain in the console

Rollback strategy

Keep the @vue/compat install, the createApp switch, and each warning-category fix in separate commits.
Revert to vue@2 and the old ecosystem versions and reinstall if a blocking plugin incompatibility appears.
Hold the upgrade behind a release branch until the suite is green and warnings are clear.

Common errors

'Vue is not a constructor' — replace `new Vue` with `createApp`.
Filters no longer render — convert `{{ value | format }}` to a method or computed.
Event bus events never fire — $on/$off/$once were removed; use mitt or props/emit.
See the fix-vue-3-migration-errors workflow for the full triage list.

Official sources

Official docsVue.js Guidevuejs.orgreliability 98%
Backs the breaking-change and migration-step claims.
Migration guideVue 3 Migration Guidevuejs.orgreliability 98%
Backs the breaking-change and migration-step claims.
GitHub releaseVue core releasesvuejs/corereliability 92%
Backs the breaking-change and migration-step claims.

Copy-ready AI prompts

Structured prompts for an AI coding assistant. Inspect first, then execute incrementally, and keep a human in the review loop.

Repo inspectionRepo inspection prompt

You are helping with a Vue migration: upgrade to Vue 3.

Do not edit files yet. First inspect the repository and report:
1. The exact vue version in package.json and the lockfile, plus vue-router, vuex, @vue/cli-service, and any vue plugins, and whether each has a Vue 3-compatible release.
2. The application entry point: `new Vue(...)` vs `createApp(...)`, and global registrations (Vue.use, Vue.component, Vue.directive, Vue.prototype / Vue.config.globalProperties).
3. Usage of removed Vue 2 features: filters, the global event bus / $on / $off / $once, `$children`, and `.sync` modifiers.
4. Components relying on multiple-root-node assumptions, v-model usage on custom components, and any `functional` components.
5. The build tool (Vue CLI vs Vite), test runner, and the build/lint/test commands.

Return: a migration risk summary, the highest-risk files, a suggested migration order, the commands to run before editing, and any questions that need human confirmation.

Safety: Inspection only. The agent must not modify files in this step.

Works with Claude Code, Cursor, GitHub Copilot

Migration executionMigration execution prompt

Perform the migration (upgrade to Vue 3) one concern at a time.

Work in this order and pause for review after each: (1) install the @vue/compat migration build so the app runs on the Vue 3 runtime with Vue 2 behavior, (2) switch the entry point from `new Vue` to `createApp` and move global registrations onto the app instance, (3) clear compat warnings by category — filters, the event bus ($on/$off/$once), `$children`, and `.sync` — (4) upgrade ecosystem packages (Vue Router 3 to 4, Vuex to Pinia, Vue CLI to Vite), (5) remove @vue/compat once warnings are clear.

After each step run the project's build, lint, and test commands and report results before continuing. Do not refactor unrelated code or convert components to the Composition API in this pass.

Safety: Apply changes incrementally and keep each step reviewable. Lean on @vue/compat warnings as your checklist; never suppress them to force a green build.

Works with Claude Code, Cursor, GitHub Copilot

Test plan

Commands

npm run lint
npm test -- --watch=false
npm run build

Manual checks

Boot: load the app and confirm it mounts with createApp and no console errors.
Routing: exercise navigation, route guards, and lazy routes after the Vue Router 3 to 4 upgrade.
State: verify store reads/writes still work after moving from Vuex to Pinia.
Compat: read remaining @vue/compat warnings and confirm each is resolved before removal.

Regression risks

Removed filters silently dropping formatted output.
Event-bus ($on/$off/$once) communication broken with the events API removed.
Third-party Vue 2 plugins without a Vue 3 release blocking the upgrade.
v-model behavior changes on custom components.

Acceptance criteria

Lint, unit tests, and build all pass on the Vue 3 runtime.
No @vue/compat deprecation warnings remain in the console.
Vue Router, the store, and every plugin resolve to Vue 3-compatible versions.

Frequently asked questions

Do I have to rewrite the whole app to upgrade to Vue 3?

No. The @vue/compat migration build runs your app on the Vue 3 runtime while keeping Vue 2 behavior and emitting per-feature deprecation warnings. You clear those warnings category by category, so the upgrade is incremental rather than a big-bang rewrite.

Do I have to adopt the Composition API when upgrading to Vue 3?

No. The Options API is fully supported in Vue 3. Upgrading the major version and adopting the Composition API are separate efforts — do the version upgrade first, then modernize patterns component by component if you choose to.