Libraries

Assuming that you already have the CSS/JS files, libraries are defined inside a module_name.libraries.yml file in the module root folder. A simple example of a library definition inside this file would look like this:

my-library:
 version: 1.x
 css:
   theme:
     css/my_library.css: {}
 js:
   js/my_library.js: {}

This is a standard YAML notation by which we define a library called my-library and provide some information about it. We can specify a version number and then add as many CSS and JS file references as we need. The file paths are relative to the module folder this library definition is in, and we can add some options between the curly braces (more advanced, but we will see an example in a moment).

Additionally, you'll note that the CSS file has an extra level key called theme. This is to indicate the type of CSS to be included and can be one of the following (based on SMACSS (https://smacss.com/) standards):

• base: Usually contains CSS reset/normalizers and HTML element styling
• layout: High-level page styling, such as grid systems
• component: UI elements and reusable components
• state: Styles used in client-side changes to components
• theme: Visual styling of components

The choice here is also reflected in the weighting of the CSS file inclusion, the latter being the "heaviest"—it will be included last.

Another important aspect of using libraries in any application is the ability to include externally hosted files (usually from a CDN) for better performance. Let's take a look at an example library definition that uses externally hosted files:

angular.angularjs:
   remote: https://github.com/angular/angular.js
   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 }

This example is taken from Drupal.org (https://www.drupal.org/docs/8/creating-custom-modules/adding-stylesheets-css-and-javascript-js-to-a-drupal-8-module) on defining libraries in Drupal 8. However, as you can see, the structure is the same as our previous example, except that it has some more meta information regarding the external library. And instead of a local path reference, we have a remote URL to the actual resource. Moreover, we also see some options within the curly braces with which we can specify that the file is actually externally located and minified.

An important change when it comes to JS in Drupal 8 is that Drupal no longer includes all libraries such as jQuery by default. It does so only where and when it's needed. This has, therefore, brought the concept of library dependencies to the forefront, as certain scripts require other libraries to be loaded for them to work.

Let's assume that my-library depends on jQuery and specify it as a dependency. All we need to add to our library definition is the following:

dependencies:
  - core/jquery

Keep in mind that the dependencies key is at the same YML level as css and js.

With this, we declare the Drupal core jQuery library to be required by our library. This means that if we use our library somewhere and jQuery is not included, Drupal will process the dependencies and include them all. A side-benefit of this is that dependencies are always included before our scripts, so we can also control that.

The core/jquery notation indicates that the extension (module or theme) that defines the jquery library is Drupal core. If it had been a module or theme, core would have been replaced by the module or theme machine name. So, for example, to use our new library somewhere, it would be referenced as module_name/my-library.