The
externals
configuration option provides a way of excluding dependencies from the output bundles. Instead, the created bundle relies on that dependency to be present in the consumer's (any end-user application) environment. This feature is typically most useful to
library developers
, however there are a variety of applications for it.
externals
string
object
function
RegExp
[string, object, function, RegExp]
Prevent bundling
of certain
import
ed packages and instead retrieve these
external dependencies
at runtime.
For example, to include
jQuery
from a CDN instead of bundling it:
The property name jquery specified under externals in the above webpack.config.js indicates that the module jquery in import $ from 'jquery' should be excluded from bundling. In order to replace this module, the value jQuery will be used to retrieve a global jQuery variable, as the default external library type is var, see externalsType.
While we showed an example consuming external global variable above, the external can actually be available in any of these forms: global variable, CommonJS, AMD, ES2015 Module, see more in externalsType.
You can specify the external library type to the external with the ${externalsType} ${libraryName} syntax. It will override the default external library type specified in the externalsType option.
For example, if the external library is a CommonJS module, you can specify
subtract: ['./math', 'subtract'] allows you select part of a module, where ./math is the module and your bundle only requires the subset under the subtract variable.
When the externalsType is commonjs, this example would translate to require('./math').subtract; while when the externalsType is window, this example would translate to window["./math"]["subtract"];
Similar to the string syntax, you can specify the external library type with the ${externalsType} ${libraryName} syntax, in the first item of the array, for example:
module.exports ={//...
externals:{
react:'react',// or
externals:{
lodash:{
commonjs:'lodash',
amd:'lodash',
root:'_',// indicates global variable// or
externals:{
subtract:{
root:['math','subtract'],
This syntax is used to describe all the possible ways that an external library can be made available. lodash here is available as lodash under AMD and CommonJS module systems but available as _ in a global variable form. subtract here is available via the property subtract under the global math object (e.g. window['math']['subtract']).
function
function ({ context, request, contextInfo, getResolve }, callback)
function ({ context, request, contextInfo, getResolve }) => promise5.15.0+
It might be useful to define your own function to control the behavior of what you want to externalize from webpack. webpack-node-externals, for example, excludes all modules from the node_modules directory and provides options to allowlist packages.
Here're arguments the function can receive:
ctx (object): Object containing details of the file.
ctx.context (string): The directory of the file which contains the import.
ctx.request (string): The import path being requested.
ctx.contextInfo (object): Contains information about the issuer (e.g. the layer and compiler)
ctx.getResolve5.15.0+: Get a resolve function with the current resolver options.
callback (function (err, result, type)): Callback function used to indicate how the module should be externalized.
The callback function takes three arguments:
err (Error): Used to indicate if there has been an error while externalizing the import. If there is an error, this should be the only parameter used.
result (string[string]object): Describes the external module with the other external formats (string, [string], or object)
type (string): Optional parameter that indicates the module external type (if it has not already been indicated in the result parameter).
As an example, to externalize all imports where the import path matches a regular expression you could do the following:
webpack.config.js
module.exports ={//...
externals:[function({ context, request }, callback){if(/^yourregex$/.test(request)){// Externalize to a commonjs module using the request pathreturncallback(null,'commonjs '+ request);// Continue without externalizing the importcallback();
Other examples using different module formats:
webpack.config.js
module.exports ={
externals:[function(ctx, callback){// The external is a `commonjs2` module located in `@scope/library`callback(null,'@scope/library','commonjs2');
webpack.config.js
module.exports ={
externals:[function(ctx, callback){// The external is a global variable called `nameOfGlobal`.callback(null,'nameOfGlobal');
webpack.config.js
module.exports ={
externals:[function(ctx, callback){// The external is a named export in the `@scope/library` module.callback(null,['@scope/library','namedexport'],'commonjs');
webpack.config.js
module.exports ={
externals:[function(ctx, callback){// The external is a UMD modulecallback(null,{
root:'componentsGlobal',
commonjs:'@scope/components',
commonjs2:'@scope/components',
amd:'components',});
RegExp
Every dependency that matches the given regular expression will be excluded from the output bundles.
Specify the default type of externals. amd, umd, system and jsonp externals depend on the output.libraryTarget being set to the same value e.g. you can only consume amd externals within an amd library.
Note that the output bundle will have an import() statement.
externalsType.module-import
5.94.0+
Specify the default type of externals as 'module-import'. This combines 'module' and 'import'. Webpack will automatically detect the type of import syntax, setting it to 'module' for static imports and 'import' for dynamic imports.
Ensure to enable experiments.outputModule first if static imports exist, otherwise, webpack will throw errors.
Note that the output bundle will have an import or import() statement.
When a module is not imported via import or import(), webpack will use the "module" externals type as a fallback. If you want to use a different kind of externals as a fallback, you can specify it with a function in the externals option. For example:
Specify the default type of externals as 'node-commonjs'. Webpack will import createRequire from 'module' to construct a require function for loading externals used in a module.
Specify the default type of externals as 'script'. Webpack will load the external as a script exposing predefined global variables with HTML <script> element. The <script> tag would be removed after the script has been loaded.
Syntax
module.exports ={
externalsType:'script',
externals:{
packageName:['http://example.com/script.js','global','property','property',],// properties are optional
You can also use the shortcut syntax if you're not going to specify any properties:
module.exports ={
externalsType:'script',
externals:{
packageName:'global@http://example.com/script.js',// no properties here
Treat common electron built-in modules in main and preload context like electron, ipc or shell as external and load them via require() when used.
boolean
electronMain
Treat electron built-in modules in the main context like app, ipc-main or shell as external and load them via require() when used.
boolean
electronPreload
Treat electron built-in modules in the preload context like web-frame, ipc-renderer or shell as external and load them via require() when used.
boolean
electronRenderer
Treat electron built-in modules in the renderer context like web-frame, ipc-renderer or shell as external and load them via require() when used.
boolean
node
Treat node.js built-in modules like fs, path or vm as external and load them via require() when used.
boolean
nwjs
Treat NW.js legacy nw.gui module as external and load it via require() when used.
boolean
web
Treat references to http(s)://... and std:... as external and load them via import when used. (Note that this changes execution order as externals are executed before any other code in the chunk).
boolean
webAsync
Treat references to http(s)://... and std:... as external and load them via async import() when used (Note that this external type is an async module, which has various effects on the execution).
boolean
Note that if you're going to output ES Modules with those node.js-related presets, webpack will set the default externalsType to node-commonjs which would use createRequire to construct a require function instead of using require().
Example
Using node preset will not bundle built-in modules and treats them as external and loads them via require() when used.