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:
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
cssfiles to copy from the modules folder to the
distfolder 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
distfolder. This can be used to copy assets like fonts.
- includeExternals: If true the
webpack.externals.jsof 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
If you want to add just an hint on what a module depents you can add just an entry only with the module name:
1 2 3 4 5 6 7
This configuration tells webpack to copy the
bootstrap assets but let the module
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
jquery in front of
bootstrap will ensure that
jquery assets will be injected before
A last word to the order concerns the
@cc-external packages. Keep in mind that
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
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:
1 2 3 4 5 6
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
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
1 2 3 4 5 6 7
Here is an example to define jQuery as an external library:
1 2 3 4 5 6 7
This configuration will:
- Exclude the module
jqueryfrom the build
- Define the global variable
jQueryas the source for this library
- Copy the file
node_modulesfolder of jQuery to a subdirectory of your
vendor/jquery-X.X.X/dist/jquery.min.js(the current version will be read from the current installed package)
- Copy the corresponding source map (if exists of course)
dist/jquery.min.js.mapalso to the destination folder
- 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:
1 2 3 4 5 6 7 8 9 10 11
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
.css. All other exetensions will be ignored.
Last but not least we add the module of Font Awesome to the configuration:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
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.