Manual:Coding conventions/Vue
File:OOjs UI icon check-constructive.svg | <translate> This page documents a MediaWiki [[<tvar name=1>Special:MyLanguage/Development guidelines</tvar>|development guideline]], crafted over time by developer consensus (or sometimes by proclamation from a lead developer)</translate> |
This page is currently a draft.
|
This page describes coding conventions for Vue in the MediaWiki codebase. See also the JavaScript and CSS/LESS conventions which apply to such code within Vue files.
Linting
We use ESLint as our code quality tool.
The custom config for Wikimedia (eslint-config-wikimedia
) contains both general and MediaWiki-specific rules for Vue code.
Making ESLint recognize component definitions
You must include // @vue/component
above a component definition for it to be recognized as such by ESLint (see example below).
If ESLint detects that this comment is missing, it will warn you and tell you to add it, but it won't be able to interpret your code as Vue code until you do so.
<script>
var AnotherComponent = require( './AnotherComponent.vue' );
// @vue/component
module.exports = {
name: 'MyComponent',
components: { 'another-component': AnotherComponent },
...
}
</script>
Setting up ESLint
If you are already using the wikimedia/client
or wikimedia/client-es6
preset from the eslint-config-wikimedia package in your .eslintrc.json
, lint rules for Vue are automatically applied to .vue
files.
Starting with version 0.23.0 of eslint-config-wikimedia, the ES5 rules default to Vue 2, and the ES6 rules default to Vue 3.
New code should be written using Vue 3 (and consequently, using ES6); the ES5+Vue2 rules are only meant for legacy code.
Naming
File:Under construction icon-blue.svg | <translate> This section is currently a draft.</translate> <translate> Material may not yet be complete, information may presently be omitted, and certain parts of the content may be subject to radical, rapid alteration.</translate> <translate> More information pertaining to this may be available on the [[<tvar|1>Manual talk:Coding conventions/Vue</>|talk page]].</translate> |
Single-file Components
Vue's single-file components format (.vue
) should be used wherever possible.
This allows templates, logic, and (optionally) styles for a given component to live together in one file.
ResourceLoader supports on-the-fly compilation of .vue
files (see here for more info about using Vue with ResourceLoader).
This allows developers to write .vue
files without needing to rely on any new build tools (Rollup, Webpack, etc), while still benefiting from the various optimizations that ResourceLoader provides for front-end code (RTL styling via CSS Janus, JS minification, etc).
Where possible, Vue code should follow the Vue community's style guide. In particular, all recommendations in "Priority A: Essential" should be followed at all times. Any MediaWiki-specific exceptions will be called out below. If ESLint is set up correctly, it will enforce all rules from the Vue style guide (Priority A, B and C) as well as MediaWiki-specific rules and exceptions.
General Structure
Single-file components are broken into three sections: <template>
, <script>
, and <style>
; components should follow this order, with the <style>
block being optional.
Each component file should be listed individually under the packageFiles
property in the appropriate module definition in extension.json
.
Make sure that the module definition also includes the vue
module as a dependency.
Template
- Component tags must not be self-closing: this is a departure from Vue's style guide recommendations based on current limitations in ResourceLoader. Regardless of whether a component uses slots, it should have a closing tag.
Correct: | Wrong (self-closing components): |
---|---|
<slot-based-component>
<h1>Hello world</h1>
</slot-based-component>
<props-component
:foo="bar"
:baz="quux"
@click="doSomething"
></props-component>
<basic-component></basic-component>
|
<props-component
:foo="bar"
:baz="quux"
@click="doSomething"
/>
<basic-component />
|
- Component tags must use kebab-case, as opposed to PascalCase. This is also a departure from Vue's style guide recommendations due to limitations in ResourceLoader.
Correct (kebab-case): | Wrong (PascalCase): |
---|---|
<some-component :foo="bar"></some-component>
|
<SomeComponent :foo="bar"></SomeComponent>
|
- Use the directive short-hands (
:foo
instead ofv-bind:foo
,@click
instead ofv-on:click
). - Elements with multiple attributes should break them out onto separate lines
- Component templates should only include simple expressions; for anything more complex, define a computed property or method in the
<script>
section instead. - Message strings in templates must be internationalized just like in standard JS or PHP UI development. See the documentation on internationalization in Vue for more information.
- Use
v-html
sparingly and carefully, because it can lead to XSS vulnerabilities if used incorrectly. If you must usev-html
, carefully audit the code that generates the HTML to ensure that all untrusted input is escaped.- For parsed i18n messages (
mw.message( 'foo' ).parse()
), usingv-html
is not necessary in most cases. Usev-i18n-html
instead, if possible. - Because
v-html
is discouraged, using it causes an ESLint error. If you must use it, add<!-- eslint-disable-next-line vue/no-v-html -->
on the line above the tag that usesv-html
to dismiss the ESLint warning. - Before adding this override, double-check your code to ensure your usage of
v-html
is safe.
- For parsed i18n messages (
Script
- Single-file components delivered via ResourceLoader should follow the CommonJS module format and should use ResourceLoader's PackageFiles feature. This means that each component file should include a
module.exports
statement, and should import other code usingrequire():
var OtherComponent = require( './OtherComponent.js' ); // @vue/component module.exports = { name: 'MyComponent', components: { 'other-component': OtherComponent } // … etc. };
- Component options should be specified in the order defined here: https://github.com/wikimedia/eslint-config-wikimedia/blob/master/vue-common.json. Generally this means:
name
,components
,mixins
,props
,emits
,setup
,data
,computed
properties,methods
, watchers, lifecycle hooks, and finally render functions (in the rare situations where those need to be defined manually). - Render functions should be avoided outside of special cases; HTML-style templates are preferred instead. The
vue
module provided in MediaWiki core is the full version, which includes the template compiler. - Use prop definitions and consider specifying defaults or validating data where necessary. Boolean props should default to false.
- Avoid implicit parent-child communication and the mutation of received props within a child component. Prefer the "props down / events up" approach
Style
- MediaWiki CSS and LESS conventions apply, styles are linted with custom Wikimedia stylelint config
- Since each component should contain a single top-level component, styles should be nested under a single selector (if using LESS)
- Conditional CSS classes should be used for dynamic styles. Object syntax is preferred for computed properties that are bound to class attributes.
- Vue transition names should follow the same pattern as CSS class names (e.g. including an extension-specific prefix)
Progressive Enhancement
TBD: define a no-JS fallback for most features you build this way.