CC 4.0 License

The content of this section is derived from the content of the following links and is subject to the CC BY 4.0 license.

The following contents can be assumed to be the result of modifications and deletions based on the original contents if not specifically stated.

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:

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.

externalsPresets.node

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

externalsPresets.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).

externalsPresets.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).

externalsPresets.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.

externalsPresets.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.

externalsPresets.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.

externalsPresets.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.