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:
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).
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
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.
Is migrating a large project at once a good idea?
Does it make sense to migrate a small project with a migration build?
What can be the most troublesome?
Should you start a new project in Vue 3?
What about the migration of small libraries?
vue-jsonapilib (I don't have any big plans for it, but I did it for learning purposes).
What I don't like: