Page MenuHomePhabricator

[Epic] Migrate from Vue 2 to Vue 3
Open, Needs TriagePublic

Description

As a result of decisions made at the recent Vue.js Developer Summit, we will migrate to Vue 3 for all existing and new Vue-based code. This means Vue-based features will no longer be able to support IE11 and other non-ES5 browsers.

Acceptance criteria

The Vue 3 migration is complete. All code that uses Vue has been migrated, and the compatibility build has been removed.

Steps
  • Prepare a patch to upgrade the Vue version in MediaWiki to the migration build of Vue 3.2 (more detail at T251974)
  • Verify that this patch doesn't break any of the existing extensions using Vue (T289019)
  • Wait for the security readiness review for Vue 3 (T257734) to be completed
  • Merge the upgrade patch
  • Begin migrating all code using Vue, addressing migration warnings then disabling compat mode for migrated components (T289020)
  • Ensure all code using Vuex is ready to be migrated (T289089)
  • Wait for the security readiness review for Vuex 4 (T288768) to be completed
  • Upgrade the Vuex version in MediaWiki to 4.0.2 (T289102)
  • Migrate code using Vuex to the new calling style (T289103)
  • Once everything is migrated, remove compatibility code and switch from the migration build of Vue to the regular build (T289104)
  • Clean up other compatibility/migration remnants, like the { compatConfig: { MODE: 3 } } settings disabling compat mode for migrated components (T289105)

Event Timeline

DannyS712 added a subscriber: DannyS712.

(didn't realize it was a subproject)

Hey @Catrope, if you were starting a new MW extension using Vuejs in the next week or two, would you

  1. use Vue 2 and migrate it to Vue 3 later or
  2. start with Vue 3 by including a private copy and use the official version later or
  3. something else

The extension won't be deployed anywhere for several months. The whole team is new to Vue so it would feel wasteful to learn a style and quickly migrate to a different style (of there are significant differences between v2 and v3, that it).

thanks!

Hey @Catrope, if you were starting a new MW extension using Vuejs in the next week or two, would you

  1. use Vue 2 and migrate it to Vue 3 later or
  2. start with Vue 3 by including a private copy and use the official version later or
  3. something else

Apologies for the late response, I started my vacation the day after you posted your comment.

I will ask the other engineers on the Design Systems Team to weigh in too (cc @egardner , @AnneT), but my recommendation would be #1. Use the Vue copy in MW core, and upgrade along with it.

The extension won't be deployed anywhere for several months. The whole team is new to Vue so it would feel wasteful to learn a style and quickly migrate to a different style (of there are significant differences between v2 and v3, that it).

The biggest difference between v2 and v3 that affects how you write code and how you think about things is the composition API, but we have already installed a plugin for v2 that provides that API, and some of our existing code written for v2 already uses it. The remaining differences between v2 and v3 are relatively minor. There are some other nice features that v3 adds, and there are some breaking changes that make upgrading harder (most which are papered over by Vue's migration build), but they're mostly things that you wouldn't encounter very often and that don't affect the way that you would architect or think about things. An example that I think is pretty representative is that the behavior of <div :some-attribute="foo"> changed in the case where foo is false (from dropping the attribute to setting it to the string "false"). For a list of new features and breaking changes see this page in the migration guide.

Overall, most code written for Vue 2 (especially user interface code that is just programming an application rather than providing a library) works in Vue 3 with minor modifications, and works with the compat build of Vue 3 with no or minimal modifications in most cases; see T289019 for our adventures in validating this and finding edge cases. In some cases you may write something differently for Vue 2 than you would for Vue 3, but I think those cases are pretty limited and specialized; the ones I can think of are the teleport feature and the ability to use Vue-native two-way bindings (v-model) for multiple props in the same component. If you start your project with Vue 2 and then keep a running list of things you'll make nicer once you have Vue 3, I think that list will not be empty but will be fairly short.

We're hoping to upgrade to Vue 3 (with compatibility) in MW core soon, so hopefully this issue will be moot anyway. The main blockers are the security review (T257734) which is estimated to be completed by the end of September, and unbreaking the extension breakages in T289019. If that goes well we could have Vue 3 available in 3-4 weeks, but we haven't tried running it against Wikidata yet, so we'll see.

I agree that Vue 2 is safest for now, and that migration to Vue 3 shouldn't be very time-consuming or difficult, especially with the compatibility build.

To expand a bit on the Composition API: Vue 2 components use the Options API, which is still available in Vue 3, but you can also start using Vue 3' Composition API via the Composition API plugin. You can check out how we're using it in a few WVUI components (Checkbox, Dropdown, and Radio - all the others exclusively use the Options API).

When starting out with Vue I found the Options API to be very straightforward to learn, so if you want to keep your first Vue project simple you could stick with it. However, the Composition API offers some benefits (better code organization and sharing, for example) and you'll also get a chance to learn Vue 3's new reactivity system, which offers more granular control of reactivity than the previous version.