< ResourceLoader
MediaWiki version:
≥ 1.41
Gerrit change 911307

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

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

How to install a foreign resource

  1. Add or update the url(s) for the upstream module in foreign-resources.yaml.
    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 [email protected], use https://registry.npmjs.org/jquery-client/-/jquery-client-9.2.0.tgz.
  2. If the upstream maintainers publish an integrity hash, set that as well.
    Otherwise, use manageForeignResources.php to compute the integrity hash. Run php manageForeignResources.php --extension <my extension name> make-sri <my module name> - 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 dest keys. Once you've set any dest keys, run php manageForeignResources.php --extension <my extension name> update <my module name>.

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:

  • file: For a plain file.
  • multi-file: For multiple plain files.
  • tar: For a tarball archive (file may be compressed).
  • doc-only: For documenting that a package is used, without managing it

Shared fields

The following fields are shared by all package types:

  • license: SPDX license identifier
  • homepage: [optional] Homepage URL of library shown on Special:Version
  • version: [optional] Version string of library shown on Special:Version

The "file" type

Besides the shared ones, the following fields are used:

  • src: Full URL to the remote resource.
  • integrity: SRI cryptographic hash.
  • dest: [optional] The file name to use in the module directory. Default: Basename of URL.

For example, the following would produce resources/lib/mymodule/x.js:

    mymodule:
      type: file
      src: https://mymodule.example/1.2.3/x.js
      integrity: sha384-Je+NE+saisQuoi

The "multi-file" type

Besides the shared ones, the following fields are used:

  • files: An object mapping destination paths to src and integrity keys.

For example:

    mymodule:
      type: multi-file
      files:
        x.js:
          src: https://mymodule.example/1.2.3/x.js
          integrity: sha384-Je+NE+saisQuoi
        x.css:
          src: https://mymodule.example/1.2.3/x.css
          integrity: sha384-Je+NE+saisQuoi

The "tar" type

Besides the shared ones, the following fields are used:

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

For example:

    mymodule:
      type: tar
      src: https://registry.npmjs.org/jquery-client/-/jquery-client-9.2.0.tgz
      integrity: sha384-Je+NE+saisQuoi
      dest:
        package/dist/x.js:
        package/dist/i18n:
        package/dist/style/*.css: themes

The above would extract the x.js file, the i18n directory (recursive), and any *.css files from the style 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.

Notes

  1. ↑ Note that this is not a configuration global but a core attribute; changing $wgForeignResourceDirs doesn't achieve anything.
This article is issued from Mediawiki. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.