CodeCoupler Webpack Externals Plugin Configuration Reference
You have to define each 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:
1 |
|
As you can see an array will be defined here. Each item in this array is an object which define an external module. The available options for each 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
orcss
files to copy from the modules folder to thedist
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:
1 2 3 4 5 6 7 |
|
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:
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 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
:
1 2 3 4 5 6 7 |
|
Walkthrough Example
Here is an example to define jQuery as an external library:
1 2 3 4 5 6 7 |
|
This configuration will:
- Exclude the module
jquery
from the build - Define the global variable
jQuery
as the source for this library - Copy the file
dist/jquery.min.js
from thenode_modules
folder of jQuery to a subdirectory of yourdist
folder namedvendor/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.map
also 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 .js
or .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.