How to Seamlessly Migrate a Large Codebase to Vue 3

Hello, I am Baptiste from CRISP, and in this conference I'm going to show you how to migrate a large project from View 2 to View 3. Recently, at CRISP we've been moving our messaging app from View 2.6 to View 3.2, and so far I can tell you that the migration process has been really smooth. However, there are many mistakes that can be avoided when moving to View 3, and it's exactly what we are going to talk about in this conference.

So I'm the CEO of CRISP, and at CRISP we are doing a messaging app allowing companies to unify all their customer relationships using one app. So basically, it's a shared inbox allowing companies to unify messages from the live chat on the website, to emails, direct messages on Twitter or on WhatsApp messenger, and you can even reply to your GitHub issues right from CRISP. And all of that is made using Vue.js. We have around 300,000 companies using CRISP and at the end it's around 200 million people using CRISP every month. So it's been a big challenge for us moving from Vue 2 to Vue 3 because we wanted to avoid any impact for our customers.

Moving from Vue 2 to Vue 3 is a different situation than moving from Angular 1 to Angular 2. In fact, many developers, when Angular 2 was released, choose to use another framework such as Vue.js instead because the migration cost was too important. The learning curve to Angular 2 was too important. For this reason, if you look at the Google Trends, Vue.js went more and more popular and even replaced Angular.js. So moving to Vue.3 is not this kind of situation because Vue.3 is a simple migration. A reason for that is the Vue.compat package. The Vue.compat package allows you to use Vue.2 code along with Vue.3 codebase. Also Vue.3 allows you to use the same tooling. So you can use the same Vue.cli with the same webpack. Also, Vue.3 has a similar documentation. And finally you just don't need to relearn everything because Vue.3 is really similar to Vue.2. But Vue.3 comes with many different improvements. And the first is performances. Vue.3 comes with many improvements in terms of performances thanks to the new reactivity system. Also Vue.3 is more modular thanks to the composition API. And also there are many good API changes and one of them is the new vmodel system allowing you to have two vmodels for the same component. But obviously Vue.3 comes with some trade-offs. The main one is dropping IE11. But to be honest nowadays it's not a big deal. For instance for an app like Crisp, we had around 0.1% of companies using IE11. So it's not a big deal to drop IE11. Also some APIs have been duplicated such as the global vue API.

You won't be able to do vue.set or vue.delete. But in fact it's not a big deal. Because using vue 3 you don't need to do that anymore thanks to the new reactivity system. And also filters have been duplicated and for us it was important because as we came from the angular world we've been Crisp used to be an Angular app before and we've been using filters and we've been using filters a lot.

So it's been a challenge for us moving all our filters to a new Vue 3 compatible syntax. So let's talk about migration strategy. So we wanted to maintain our existing Vue 2 app while moving the codebase to Vue 3 and also we wanted to reduce the impact for customers. So once we released the Vue 3 version they don't notice anything and as we are a small team at Crisp we are only 4 developers we wanted to reduce the migration time.

So the strategy was to create a dedicated branch for Vue 3. So what we did is we used our existing master branch to deploy features and fixes on the existing production app. And at the end we have been able to port all the fixes from the master on the Vue 2 version to the Vue 3 version because Vue 2 and Vue 3 are really similar. So we've been able to merge the two projects without any conflicts. And also we wanted to use the same tooling so we keep Vue-CLI and we are not using Vids. Also we didn't implement the new composition API because we wanted to avoid risk of creating new bugs and regression. No composition API. We wanted to migrate only what is necessary. And likely we're going to use the composition API later but just not now.

So it's been 5 minutes I'm talking and now let's code. This is the crisp existing app using V2. The first step would be to update your packages.json so we can update vue to vue 3. So we're going to have to update vue 2 to vue 3 and also include the vue-compat package. Finally we're going to have to update vue-loader to the vue 16 version. So we're going to have to update the vue-cli services and it's very important. So we can do the next step. The next step would be to update the vue configuration. So we're going to have to update webpack for the vue-loader so we can enable the vue 3 and with the vue 2 compact. So we're going to resolve the vue-compat package instead of vue and it's very important to do that. Next step would be to open your main.js file and we're going to rework this file this way. So first you're going to have to import vue using a new way. So you're going to have to import create-app and configure-compat.

So now you need to create your app this way. Now instead of importing the router and the store inside the vue constructor, you're going to have to use app.use and also now you're going to have to use app.mount. Finally the next step would be to use the configure-compat. This way you're going to enable the vue 2 compatibility with vue 3.

