ResourceLoader/ES6

From mediawiki.org
Jump to navigation Jump to search

Since MediaWiki 1.36, you can use ES6 in JavaScript code that is loaded through ResourceLoader. ES6 code will only be served to browsers that support it: ResourceLoader will detect whether the user's browser supports ES6, and will not load your code if it doesn't.

Some older browsers (most notably Internet Explorer 11) are supported by MediaWiki but do not support ES6. Attempting to load an ES6 module in these browsers will gracefully be refused.

When it's OK to use ES6[edit]

ES6 may be used in cases where support for older browsers like IE11 is not required, or where you have a server-side fallback that works in all supported browsers. Typically, this means individual modal features, or standalone special pages. ES6 should generally not be used in code that is intended to be reused in many places, such as libraries or utility modules. This is because the ES6 requirement is viral: if module A requires ES6, and module B depends on A, then B will also fail to load in a non-ES6 browser, even if B itself does not use ES6. For this reason, code that is intended to be used by both ES5 and ES6 code must continue to be written in ES5.

Making a ResourceLoader module ES6-only[edit]

MediaWiki version:
1.36

Every ResourceLoader module that contains ES6 code must indicate this in its module definition, by setting the es6 flag to true (see examples below). Modules with this flag will only be loaded in browsers that support ES6.

Example ES6 module definition in MediaWiki core[edit]

In resources/Resources.php:

'myFeature' => [
    'es6' => true,
    'packageFiles' => [
        'resources/src/myFeature/index.js',
        'resources/src/myFeature/foo.js',
        // more files here
    ],
    // ...
]

Similarly, es6 flag can be used with scripts property of module declarations.

Example ES6 module in an extension or skin[edit]

In extension.json or skin.json:

{
    "ResourceModules": {
        "ext.myFeature": {
            "es6": true,
            "packageFiles": [
                "resources/src/myFeature/index.js",
                "resources/src/myFeature/foo.js"
            ]
        }
    }
}

Setting up linting for ES6[edit]

The standard eslint configuration for MediaWiki code[1] expects ES5, so using ES6 syntax will cause lint errors. To configure the linter to allow ES6, you have to either change the linter configuration for your entire repository (if all code is going to be ES6), or add a local override in the directory for the module with your ES6 code.

Configuring a module directory to use ES6 (recommended)[edit]

Use this if you are adding ES6 code to MediaWiki core, or to another repository that also contains ES5 code.

Put your ES6 code in its own directory or directories, so that every directory contains either only ES5 files or only ES6 files. In each of the ES6 directories, create an .eslintrc.json with the following contents:

{
    "extends": [
        "wikimedia/client-es6"
    ]
}

Configuring the entire repository to use ES6[edit]

Use this if all JavaScript code in your entire extension or skin is ES6.

Edit the .eslintrc.json file in the root directory of your repository, and change wikimedia/client-es5 to wikimedia/client-es6. A minimal example looks like this:

{
    "root": true,
    "extends": [
        "wikimedia/client-es6",
        "wikimedia/jquery",
        "wikimedia/mediawiki"
    ]
}

Notes[edit]