Vue 2 to Vue 3 Migration: Frontend Architect's Guide

I recently took time to test a so-called "migration build" from the Vue team. The idea is very simple: you add an alias in the configuration of your build tool so that instead of Vue you use a backward-compatible version of Vue @vue/compat in your project.

Before running such an application, you should do a little preparation, if your project requires it. After you run the application migration build will make sure that we do not miss any places where we use deprecated Vue 2 mechanisms. It will show the appropriate errors and warnings. Some of them will nicely show us the places where these mechanisms are used, but some of the warnings may require manual tracing (e.g. inside an external library).

After going through the whole process, we can uninstall the compatible version of Vue, and start using Vue version 3 directly.

Sounds beautiful, right?

Well, yes, it does sound like this, but…

This is not a tool that will show you how to migrate things. Honestly, it is not very different from going through the list of breaking changes, with the difference that sometimes migration build will show us something we might have forgotten about.

Alright, what is this for and who is it for? From the official documentation:

'Intended Use Cases

 

• Upgrading a Vue 2 application to Vue 3 (with limitations)
• Migrating a library to support Vue 3
• For experienced Vue 2 developers who have not tried Vue 3 yet, the migration build can be used in place of Vue 3 to help learn the difference between versions.'

Can we use it for production? Yes.

As devoted as I am to learning new things, I used this tool to test the migration of several projects:

1. implementation of a recruitment task for Junior devs
2. Monterail Tech Radar
3. small client project
4. custom library for Vue (vue-jsonapi)

The first project went fairly smoothly, although the vue-apollo upgrade was the most problematic.

Not because it was complicated, but because it was difficult to guess that it was this library that was the problem, and then to piece together the scattered information about installing the alpha version for Vue 3, which is backward compatible (the outdated documentation was misleading).

Besides vue-apollo, there was only one dependency in this project: vue-router. Migrating the router is pretty well described and in such a project is not a problem at all.

As for the small client project and the Tech Radar, in both of these cases, I encountered a similar problem: these applications used small dependencies such as vue-carousel or v-tooltip, which do not have backward-compatible versions for Vue 3.

Is this a big problem?

Not necessarily if you have some free time.

In such cases, you may replace the library with another one, but only if you have time (to look for a new library that will be sufficient to replace the previous one) and tests/tester/time for testing. I gave up at this point because I did not want to spend more time on the process.

At the point where I left the application, it could theoretically be released to production with a compatible version of Vue. New features can be written in Vue 3, and at the appropriate time, one can migrate the remaining parts of the application. But I didn't dare to do it because I wasn't at all sure that everything was working as it should in compact mode.

In the end, I gave this tool one more chance with my own library coded while writing one of the projects. It used the Vue 2 reactivity system and the framework's internal way of working quite a bit (but mostly relying on the public API). Here the migration went surprisingly well.

This library had no dependencies, so theoretically all warnings and errors were related to my code, which was pretty easy to track down. Luckily, the library also had some unit and e2e tests, so I was able to track down the bugs that the migration build didn't show me. If I hadn't had tests I probably would have finished a few steps earlier and assumed that it worked even though it didn't.

Conclusions​

Is migrating a large project at once a good idea?

• In my opinion, NO. A much better solution would be an incremental migration, the process similar to a gradual rewriting of an application to a new framework. 

Does it make sense to migrate a small project with a migration build?

• No, if you're using a UI framework or a meta framework that doesn't have Vue 3 support (e.g. Vuetify, Nuxt).
• Maybe, but only if you know it well inside out or it has good tests and you have some time. The process in some places can be similar to rewriting an application using new tools. Business logic will often remain untouched, but even in small projects, it will be hard to avoid changing dependencies to ones that are not backward compatible.

What can be the most troublesome?

• A large number of libraries do not have backward-compatible support for Vue 3
• Some libraries were abandoned some time ago and even if they don't, the authors don't have any plans on creating support for Vue 3 soon

Should you start a new project in Vue 3?

• When NOT to start a new project in Vue 3:
  • The application is supposed to use a UI framework that does not have support for Vue 3 (e.g. Vuetify)
  • The app is supposed to have support for SSR, and there is no developer on board experienced with custom solutions in this area
    • I will probably change my mind when a stable version of Nuxt for Vue 3 comes out

What about the migration of small libraries?

• I highly recommended it. I went through this process with my vue-jsonapi lib (I don't have any big plans for it, but I did it for learning purposes).

What I don't like:

• I've noticed a sad trend that authors, instead of migrating the library to Vue 3 first and ensuring full backward compatibility, start creating newer better solutions by creating new APIs and abandoning backward compatibility. I kind of understand this (as a developer) - it's certainly interesting and more engaging than looking into your old code without the ability to refactor. Still, from a user perspective, it's very cumbersome.