Migrating from Vue v.2 to Vue v.3 with a simple example project (2023)

What is Vue.js?

Vue.js is a progressive JavaScript frontend framework written by Evan You. It is one of the most powerful and easy to learn frameworks and has more than 9.5 million downloads per month.

In September 2020, the core of Vue 3 was released. The new version of Vue.js introduces some exciting new features, but also some big changes.

Why should I migrate to Vue3?

As the technology industry evolves, so do libraries, languages, and frameworks. Every version fixes bugs and introduces new features. And often your workflow improves with each major release. New features can give you the ability to do things that were previously tedious.

Vue 3 is still relatively new. You don't have to migrate all your projects, but over time version 2 support might end. Therefore, it's a good idea to know the steps you need to take to migrate your projects.

In this guide, I'll walk you through the basic steps you need to take to tackle the migration. Let's take a simple project and migrate it to Vue 3.

The project we're going to use is intentionally simple so anyone can join in. The more complex your project, the more carefully you should plan your migration.


The new version of Vue.js comes with some big changes and new features. Also, popular libraries like Vue Router have been updated to support the new version of Vue.

If you're already familiar with Vue 2, the basics are the same. But before you can port a project to Vue 3, you need to be aware of a few changes.

Depending on the size of the project being migrated, consider any changes introduced with the new version to ensure your application continues to work after the migration.

In this tutorial, I'll keep things simple and show you how to migrate a Vue.js project currently using the Vue 2 CDN.

I'll take the book project I wrote for freeCodeCamp, which you can findHere.

In this project we used the Vue router, so in this article we will also look at the changes to the Vue router.

What you need to follow along with this article

To continue, you need a basic understanding of Vue.js and the Vue Router. If you don't have that. then I suggest that you start reviewing my book which is available atfreeCodeCamp.

You can also find the full 8-hour course playlist for free on myYouTube-Kanal.

What we will cover in this article

This tutorial is divided into three main chapters. First, let's look at the changes in Vue.js v3.x, then give a quick overview of Vue Router v4.x. And finally, we start planning the migration of a real project.

  • Vue v3.x overview
    • breaking changes
  • Vue Router v4.x overview
    • breaking changes
  • Migration of portfolio projects
    • Clone the repository
    • Update CDN scripts
    • Update Vue instance
    • Update the Vue router instance

Here's the video version of this article if you want to follow along:

(Video) How to Upgrade Vue 2 to Vue 3

Watching the video will help you solidify your learning as you read through the steps below. You can find the finale hereRepositoryFor the project.

Vue v3.x overview

Vue 3 introduces some new features and a bunch of big changes. Let's see how these changes affect our application and consider them before migration.

Important changes compared to Vue V3.x

