Including 3rd party libraries

Last updated on

22 February 2024

Bundling or duplicating third party libraries into Drupal.org repositories is strongly discouraged – see Policy on 3rd party assets on Drupal.org for clarification of policy.

Instead, you should include third party libraries through one of these methods:

Composer
Libraries API module
CDN (not recommended)

Use Composer

If 3rd party library can be downloaded using Composer, just add it as a requirement in your project's composer.json.

For example, if your project requires the Symfony YAML parser, you can use the follwing:

{
  "require": {
    "symfony/yaml": ">=3.1"
  }
}

For a more complex example, see composer.json used by Mobile Detect bridge project.

However, please note that the authors and license segments the Mobile Detect composer.json refers to the authors and license of the Drupal bridge project, not the library that is required. The mobiledetect class/library is actually permissibly licensed under the MIT license.

To discover the license for any required library included using Composer, you may visit the home page of library a look for the licensing information. Also after the library has been installed as part of a Drupal site, references to its public license should be in the library's vendor directory (e.g. sites/all/vendor/project/component/), in its composer.json and/or LICENSE file.

For Drupal 7 you need to make Composer Manager as a dependency of your project in order to use Composer.

For more about using Composer, see: Using Composer to manage Drupal site dependencies.

Use the Libraries API

The Libraries API project provides a method for adding 3rd party dependencies without directly including the code in your Git repo on Drupal.org.

In order to let downstream recipients use it, provide clear instructions to users about how to download these assets from their original source in your project's README and combine them with your project by means of the Libraries API.

For more detailed instructions see: Installing an external library that is required by a contributed module.

Use a CDN

Note that it is in general not a good idea to load libraries from a CDN; avoid this if possible. It introduces more points of failure both performance- and security-wise, requires more TCP/IP connections to be set up, and usually is not in the browser cache anyway. However, 3rd party libraries should not be hosted on Drupal.org as part of your repo – see Policy on 3rd party libraries on Drupal.org for clarification of policy.

Drupal 8 (or later) lets you specify libraries by adding a *.libraries.yml file to the root of your module folder – alongside your *.info.yml file. (If the short name of your module or theme is example, then the file name should be example.libraries.yml).

To include an external library or asset that can be obtained from a CDN, declare the library or asset to be external by specifying type: external. It is also a good idea to include some information about the external library in the definition, such as version and license.

If you want your external file to be requested with the same protocol as the page is requested with, specify a protocol-relative URL.

Example, to get angular.min.js from a CDN:

angular.angularjs:
  remote: https://github.com/angular
  version: 1.4.4
  license:
    name: MIT
    url: https://github.com/angular/angular.js/blob/master/LICENSE
    gpl-compatible: true
  js:
    https://ajax.googleapis.com/ajax/libs/angularjs/1.4.4/angular.min.js: { type: external, minified: true }

If you want to add CSS, here is an example of integrating Font Awesome:

font-awesome:
  remote: https://fontawesome.com
  version: 5.3.1
  license:
    name: MIT
    url: https://github.com/FortAwesome/Font-Awesome/blob/master/LICENSE.txt
    gpl-compatible: true
  css:
    theme:
      https://use.fontawesome.com/releases/v5.3.1/css/all.css: { type: external, minified: true }