We have a controversial, but simple approach to implementing JavaScript libraries you find online.

Let’s say you want to use a JavaScript library in your component. Then you want the visitor of your site to load in that JavaScript library before executing your custom JavaScript. That's all it is, so with that in mind, let’s not make it more complex than it should be.

Downloading a minified local version #

Compony's recommended way is downloading the library to your local machine, and adding it to a component of choice. It might not be as shiny, as using a CDN or typing a npm command, but it works and is the most secure thing you could do.

Over time, Drupal has become brilliant in handling assets. Using the Libaries API, Drupal enabled us to enjoy the advantages that Drupal offers to the frontend.

Not only that, it will enable us to take advantage of any future benefit, future versions of Drupal will give us.

An example

Let's see how we would include the Select2 library in a component:

node--blog--full
dist
js-badge Created with Sketch.
node--blog--full.js
js-badge Created with Sketch.
node--blog--full.js
js-badge Created with Sketch.
select2.min.js

YAML Created with Sketch.
libraries.yml

node-blog-full:
  version: VERSION
  js:
    select2.min.js: {minified: true, weight: -20}
    dist/node--blog--full.js: {}

The weight: -20 inside the library definition will make sure that the select2.min.js is loaded before we load the node--blog--full.js. And it will also make sure that the library is only loaded on blog-details pages.

Using a CDN means you link to the external library by providing a url in the libraries.yml file. An example of this would look like this:

YAML Created with Sketch.
libraries.yml

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:
   //ajax.googleapis.com/ajax/libs/angularjs/1.4.4/angular.min.js: { type: external, minified: true }

We advice against this because your component shouldn’t rely on the maintenance of an external service. No matter how legit the external service might look, providers go down and services become unavailable. The maintainability of having one site depend on another one, is not worth the developer’s easiness of defining a link in a libraries.yml file.

There is also a security concern: if you link to an external provider, there is no telling when that provider might get hacked.

Installing with npm or Yarn #

Npm is a node package manager that you can use to download contributed scripts from a massive online community.

Compony is still in an early stage, and we are currently working on an approach to integrate the possibilities of npm with Drupal’s Library API. For now it is not possible to keep the Gulp-setup of our theme maintainable and support extra npm-packages installed through npm commands.

Our main concern is keeping Gulp maintainable. This means that your project will be able to update your Compony Gulp if you don't run npm installs for extra libraries.

If you are willing to not update the Compony-gulp in your project over time, you are welcome to use the npm-approach and install extra dependencies.

Webpack integration #

We are actively looking in to what Webpack can offer us, but at the moment we currently also don’t support this yet.