Asset Packagist makes it easy to add external JavaScript libraries to Drupal projects

If you install a Drupal module that requires an external JavaScript library, you are more or less left on your own how to get the library into your project. Some modules will leave instructions on how to install the library manually by downloading, extracting and renaming the folder; some on how to make a custom package definition for the library and many others will totally leave it up to you how you install it.

If you manage your site with Composer, manually downloading and extracting packages is one of the things you wanted to avoid. This means you would most likely also want to manage external libraries with Composer.

Enter Asset Packagist

Asset Packagist provides a repository that allows installation of Bower and npm packages as native Composer packages. You add this one repository to Composer and you are free to install most popular Bower and NPM packages 4000+ each as though the packages are lying on Packagist.

Isn't this so cool?

Adding the Repository

Let's see how easy it is to add the Asset Packagist repository to composer.json and get running with it:

Add the Composer Installers Extender PHP package by oomphinc to your project's root composer.json file, by running the following command:
```
composer require oomphinc/composer-installers-extender
```
If you skip this step the libraries will not be installed in public_html/libraries folder but in the default vendor folder.

Add Asset Packagist to the "repositories" section of your project's root composer.json. This will leave your repositories section looking a little something like this:

    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        {
            "type": "composer",
            "url": "https://asset-packagist.org"
        }
    ],

Register npm and Bower assets as new "installer types" in the "extra" section of composer.json and also register them in "installer-paths" as part of the types of assets to be saved in the public_html/libraries folder. This will leave your "extra" section looking a little something like this:

        "drupal-scaffold": {
            "locations": {
                "web-root": "public_html/"
            }
        },
        "installer-types": [
            "npm-asset",
            "bower-asset"
        ],
        "installer-paths": {
            "public_html/core": [
                "type:drupal-core"
            ],
            "public_html/libraries/{$name}": [
                "type:drupal-library",
                "type:npm-asset",
                "type:bower-asset"
            ],

You are done!

How cool?!

You can now install any library you find on Asset Packagist on your project by using single Composer commands like:
```
composer require bower-asset/colorbox
```
```
composer require npm-asset/jquery-colorbox
```
The two commands above are same library from same repository indexed with different names, 'colorbox' and 'jquery-colorbox'. If you install the Colorbox module you will find the project page recommends the library folder named 'colorbox'. The first command above will install the library with the correct folder name but the second command will install the library with folder name 'jquery-colorbox' inside the libraries folder. If you go with this the module will not find the library. You now will have need to rename 'jquery-colorbox' to 'colorbox' but you don't have to do this. Rather, you would instruct Composer to rename the library before saving it during installation. You will do this by adding an installation path for the specific Colorbox library as so:
```
            "public_html/libraries/colorbox": ["npm-asset/jquery-colorbox"],
            "public_html/libraries/{$name}": [
                "type:drupal-library",
                "type:npm-asset",
                "type:bower-asset"
            ],
```
Remember to add the specific library path above the general configuration.

With this, if you run composer require npm-asset/jquery-colorbox again, the library will be saved correctly as 'colorbox' in the libraries folder.

If there is a library you do not find on Asset Packagist check Packagist to see if it is there e.g. the Drupal community added many of the CKEditor plugins to Packagist. If all fails and you do not find the library then it would be a good time to make a custom package definition for it.

Let's use an example of the DropzoneJS library (just to demo because you can easily find this on both Packagist and Asset Packagist).

Add this bit to your composer.json:

        {
            "type": "package",
            "package": {
                "name": "enyo/dropzone",
                "version": "5.7.1",
                "type": "drupal-library",
                "dist": {
                    "url": "https://github.com/enyo/dropzone/archive/v5.7.1.zip",
                    "type": "zip"
                }
            }
        }

This will get your entire repositories section looking a little something like this:

    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.drupal.org/8"
        },
        {
            "type": "composer",
            "url": "https://asset-packagist.org"
        },
        {
            "type": "package",
            "package": {
                "name": "enyo/dropzone",
                "version": "5.7.1",
                "type": "drupal-library",
                "dist": {
                    "url": "https://github.com/enyo/dropzone/archive/v5.7.1.zip",
                    "type": "zip"
                }
            }
        }
    ],

You will now install the library with the command:

composer require enyo/dropzone

In this definition, you tell Composer the library is of type 'drupal-library' and assets defined of this type are installed in the 'public_html/libraries' folder. Remember we are using DropzoneJS just to demo for other not-so-popular libraries you couldn't find on the repositories.

Note that when you define a custom package like this, it is now up to you to track new releases and update composer.json accordingly.

Last updated: August 26, 2022