Vue 2 to Vue 3 Migration: Q&A with Monterail's Experts

Believe it or not: migrating an application from Vue 2.x to Vue 3 can be easy. 

The key is planning it in advance. 

How to do it right and what things should you consider? These topics were discussed during the online event about Vue 2 to Vue 3 migration organized at Monterail. The guest speakers included Szymon Licau, our Principal Frontend Engineer, and Artur Rosa who works on our team as a Frontend Architect.

Here’s the 60-minute recording of their presentations, with more details about how you could approach the migration stages and what to prepare in advance:

If you’re pressed for time, you’ll also find a summary of the event with the most common questions about the Vue 2 to Vue 3 migration process. Learn how to go through it step-by-step and decide what approach would work best for your project. You’ll also get familiar with migration time estimations.

Let’s start.

The Story Behind Vue 3 and Monterail

Artur Rosa: At Monterail, we have a lot of success stories with Vue, we’ve used Vue 2 in our projects, and we’ve also used Vue 1 before. I must admit we kind of love Vue. Now, you will probably understand why when our development team found out that Vue 3 was about to be released, we immediately wanted to start using it. 

But it turned out that even though the stable version of Vue 3 was released in September 2020, the Vue ecosystem needed quite some time to catch up. So, for a long time, the migration of our projects seemed like a really tough task. In a lot of those projects, we had critical dependencies that did not support Vue 3.

Now, we’re in a totally different situation. The ecosystem of Vue 3 is already pretty strong, and Vue 3 has become the default version of Vue. It’s also the case at Monterail - when we start a new project, Vue 3 is the way to go for us. In 2023, the time has come to think about and reconsider migrating some existing projects that we have. 

Another reason to start thinking about it is that Vue 2 is already closed when it comes to new features. It is now in maintenance mode, and this mode means that basically the Vue team will still fix newly found bugs but will not add any new features. Vue 2 applications will still work as before only until the end of 2023.

At the end of 2023, Vue 2 will reach its End of Life stage. After this date, it will no longer receive any updates, including security updates and browser compatibility fixes. I know it may sound scary, but it is good to know and understand what it means in practice. Basically, this is the final reason why you should at least consider migration. 

What Are The Risks of Staying with Vue 2?

Artur Rosa: The question really is: what will happen with Vue 2 projects once its maintenance phase is over? Truth be told: probably nothing special for quite some time. Newly found bugs will still be fixed for Vue 2, but it’s already a very stable and well-tested framework, so it should not be a big problem. There might be some issues with support in new versions of browsers sometime from now but we are not expecting it to happen in the foreseeable future. Such things did not appear to happen very often and we are not expecting them to happen more often.

The same risk applies to the community-driven Vue 2 libraries and other third-party dependencies. With Vue’s End of Life, it is very likely that most libraries won't see an update, so here the risk should be assessed per project. Depending on how many critical parts of your product depend on external libraries. 

Also, particular attention should be given to integrations with external services, because such integrations may simply stop working and the vendor can only make changes for Vue 3. In the standard scenario, the author would probably release a new version of the library, but here it may not be so. 

Another aspect that should not be underestimated is the developer community. As time goes by, it will be increasingly more difficult to find people who will be willing to work with End-of-Life technologies like Vue 2, so that’s something you should plan for in advance.

Szymon Licau: As I’ve mentioned before, migration is a risky process. Essentially, if you think about it, it’s a change that affects your whole application. As you can imagine changing your whole application can change a lot of areas and introduce bugs where you do not expect them to be. Of course, this is bad, because you don’t want to negatively impact your users.

Because it's such a big thing, it’s difficult to accurately estimate how much time and effort the migration will take - there are so many uncertainties involved. Even taking it one step at a time will uncover new things and increase the workload.

What Are The Benefits of Migrating to Vue 3?

Artur Rosa: It's not that the upgrade will only get rid of future problems but it can also be rewarding. So, what can we gain? 

Let me start with the performance aspect of Vue 3 migration. I’m not a huge fan of saying by how much percent the speed of the application has increased, because it depends on multiple factors. The truth is that in almost all cases Vue 3 is faster than the previous version. It can be quite a noticeable change for some applications. 

Performance not only has a significant impact on UX and how users perceive an application, but it can also affect search engine optimization. If that’s important for your project, you should be aware of that. 

Vue 3 introduces a number of new features such as:

• Composition API 
• Teleport 
• Suspense,
• multiple root elements for a template.

