#ExternalsPlugin

ExternalsPlugin keeps selected dependencies out of the bundle and generates code to access them at runtime. For example, an external dependency can be referenced through an ES module import or read from a browser global supplied by another script.

For most projects, configure externals and externalsType directly. Rspack applies ExternalsPlugin internally for these options. Use the plugin directly when adding external rules from another plugin or configuring separate plugin instances with different externalsType values.

#Examples

#ESM imports

Enable output.module and set externalsType to 'module' to leave react out of the bundle while generating an ES module import for it:

import { rspack } from '@rspack/core';

export default {
  output: {
    module: true,
  },
  plugins: [new rspack.ExternalsPlugin('module', ['react'])],
};

The consumer of the output must be able to resolve the react import. For example, another bundler can resolve it, or a browser can map it to a URL through an import map. The string rule matches react exactly; it does not match subpaths such as react/jsx-runtime.

For this example, the corresponding configuration options are:

export default {
  output: {
    module: true,
  },
  externalsType: 'module',
  externals: ['react'],
};

#Browser globals

If the page already loads Lodash through a script that exposes window._, map the lodash request to that global:

import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.ExternalsPlugin('window', { lodash: '_' })],
};

Application code can continue to use import _ from 'lodash'. The bundle reads window._ instead of including Lodash, so load the script that provides it before running the bundle.

#Options

Pass externalsType as the first argument and the matching rules, externals, as the second:

new rspack.ExternalsPlugin(externalsType, externals);

#externalsType

• Type: ExternalsType
• Required: Yes

Determines how matching dependencies are accessed at runtime.

Choose an externalsType that works with your output format and runtime environment. For all supported values and their requirements, see externalsType.

A rule can override externalsType by adding a type prefix to its result:

new rspack.ExternalsPlugin('module', {
  react: 'react',
  lodash: 'window _',
});

With output.module enabled, react is imported as an ES module, while lodash is read from window._.

#externals

• Type: Externals
• Required: Yes

Specifies which module requests to externalize and how to reference them. Rules match the request written in the source code, before it is resolved to a file path.

For supported rule forms and value formats, see the externals configuration reference. For custom matching and request resolution, see function externals.