Vue 3 Upgrade

Posted on  by admin


Modified7 months ago. I have an existing Vue 3.1 application. Since 3.2 came out I thought about upgrading it, but I can't find any documentation on how I should approach this. Maybe it's super simple and everyone knows how to do this.. Everything I can find talks about upgrading from 2.x to 3.x or just starting from scratch with 3.2. How should I go about going from 3.1 to 3.2.

1414 gold badges5454 silver badges6868 bronze badges. 6868 bronze badges. The Vue team has recently released the highly anticipated migration build for Vue 3. If you’ve been thinking about upgrading your Vue 2 app to Vue 3, this is what you need.

Installing the migration build

The process of upgrading an app to the latest version of the framework can be a daunting task.

This article series is created to make that process easier. The Vue 3 Migrationseries has two parts:. Vue 3 Migration Build (this article).

Vue 3 Migration Changes (the next article). Along with this article, we’ve also created a cheatsheat for the most common changes. The Vue 3.1 migration build is a “special” version of Vue 3 that allows your existing Vue 2 app to run in a Vue 2 mode (or Vue 2-compatible mode).

This Vue 2 mode is part of Vue 3, but its behaviors are almost identical to the regular Vue 2. The main difference is that it will give you warnings whenever your code is using deprecated features (things that are not supported in Vue 3). The migration build is not a tool that automatically rewrites your code to be Vue 3-compatible, you still have to do that yourself manually (for the list of code changes you have to make for Vue 3, check out the Vue 3 Migration Changes article).

The point of the migration build is to provide a “safe” environment where you can incrementally fix your code to make it Vue 3 compatible. Here’s the general workflow of upgrading your app from Vue 2 to Vue 3 using the migration build:. Install Vue 3 and the migration build (called @vue/compat) to your existing Vue 2 app.

Fix the errors caused by using features not compatible with the migration build. I’ll explain this in a bit. After fixing the errors, your Vue 2 app should run just fine. Now we just need to fix the code following to the warnings that the migration build is giving us. And finally, fully switch to Vue 3 by uninstalling the migration build.

About the errors in step 2… The Vue 2 mode in Vue 3 is not fully compatible with a Vue 2 app. There are a few features that are incompatible, and a few features that are partially compatible. (once again, check out the Vue 3 Migration Changes article for more details). To get some hands-on experience with this migration build, we are going to use a simple Vue 2 app as an example, and we’ll upgrade it to Vue 3. This sample app contains things that are no longer supported in Vue 3, so running it with the migration build will definitely give us errors and warnings.


But that’s a good thing because that means the migration build is working, and we just have to fix these errors and warnings, one by one. You can download the sample app from github like this:. The compat-app-starting tag is where the app is running in Vue 2.

There’s another tag compat-app-ending, that’s our finish code where the app is running in Vue 3.

But to follow along this tutorial, we are starting with the compat-app-starting tag. To run the app:. Now, you can check out the app at localhost:8080. The app is very simple. It just renders a heading and a list of numbers. The Pop button will remove a number from the list whenever it’s clicked. If you check out the code at main.js, App.vue, and Heading.vue, it’s using a few features that are deprecated in Vue 3. The way that we’re rendering the root component:. 📁 /src/main.js. The use of watch on an array without the deep option:.

📁 /src/App.vue. The watcher here is watching the items array, and whenever it’s mutated, the handler will get triggered. We’re using it to display a log message to the browser console. The use of a functional component like this:.

  • 📁 /src/components/Heading.vue. Functional component is still allowed in Vue 3, but it uses a different syntax.
  • There are many other Vue 2 features deprecated in Vue 3. The above ones are just used for demonstrations for this tutorial.
  • Next, let’s install the migration build. Since the Vue-CLI is the most common tool people used to create Vue 2 apps, this tutorial will be about upgrading a Vue-CLI app. If you’re using Vite or some other build systems, you can check out the migration build’s GitHub readme for more information.

