On this page
Including 3rd party libraries
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 }
Drupal 7
The Libraries CDN API project is an API module to query CDN services to automatically provides libraries on your site.
It also provides a kind of autodiscovery for Libraries API (see below) through hook_libraries_info_alter()
.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion