Overview

Two years have passed since the original RFC around using 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, 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 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: 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 linter configuration.

Dedicated MediaWiki Special Page

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

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 if we shipped only the Vue runtime and somehow did just-in-time template compilation of .vue files in ResourceLoader (assuming this was feasible)?
• What about the aggressively-optimized 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.

• 1. Acceptance criteria
• Deliver a proposal that outlines a few options for paths forward with Vue/Codex, to review with key stakeholders (DST to draft)
• 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