How we migrated from Vue 2 to Vue 3

About one year ago we finally migrated from Vue 2 to Vue 3. It was 6 months before its official end of life. At the time, our app has around 100 pages and 300 components, and used some of the classic dependencies tied to Vue: Vue-router, Pinia (and Pinia ORM), Vue-i18n, TipTap, ElementUI (ElementPlus for Vue 3)

Here are a few advices that helped us. As Vue 2 still work pretty well, you better take the time to ease the migration instead of rushing it, breaking your app and destroying your moral!

1️⃣ Before starting#

Warn others#

Things will certainly break, even a little. You better make sure it's ok with other teams.

Upgrade to latest Vue 2.7#

Obviously, as most of the new features are available in Vue 2.7, and retrocompatible, it's important to catch up if you don't already have. While migrating to Vue 3 you'll still be able to enjoy its features. The step to migrate will also be smaller.

Take the time#

This can be a pretty big work so you better anticipate to mitigate the risk over a long period. Also, it helped us (the developers) keep the moral! Plan a few weeks or even months, as you know when you start, but you don't know when you'll finish... Finally, it's better to dedicate some time every week, so any outage won't be disastrous.

Create a team#

Don't rely on only one developer if possible, as it's an exhausting task. Also, you need quick feedback & merge loops, because a lot of changes will affect the entire codebase and could create conflicts on a daily basis. It's already hard enough without having to handle this!

Test driven migration#

Half of the time will be spent testing the whole app, so you better automate it the most possible. In our experience:

• Unit tests are not very useful, as they're usually testing things not really tied to Vue (only "pure JS" functions for instance), se we didn't focus on them
• Component testing with vue-test-utils were a pain to migrate, in the end we even had to disable some of them
• End to end tests were the most valuable as it's not tied to any JS or Vue internals and failed as soon as a error was thrown away in the app

In conclusion the best is to create so-called "smoke test", where you just navigate within the app with the most basic scenario you can think of. Keep them simple, so they're fast, because the sooner you can make them run, so the more useful they'll be. Bonus point if they run before merging (in a CI for instance).

Type everything#

TypeScript helped a bit, but support for it in Vue 2 is still poor. Using TypeScript is still a good idea, but it might not help too much there; Once using Vue 3, the setup syntax will be your best friend though!

Lint everything#

It's obvious, but a lot of changes will happen in the code, so does a lot of errors. A simple ESLint / Prettier can save a lot of time. If you already do have them, you can check the new rules for Vue 3 meanwhile you migrate: https://eslint.vuejs.org/rules/

Use Vite#

We already had migrated from Webpack to Vite before beginning migrating Vue, so I'm not sure it helps a lot, but as it's the clear standard today, some plugins might not even give instruction for upgrade with Webpack. I guess it's safer to do it first as Vite supports Vue 2, but in the opposite the Vue 3 ecosystem might not support Webpack.

2️⃣ Small steps first#

The goal is to have the less changes possible when actually upgrading Vue itself.

Upgrade dependencies#

Take a look at every Vue-related dependency you use, and check if there's a version that support both Vue 2 and Vue 3, and upgrade to it. Vue-demi helped a lot plugin maintainers to achieve it, so there's a good chance it's available.

For instance, you might want to migrate from Vuex to Pinia, which support both versions (Vuex still requires a small migration) and is the new standard anyway.

Replace dependencies#

For other dependencies, you might want to check if any modern alternative could suit your needs. For instance, we replaced vue-mq by vue-use.

Monkeypatch when needed#

We had to be pragmatic, so as some migrations were harder than others, we ended up creating a small layer of abstractions to fix it. For instance, we had a hard time with vue-i18n v9 which brings some (sometimes undocumented) breaking changes. So we finally created a helper that expose a custom version of $t to prevent having to rewrite every component (because this most used function now doesn't accept "nullish" values for basically no reason). In other terms, don't be too perfectionist!

3️⃣ Start migrating#

Now the hard work begins. Everything we did before will ease the pain. There's no magic here, it will probably be the hardest part of the migration.

Change everything, but nothing#

Replace Vue 2 by Vue 3 with the "migration build" (also called compat mode) by following the instructions.

Turn off every available flag so the app runs almost as it did with version 2.

Check that no breaking change is impacting your app, or fix them.

Small steps#

Incrementally enable each flag and test the app thoroughly. If some components are too hard to migrate, keep in mind you can override its compatibility option; so you better merge everything but keep a few components to migrate later instead of waiting for the whole app to work right now. Don't try to fix everything at once, let some days pass so you can catch any bugs (and recharge your mental health).

Big steps#

Some dependencies don't provide shortcuts though. In our case, migrating our UI library from ElementUI (Vue 2) to ElementPlus (Vue 3) was hard, and couldn't be split into smaller steps. I heard it was even harder for Vuetify. For this, you'll have to be strong, patient, and take time to do it all at once. Maybe allow a full week for it in your team calendar!

Remember that you can still override the compatibility behavior of each component you import at runtime:

import { ElButton } from 'element-plus'

ElButton.compatConfig = {
  FEATURE_ID_A: true // features can also be toggled at component level
}

Last step#

Once every flag has been turned on, it's time to remove the migration build. Hopefully you won't discover new unexpected issues by now!

Don't forget to celebrate, you deserved it! 🥳