Upgrading your Vue 2 application to Vue 3

Upgrading your project from Vue 2 to Vue 3 can sometimes be done automatically, but in other cases, this needs to be done manually. This depends on how deep into the use of the Vue API you go with your application.

With projects made and managed by Vue-CLI, this process will be made seamlessly and will have a more straightforward approach compared to projects using a custom framework wrapper CLI.

In this recipe, you will learn how to upgrade your application using Vue-CLI and how to upgrade the project and the dependencies manually.

Getting ready

• Node.js 12+

The Node.js global objects that are required are as follows:

• @vue/cli
• @vue/cli-service-global

How to do it...

In order to upgrade your Vue 2 project to Vue 3, you will have to split the upgrade into different parts. We have the upgrade of the framework itself, and then we have the ecosystem components, such as vue-router and vuex, and finally, the bundler that joins everything in the end.

Using Vue-CLI to upgrade the project

Using the latest version of Vue-CLI, you will be able to use Vue 3 in your project, out of the box, and you will be able to update your current project to Vue 3.

To update Vue-CLI to the latest version, you need to open Terminal (macOS or Linux) or Command Prompt/PowerShell (Windows) and execute the following command:

> npm install @vue/cli-service@latest

Upgrading the project manually

To upgrade the project manually, you will have to first upgrade the project dependencies to their latest versions. You cannot use an old version of a Vue ecosystem plugin with Vue 3. To do this, perform the following steps:

1. We need to upgrade the Vue framework, the ESLint plugin (which Vue depends on), and the vue-loader for the bundler. To upgrade it, you need to open Terminal (macOS or Linux) or Command Prompt/PowerShell (Windows) and execute the following command:

> npm install vue@next eslint-plugin-vue@next vue-loader@next

1. We need to add the new Vue single-file component compiler as a dependency to the project. To install it, you need to open Terminal (macOS or Linux) or Command Prompt/PowerShell (Windows) and execute the following command:

> npm install @vue/compiler-sfc@latest

1. If you are using unit tests and the @vue/test-utils package on your project, you will also need to upgrade this dependency. To upgrade it, you need to open Terminal (macOS or Linux) or Command Prompt/PowerShell (Windows) and execute the following command:

> npm install @vue/test-utils@next @vue/server-test-utils@latest

1. For the Vue ecosystem plugins, if you are using vue-router, you will need to upgrade this too. To upgrade it, you need to open Terminal (macOS or Linux) or Command Prompt/PowerShell (Windows) and execute the following command:

> npm install vue-router@next

1. If your application is using vuex as the default state management, you will need to upgrade this too. To upgrade it, you need to open Terminal (macOS or Linux) or Command Prompt/PowerShell (Windows) and execute the following command:

> npm install vuex@next

Changing the starting files

With the new version of the packages, we will need to change our starting files. In a Vue project that was created with the Vue-CLI starter kit, you will find a file named main.js or main.ts. If you are using TypeScript, this file is located in the src folder. Now follow these instructions:

1. Open the main.js file in the src folder of your project. At the top of the file, where the packages are imported, you will see the following code:

import Vue from 'vue';

We need to change this to the new Vue exposed API method. To do this, we need to import createApp from the Vue package as follows:

import { createApp } from 'vue';

1. Remove the global Vue static attribute definition of Vue.config.productionTip from your code.
2. The mounting function of your application needs to be changed. The old API will look like this:

new Vue({
  router,
  store,
  render: (h) => h(App),
}).$mount('#app');

The old API should be changed to the new createApp API, as follows:

createApp(App)
  .use(router)
  .use(store)
  .mount('#app')

1. Open your vuex store instantiation file (normally, this file is located in src/store and is named store.js or index.js).
2. Change the creation of the store from the instantiation of a new vuex class to the new createStore API. The vuex v3 class instantiation may look like this:

import Vue from 'vue';
import Vuex from 'vuex';

Vue.use(Vuex);

export default new Vuex.Store({
  state: { /* ... */ },
  mutations: { /* ... */ },
  actions: { /* ... */ },
  getters: { /* ... */ },
  modules: { /* ... */ },
});

You need to replace its content with the createStore API, which could look like this, for example:

import { createStore } from 'vuex';

export default createStore({
  state: { /* ... */ },
  mutations: { /* ... */ },
  actions: { /* ... */ },
  getters: { /* ... */ },
  modules: { /* ... */ },
});

1. In the vue-router ecosystem, we will need to replace the old API from the router creation with the new one. To do this, open the router creation file (in the src/router folder, normally named router.js or index.js).
2. Finally, in the creation file, replace the old vue-router class instantiation with the new createRouter API. The vue-router v3 class instantiation may look like this:

import Vue from 'vue';
import VueRouter from 'vue-router';

Vue.use(VueRouter);

export default new VueRouter({
  routes: [{
    path: '/',
    name: 'HomePage',
    component: () => import('pages/home'),
  }]
});

You will also need to replace the new VueRouter instantiation with the new createRouter and createWebHistory API, as in this example:

import {
  createRouter,
  createWebHistory,
} from 'vue-router';

Vue.use(VueRouter);

export default createRouter({
  history: createWebHistory(),
  routes: [{
    path: '/',
    name: 'HomePage',
    component: () => import('pages/home'),
  }]
});

How it works...

In the upgrading process, Vue has provided us with two ways to update our project. The first way is to use the Vue-CLI plugin, which tries to automate almost all the processes and changes needed for the upgrade.

The second way is to upgrade the project manually. This method requires the developer to upgrade all the dependencies to the latest version, install the new single-file component compiler, @vue/compiler-sfc, and change the entry files for the Vue application, router, and store to the new API.

Following the changes to the starter structure of the project, the developer needs to check the components to see whether there are any Vue 3 breaking changes present, refactor the component to the new Vue 3 APIs, and remove the deprecated APIs from Vue 2.