Vue2 Vue3 Migration

Breaking Changes by Category

Global API

• global-api-application-instance - Vue.component -> app.component, createApp
• global-api-treeshaking - Named exports for tree-shaking

Template Directives

• v-model-migration - v-model prop/event changes, v-bind.sync removal
• key-usage-migration - key on v-if/v-for, template v-for key placement
• v-if-v-for-precedence - v-if now has higher precedence
• v-bind-merge-behavior - Order-sensitive bindings
• v-on-native-removed - .native modifier removed

Components

• functional-components-migration - functional attribute removed
• async-components-migration - defineAsyncComponent required
• emits-option - New emits option for event declarations

Render Function

• render-function-api-migration - h globally imported, VNode props flat
• slots-unification - $scopedSlots removed, unified $slots
• listeners-removed - $listeners merged into $attrs
• attrs-includes-class-style - $attrs now includes class/style

Custom Elements

• custom-elements-interop - isCustomElement config, vue: prefix

Removed APIs

• keycode-modifiers-removed - keyCode modifiers removed
• events-api-removed - $on, $off, $once removed
• filters-removed - Filters removed, use computed/methods
• inline-template-removed - inline-template attribute removed
• children-removed - $children instance property removed
• props-data-removed - propsData option removed

Other Minor Changes

• attribute-coercion - Boolean attribute handling changed
• custom-directives-migration - Hook names renamed
• data-option-migration - data must be function, shallow merge
• mount-changes - App no longer replaces mount element
• props-default-this - Props default factory no longer has this
• transition-class-change - v-enter -> v-enter-from
• transition-as-root - Transition root behavior changed
• transition-group-root - No wrapper element by default
• vnode-lifecycle-events - hook: -> vue: prefix
• watch-arrays - Array watch requires deep option

New Features

• fragments - Multi-root component support

Migration Build Flags

When using @vue/compat (migration build), you can enable/disable compatibility features:

import { configureCompat } from 'vue'

// Disable specific compat features
configureCompat({
  COMPONENT_V_MODEL: false,
  FILTERS: false
})

// Or default to Vue 3 behavior with specific compat enabled
configureCompat({
  MODE: 3,
  FEATURE_ID_A: true
})

Common Migration Steps

1. Install Vue 3 and @vue/compat: npm install vue@3 @vue/compat
2. Update build config: Alias vue to @vue/compat
3. Fix breaking changes: Work through warnings systematically
4. Update dependencies: Vue Router 4, Vuex 4/Pinia
5. Switch to standard build: Remove @vue/compat when ready

See Also

• Vue 3 Migration Documentation
• Vue 3 Documentation
• Vue Router Migration
• Pinia State Management
• Vite Build Tool