Skip to content

libman.json reference

Jump to bottom
Jimmy Lewis edited this page Apr 24, 2025 · 9 revisions

The libman.json file is a manifest containing a list of the libraries used by the current project. It is similar to Bower's bower.json and npm's packages.json in that aspect.

Example

This example shows a libman.json file with 2 libraries defined - one from the cdnjs provider and one from the file-system provider.

{
  "version": "1.0",
  "defaultProvider": "cdnjs",
  "defaultDestination": "js/lib",
  "libraries": [
    {
      "library": "jquery@3.2.1",
      "files": [ "jquery.min.js" ]
    },
    {
      "provider": "filesystem",
      "library": "../../path/to/file.js",
      "destination": "js/files",
      "files": ["file.js"]
    }
  ]
}

For advanced scenarios, a library can specify fileMappings which allow multiple, more complex file installations. The following example installs the dist/js assets to one location and the dist/css assets to another location, and the dist/ folder is omitted in both destinations.

{
  "version": "3.0",
  "libraries": [
    {
      "library": "bootstrap@5.3.5",
      "provider": "jsdelivr",
      "fileMappings": [ 
        {
          "root": "dist/",
          "destination": "lib/js",
          "files": [ "js/**" ]
        },
        {
          "root": "dist/",
          "destination": "lib/css",
          "files": [ "css/**" ]
        }
      ]
    }
  ]
}

The fileMappings feature requires version 3.0 or higher.

Reference

version

Specifies the version of the libman.json syntax being used on the file. The only valid values are "1.0" and "3.0" currently, but that may change with future versions.

Type: string

defaultProvider (optional)

Use this field to specify a default provider to avoid having to specify the provider in the individual library entries (see below). If a package has a "provider" property specified, then that will always win over the "defaultProvider".

Type: string

defaultDestination (optional)

Use this field to specify a default destination to avoid having to specify the destination in the individual library entries (see below). If a package has a "destination" property specified, then that will always win over the "defaultDestination".

defaultDestination can use [Name] and [Version] to represent the library name and version of the installed library. These macros do not apply to other destination fields.

Type: string (a valid provider id)

libraries

This is an array of objects describing an individual library.

Type: array of library objects

libraries.provider

A string matching the id of a known provider. This field is required if the root property "defaultProvider" is not set.

Type: string

libraries.library (required)

The library is a identifier for a library that is uniquely identifiable by the specified provider.

Type: string

libraries.destination

The destination is a folder path relative to the libman.json file. It represents the folder you want the library files copied to. This field is required if the root property "defaultDestination" is not set. If a fileMapping has a destination set, it will win over this value.

Type: string

libraries.files (optional)

The files array is a list of files from the individual library you wish to copy to your project. It allows you to copy just the files from the library you need. Some providers leaves the files array optional which means that when not specified, all files from the library will be copied to the project.

Type: array of string

libraries.fileMappings (optional)

This fileMappings array allows more complex ways to map files from the library into your project. It can take multiple subsets of files and install them independently.

libraries.fileMappings.root (optional)

The root property defines a starting directory within the library. This affects which files are included, as well as the destination path - the relative path prefix is preserved when files are installed, but the root segments are omitted.

For example, given a library:

SampleLibrary@1.0.0
  - Folder
    - SubFolder
      * subFolderFile.js
    * folderFile.js
  * rootFile.js

A fileMapping which specifies the root as Folder would omit that portion from the files patterns specified.
Example:

{
    "root": "Folder/",
    "destination": "lib/Sample",
    "files": [
      **/*.js
    ]
}

This fileMapping would install files lib/Sample/folderFile.js and lib/Sample/SubFolder/subFolder.js

Type: string

libraries.fileMappings.files (optional)

This specifies which files are included in the mapping. If omitted, the mapping will contain all files in the library. If root is specified on the fileMapping, then all file names in this array are determined relative to that subpath of the library.

Type: array of string

libraries.fileMappings.destination

This specifies the destination relative to the project where the files in this mapping should be installed. It is optional if either libraries.destination is set, or if the root "defaultDestination" is set.

Type: string

Clone this wiki locally