drupal-libraries-webpack-plugin

drupal-libraries-webpack-plugin

This plugin generates a Drupal asset library file based on a webpack build.

It requires webpack 5 to work. For webpack 4 use the 1.x version of this plugin.

Install

npm install --save-dev drupal-libraries-webpack-plugin

Usage

webpack.config.js

const DrupalLibrariesPlugin = require('drupal-libraries-webpack-plugin');

module.exports = {
  plugins: [
    new DrupalLibrariesPlugin()
  ],
};

By default, when you compile webpack, the drupal library file will be generated to 'webpack.libraries.yml'.

The plugin will automatically figure out what libraries need to depend on other libraries based on the final webpack chunks.

You can explicitly add a Drupal library dependency to module by using a special require statement:

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

Drupal libraries must be added as external dependencies in your webpack configuration:

externals: {
  '@drupal(drupal/core)': 'Drupal'
}

Configuration

path

Type: String|Function

Default: 'webpack.libraries.yml'

Specifies a custom public path for the target webpack file relative to the process working directory.

Minimal example

webpack.config.js

module.exports = {
  plugins: [
  	new DrupalLibrariesPlugin({
  	  path: 'my-theme-name.libraries.yml',
  	})
  ],
};

Advanced Example

Split a library into multiple library files.

module.exports = {
  plugins: [
  	new DrupalLibrariesPlugin({

  	  path: (library, metadata) => {
  	    const lib1 = new DrupalLibraryFile('a.libraries.yml'),
  	    	lib2 = new DrupalLibraryFile('webpack.libraries.yml')

  	    Object.keys(library).forEach(name => {
  	      if (name == 'a') {
  	        lib1.add(name, library, metdata)
  	      }
  	      else {
  	        lib2.add(name, library, metadata)
  	      }
  	    })

  	    return [lib1, lib2]
  	  }
  	})
  ],
};

nameGenerator

Type: Function

Default: nameGenerator

Generates a library name for a chunk.

Minimal example

webpack.config.js

module.exports = {
  plugins: [
  	new DrupalLibrariesPlugin({
  	  nameGenerator: chunk => chunk.hash
  	})
  ],
};

requirePattern

Type: RegExp

Default: /^@drupal\(([^\)]+)\)$/

The pattern to use for detecting drupal library dependencies.

module.exports = {
  plugins: [
  	new DrupalLibrariesPlugin({
  	  // Only pick up require('jquery') or require('Drupal') statements.
  	  requirePattern: /^(jquery|Drupal)$/
  	})
  ],
};

prepareFile

Type: Function

Default: DrupalLibrariesPlugin.defaults.prepareFile

Prepares a library file that is about to be written.

webpack.config.js

module.exports = {
  plugins: [
  	new DrupalLibrariesPlugin({
  	  prepareFile: (file, compiler, compilation) => {
  	    // Add an extra entry to the file when outputting
  	    file.content['external'] = {
  	      remote: 'https://external-library.js',
  	    }
  	    return DrupalLibrariesPlugin.defaults.prepareFile(file, compiler, compilation)
  	  },
  	})
  ],
};

libraryEntryGenerator

Type: DrupalLibraryEntryGenerator

Default: DrupalLibraryEntryGenerator

Generates a flat Drupal library entry as a javascript object from a DrupalLibraryMetadata object.

webpack.config.js

class StaticVersionLibraryGenerator extends DrupalLibraryEntryGenerator {
  constructor(version) {
    this.version = version
  }

  async versionGenerator(metadata) {
    return this.version
  }
}

module.exports = {
  plugins: [
  	new DrupalLibrariesPlugin({
  	  libraryEntryGenerator: new StaticVersionLibraryGenerator('2.0'),
  	})
  ],
};