In Vue 3, breaking changes generally fall into seven categories:

  • Global APIs
    (responsible for Vue's behavior): You most likely want to see these changes.
  • The Template Directive
    (Changes to how v-directives work): You'll probably want to see these changes.
  • components
    (Changes to how components work): If your app uses components, you most likely want to see these changes.
  • Render function (allows you to create HTML elements programmatically)
  • Custom Elements (tells Vue about creating custom HTML elements)
  • Minor changes (these may not affect you, but you should investigate them anyway)
  • Removed APIs (stuff no longer available in Vue 3)

Among all the changes, there are some that every application will use, such as: B. the global API and components. So you need to keep them in mind if you want to use the new version of Vue.

And the following additional changes are worth noting:

  • The way you create Vue apps and component instances has changed (Global API)
  • You should always declare the data option as a function (minor change)
  • Changing the priority when using v-if and v-for on the same element (template addresses)
  • You must declare an output option for component events (components).

For a full list of changes seeDocumentation

Now let's take a closer look at some of these changes.

How to instantiate applications and components in Vue 3

In Vue 3, the way of building an app has changed. The Vue app is now using the new.createApp()Method for creating application instances.

The Vue app is now considered a root component, so the way you define its data options has also changed.

The HTML root element hasn't changed, so in an index.html file you'll still see something like this:

<div id="application"></div>

There is one important change within the JavaScript file that you should understand: you will no longer use itnew view()to create a new application instance, but a new called method is used insteadcreate app ():

// Vue 3 Application syntaxconst = Vue.createApp({ // options object})app.mounth('#app') // Vue Instance - Root Component // Vue 2 Application syntaxconst = new Vue({ // object of options die Anwendung'})

How to define a component in Vue 3

To define a component in Vue 3, use no moreview.component(). Instead, it now uses the root component of the application like this:

/* Vue 3-Syntax */const app = Vue.createApp({ // Options here})app.component('componentet-name', { // Component code here})/* Vue 2-Syntax*/Vue .component ('componentname', { // component code here })

How to use data option object in Vue 3

Because the main application instance is now considered the root component, you can no longer specify the data property as an object. Instead, you should define it as a function that returns an object, as you normally do in components.

// Vue 3const app = Vue.createApp({ // options object data(){ return {message: 'hello' } }})app.mounth('#app') // Vue Instance - Root Component/ / Vue 2 syntaxconst app = new Vue({ // options object el: '#app' data: { message: 'hello' }})

Change precedence for v-if/v-for in Vue 3

In Vue 2, if you used both directives on the same element, the v-for directive takes precedence over v-if . But in Vue 3, v-si always takes precedence.

However, it's not a good idea to use both directives. Be sure to visit the documentation.HereLearn more.

(Video) Vue JS tutorial create project - Dependency Wheel 1/10

How to use Emits property for component events in Vue 3 (recent change/new feature)

Similar aAccesoriesproperty, now in Vue 3 there is one toooutputproperty that allows a component to declare events that it can emit to the parent component.

I highly recommend using this property to avoid emitting events twice in components that need to re-emit native events, e.g. a click event.

Here is an example from the official documentation:

<template> <div> <p>{{ text }}</p> <button v-on:click="$emit('accepted')">OK</button> </div></template>< script> export default { props: ['text'], output: ['accepted'] }</script>

The emits property can also take an object.

I won't get into that yet, but I'll cover each of the features/changes in a dedicated video series sooner or later, I promise.

Vue Router v4.x overview

With the new version of Vue.js we also have a new version of Vue Router. The new version v4.x comes with some important changes that you need to take into account if you want to migrate a project to the new version of Vue.

Important changes in Vue Router V4

Two key changes are particularly noteworthy as they form the core of a Vue router application. You need to know them to migrate your application later.

  • Vue Router instance has changed
  • There is a new history option.

The full list of changes is available.Here.

Let's take a closer look at these two changes.

Vue Router 4 instance has changed

To create a new Vue Router instance, you no longer use the VueRuter function constructor.

Here is the vue router v.3xDocumentationso you can compare.

The code changes from this:

// 3. Create the router instance and pass the `routes` option // You can pass additional options here, but let's // keep it simple for now. const router = new VueRouter({routes // short for `routes: route`}) // 4. Create and mount the root instance. // Be sure to inject the router with the router option to inject the // Make application fully compatible with router.const app = new Vue({ router}).$ mount('#app')

In addition:

// 3. Create the router instance and pass the "routes" option // You can pass additional options here, but let's keep it simple for now. const router = VueRouter.createRouter({ // 4. Specify the implementation history to use. For simplicity, we use hash history here: VueRouter.createWebHashHistory(), // <-- this is a new property and it is required !routes, // short for `routes:routes`}) // 5. Create and mount the root instance. const app = Vue.createApp({}) // Make sure you _use_ the router instance so the whole app is compatible with router.app.use(router)app.mount('#app ') .

To create a new VueRouter instance in the code above, you now need to use and invoke the VueRouter objectcreate routers ()Method.

The new history property is also required:historial: VueRouter.createWebHashHistory(). You must define it or you will get a console error.

(Video) Vue 3 - What's New? What Changed?

Next, create the Vue instance with thecreate app ()Method and usage variableApplicationcall to.use()Method. There you pass the instance of the router that you created in the previous step.

Finally, you can mount the root DOM element with the application instanceapp.mount('#app').

Can read vue-router v4.xDocumentationfor more details.

How to migrate a portfolio project from Vue 2 to Vue 3

You can see how it works in the videoYoutubeif you wanna keep going

Keeping all of the above in mind and after carefully reviewing all the major changes, let's try to update one of our projects, my Vue course. I will use the portfolio, the final project of the course.

We will have to:

  • Clone the repository
  • Update CDN scripts
  • Update Vue instance
  • Update the Vue router instance

In any case, in order to migrate our application to Vue 3, we need to update the following:

  • Vue Application Instance
  • view-router-instance
  • CDN-Links

Let's do it step by step.

Clone the project repository

First, make sure you clone the repository in the current folder:

Git-Clone https://bitbucket.org/fbhood/view-folio/src/master/view-folio

Since our project is still using CDN, the next step is to update your links.

Update the project CDN

In our project we use both Vue CDN and Vue Router CDN, so we update both.

Open the index.html file and replace it:

<!-- VueJS 3 Production Version --> <script src="https://cdn.jsdelivr.net/npm/vue@2.6.12"></script> <!-- Vue Router --> <script src ="https://unpkg.com/vue-router@2.0.0/dist/vue-router.js"></script>

with this:

<!-- VueJS 3 --> <script src="https://unpkg.com/vue@3"></script> <!-- Vue Router --> <script src="https://unpkg .com/vue-router@4"></script>


Now if you open the project with the live server and open the inspector, you will notice that the app doesn't show up and there are two errors in the console. Both seem to be related to the Vue router:

You are running a development build of Vue. Make sure to use the production build (*.prod.js) when deploying to production. Uncaught TypeError: window.Vue.use is not a function in vue-router.js:1832 in vue -router.js:9 in vue-router.js:10 Uncaught Reference Error: VueRouter is not defined in main.js :185

Vue router? Why?

(Video) Vue 3 Tutorial for Beginners - FULL COURSE in 3 Hours

Keep in mind that when Vue was rewritten, its libraries also had to update their codebases. So don't forget about these important changes related to the Vue router since our application uses it.

First, let's update the main instance of Vue to use the new syntax. Then we will see what changes we need to make to make Vue Router work.

Update this code in the main.js file from here:

// Create and mount Vue application instanceconst = new Vue({router}).$mount('#app')

in addition:

// Create and mount Vue application instanceconst = Vue.createApp({router})app.mount('#app')

Show changes in router 4

Above we saw the new syntax for defining Vue's root instance component. But now that we're using the Vue router, we need to take that into accountradical changesAlso.

The way the Vue router instance is created has changed

Changed from this:

// crea el router instanciaconst router = new VueRouter({routes})

in addition:

// create the router instanceconst router = VueRouter.createRouter({ // Specify the history implementation to use. We use hash history here for simplicity `})

The code above takes care of two important changes:new VueRouter()was replaced byVueRouter.createRouter(), and the newStoryOption replaces nowAway.

Visit theDocumentationfor Vue Router 4 for more information.

Finally, let's tell our app that we're using the Vue Router. When we inject the router instance into the Vue application, we now need to tell it to use the Vue router, use the.use()to do this and pass the router instance to it.

change of this:

// Create and mount Vue application instanceconst = Vue.createApp({router})app.mount('#app')

in addition:

// Create and mount Vue application instanceconst = Vue.createApp({})app.use(router)app.mount('#app')

And there you have it!


It doesn't matter how complex your Vue application is - if you're looking to migrate to a new major release, you still need to plan, read the release notes, and review any major changes to make sure you understand it's going to break.

The more complex the application, the more carefully you need to plan your migration.

(Video) Vue.js Course for Beginners [2021 Tutorial]

For our simple app, that's all. But it's not always like that. So be prepared and plan ahead.

If you enjoyed this guide, please share the article and remember to subscribe to mineYouTube-Kanal. Thank you for reading!


How do I move from Vue 2 to Vue 3? ›

‍Install Vue's Migration Build
  1. Update vue to its latest version;
  2. Install @vue/compat in the same version as vue;
  3. Replace vue-template-compiler (if present) with @vue/compiler-sfc in the same version as vue.
Nov 7, 2022

What is the major difference between Vue 2 and Vue 3? ›

What's the difference between Vue 2 and Vue 3? # Vue 3 is the current, latest major version of Vue. It contains new features that are not present in Vue 2, such as Teleport, Suspense, and multiple root elements per template.

Should you migrate to Vue 3? ›

Should I learn Vue 2 or Vue 3 in 2022? Most of the syntax and practices in Vue 2 remain the same in Vue 3, so it shouldn't make a big difference if you learn Vue 2 or Vue 3. Most libraries now support Vue 3 and we are also expecting a compatibility version of Vue 3 to be launched soon.

Can you mix Vue 2 and 3? ›

Vue2 components can be used with Vue3 and Vue3 components can be used in Vue2.

Should I use Vue 2 or Vue3? ›

If you are facing performance issues after doing various optimizations, then use Vue 3. This is written from scratch and offers better performance than its previous version. If you need better TypeScript compatibility use Vue 3, it's much better than before!

What is the difference between Vue 2 and Vue 3 create app? ›

What is the difference between Vue 2 and Vue 3?
  • Components becoming less readable and, consequently, less maintainable as they grow larger.
  • Bottlenecks created by Vue 2's available code reusability patterns.
  • Larger bundle size, as Vue 3 allows for tree shaking.
Sep 25, 2021

Why Vue 3 is faster than Vue 2? ›

> Vue 3 has demonstrated significant performance improvements over Vue 2 in terms of bundle size (up to 41% lighter with tree-shaking), initial render (up to 55% faster), updates (up to 133% faster), and memory usage (up to 120% less). What does 120% less memory usage mean, really?

What are new features in Vue 3? ›

Also, It comes with exciting new sub-projects & updations as below,
  • Blazing fast, Vite-powered build toolchain.
  • More ergonomic Composition API syntax via <script setup>
  • Improved TypeScript IDE support for Single File Components via Volar.
  • Command-line type checking for SFCs via vue-tsc.
  • Simpler state management via Pinia.
Apr 9, 2022

Is Vue 3 ready production? ›

You can start your new production projects with Vue 3 - the core and subprojects are ready to use. Keep in mind that the ecosystem is still evolving, so some open-source components may not yet available in Vue 3 versions.

How do I upgrade Vue CLI 2 to 3? ›

Migrate from Vue Cli 2 to 3
  1. Install the Vue Cli 3 with npm install -g @vue/cli.
  2. Create a new project with vue create myapp-cli3.
  3. Copy the content of src folder from old app to new app.
  4. Create aliases. config. js in the root folder, content (to enable the @ as src root):
Aug 15, 2018

How do I switch between Vue components? ›

Swap components without using Vue-Router is that easy. By using v-bind:is you can easily swap and access other components. Resources are: Vue.

How do I get Vue 3? ›

How to learn Vue 3
  1. Watch through Vue Mastery's free Intro to Vue 3 Course.
  2. Code along with the course, using the CDN <script src="https://unpkg.com/vue@next"></script>
  3. Try installing Vue 3 using the CLI. See below for the instructions.
  4. Take a read through the official docs.
Sep 21, 2020

How do I change my Vue version? ›

How to update vue-cli to latest version?
  1. Uninstall old vue-cli version.
  2. Install latest version of vue/cli.
  3. Update vue-cli to latest version (v3 or v4)


1. Vue JS 2 Tutorial #12 - Looping with v-for
(The Net Ninja)
2. Vue JS Crash Course
(Traversy Media)
3. Vue 3 Animations Tutorial #2 - Starter Project Walkthrough
(The Net Ninja)
4. Vue JS 3 Tutorial for Beginners #2 - Vue.js Basics (part 1)
(The Net Ninja)
5. Vuejs Tutorial #8 - Vue Router
6. Vue JS 3 Tutorial for Beginners #8 - The Vue Router
(The Net Ninja)
Top Articles
Latest Posts
Article information

Author: Dong Thiel

Last Updated: 02/26/2023

Views: 6658

Rating: 4.9 / 5 (59 voted)

Reviews: 82% of readers found this page helpful

Author information

Name: Dong Thiel

Birthday: 2001-07-14

Address: 2865 Kasha Unions, West Corrinne, AK 05708-1071

Phone: +3512198379449

Job: Design Planner

Hobby: Graffiti, Foreign language learning, Gambling, Metalworking, Rowing, Sculling, Sewing

Introduction: My name is Dong Thiel, I am a brainy, happy, tasty, lively, splendid, talented, cooperative person who loves writing and wants to share my knowledge and understanding with you.