So now as you can see when we open our app we have errors. And the reason is we need to update the core libraries. So we're going to have to update vuex and vue router to the 4 version. So you don't need to do anything for vuex, however as you can see we have some updates to do on the router. So you can check, you can have a look at the vue router documentation. So we need to rework the router this way. So we need to import the router this way and we're going to rework the constructor like this.

Okay so now we can open our app and as you can see there is an error. And the reason we get this is because we now need to use a regex for the default route. So we're going to open the router file and we're going to rework this line with a regex. So now it's very important updating the community libraries. We are relying a lot on vValidate and the Vue internalization plugin. So we have to update those libraries first. As you can see now our app is working thanks to the VueCompat package. So basically it's working because we are having the Vue 2 compatibility. However so we can benefit of the Vue 3 performances and all the new features, we wanted to get the rid of the VueCompat package. So what we had to do is moving all of the Vue 2 APIs to Vue 3 APIs. So for instance we had to replace all the destroyed methods to the Vue 3 version which is unmounted and same for v4.destroy to v4.unmount. So we did that for all the new Vue 3 APIs and once we moved the Vue 2 APIs to Vue 3 APIs what we did is we disabled the compatibility mode for those specific features. It allowed us to track the progress of the migration. So now let's take an example of how to move the vue.set and vue.delete to a Vue 3 version. Just open your VS code and have a look at all the vue.delete. We don't need any more vue.delete just replace it using a native JavaScript function. And do this for all your vue.delete. And obviously you can do the same for vue.set. You can do this this way.

One important task for us was updating vmodels because obviously in a big project, we are using vmodels a lot. And now, since Vue 3, it's possible to use two different vmodels for the same component. So what we're going to do is just update every component so we can use a V3 compatible syntax. So, instead of using value, we need to replace it with modelValue. So do that for every value in your component. And now, when you want to do an update for your value, you had to do toEmitInput. Now you're going to have to update modelValue. And when you think about that, it's logical. But, now, there is also a big change on Vue 3. You need to specifically tell what your component is emitting. So our component is emitting updateModelValue. We also have blur, click, etc. So, you're going to have to search for all your this.emit inside your project. And for every component, tell specifically what your component is emitting in an array.

We came from the AngularJS world and previously, Crisp used to be an AngularJS app. So, we relied a lot on filters and we had around 200 filters. So, we had to find a solution, an elegant way to move all those features to View3.

So, what we did is moving all the filters to native JavaScript methods. So, here is an example with a ColorForValue filter. So, it's a native JavaScript function. And now, what we're going to do is to import this function as a global method in Vue. So, what we did is a global $Filter object, so we can access to all our filters in every component. So, here is an example with an uppercase filter.

And then, so we can find all the filters we were using inside components, we've been using a regex. So, using this regex, you can basically find all your different filters. And this way you can move all the filters to a new method syntax. Also, we discovered that it's not possible anymore using a VIF with V4 with Vue 3. And I do agree, it's not a good idea using the two each other. But anyway, we've been using this, so we had to replace this behavior with computed properties. Also, an important task was updating some third-party libraries.

We had to fork some libraries, so for instance, Vue Chartist. So nothing very complicated, as you can see, moving an external library from Vue 2 to Vue 3 is not very complicated. Basically most of the stuff is related to the Vue Global API. So you just basically need to replace the constructor and some APIs. And we had to do that for around 5 different libraries. We relied on Trello to manage all the tasks while moving to Vue 3. And it was important to us to not miss anything. So, you should use something like GitHub, GitLab, JIRA or Trello to note down everything, so you don't miss any bugs or library.

We've been able to release this Vue 3 migration after almost 2 weeks. And so far, it's been great, no one noticed anything. To be honest, we had some bugs, but nothing very important. The good news has been performances. From Vue 2 to Vue 3, we've been able to cut the Jira heap from health. And so far, the app feels faster and more responsive.

And it's definitely thanks to Vue 3 and its new reactivity system. And the impact is very good, because at Crisp, we have users all around the world and some users are using low-end computers. Not everybody is using powerful MacBooks like developers. And some people have low-end computers. So it's important to optimize the code base and Vue 3 is great for that.

So it's now the end of this conference. As a reminder, Crisp is hiring full-stack developers, so if you want to join us working on Vue.js, you can have a look at our website on Crisp.chat. Most of our team works remotely and the rest works in France. As we rely a lot on Vue.js, we wanted to give back to the community. So we are now a sponsor of the Vue.js Foundation. I really think you should do the same if your company is profitable enough. It will help us grow the community and help the project in the long term.

I really hope you enjoyed watching the video. You can reach us on Crisp.chat. You have my email. And I'll be here to reply to all your questions on this Discord community.