Third-party library manifest file rules

This topic explains what Third-party Library Manifests (library.manifest files) are, why you might need to use them, and the rules for doing so. For details of adding third-party code libraries to your BladeRunner application, see How Can I Add Third-party Libraries to an App?

Third-party library.manifest files allow you to specify JavaScript and CSS files that will be loaded for a third-party library, and also let you specify dependencies between different third-party libraries. Any image files referred to by the third-party CSS will be loaded implicitly.

Manifest files are processed by the JavaScript bundler and the CSS bundler, but they are not compulsory; if a library.manifest is not present in the folder of a particular third party library, the bundlers will revert to the default behaviour described under Rules, below.

Manifest File Format

A third-party library manifest is essentially a Java .properties file with the name "library.manifest". It contains the following keys:

Key Value

depends

If the library described by this manifest is dependent on any other third-party libraries, they should be listed under this key. Each listed name should correspond to the folder name of that library, as it exists within the thirdparty-libraries/ directory. Multiple dependencies should be separated by commas.

js

This key specifies the JavaScript files that will be included by the JavaScript bundler for this library. If there is more than one JS file, they should be separated by commas.

css

This key specifies the CSS files which will be included for this library by the CSS Bundler. If there is more than one, they should be comma-separated.

For example:

Sample directory structure

Contents of a sample library.manifest file

depends: amcharts
js: library-file-1.js, library-file-2.js
css: style.css

In the above example, the library.manifest file is stating that it has a dependency on amcharts (and its library.manifest contents).

Now, when this library is referenced, it will load amcharts as a dependency.

Rules

  1. Each third-party library can (but does not have to) have one library.manifest file, which is stored in the root folder for that library’s resource files.

  2. If "depends" is absent from the manifest, the library is considered to have no dependencies.

  3. If "js" is absent from the manifest, only the first .js file in the library directory will be included by the JavaScript Bundler.

  4. If "css" is absent, no CSS files will be included for the library.

    At time of writing, a known issue means that all CSS files present in the library directory will be included, whether in the manifest or not, but this won’t be the case for long, and if you want to include CSS within a library, it is better to declare it in the manifest.

  5. If any of these keys has multiple values, the order in which they are listed determines the include order in which the corresponding library files will be loaded.

  6. If a library does not have a library.manifest file, the library will be handled by the default behaviour. This means that the rules for all three keywords being absent will be applied. I.e:

    1. No dependencies will be assumed.

    2. Only the first .js file in the library folder will be included by the bundlers.

    3. No CSS will be included by the bundlers.