Those functionalities open up completely new possibilities for creating a maintainable and scalable architecture. Again, it’s particularly important for complex applications. The Vue team has poured some of these features into Vue 2, but only some of them and with additional limitations. To take full advantage of them, migration is necessary and as I mentioned in the question about performance, those new features also can support it because they provide new ways of sharing logic. They are not only great tools for developers, but they can impact how the applications work.  

When creating Vue 3, the core team was very much focused on developer experience. My impression is that this focus has become a priority across the ecosystem - just take a look at Vite, Vitest, and libraries such as Pinia or VueUse that work with virtually no configuration, and are super fast, lightweight, and intuitive.

Thanks to Vue 2.7, it’s still possible to use some of the libraries developed mostly for Vue 3 applications, but unfortunately only a tiny part of them. 

Another thing is Typescript support - thanks to this, code editors can help as developers do their work. We also have more options to ensure the stability of the software - Vue 3 allows you to statistically analyze the code of the entire application.

Last but not least, I want to mention some upcoming features in Vue 3. As a sneak peek, let me mention some releases for this year: lazy hydration and SSR-only template elements. For the second half of this year, the plan is to ship Vapor mode, an alternative compilation strategy for Vue components based on the Solid framework. This could be a game changer for applications required to be extremely performant. Unfortunately, there’s no hope for those new features to be imported back to version 2.

Who Should Migrate from Vue 2 to Vue 3?

Szymon Licau: So, you know the benefits and the migration process may look enticing. It’s not as simple as one might think. In some cases, it may not be a good choice or even a possibility.Before we start driving into things a bit deeper, let me bring you back a quote from Evan You from last year’s Vue Report produced by the team at Monterail. 

What it says is that we should approach the migration process on a case-by-case basis. Essentially, if Vue 2 works for you and works well, it might not be worth it and it may not be the most cost-effective solution. What you should really consider are different factors. 

The situation changed quite a bit since Evan wrote about it, i.e. there was End of Life announced for Vue 2, but I think that the point essentially still stands. We need to evaluate it on a case-by-case basis and essentially take a closer look at a few factors.

In some cases, the decision won’t be as difficult as you think. Take a look at the size of your application. If you have a small application that has been working reliably for a long time, it may not be worth it to migrate it to Vue 3, perhaps your resources could be allocated elsewhere.

Likewise, if you have an application that you don’t build new features for us, maybe you are doing so but in a limited fashion, or maybe it's just mostly maintenance, then perhaps the migration may be too costly for you because it will require additional resources spent just to migrate. Perhaps staying with Vue 2 may be a better option.

Finally, if your application is built with support for older browsers in mind such as Internet Explorer 11, Vue 3 won’t support these, so you have to stay with Vue 2. That’s the only choice you have, but there are some actions you can take to improve your codebase with Vue 2.7.

Now, there are also some technical factors that might influence the complexity of the migration process. You may want to look at:

• How many dependencies are there without Vue 2 support, and how important are they? Do you have any alternatives?
• Does your app use non-public Vue APIs?
• Does the app rely on behavior that changed between Vue 2 and Vue 3?
• Does the code follow best practices as listed in the Vue Style Guide?
• Does it use non-standard syntax (i.e. class-based components)?
• Is there server-side rendering involved?
• Does it use a meta-framework on top of Vue (e.g. Nuxt)?
• Are you using a UI framework?

What are the Beneficial Factors for the Migration Process?

Szymon Licau: If you have high test coverage in your application, that's excellent- this will make you much more confident when you migrate your application to be sure that it works and you are not introducing new bugs or errors. Migration is actually quite a scary and risky process. 

If you have few external dependencies, then the migration may be a pretty straightforward process and Vue Migration Guidelines are just what you need to complete it, and it won’t take that much time or effort.

How Much Time Will The Migration Process Take?

Szymon Licau: The answer to this question is: that it depends on a lot of factors you have to carefully look at. The short answer to this question is: it depends.

Time-consuming things to improve before the migration

Still, even if you do not decide to migrate or you do not want to migrate at this time, there are some good steps you can take to improve your codebase:

Moving away from Vue CLI and Webpack to Vite: It’s a new recommended approach to building applications. This brings up improved speed of building your application and also improved development experience, and simpler configuration.

Upgrading to Vue 2.7: If you haven't already upgraded your Vue version, I highly recommend that. There are a lot of features that are backported from Vue 3, including Composition API, script setup, new libraries (VueUse), better Typescript support, and better tooling support (Volar). 

Monterail’s Approach to Vue Migration

Szymon Licau: Before we even begin the migration process, we - of course - have to audit the project to get a bigger picture of it. You have to think not only about what to complete before migrating to Vue 3 but also about your resources, technical aspects, and project status.

