Externals#

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#

• Type: string | object | function | RegExp | Array<string | object | function | RegExp>

Prevent bundling of certain imported packages and instead retrieve these external dependencies at runtime.

For example, to include jQuery from a CDN instead of bundling it:

index.html

<script
  src="https://code.jquery.com/jquery-3.1.0.js"
  integrity="sha256-slogkvB1K3VOkzAI8QITxV3VzpOnkeNVsKvtkYLMjfk="
  crossorigin="anonymous"
></script>

rspack.config.js

module.exports = {
  //...
  externals: {
    jquery: 'jQuery',
  },
};

This leaves any dependent modules unchanged, i.e. the code shown below will still work:

import $ from 'jquery';

$('.my-element').animate(/* ... */);

The property name jquery specified under externals in the above rspack.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.

string#

Depending on the externalsType, this could be the name of the global variable (see 'global', 'this', 'var', 'window') or the name of the module (see amd, commonjs, module, umd).

You can also use the shortcut syntax if you're defining only 1 external:

module.exports = {
  //...
  externals: 'jquery',
};

equals to

module.exports = {
  //...
  externals: {
    jquery: 'jquery',
  },
};

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

module.exports = {
  //...
  externals: {
    jquery: 'commonjs jquery',
  },
};

object#

An object with { root, amd, commonjs, ... } is only allowed for libraryTarget: 'umd' and externalsType: 'umd'. It's not allowed for other library targets.

module.exports = {
  //...
  externals: {
    react: 'react',
  },

  // or

  externals: {
    lodash: {
      commonjs: 'lodash',
      amd: 'lodash',
      root: '_', // indicates global variable
    },
  },
};

externalsType#

• Type: string
• Default: var

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.

Supported types:

• 'amd'
• 'amd-require'
• 'assign' - same as 'var'
• 'commonjs'
• 'commonjs-module'
• 'global'
• 'import' - uses import() to load a native ECMAScript module (async module)
• 'jsonp'
• 'module'
• 'node-commonjs'
• 'self'
• 'system'
• 'this'
• 'umd'
• 'umd2'
• 'var'
• 'window'

externalsType.commonjs#

Specify the default type of externals as 'commonjs'. Webpack will generate code like const X = require('...') for externals used in a module.

import fs from 'fs-extra';

rspack.config.js

module.exports = {
  // ...
  externalsType: 'commonjs',
  externals: {
    'fs-extra': 'fs-extra',
  },
};

Will generate into something like:

const fs = require('fs-extra');

Note that there will be a require() in the output bundle.

externalsType.global#

Specify the default type of externals as 'global'. Webpack will read the external as a global variable on the globalObject.

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'global',
  externals: {
    jquery: '$',
  },
  output: {
    globalObject: 'global',
  },
};

Will generate into something like

const jq = global['$'];
jq('.my-element').animate(/* ... */);

externalsType.module#

Specify the default type of externals as 'module'. Webpack will generate code like import * as X from '...' for externals used in a module.

Note that there will be an import statement in the output bundle.

externalsType.node-commonjs#

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.

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.export = {
  externalsType: 'node-commonjs',
  externals: {
    jquery: 'jquery',
  },
};

Will generate into something like

import { createRequire } from 'module';

const jq = createRequire(import.meta.url)('jquery');
jq('.my-element').animate(/* ... */);

Note that there will be an import statement in the output bundle.

externalsType.self#

Specify the default type of externals as 'self'. Webpack will read the external as a global variable on the self object.

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'self',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = self['$'];
jq('.my-element').animate(/* ... */);

externalsType.this#

Specify the default type of externals as 'this'. Webpack will read the external as a global variable on the this object.

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'this',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = this['$'];
jq('.my-element').animate(/* ... */);

externalsType.var#

Specify the default type of externals as 'var'. Webpack will read the external as a global variable.

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'var',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = $;
jq('.my-element').animate(/* ... */);

externalsType.window#

Specify the default type of externals as 'window'. Webpack will read the external as a global variable on the window object.

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'window',
  externals: {
    jquery: '$',
  },
};

Will generate into something like

const jq = window['$'];
jq('.my-element').animate(/* ... */);

externalsPresets#

Enable presets of externals for specific targets.

node#

Treat node.js built-in modules like fs, path or vm as external and load them via require() when used.

web#

Treat references to http(s)://... and std:... as external and load them via import (externalType: "module") when used. (Note that this changes execution order as externals are executed before any other code in the chunk).

webAsync#

Treat references to http(s)://... and std:... as external and load them via import() (externalType: "import") when used. (Note that this external type is an async module, which has various effects on the execution).

electron#

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.

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.

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.

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.