vue-upgrade-tool

A codemod built on vue-metamorph to upgrade Vue 2 projects to Vue 3.

It will upgrade JS/TS files, SFCs, and unit tests.

Important

Results are not guaranteed to be perfect! You should manually verify every single change this tool made. There are probably edge cases I missed here. Please open a GitHub Issue if you spot something it did wrong, or if it should have transformed/reported on something and didn't!

Note

vue-metamorph does not print well-formatted code when making changes. Use a formatting tool such as eslint or prettier to fix formatting in accordance with your project's code style conventions

Usage

Since the list of manual migrations can be large depending on your project, it's recommended to pipe the output into a file.

npx vue-upgrade-tool --files 'src/**/*' > vue_upgrade_output

To run only some transformations, lookup their IDs in the table below or find them using npx vue-upgrade-tool --list-plugins, then pass them via the --plugins flag using a micromatch pattern. To use multiple micromatch patterns, pass --plugins multiple times:

npx vue-upgrade-tool --files 'src/**/*' --plugins 'vue-*' --plugins 'test-utils-*' > vue_upgrade_output

Vue

Plugin	Plugin Name	Migration Type	Migration Guide
new emits option	vue-emits-sfc / vue-emits-non-sfc	automatic	Link
array watchers should be deep	vue-array-watch	automatic	Link
data option must return a function	vue-data-function	automatic	Link
component options wrapped with defineComponent()	vue-defineComponent	automatic	Link
Vue.delete() / this.$delete() rewritten to delete expression	vue-delete	automatic	Link
remove .native modifier from v-on directives	vue-v-on-native	automatic	Link
remove functional component markers	vue-functional-component	automatic	Link
render function h()	vue-contextual-h	automatic	Link
hook: events renamed to vue:	vue-hook-events	automatic	Link
$nextTick()	vue-nextTick	automatic	Link
$scopedSlots removed	vue-scoped-slots	automatic	Link
Vue.set() removed	vue-set / vue-set-manual	automatic	Link
v-bind:foo.sync becomes v-model:foo	vue-v-bind-sync	automatic	Link
$listeners removed	vue-remove-$listeners / vue-remove-$listeners-manual	automatic / manual	Link
destroyed and beforeDestroy lifecycle hooks renamed	vue-lifecycle-hooks	automatic	Link
v-model updates	vue-v-model	automatic	Link
transition-group no longer renders a root element	vue-transition-group-root-element	automatic	Link
transition props were renamed	vue-transition-props	automatic	Link
is attribute can only be used on a <component> tag	vue-is-attribute	manual	Link
$children removed	vue-$children	manual	Link
v-if / v-for precedence changed	vue-if-for-precedence	manual	Link
vue filters removed	vue-filters	manual	Link
global application instance / app instantiation	vue-globals	manual	Link

Vue Router

Plugin	Plugin Name	Migration Type	Migration Guide
vue-router instantiation changed (WIP)	vue-router-instantiation	automatic	Link
currentRoute.something becomes currentRoute.value.something	not yet implemented	automatic	Link
onReady replaced with isReady	vue-router-onReady	automatic	Link
router.getMatchedComponents() removed	vue-router-getMatchedComponents'	automatic	Link
passing slot content to router-view	vue-router-view-slot-content	automatic	Link
RouteConfig, Location, Route types renamed	not yet implemented	automatic	Link
router.app removed	vue-router-router.app	manual	Link
catch-all routes syntax changed	vue-router-catch-all	manual	Link
append prop in router-link removed	vue-router-link-props	manual	Link
event and tag props in router-link removed	vue-router-link-props	manual	Link
exact prop in router-link removed	vue-router-link-props	manual	Link
router.match() removed	vue-router-match	manual	Link

Vuex

Plugin	Plugin Name	Migration Type	Migration Guide
Store instantiation changed	vuex-instantiation	automatic	Link

Vue Test Utils

Plugin	Plugin Name	Migration Type	Migration Guide
propsData mount option renamed to props	test-utils-propsData	automatic	Link
new global mount option	test-utils-global-mount-options	automatic	Link
wrapper.destroy() renamed to wrapper.unmount()	test-utils-wrapper-destroy	automatic	Link
scopedSlots option merged with slots	test-utils-scoped-slots-mount-option	automatic	Link
createLocalVue removed	test-utils-createLocalVue	manual	Link
Wrapper APIs removed	test-utils-removed-wrapper-apis	manual	Link