NOTE: Design Systems is seeking feedback from other WMF teams on this topic; input greatly appreciated.
## Overview
Two years have passed since the original RFC around using [[ https://vuejs.org/ | Vue.js ]] in Mediawiki (T241180) was opened. Since then several teams have been able to experiment with using Vue for different features, and most feedback around the framework has been positive. Today, the Design Systems Team is working towards an initial release of a new Vue-based UI library, **[[ https://doc.wikimedia.org/codex/main/ | Codex ]]** (T299138), and a general migration from Vue 2 to Vue 3 is underway as well (T289017). Vue is clearly here to stay in the MediaWiki universe.
**However, there is still a lot of uncertainty about when and where this new JavaScript framework can be used.** Some things that complicate the question within our projects:
1) Many of our projects have strict performance requirements (supporting users with older/slower mobile devices, limited bandwidth, etc)
2) Some projects still need to support legacy browsers to varying degrees (though this is [[ https://www.mediawiki.org/wiki/Compatibility/IE11 | starting to change ]])
3) We don't currently have a way to provide SSR capability for Vue components (though we hope to start exploring solutions here soon).
**The Design Systems Team would like to develop a clear set of criteria (based in input from appropriate stakeholders) to help WMF teams and volunteers decide whether to use Vue for a particular project.** And since Vue 3 drops support for IE11, this question will be closely related with the question of how new features should support users of legacy (non-ES6) browsers.
## Draft Guidelines
Below are draft guidelines based on feature/product type. These likely need to be refined; please discuss below.
#### Off-Wiki
**Example**: [[ https://stats.wikimedia.org | stats.wikimedia.org ]]
Off-wiki products represent the simplest case. Stand-alone tools that exist outside of MediaWiki are great candidates for using Vue.js. Dashboard pages that pull data from various APIs in particular can benefit greatly from being built in Vue. Such products may not need any sort of SSR at all.
**Recommendation**: Off-wiki projects are encouraged to use Vue 3, Codex (once released) and Vite. We also encourage teams creating new off-wiki tools to write JS code according to modern standards (ES6, ES Modules syntax, prefer native web APIs like `fetch` and `promise` over 3rd-party libraries, etc). Modern CSS layout APIs like Flexbox are also encouraged, as is the use of appropriate [[ https://github.com/wikimedia/eslint-config-wikimedia/blob/master/vue3-es6.js | linter configuration ]].
#### Dedicated MediaWiki Special Page {icon cog spin}
**Example**: [[ https://commons.wikimedia.org/wiki/Special:MediaSearch | Commons MediaSearch ]]
Dedicated MediaWiki special pages are also good candidates for Vue.js in many cases. However, since these pages live within the MediaWiki environment, some different coding practices may need to be followed.
**Recommendation**: Features that live on dedicated Special pages are encouraged to use Vue and Codex if it makes sense to do so. However, we recommend that teams rely on the Mediawiki-provided versions of Vue, Vuex, and the Codex component library (once it is available), rather than bundling their own copies of these dependencies via a project-specific build tool. Single-file components (aka `.vue` files) are supported natively in ResourceLoader but must use RL-compatible module syntax (`require` instead of `import`, etc). ES6/ES2015 syntax should be used throughout these projects (`let`, `const`, arrow functions, modern array methods, etc).
**Additional Considerations**: If a Special page needs to provide server-rendered content (for SEO, performance, or audience reasons), the server-rendered version of the feature needs to be defined separately in PHP. We know this is not ideal since it means double work; wherever possible, we encourage teams to rely on Mustache templates (since markup from Vue components could probably be easily adapted there). Commons MediaSearch renders a Mustache template from PHP and then replaces it with a matching client-side UI written in Vue as soon as page JS initializes. For this project, component styles were split out separately from the `.vue` files so that they could be re-used by server-rendered elements.
#### Globally-enabled Skin/Extension feature {icon cog spin}
**Example:** New Vector search tool, Related Articles feature
Some features are enabled globally on a given Wiki as part of a skin or extension. Search boxes and Related Articles sections appear on every page (or at least every page of a given type).
**Recommendations**: TBD – discuss below. Some open questions we should answer:
* **Is it acceptable to load Vue.js on pageload?**
* **If not, why not?** What else constitutes an appropriate "cue" to signal when to load the framework?
* **Are there any tests we need do to properly assess impact?**
* If the full build of Vue is not acceptable in this context, would a bundled/optimized build (tree-shaken, no template compiler, produced by a skin- or extension-specific build step) be acceptable?
* What about the aggressively-optimized [[ https://github.com/vuejs/petite-vue | petite-vue ]] (an alternative distribution of the framework). Note that this approach could not use the standard Codex UI components and would rely instead on something like a set of Mustache templates; some extra work would be required to set this up for easy usage across teams.
## Acceptance criteria
[] Reach a consensus on the open questions above after discussing with key stakeholders (Web Team, Performance Team, etc).
[] Publish the guidelines in an appropriate location on-wiki and share them with interested parties