First, we are going to make sure @vue/cli-service is at its newest version:. (run the above command inside the sample app directory). Next, modify package.json to install Vue 3, the migration build (@vue/compat), and the compiler for single file components (@vue/compiler-sfc).

(We had to remove Vue 2 and vue-template-compiler from package.json because they are no longer needed.). Install the added dependencies:. There’s only one more step to get the migration build working. We have to create a vue.config.js file to set up some compiler options:. 📁 /vue.config.js. (create this file in the root directory). Now, we can restart the development server:. And you should see an error like this:. This just means that the migration build is working!


Next, let’s fix this error. As I said previously, there are features incompatible with the migration build, and they will just give you errors instead of friendly warnings. The source of this particular error is the Heading.vue functional component:.

Uninstalling the migration build

📁 /src/components/Heading.vue. All we need to do is to remove the functional attribute and use msg instead of props.msg:. 📁 /src/components/Heading.vue. Now, the error should be gone. But if you check the browser, you should see a list of warnings in the browser console.

Even with these warnings, the app is fully functional. But to make it Vue 3 compliant, let’s also fix the warnings. Because our app is using some features deprecated in Vue 3, we are getting three warnings:.

One complaining that we can’t use the mount method in main.js. One complaining that we can’t use render in that same file.

And one telling us that we need to add a deep option to the watcher we used in App.vue. We can knock out the first two by initializing the app with createApp:. 📁 /src/main.js. Refresh the app and you should see only one warning left. All we need to do is to add a deep option as instructed by the warning:.

📁 /src/App.vue. If for some reason you can’t change the code at the moment but still want to get rid of the warnings, you can do that by setting the warning configurations. For example, if we didn’t add the deep option to our watcher, we can go to main.js and turn off the warning for this feature:.


📁 /src/main.js. WATCH_ARRAY is a configuration ID for this particular deprecated feature. You can see the full list of IDs of deprecation warnings in the migration build readme.

At this point, our app is fully compatible with Vue 3. So we no longer need the migration build; it has done its job. To make the app run in Vue 3 mode instead of the migration build’s Vue 2 mode, we have to uninstall @vue/compat. Remove it from package.json:. 📃 /package.json. After modifying package.json, we have to run npm install again:. Next, remove the Vue import and the configuration from main.js:. And finally, remove the vue.config.js file that we created earlier. Restart the server:. The app is now running in the actual Vue 3.

Some background around Vue 3

In practice, you’ll probably run into many more errors and warnings than what we’ve seen here in this simple demo. But the workflow is the same: 1) install Vue 3 with the migration build, 2) fix the errors, 3) fix the warnings, and 4) uninstall the migration build. In the next part of this mini-series, we’ll get into the details of all the deprecation warnings that you will most likely run into.

If you are using Vue Router or Vuex, you will have to upgrade both of them to v4. (more details in the next part). Also, Vue 3 is dropping support for IE 11. So if you need to support IE 11, your best option is to wait for the various Vue 3 features to be backported to Vue 2.

The backporting features will be available in Vue 2.7 expected somewhere around 2021Q3. If you’d like to continue learning about transitioning from Vue 2 to Vue 3, check out our full course on that topic. The release of Vue 3 is just around the corner. We can expect a faster, smaller, more maintainable version with a lot of new exciting features.

Fixing the errors

Mostly these are additions and improvements over the existing API.

Nothing is stopping you from starting your new applications with Vue 3. In this article, I'll show you how to get ahead of the curve and start experimenting with the new API by upgrading your application.

If you are interested in an upgraded application, take a look at my TodoMVC application written with the Composition API or the playground that includes every new feature.

  1. I highly recommend using the official CLI for Vue projects. Besides development and deployment tooling, it simplifies the upgrade to a one-line command: vue add vue-next. The Vue Next plugin not only upgrades and installs the new dependencies but modifies the code to be compatible with version three. Installing the plugin upgrades the packages vue, vuex, vue-router, eslint-plugin-vue and @vue/test-utils to the next major version.
  2. Also, a new package named @vue/compiler-sfc appears among the development dependencies.
  3. What is it good for? It compiles the new Vue single file components into runnable Javascript code. Let's look at what has changed in the code.

