Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 118 additions & 0 deletions src/content/configuration/externals.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ contributors:
- kinetifex
- anshumanv
- SaulSilver
- fi3ework
---

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.
Expand Down Expand Up @@ -353,6 +354,8 @@ Supported types:
- `'import'` - uses `import()` to load a native EcmaScript module (async module)
- `'jsonp'`
- [`'module'`](#externalstypemodule)
- [`'import'`](#externalstypeimport)
- [`'module-import'`](#externalstypemodule-import)
- [`'node-commonjs'`](#externalstypenode-commonjs)
- [`'promise'`](#externalstypepromise) - same as `'var'` but awaits the result (async module)
- [`'self'`](#externalstypeself)
Expand Down Expand Up @@ -474,6 +477,121 @@ jq('.my-element').animate(/* ... */);

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

### externalsType.import

Specify the default type of externals as `'import'`. Webpack will generate code like `import('...')` for externals used in a module.

#### Example

```javascript
async function foo() {
const jq = await import('jQuery');
jq('.my-element').animate(/* ... */);
}
```

**webpack.config.js**

```js
module.exports = {
externalsType: 'import',
externals: {
jquery: 'jquery',
},
};
```

Will generate something like below:

```javascript
var __webpack_modules__ = {
jQuery: (module) => {
module.exports = import('jQuery');
},
};

// webpack runtime...

async function foo() {
const jq = await Promise.resolve(/* import() */).then(
__webpack_require__.bind(__webpack_require__, 'jQuery')
);
jq('.my-element').animate(/* ... */);
}
```

Note that the output bundle will have an `import()` statement.

### externalsType.module-import

Specify the default type of externals as `'module-import'`. This combines [`'module'`](#externalstypemodule) and [`'import'`](#externalstypeimport). 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`](/configuration/experiments/#experimentsoutputmodule) first if static imports exist, otherwise, webpack will throw errors.

#### Example

```javascript
import { attempt } from 'lodash';

async function foo() {
const jq = await import('jQuery');
attempt(() => jq('.my-element').animate(/* ... */));
}
```

**webpack.config.js**

```js
module.exports = {
externalsType: 'import',
externals: {
jquery: 'jquery',
},
};
```

Will generate something like below:

```javascript
import * as __WEBPACK_EXTERNAL_MODULE_lodash__ from 'lodash';
const lodash = __WEBPACK_EXTERNAL_MODULE_jquery__;

var __webpack_modules__ = {
jQuery: (module) => {
module.exports = import('jQuery');
},
};

// webpack runtime...

async function foo() {
const jq = await Promise.resolve(/* import() */).then(
__webpack_require__.bind(__webpack_require__, 'jQuery')
);
(0, lodash.attempt)(() => jq('.my-element').animate(/* ... */));
}
```

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:

```js
module.exports = {
externalsType: "module-import",
externals: [
function (
{ request, dependencyType },
callback
) {
if (dependencyType === "commonjs") {
return callback(null, `node-commonjs ${request}`);
}
callback();
},
]
```

### externalsType.node-commonjs

Specify the default type of externals as `'node-commonjs'`. Webpack will import [`createRequire`](https://nodejs.org/api/module.html#module_module_createrequire_filename) from `'module'` to construct a require function for loading externals used in a module.
Expand Down