Library definition structure

In order to be useful to other modules Libraries API needs a list of known libraries and basic metadata about each. The metadata about an individual library is referred to as it definition file and is managed independently from any individual modules that use the library.

Each library definition file is a simple structured JSON data object for maximum portability. This data in this file is similar to what was declared in hook_libraries_info() implementations in 7.x-2.x with a few key differences.

Definition file name (Library machine name)

A central part of a library's metadata is the library's machine name or ID. This machine name also serves as the name of the JSON file containing the library's definition, and therefore the unique URI used to access the definition locally or remotely. For maximum interoperability the machine name must consist of only lowercase ASCII letters, numbers, and underscores. As the machine name is the single identifier of a library and is independent of any given module or theme name it must be unique among all libraries known to Libraries API.

Example definition with property documentation

Below is a simple example for quick reference followed by additional documentation of each property. This definition could serve as a starting point when creating a new definition from scratch. Many additional (real) examples can also be seen by browsing the current global library registry.

This example definition, using library machine name "example", would be accessible via global remote registry at:
http://cgit.drupalcode.org/libraries_registry/plain/registry/8/example.json

{
    "name": "Example Library",
    "type": "asset",
    "vendor url": "http:\/\/example.com",
    "download url": "http:\/\/example.com\/download\/example.zip",
    "css": {
        "base": [
            "css\/example-styles.css"
        ]
    },
    "js": {
        "js\/example-logic.js": {}
    },
    "version_detector": {
        "id": "line_pattern",
        "configuration": {
            "file": "js\/example-logic.css",
            "pattern": "\/Example Library v([0-9a-zA-Z\\.-]+)\/",
            "lines": 3,
            "columns": 50
        }
    },
    "variants": {
        "minified": {
            "css": {
                "base": [
                    "css\/example-styles.min.css"
                ]
            },
            "js": {
                "js\/example-logic.min.js": {}
            }
        }
    }
}

Currently recognized properties

• name: (string) The official, human-readable name of the library.
• type: (string) The library type plugin used to load and manage the library in Libraries API. The following types are native to Libraries API, though additional type plugins can be created (see the Advanced API docs for more):
  • "asset": Applicable for asset libraries that declare css and js additions.
  • "asset_multiple": Applicable for asset libraries that contain multiple "sub" libraries, each of which can be loaded individually. See the "Multiple Asset Libraries" section below for more.
  • "php_file": Applicable for simple php includes that cannot be handled via a formal dependency management tool such as Composer
• vendor url: (string, optional) The URL of the homepage of the library.
• download url: (string, optional) The URL of a web page on which the library can be obtained.
• css: (object, optional for asset libraries) List of CSS files to include as part of the library nested by SMACSS groupings. The structure of this property must follow the "css" property structure used for a core library definition.
• js: (array, optional for asset libraries) List of JS files to include as part of the library. The structure of this property must follow the "js" property structure used for a core library definition.
• files: (array, required for php libraries) List of PHP files to include as part of the library. All file paths are relative to the library source root.
• version detector: (object) The version detector plugin used to calculate the currently installed library version. This consists of:
  • id: (string) The version detector plugin ID in libraries API. See the configuration property below for examples.
  • configuration: (object) The configuration needed by the plugin to determine the version. The specific properties will depend on the plugin id. The following detector plugins, and their configuration properties, are native to Libraries API, though additional detector plugins can be created (see the Advanced API docs for more):
    • "line_pattern": Reads the version from a text pattern inside a library file. Uses configuration:
      • file: (string) The filename to parse for the version, relative to the library path.
      • pattern: (string) A string containing a regular expression (PCRE) to match the library version.
      • lines: (string, optional) The maximum number of lines to search the pattern in. Defaults to 20.
      • columns: (string, optional) The maximum number of characters per line to take into account. Defaults to 200.
    • "static": Provide a static version as part of the definition itself. Uses configuration:
      • version: (string) The static version declaration.

Planned properties (not yet implemented)

• variants
• etc...

Multiple Asset Libraries

Individual asset libraries can package multiple "sub" libraries that can be loaded independently by using the "asset_multiple" library type. Each sub-library shares the same high-level library metadata (name, vendor URL, etc.) but can declare different file assets. The sub-libraries are then identified via a unique name that consists of the library machine name plus the sub-library machine name separated by a period (.) delimiter (e.g "example_multiple.first"). Within the library definition the unique asset files for a sub-library can be defined by nesting the "js" and "css" properties under the machine name of the sub-library. For example, an example_multiple.json definition may declare both "example_multiple.first" and "example_multiple.second" sub-libraries as follows:

{
  "name": "Example Library with Multiple Sub-Libraries",
  "type": "asset_multiple",
  "version_detector": {
    "id": "static",
    "configuration": {
      "version": "1.0.0"
    }
  },
  "remote_url": "http://example.com",
  "libraries": {
    "first": {
      "css": {
        "base": {
          "example.first.css": {}
        }
      },
      "js": {
        "example.first.js": {}
      }
    },
    "second": {
      "css": {
        "base": {
          "example.second.css": {}
        }
      },
      "js": {
        "example.second.js": {}
      }
    }
  }
}