The first thing you notice is that the main Vue package no longer has a default export. The named export createApp creates a new Vue application as it did with the constructor in Vue 2.

The plugin setup moves to the application instance with the use method instead of the constructor's parameter. The $mount method loses its dollar sign but behaves the same way. As you have seen with the application, plugins adopt the factory pattern: no more constructor with the new keyword.

Instead of calling new Vuex.Store, the createStore factory method is needed. Passing the store's default export as a plugin is no longer possible.

The router plugin follows the same pattern: new VueRouter becomes a call to createRouter, and the global plugin setup must be left. In the new version, you always have to define the type of history. You can choose from createWebHashHistory, createMemoryHistory and createWebHistory. And basically, this is it, the application can be started and runs on the new Vue version.

Everything with a single bash command. Anything else should work with the old syntax, as the old APIs are still intact. If you check the output size of the build command, you can notice a slight drop: 43.75 KiB -> 40.57 KiB. It's the result of leaving the default Vue instance in favor of named exports. Build tools like Webpack and Rollup can do tree-shaking (removing unused code) on named exports, but not on default exports. Without the CLI, you have to upgrade vue-loader or rollup-plugin-vue to the next major version and add the @vue/compiler-sfc package.

Browse other questions tagged vue.jsmigrationvuejs3 or ask your own question.

No more magic here, you have to do everything manually. You have to do code modifications also manually, and there is no tool here that searches the codebase and updates the syntax. If you don't want to modify your project but interested in trying out the new version, just try this online playground.

We've reached the end of the modifications that you have to do during the upgrade process. These modifications are done automatically by the Vue CLI. All you have to do now is to start experimenting with all the new features that Vue 3 offers: the new reactivity system, Composition API, Fragments, Teleport and Suspense.


Vue.js team released Vue 3.0 in September 2020. This new version came with many new features, optimizations, but also comes with a few breaking changes.In June 2021, Vue.js team released the Vue 3.1 version.

This new release comes with @vue/compat (aka "the migration build"). It allows to migrate large projects smoothly by running a Vue 2 codebase along with Vue 3 changes. Migrating to Vue 3 can be an important task (depending on your project's size). At Crisp, we recently migrated our app (250K lines of code) from Vue 2.6 to Vue 3.2 in about 2 weeks.We prepared this migration by reading the official Vue Migration Tutorial, but we discovered many different caveats while migrating our project.We felt it would be good to share our learnings so other companies can benefit from our experience.

Other considerations

This article will tell you:. The major differences between Vue 2 and Vue 3. Dilemmas we've encountered and how we dealt with them. Our Vue.js migration strategy. Created in 2013, Vue.js initial philosophy was to create a minimalistic alternative to AngularJS 1. At the time, Angular was a bulky framework, with a ton of new features. Vue.js first versions were like a mini-angular framework with Templating, Data Binding, Filters and Directives. Vue 2 was then released in 2o16 (almost at the same time as Angular 2), and offered a great alternative to AngularJS.

In fact, many developers using Angular 1 decided to move to Vue 2 because they didn't like Angular 2: Vue 2 was offering something as simple as AngularJS, but with better performances.

Vue 3 was created with performances in mind. It's an evolution rather than a revolution.

Most new features and breaking changes have been released for performance reasons. The internal reactivity system has been reworked from the ground, and for this reason, IE 11 support has been dropped (which is not a huge loss 😂).Finally, this new version is meant to be more modular and introduces features like the Composition API.

The Vue global API has been deprecated. While it is still supported with @vue/compat, reworking your app will be required in order to fully support Vue 3.It means it won't be possible to use APIs like Vue.set or Vue.delete.