@vue/compat
(aka "the migration build") is a build of Vue 3 that provides configurable Vue 2 compatible behavior.
The migration build runs in Vue 2 mode by default - most public APIs behave exactly like Vue 2, with only a few exceptions. Usage of features that have changed or been deprecated in Vue 3 will emit runtime warnings. A feature's compatibility can also be enabled/disabled on a per-component basis.
While we've tried hard to make the migration build mimic Vue 2 behavior as much as possible, there are some limitations that may prevent your app from being eligible for upgrading:
Dependencies that rely on Vue 2 internal APIs or undocumented behavior. The most common case is usage of private properties on VNodes
. If your project relies on component libraries like Vuetify (opens new window), Quasar (opens new window) or ElementUI (opens new window), it is best to wait for their Vue 3 compatible versions.
Internet Explorer 11 support: Vue 3 has officially dropped the plan for IE11 support (opens new window). If you still need to support IE11 or below, you will have to stay on Vue 2.
Server-side rendering: the migration build can be used for SSR, but migrating a custom SSR setup is much more involved. The general idea is replacing vue-server-renderer
with @vue/server-renderer
(opens new window). Vue 3 no longer provides a bundle renderer and it is recommended to use Vue 3 SSR with Vite (opens new window). If you are using Nuxt.js (opens new window), you can try Nuxt Bridge, a Nuxt.js 2 to 3 compatibility layer (opens new window). For complex, production projects, it is probably best to wait for Nuxt 3 (currently in beta) (opens new window).
Please note that the migration build aims to cover only publicly documented Vue 2 APIs and behavior. If your application fails to run under the migration build due to reliance on undocumented behavior, it is unlikely that we'll tweak the migration build to cater to your specific case. Consider refactoring to remove reliance on the behavior in question instead.
A word of caution: if your application is large and complex, migration will likely be a challenge even with the migration build. If your app is unfortunately not suitable for upgrade, do note that we are planning to backport Composition API and some other Vue 3 features to the 2.7 release (estimated late Q3 2021).
If you do get your app running on the migration build, you can ship it to production before the migration is complete. Although there is a small performance/size overhead, it should not noticeably affect production UX. You may have to do so when you have dependencies that rely on Vue 2 behavior, and cannot be upgraded/replaced.
The migration build will be provided starting with 3.1, and will continue to be published alongside the 3.2 release line. We do plan to eventually stop publishing the migration build in a future minor version (no earlier than EOY 2021), so you should still aim to switch to the standard build before then.
The following workflow walks through the steps of migrating an actual Vue 2 app (Vue HackerNews 2.0) to Vue 3. The full commits can be found here (opens new window). Note that the actual steps required for your project may vary, and these steps should be treated as general guidance rather than strict instructions.
Upgrade tooling if applicable.
vue-loader
to ^16.0.0
.vue-cli
: upgrade to the latest @vue/cli-service
with vue upgrade
In package.json
, update vue
to 3.1, install @vue/compat
of the same version, and replace vue-template-compiler
(if present) with @vue/compiler-sfc
:
"dependencies": { - "vue": "^2.6.12", + "vue": "^3.1.0", + "@vue/compat": "^3.1.0" ... }, "devDependencies": { - "vue-template-compiler": "^2.6.12" + "@vue/compiler-sfc": "^3.1.0" }
In the build setup, alias vue
to @vue/compat
and enable compat mode via Vue compiler options.
Example Configs
// vue.config.js module.exports = { chainWebpack: config => { config.resolve.alias.set('vue', '@vue/compat') config.module .rule('vue') .use('vue-loader') .tap(options => { return { ...options, compilerOptions: { compatConfig: { MODE: 2 } } } }) } }
// webpack.config.js module.exports = { resolve: { alias: { vue: '@vue/compat' } }, module: { rules: [ { test: /\.vue$/, loader: 'vue-loader', options: { compilerOptions: { compatConfig: { MODE: 2 } } } } ] } }
// vite.config.js export default { resolve: { alias: { vue: '@vue/compat' } }, plugins: [ vue({ template: { compilerOptions: { compatConfig: { MODE: 2 } } } }) ] }
If you are using TypeScript, you will also need to modify vue
's typing to expose the default export (which is no longer present in Vue 3) by adding a *.d.ts
file with the following:
declare module 'vue' { import { CompatVue } from '@vue/runtime-dom' const Vue: CompatVue export default Vue export * from '@vue/runtime-dom' }
At this point, your application may encounter some compile-time errors / warnings (e.g. use of filters). Fix them first. If all compiler warnings are gone, you can also set the compiler to Vue 3 mode.
After fixing the errors, the app should be able to run if it is not subject to the limitations mentioned above.
You will likely see a LOT of warnings from both the command line and the browser console. Here are some general tips:
You can filter for specific warnings in the browser console. It's a good idea to use the filter and focus on fixing one item at a time. You can also use negated filters like -GLOBAL_MOUNT
.
You can suppress specific deprecations via compat configuration.
Some warnings may be caused by a dependency that you use (e.g. vue-router
). You can check this from the warning's component trace or stack trace (expanded on click). Focus on fixing the warnings that originate from your own source code first.
If you are using vue-router
, note <transition>
and <keep-alive>
will not work with <router-view>
until you upgrade to vue-router
v4.
Update <transition>
class names. This is the only feature that does not have a runtime warning. You can do a project-wide search for .*-enter
and .*-leave
CSS class names.
Update app entry to use new global mounting API.
Upgrade vue-router
to v4 (opens new window). If you also use vuex-router-sync
, you can replace it with a store getter.
After the upgrade, to use <transition>
and <keep-alive>
with <router-view>
requires using the new scoped-slot based syntax (opens new window).
Pick off individual warnings. Note some features have conflicting behavior between Vue 2 and Vue 3 - for example, the render function API, or the functional component vs. async component change. To migrate to Vue 3 API without affecting the rest of the application, you can opt-in to Vue 3 behavior on a per-component basis with the compatConfig
option.
When all warnings are fixed, you can remove the migration build and switch to Vue 3 proper. Note you may not be able to do so if you still have dependencies that rely on Vue 2 behavior.
Compat features can be disabled individually:
import { configureCompat } from 'vue' // disable compat for certain features configureCompat({ FEATURE_ID_A: false, FEATURE_ID_B: false })
Alternatively, the entire application can default to Vue 3 behavior, with only certain compat features enabled:
import { configureCompat } from 'vue' // default everything to Vue 3 behavior, and only enable compat // for certain features configureCompat({ MODE: 3, FEATURE_ID_A: true, FEATURE_ID_B: true })
A component can use the compatConfig
option, which expects the same options as the global configureCompat
method:
export default { compatConfig: { MODE: 3, // opt-in to Vue 3 behavior for this component only FEATURE_ID_A: true // features can also be toggled at component level } // ... }
Features that start with COMPILER_
are compiler-specific: if you are using the full build (with in-browser compiler), they can be configured at runtime. However if using a build setup, they must be configured via the compilerOptions
in the build config instead (see example configs above).
Should be fixed upfront or will likely lead to errors
ID | Type | Description | Docs |
---|---|---|---|
GLOBAL_MOUNT_CONTAINER | ⨂ | Mounted application does not replace the element it's mounted to | link |
CONFIG_DEVTOOLS | ⨂ | production devtools is now a build-time flag | link (opens new window) |
COMPILER_V_IF_V_FOR_PRECEDENCE | ⨂ |
v-if and v-for precedence when used on the same element has changed | link |
COMPILER_V_IF_SAME_KEY | ⨂ |
v-if branches can no longer have the same key | link |
COMPILER_V_FOR_TEMPLATE_KEY_PLACEMENT | ⨂ |
<template v-for> key should now be placed on <template>
| link |
COMPILER_SFC_FUNCTIONAL | ⨂ |
<template functional> is no longer supported in SFCs | link |
ID | Type | Description | Docs |
---|---|---|---|
CONFIG_IGNORED_ELEMENTS | ◐ |
config.ignoredElements is now config.compilerOptions.isCustomElement (only in browser compiler build). If using build setup, isCustomElement must be passed via build configuration. | link |
COMPILER_INLINE_TEMPLATE | ◐ |
inline-template removed (compat only supported in browser compiler build) | link |
PROPS_DEFAULT_THIS | ◐ | props default factory no longer have access to this (in compat mode, this is not a real instance - it only exposes props, $options and injections) | link |
INSTANCE_DESTROY | ◐ |
$destroy instance method removed (in compat mode, only supported on root instance) | |
GLOBAL_PRIVATE_UTIL | ◐ |
Vue.util is private and no longer available | |
CONFIG_PRODUCTION_TIP | ◐ |
config.productionTip no longer necessary | link |
CONFIG_SILENT | ◐ |
config.silent removed |
ID | Type | Description | Docs |
---|---|---|---|
TRANSITION_CLASSES | ⭘ | Transition enter/leave classes changed | link |
ID | Type | Description | Docs |
---|---|---|---|
GLOBAL_MOUNT | ✔ | new Vue() -> createApp | link |
GLOBAL_EXTEND | ✔ | Vue.extend removed (use defineComponent or extends option) | link |
GLOBAL_PROTOTYPE | ✔ |
Vue.prototype -> app.config.globalProperties
| link |
GLOBAL_SET | ✔ |
Vue.set removed (no longer needed) | |
GLOBAL_DELETE | ✔ |
Vue.delete removed (no longer needed) | |
GLOBAL_OBSERVABLE | ✔ |
Vue.observable removed (use reactive ) | link |
CONFIG_KEY_CODES | ✔ | config.keyCodes removed | link |
CONFIG_WHITESPACE | ✔ | In Vue 3 whitespace defaults to "condense"
| |
INSTANCE_SET | ✔ |
vm.$set removed (no longer needed) | |
INSTANCE_DELETE | ✔ |
vm.$delete removed (no longer needed) | |
INSTANCE_EVENT_EMITTER | ✔ |
vm.$on , vm.$off , vm.$once removed | link |
INSTANCE_EVENT_HOOKS | ✔ | Instance no longer emits hook:x events | link |
INSTANCE_CHILDREN | ✔ |
vm.$children removed | link |
INSTANCE_LISTENERS | ✔ |
vm.$listeners removed | link |
INSTANCE_SCOPED_SLOTS | ✔ |
vm.$scopedSlots removed; vm.$slots now exposes functions | link |
INSTANCE_ATTRS_CLASS_STYLE | ✔ |
$attrs now includes class and style
| link |
OPTIONS_DATA_FN | ✔ |
data must be a function in all cases | link |
OPTIONS_DATA_MERGE | ✔ |
data from mixin or extension is now shallow merged | link |
OPTIONS_BEFORE_DESTROY | ✔ |
beforeDestroy -> beforeUnmount
| |
OPTIONS_DESTROYED | ✔ |
destroyed -> unmounted
| |
WATCH_ARRAY | ✔ | watching an array no longer triggers on mutation unless deep | link |
V_FOR_REF | ✔ |
ref inside v-for no longer registers array of refs | link |
V_ON_KEYCODE_MODIFIER | ✔ |
v-on no longer supports keyCode modifiers | link |
CUSTOM_DIR | ✔ | Custom directive hook names changed | link |
ATTR_FALSE_VALUE | ✔ | No longer removes attribute if binding value is boolean false
| link |
ATTR_ENUMERATED_COERCION | ✔ | No longer special case enumerated attributes | link |
TRANSITION_GROUP_ROOT | ✔ |
<transition-group> no longer renders a root element by default | link |
COMPONENT_ASYNC | ✔ | Async component API changed (now requires defineAsyncComponent ) | link |
COMPONENT_FUNCTIONAL | ✔ | Functional component API changed (now must be plain functions) | link |
COMPONENT_V_MODEL | ✔ | Component v-model reworked | link |
RENDER_FUNCTION | ✔ | Render function API changed | link |
FILTERS | ✔ | Filters removed (this option affects only runtime filter APIs) | link |
COMPILER_IS_ON_ELEMENT | ✔ |
is usage is now restricted to <component> only | link |
COMPILER_V_BIND_SYNC | ✔ |
v-bind.sync replaced by v-model with arguments | link |
COMPILER_V_BIND_PROP | ✔ |
v-bind.prop modifier removed | |
COMPILER_V_BIND_OBJECT_ORDER | ✔ |
v-bind="object" is now order sensitive | link |
COMPILER_V_ON_NATIVE | ✔ |
v-on.native modifier removed | link |
COMPILER_V_FOR_REF | ✔ |
ref in v-for (compiler support) | |
COMPILER_NATIVE_TEMPLATE | ✔ |
<template> with no special directives now renders as native element | |
COMPILER_FILTERS | ✔ | filters (compiler support) |
© 2013–present Yuxi Evan You
Licensed under the MIT License.
https://v3.vuejs.org/guide/migration/migration-build.html