Working with Drupal Libraries

Bundling Bolt for the web requires the use of Webpack.

Webpack uses its own dependency management and aggregation systems, which aren't directly compatible with the Drupal Library system. In order to use the two systems together, there are some conventions to follow.

Automatic Library Generation

Webpack will automatically create Library entries for each entrypoint. The library entries are based on the package name, so it is important to ensure you follow the proper naming conventions when creating packages.

The library name in Drupal is the same as the entrypoint package name, with the @ removed from the front.

For example, to include @pega_bolt_theme/components-messages in Drupal, you would attach the Drupal library:

pega_bolt_theme/components-messages

This will also pull in any required webpack dependencies.

Adding Drupal Library Dependencies

To tell webpack that a javascript file depends on a Drupal Library we can use the @drupal(<library-name>) convention.

For example, to add a dependency on the Drupal core javascript you can add this to the top of your javascript file:

require('@drupal(core/drupal)')

This corresponds to the Drupal core library entry for core/drupal.

Externals

Several commonly used Drupal libraries are mapped to global window variables.

Most javascript will probably contain somthing that looks like this.

const Drupal = require('@drupal(core/drupal)'),
  $ = require('@drupal(core/jquery)')

Drupal.behaviors.myBehavior = {
  attach() {
    $('...')
  }
}

This tells webpack to add dependencies on the Drupal libraries core/drupal and core/jquery. Additionally webpack is configured to import window.Drupal when it sees core/drupal, and window.jquery when it sees core/jquery.

A full list of supported externals is: