Vue.js/Guidelines

Get Vue.js from ResourceLoader
Developers should rely on the version of Vue that is already provided via ResourceLoader rather than bundling or vendoring their own copy of the library. Currently MW ships Vue 3 with the Compatibility Build included.

Developers of skins or extensions which list "vue" as a dependency in  or   can require the library as they would any other RL module.

Developers of gadgets, or of any feature where Vue is to be loaded conditionally, can load the Vue module on the client-side:

Use Single-file components
MediaWiki supports Vue single-file components (aka  files) within any ResourceLoader module that is using the packageFiles feature. However, MediaWiki's support for single-file components is incomplete, and has the following limitations:


 * is not supported
 * Advanced style features, such as,  , and   in styles are not supported
 * Src Imports are not supported (but support for this feature could potentially be added, if developers find it useful)
 * Pre-processors, such as  or   (TypeScript) are not supported. For styles, only   is supported.
 * LESS styles are processed using MediaWiki's LESS processor, which uses an old version of LESS. On the other hand, this means all the features supported in other LESS files in MediaWiki are supported here too.
 * ES6  and   are not supported. Instead of , use  ; instead of   use  . Other ES6 syntax is supported.
 * ES2016 and newer syntax is not supported. Notable examples of unsupported syntax include the spread operator in object literals, / , and  /.
 * Self-closing tags for components (e.g. ) are not supported. Instead, you have to use open and close tags (e.g.  ).
 * Component tags using PascalCase (e.g. ) are not supported. Instead, you have to use kebab-case for component names (e.g.  ).
 * files are only supported in package modules (modules that use )

If you try to use an unsupported SFC feature, ResourceLoader will throw an error at runtime. Unsupported JS or template syntax results in a lint error, so make sure you set up linting for your code to catch these, as well as other pitfalls and style guideline violations.

Initialize with
To mount your component to the DOM, use. This function works the same as, but adds shared MediaWiki-specific plugins for internationalization and error logging. The code mounting your component should be in a simple init file that requires the top-level component (plus any stores and plugins) and mounts it to a placeholder div. Other logic and UI code should live in other files (for example, the top-level component) as much as possible. Conventionally, the top-level component file is called, unless there are multiple entry points that each have their own top-level component.

A simple example of an init file would look like this: A more complex init file that uses a Vuex store and a custom plugin would look like this:

Write Vue3-compatible code
MediaWiki uses the compatibility build of Vue 3. This means that Vue will try to provide compatibility with Vue 2 code by default, which breaks certain Vue 3 features (in particular  on components, and setting attributes to  ). To avoid this breakage, all new code written for Vue 3 (and old code that has been fully migrated to Vue 3) must set  in the component definition of every component. For an example of how to do this, see the code sample above. Once all old code written for Vue 2 has been migrated to Vue 3, MediaWiki will migrate to the non-compatibility build of Vue 3. Once that has happened, these compatConfig settings will no longer be necessary.

Don't rely on build tools or server-side rendering
In the wider Vue.js community, developers make frequent use of Node.js build tools like Vite, Rollup, Next.js, etc. MediaWiki is a PHP application, and currently no Node.js service is available for use in production in WMF projects. For the time being, developers working with Vue in MediaWiki must limit themselves to client-side functionality only. The Design Systems Team is currently exploring ways to support a front-end build step or server-side component rendering, but this remains experimental.

Use other MW-provided libraries when necessary
Vuex 4 is available for use in MediaWiki. Pinia, the new official state management library for use with Vue 3 and successor to Vuex 4, is currently awaiting security review (see T308495). If you're building a project with Vue 3 and want to use Pinia, please add a comment to that task so we can connect the security review with a project timeline.

Code style guidelines
See MediaWiki's Vue coding conventions, which are largely based on the official Vue Style Guide. We use ESLint to enforce these conventions; see here for how to set up ESLint in your repository.

General guidelines

 * Avoid globals of all kinds. Instead, pass the dependencies needed in from the outermost to the part that needs it.
 * Avoid jQuery as a dependency. There are several reasons for limiting jQuery usage including:
 * jQuery is a large dependency both in terms of bytes shipped to users (performance) and comprehension (API) but its usefulness is less and less. For libraries, jQuery as a dependency especially limits reusability by third parties.
 * The jQuery API is invasive--any usage returns jQuery specific types that are cumbersome to pick apart and usually results in further usage whether it’s truly necessary or not.
 * Usage of jQuery has encouraged construction of entire user interfaces by manually assembling bits and pieces of HTML wrapped in jQuery parser calls. This imperative style is challenging to read, verbose, difficult to maintain, unwieldy to compose, and doesn’t scale well to application development. For user interface development especially, Vue.js is the greatly preferred alternative.
 * Since the need for jQuery is diminishing, it is perceived as a redundant technology (e.g., GitHub removed its usage in 2018 and close proximity to or, worse, dependency on it makes our code appear out of fashion which is unbecoming to newcomers.