Vue 2 → Vue 3

Vue 2 is end of life, so this upgrade is a security item, not just a feature upgrade. Use the @vue/compat migration build to run on the Vue 3 runtime with Vue 2 behavior and migrate breaking changes — createApp, the global API, filters, the event bus, $children — incrementally.

Version upgradeDifficulty: hardEffort: 1–4 weekshigh risk

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

Migrating from Vue 2 to Vue 3 is mandatory for maintained apps because Vue 2 is end of life. There is no intermediate version — the @vue/compat migration build is your bridge: it runs on the Vue 3 runtime with Vue 2 behavior so you can clear breaking changes one category at a time.

Should you upgrade incrementally?

Yes. Vue 2 to Vue 3 is a single major step, but doing it all at once on a large app is risky. The recommended path is to install @vue/compat, alias vue to it so the app runs on the Vue 3 runtime with Vue 2 semantics, and then resolve the deprecation warnings it emits category by category. That keeps the app shippable throughout the migration instead of breaking on day one.

Key differences

App init: `createApp(App)` replaces `new Vue(...)`; global config moves to the app instance.
Global API: Vue.use/Vue.component/Vue.directive and Vue.prototype move onto the app, not the global Vue object.
v-model on custom components changed; multiple v-models are now supported.
Multiple root nodes (fragments) and Teleport are available.
Removed: filters, the global event bus ($on/$off/$once), and `$children`.

Files and patterns to inspect

The entry point (src/main.js / src/main.ts) for `new Vue` and global registrations.
Templates using filters (`{{ value | filter }}`).
Any global event bus and `$on` / `$off` / `$once` usage.
Components reading `$children` and `.sync` modifiers on props.
package.json for vue-router, vuex, @vue/cli-service, and plugins needing Vue 3 releases.

Pre-migration checklist

Green test suite on Vue 2 before starting
Lockfile committed; every plugin checked for a Vue 3-compatible release
A dedicated upgrade branch
@vue/compat installed and vue aliased to it

Filters, the event bus, and $children are removed

Vue 3 removed template filters, the instance event emitter ($on/$off/$once) used for global event buses, and $children. Replace filters with methods or computed properties, swap the event bus for a small emitter like mitt (or props/emit), and reach children via template refs or provide/inject.

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
Migration bridge	n/a	@vue/compat (run Vue 2 behavior on the Vue 3 runtime)

Diagnostic commands

Surface compat warnings to drive the migration

# Install the Vue 3 runtime, compat build, and upgraded ecosystem$ npm install vue@3 @vue/compat@3 vue-router@4 pinia# Run the app and read the @vue/compat deprecation warnings$ npm run dev

Official sources

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: Vue 2 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 (Vue 2 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

Can I skip straight to Vue 3 from Vue 2?

Yes — there is no intermediate version. Vue 2 to Vue 3 is one major hop, and the @vue/compat migration build is the supported way to take it incrementally: run on the Vue 3 runtime with Vue 2 behavior, then clear deprecation warnings category by category.

What happens to my Vuex store and Vue Router setup?

Vue Router 3 upgrades to Vue Router 4, which has its own breaking changes (history mode config and route matching). Vuex 4 supports Vue 3, but the recommended target is Pinia. Migrate them as part of the ecosystem step, after the core createApp switch.