ResourceLoader/Foreign resources

Foreign resources are upstream frontend libraries registered in MediaWiki as ResourceLoader modules. They are defined a file called. This tracks the source and version of upstream projects currently in use.

In MediaWiki core, foreign resources are stored in the  directory. Extensions and skins can use the  attribute in their  /  file to manage a similar directory. That directory needs to contain a  file. The manageForeignResources.php maintenance script can be used to install, update, or verify these resources.

Minified files
You may use minified distribution files provided by the library, but in that case, the corresponding non-minified files must also be downloaded and committed, and they should be used when ResourceLoader debug mode is active. This is because of the requirements for Debian packages, and to improve the developer experience given the lack of support for source maps of external libraries. (related tasks: T217351, T257878, T346075)

How to install a foreign resource

 * 1) Add or update the url(s) for the upstream module in  .  Look at other modules for examples. To install a module from npm, we use the tarball distribution from npmjs.org. This is the same as what the npm CLI uses. For example, to install , use.
 * 2) If the upstream maintainers publish an integrity hash, set that as well.  Otherwise, use   to compute the integrity hash. Run   - this will download the specified file(s) and print their integrity hashes, already formatted in YAML, ready for copying to this file.
 * 3) Last but not least, decide where files go.  If you specified a direct url to JavaScript or CSS file, this step is optional. See the corresponding documentation section below for more information and examples for   keys. Once you've set any   keys, run.

foreign-resources.yaml format

 * See resources/lib/foreign-resources.yaml for up-to-date documentation

Each top-level key must use one of these types:
 * : For a plain file.
 * : For multiple plain files.
 * : For a tarball archive (file may be compressed).
 * : For documenting that a package is used, without managing it

Shared fields
The following fields are shared by all package types:
 * : SPDX license identifier
 * : [optional] Homepage URL of library shown on Special:Version
 * : [optional] Version string of library shown on Special:Version

The "file" type
Besides the shared ones, the following fields are used:
 * : Full URL to the remote resource.
 * : SRI cryptographic hash.
 * : [optional] The file name to use in the module directory. Default: Basename of URL.

For example, the following would produce :

The "multi-file" type
Besides the shared ones, the following fields are used:
 * : An object mapping destination paths to  and   keys.

For example:

The "tar" type
Besides the shared ones, the following fields are used:
 * : Full URL to the remote resource.
 * : SRI cryptographic hash.
 * : [optional] The default is to extract all files from the package. To only extract some of the files or directories, use  to specify files, directories, and/or glob patterns. You can use a site like https://unpkg.com/ to easily inspect an npm package, like  . This field can also be used to extract files to a subdirectory (by default the files and directories listed in   are extracted to the module directory root).

For example:

The above would extract the  file, the   directory (recursive), and any   files from the   directory. They will end up in mymodule/x.js, mymodule/i18n and mymodule/themes, respectively.

The "doc-only" type
This type can be used for packages which are managed in some custom way (e.g. they require a manual build step). manageForeignResources.php will ignore these records, but they will still be shown on Special:Version. Only the shared fields are used.