Skip to content
Merged
Changes from 3 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 into something like

```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 there will be an `import()` statement in the output bundle.

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

Make sure 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 into something like

```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 there will be an `import` or `import()` statement in the output bundle.

When a module is not imported via `import` or `import()`, webpack will use `"module"` externals type as fallback. If you want to use a different type of externals as 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