> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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`](/config/externals.md) and [`externalsType`](/config/externals.md#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`](/config/output.md#outputmodule) and set `externalsType` to `'module'` to leave `react` out of the bundle while generating an ES module import for it:

```js title="rspack.config.mjs"
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:

```js title="rspack.config.mjs"
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:

```js title="rspack.config.mjs"
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:

```js
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`](/config/externals.md#externalstype).

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

```js
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](/config/externals.md). For custom matching and request resolution, see [function externals](/config/externals.md#function).