Now, in terms of the actual migration process, at Monterail, we always try to minimize the amount of risk that we could cause for your end users. This is why we introduce a concept called incremental migration. The process, as the name suggests, is not a single step for the migration with your team taking a giant leap. Instead, you should define smaller milestones and deploy your application more often and successfully do it with simple smaller steps. Therefore, we will be also minimizing the amount of risks, because we will be in control of what areas we will affect in your application.

If you do it on a step-by-step basis, you will have better predictability of the amount of effort we need or the unknowns that we see, and how much time such a given step could take.

Now, if there are also automated tests implemented in your project, this is an excellent moment to introduce them to increase your confidence in the code that you ship to production. The result of that means that you can continuously improve your codebase and start reaping the benefits early. 

It's also important to keep in mind that the migration itself does not necessarily mean you need to be blocked with the development process. It can happen in parallel to the migration process.

Potential solutions: a migration build

Here are a few solutions that could make it possible.

The first one is probably the most obvious: using a migration build. This type of build allows you to have Vue 3 and Vue 2 code in one single codebase. It means that you can essentially change parts of the application you want one by one, gradually migrating them over to Vue 3. Once you’re done, you can change the migration build to a Vue 3 build. 

Now, it’s not all roses - there are some downsides to this migration approach, i.e. migration build will add unnecessary performance overhead to your application or increase your bundle size. If there are areas in your application that are very performance-critical, this might not be the way for you, because it will definitely impact those areas. 

Another solution is perhaps radical, but it’s particularly great if you’re planning to introduce new features to your application. The idea is this: you can start writing them in Vue 3 even before you migrate. Again, there are quite a few and not-so-simple issues you have to solve here like code sharing between the two applications, but you can start writing new modern Vue 3 code and essentially slowly move the old modules to the new application. Once you’re done, you can sunset your Vue 2 application. This approach can also be especially helpful if you have some refactoring in mind with your codebase. 

Also, another solution but perhaps the most complex one is to introduce micro frontend architecture to your application. This approach means that instead of having one large application, you split it into chunks and have several submodules - each working as a small application.

This approach - while introducing complexity - gives you some benefits. Each of these smaller applications might use different technology, so they need to use different frameworks or different versions of a framework. Therefore, you essentially cut your workload into smaller pieces which you can address in parallel or one by one. Then you can migrate them one at a time when you need to.

Vue 2 vs. Vue 3 Dependency Issues

Szymon Licau: In terms of dependency issues between the two versions, here are some steps you could take to address some of them. 

If you have a dependency that perhaps does not support Vue 3, but it was working fine with Vue 2, you can of course try to find an alternative. It's not always possible of course to tweak your code to address differences between these two dependencies, but it’s always an option.

If you're not already doing so, you can also try to decouple your dependencies and wrap them around in a wrapper, so you have your own abstraction that uses these dependencies which are external inside of it. You treat it like a black box. You can essentially tweak and change the inside of it while still keeping the dependency working. This works especially well for UI components. 

You have the option to wait for the support for Vue 3 if you know that the team behind the dependency is working on it. Check if waiting aligns with your product timeline, but this decision could force you to put off the migration process if the dependency is important or big. 

If you don't necessarily feel confident and you know that there’s no alternative to dependency, you can always contribute to the Vue community and work to solve this issue.

Lastly, if everything else fails, you can always try to replace the dependency with a custom solution which will - obviously - increase your workload, so I’d see it as a last resort.

Troubleshooting

What are the typical issues that might come up during the migration process?

Szymon Licau: Typically, the issues that come up are not usually connected to the Vue framework itself - they’re usually about the dependencies. For example, migrating your Nuxt application might be quite complex and challenging, especially considering the fact that many of the modules that are popular for Nuxt 2 are still not there for Nuxt 3. 

There are some solutions here that the Nuxt team has proposed and some other ways to approach it like Nuxt Bridge. If your product doesn’t have many dependencies and if you follow the Vue Migration Guidelines, the whole process should be pretty straightforward.

To Sum Up

It’s worth mentioning that deciding not to migrate can also be a valid choice. Your approach should depend on your project status, your resources, and other factors. You can also migrate later and prepare for it now. 

If you do plan to migrate, keep in mind that it’s a lengthy process. And even a very thorough process won’t address everything, but it’s a good starting point.

Even with a great plan, migrate your application incrementally to minimize the risks and move your features to production faster. Get in control of the challenges and limit their likelihood, because the worst thing that can happen are errors that will affect your users. 

Of course, you can migrate the application even if you’re still actively working on it. Migration doesn't necessarily mean that you have to block development. It can still happen in parallel if you have proper solutions.