## Summary
Which Vue.js version should our shared component library target, and how can we plan/facilitate migration of projects from Vue 2 to Vue 3?
## Considerations
#### Why does this matter?
This is closely tied up in the question of whether the library should continue supporting IE11 (T286947), because Vue 2 will continue supporting IE while Vue 3 will not. Many Vue 3 features (like the composition API) either already exist for Vue 2 or will be backported in an upcoming 2.x release. However, this is not true for many of the Vue 3 performance optimizations; if we want those we'll need to upgrade. Vue 3 also is fully written in Typescript and promises some improvements in TS workflow.
#### Impact on tooling
* If we want to use more modern build tools like Vite (very fast, less config than Webpack, HMR), Vue 3 is supported natively while Vue 2 requires an additional plugin; using Vue 2 and continuing to support IE11 means we'll need to continue relying on things like Babel.
* Different versions of the Vue.js browser DevTools are required to support Vue 2 vs Vue 3 apps, which is annoying. There may be other tools we're using that still rely mainly on Vue 2 – however, we're not really depending on any external Vue libraries so that is one less barrier to migration
#### Compatibility helpers
* Vue 3.1 is the official "migration build" of the library;comes with an official [[https://v3.vuejs.org/guide/migration/migration-build.html|"migration build"]] of the library (also called the "compatibility build" because the npm package is called [[https://www.npmjs.com/package/@vue/compat|@vue/compat]]), we may want to look at this too: https://www.thisdot.co/blog/vue-3-1-official-migration-build-from-vue-2-to-3hich provides backwards compatibility for almost all Vue 2 behavior. Almost all code written for Vue 2 (and all code written for Vue 3) should be able to run on this version of Vue.
* [[ https://github.com/vueuse/vue-demi | Vue Demi ]] could enable the component library to work in both Vue 2 and Vue 3 apps, but now that the official compatibilitymigration build of Vue is out, this might be obselete
#### Migration timeline
- Do all WMF and WMDE applications *need* to migrate, or can some finished work remain in Vue 2 indefinitely?
- Are we migrating projects to Vue 3 at the same time that we are migrating them to a shared component library, or are these separate processes?
- Consider the collision of one product that's on Vue 2 and another that's on Vue 3: is this a big problem (avoid at all costs) or no big deal?
#### Relevant Links
- [[ https://v3.vuejs.org/guide/migration/introduction.html | Vue 3 migration guide ]]
- [[ https://phabricator.wikimedia.org/T286948#7228961 | Summary of Vue 3 changes and benefits ]]
- T251974: see here for lots of discussion about a potential migration and a proposed plan
---
## Decisions
#### 1. When will the shared component library migrate to Vue 3?
**Options:**
- Use Vue 3 in shared lib starting now
- Use Vue 2 in shared lib indefinitely
- Use Vue 2 in shared lib for now and re-evaluate in 6 months to 1 year (implies future migration work will need to be done both for library and for consuming applications)
- Use the Vue compatibility build (or vue-demi) to attempt to write a shared library that can be consumed in both Vue 2 and Vue 3 applications
**Design Systems Team proposal:** To avoid additional migration work in the future, start developing the shared component library in Vue 3 immediately. Introduce this version of the library into MediaWiki once we update the version of Vue within MediaWiki to 3.1, the compatibility buildmigration build of Vue 3.1.
//Fallback option//: if some of us want to adopt the shared component library ASAP but must continue to support IE for a while, continue developing the library in Vue 2 with the composition API plugin, and plan for a future migration to Vue 3. This wouldn't prevent us from migrating other code to Vue 3: if MediaWiki upgrades to the migration build of Vue 3.1, embedding a library built with Vue 2 will continue to work.
#### 2. When will existing WMF and WMDE Vue work migrate to Vue 3?
#### 3. How will we enable and facilitate these migrations?
**Design Systems Team proposal:** Use the compatibility build to facilitate project migrations, and to support projects running Vue 2 or Vue 3 in the meantime. Eventually, upgrade the Vue version off the compatibility build. See T251974 for full details.
#### 4. How will we handle situations where some projects use Vue 2 and some use Vue 3?
**Design Systems Team proposal:** Lean on the compatibility build to prevent collisions while we're in the middle of the migration process. This way there's only one version of Vue (the migration build of Vue 3.1) running on our pages, supporting both code written for Vue 2 and code written for Vue 3.