CodeCoupler Webpack Externals Plugin Configuration Reference

You have to define every module that should be handled as external in a file named webpack.externals.js in your root project folder. An absolute minimum file content would be:

module.exports = [];

As you can see an array will be defined here. Every item in this array is an object which define an external module. The available options for every entry are:

• module: The name of the module (corresponds to the package name).
• alias: Optional. The module name you can use in your import and require statements instead of the module name.
• global: Optional. The global variable name to access the library provided by the node module.
• entries: Optional. String or array of strings. Name of js or css files to copy from the modules folder to the dist folder and inject links to them into your HTML files.
• copy: Optional. String or array of strings. Globs to copy from the modules folder to the dist folder. This can be used to copy assets like fonts.
• includeExternals: If true the webpack.externals.js of the module will be read and merged (default is true).

The order and dependencies

You have to pay attention to the order. All the injections will be done in the order defined in the configuration file. Because Bootstrap depends on jQuery you have to place the module bootstrap after jquery.

If you want to add just an hint on what a module depents you can add just an entry only with the module name:

module.exports = [
  { module: "jquery" },
  {
    module: "bootstrap",
    entries: ["dist/css/bootstrap.min.css", "dist/js/bootstrap.bundle.min.js"],
  },
];

This configuration tells webpack to copy the bootstrap assets but let the module jquery untouched. This is useful if you want to leave the decission up to the user of your library if jquery should be bundled or not (and what assets exactly should be injected). However putting the module jquery in front of bootstrap will ensure that jquery assets will be injected before bootstrap injections.

A last word to the order concerns the @cc-external packages. Keep in mind that @cc-external packages will be loaded always first.

Recursively include further externals

Now that you have written your library and you want to publish it, you should include the webpack.externals.js in you package. Because this will simplify some steps for the developer using your library.

The developer could install your library with npm i your_library. Because your library have all the external modules listed as dependencies they will be automatically installed, too. The developer have just to install this plugin and point in the webpack.externals.js to your library like this:

module.exports = [
  {
    module: "your_library",
    entries: ["dist/your_library.js"],
  },
];

Now all the externals you have defined in your own webpack.externals.js will be automatically merged into his configuration. Your externals will be placed in front of his externals.

If the developer is using a same module in his configuration, the keys entries and copy will be merged and deduplicated.

This principle will work recursively. That means that the developer using your library himself can include his own webpack.externals.js pointing to your library and publish his work. The next developer have just to point to this library and your externals will also be included.

You can stop including externals of modules by setting includeExternals: false:

module.exports = [
  {
    module: "your_library",
    entries: ["dist/your_library.js"],
    includeExternals: false,
  },
];

Walkthrough Example

Here is an example to define jQuery as an external library:

module.exports = [
  {
    module: "jquery",
    global: "jQuery",
    entries: "dist/jquery.min.js",
  },
];

This configuration will:

1. Exclude the module jquery from the build
2. Define the global variable jQuery as the source for this library
3. Copy the file dist/jquery.min.js from the node_modules folder of jQuery to a subdirectory of your dist folder named vendor/jquery-X.X.X/dist/jquery.min.js (the current version will be read from the current installed package)
4. Copy the corresponding source map (if exists of course) dist/jquery.min.js.map also to the destination folder
5. Inject a link like <script src="vendor/jquery/dist/jquery.min.js"> to your HTML files processed by the html-webpack-plugin

Now we extend the example by adding the Bootstrap module into the configuration:

module.exports = [
  {
    module: "jquery",
    global: "jQuery",
    entries: "dist/jquery.min.js",
  },
  {
    module: "bootstrap",
    entries: ["dist/css/bootstrap.min.css", "dist/js/bootstrap.bundle.min.js"],
  },
];

As you can see, the key global is not necessary and entries can be a single string or an array of strings. All entries must end with .js or .css. All other exetensions will be ignored.

Last but not least we add the module of Font Awesome to the configuration:

module.exports = [
  {
    module: "jquery",
    global: "jQuery",
    entries: "dist/jquery.min.js",
  },
  {
    module: "bootstrap",
    entries: ["dist/css/bootstrap.min.css", "dist/js/bootstrap.bundle.min.js"],
  },
  {
    module: "@fortawesome/fontawesome-free",
    entries: "css/all.min.css",
    copy: ["webfonts/"],
  },
];

Here you see the key copy in action. This can be a string or an array of strings. All the globs defined here will be just copied to the destination folder but not injected anywhere. Here you can define single files or folders.