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
  
  
  

  
  
  
  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. ) 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 .

  
  
  

  
  
  
  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 ".

  
  
  

  Turn off every is impacting your app, or fix them.

  
  
  

  
  
  
  Small steps
  

  
  
  

  ; 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:
  
  

  
  
  
  
  

  CODE Kopieren

  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! 🥳

  Vollständiger Original-Bericht

  Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

  ↗ Original-Artikel auf dev.to lesen