We have been using the new Composition API with Vue 2 for some time now and recently experimented with porting some projects to Vue 3. However we have a significant issue with the changes to reactivity in Vue 3. The fundamental issue we have with the re-write of reactivity in Vue 3 is that changes to raw objects are not tracked - only changes to the proxies generated by ref/reactive are now tracked.
This means the same code in Vue 2 with Compoistion API does not work the same in Vue 3. With Vue 2 reactivity, it was an excellent feature that you could have objects created by business logic shared between Vue components and when the business logic changed properties of these objects, the UI reacted accordingly.
How to Migrate a Portfolio Project from Vue 2 to Vue 3
However, with Vue 3, this no longer works unless you generate a proxy using ref/reactive in the UI code and somehow pass that proxy back to the business logic layer (or get Vue to wrap the object in a proxy within the business logic code which is otherwise independent/unaware of Vue). As a simple example, the following Vue component works completely differently in Vue 2 and Vue 3. In Vue 2, the raw object used to create the two refs and the reactive object can be manipulated and everything reacts including both watches as can be seen by clicking the first button. In Vue 3, manipulating the raw object does change the value in the proxies but none of the reactivity works including the raw watch.
However, modifying either of the refs or the reactive object works the same as with Vue 2. For me, this is a big backwards step because essentially with Vue 3, only objects within the UI code can be reactive - objects from non-UI code (business logic) cannot be updated outside of the UI without polluting the non-UI code. In addition, we have found that the proxy mechanism used by Vue 3 reactivity can break business logic objects that themselves already had some form of proxying whereas Vue.Observable from Vue 2 worked and didn’t break anything.
In particular, we have projects using BreezeJS which creates entity objects for records in a database and these entity objects break when made reactive by Vue 3 and are no longer able to track property changes themselves (i.e. they only work if the properties are changed on the raw unproxied objects).
Why should I migrate to Vue3?
The new Vue.js release introduces some cool new features but also some breaking changes.
- As the tech industry evolves, so do libraries, languages, and frameworks.
- At each release, bugs are fixed and new features introduced.
- And often with any major release, your workflow is enhanced.
New features can give you the opportunity to do things that were tedious before. Vue 3 is still relatively new. You don't have to migrate all your projects over, but as time goes by, support for version 2 might end. Because of this it's a good idea to know the steps you'll need to take to migrate your projects. In this guide, I'll walk you through the basic steps you will need to follow to approach the migration. We will take a simple project and migrate it to Vue 3.
The project that we will use is intentionally simple, and so anyone can follow along. The more complex your project is, the more carefully you'll want to plan for the migration. The new Vue.js version does come with quite a few breaking changes and new features. Also, popular libraries like Vue Router have been updated to support the new Vue version.
If you already know Vue 2, the basics are quite the same.
But before you can migrate a project to Vue 3 there are changes you need to take into account.
- Depending on the size of the project you want to migrate, make sure to consider all the changes introduced with the new release so that your application will still work after the migration.
- For this tutorial, I'll keep things simple and show you how to migrate a Vue.js project that currently uses the Vue 2 CDN.
- I'm taking the project from the book I wrote for freeCodeCamp, which you can find here.
- In that project we used Vue Router, so we will also look at Vue router's changes in this article.
- To follow along you need a basic knowledge of Vue.js and Vue Router.
- If you don't have that.
then I suggest you start by checking out my book available on freeCodeCamp. You can also find the playlist with the full 8 hour course available for free on my YouTube channel.
This tutorial is organised into three main chapters. First, we will have a look at the changes in Vue.js v3.x then a quick overview of Vue Router v4.x. And finally, we will start planning the migration of a real project.
Vue v3.x overviewbreaking changes. breaking changes.
Vue Router v4.x overviewbreaking changes. breaking changes. Portfolio Project MigrationClone the RepoUpdate CDN scriptsUpdate Vue instanceUpdate Vue Router instance. Update CDN scripts. Update Vue instance. Update Vue Router instance.
What’s your situation?
Here's the video version of this article if you want to follow along there:. Watching the video will help you reinforce your learning while reading the steps below. Here you can find the final repository for the project. Vue 3 introduces a few new features and a bunch of breaking changes. Let's see how these changes will affect our application and consider them before migrating.
In Vue 3 the breaking changes basically fall into seven categories:. Global API(responsible for how Vue behaves) - it's highly likely that you want to look at these changes. Template Directives(Changes made to how v- directives work) - it's highly likely that you want to look at these changes. Components(Changes to how components work) - if your application uses components it's highly likely that you want to look at these changes.
Render Function (Lets you create HTML elements programmatically). Custom Elements (Tells Vue about the creation of custom HTML elements). Minor Changes (These might not affect you, but you'll still want to look into these). Removed APIs (Things that are no longer available in Vue 3). Among all the changes there are some of them that any application will use, like the Global API and components. So you will need to take them into account if you want to start using the new Vue release.
And it's worth mentioning the following additional changes:. The way you create Vue Applications and Component Instances has changed (Global API).
What is Vue.js?
You should always declare the data option as a function (minor change). Change of precedence when using v-if and v-for on the same element (template Ddrectives). You should declare an emits option for component events (components). For a complete list of changes, you can head over to the documentation. Let's look at some of these changes in more detail now. In Vue 3 the way you create an app has changed. The Vue app now uses the new .createApp() method to create application instances.
What you need to follow along with this article
Vue Router v4.x Overview
The Vue application is now considered a root component, so the way you define its data options has changed as well.