diff --git a/src/content/configuration/externals.mdx b/src/content/configuration/externals.mdx index 2e2e31b8df99..6700150ed5d0 100644 --- a/src/content/configuration/externals.mdx +++ b/src/content/configuration/externals.mdx @@ -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. @@ -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) @@ -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.