CC 4.0 ライセンス

このセクションの内容は、以下のリンクの内容を基に作成されており、CC BY 4.0 ライセンスの対象となります。
https://webpack.dokyumento.jp/configuration/externals/
特に明記されていない限り、以下の内容は元のコンテンツに基づいた修正と削除の結果であるとみなすことができます。

外部ライブラリ

externals 設定オプションを使用すると、出力バンドルから依存関係を除外できます。代わりに、作成されたバンドルは、コンシューマー（エンドユーザーアプリケーション）の環境にその依存関係が存在することを前提とします。この機能は、通常、ライブラリ開発者にとって最も役立ちますが、さまざまな用途があります。

externals

型: string | object | function | RegExp | Array<string | object | function | RegExp>

バンドリングの防止 特定の `import` されたパッケージのバンドルを防止し、代わりに実行時にこれらの *外部依存関係* を取得します。

たとえば、バンドルする代わりにCDNからjQuery を含める場合

index.html

<script
  src="https://code.jquery.com/jquery-3.1.0.js"
  integrity="sha256-slogkvB1K3VOkzAI8QITxV3VzpOnkeNVsKvtkYLMjfk="
  crossorigin="anonymous"
></script>

rspack.config.js

module.exports = {
  //...
  externals: {
    jquery: 'jQuery',
  },
};

これにより、依存モジュールは変更されません。つまり、下記のコードは引き続き機能します。

import $ from 'jquery';

$('.my-element').animate(/* ... */);

上記の rspack.config.js の externals で指定されたプロパティ名 jquery は、import $ from 'jquery' のモジュール jquery をバンドルから除外することを示します。このモジュールを置き換えるために、値 jQuery を使用してグローバル jQuery 変数を取得します。これは、デフォルトの外部ライブラリタイプが var であるためです（externalsType を参照）。

上記ではグローバル変数の外部ライブラリを使用する例を示しましたが、実際にはグローバル変数、CommonJS、AMD、ES2015モジュールなど、さまざまな形式で外部ライブラリを使用できます。externalsTypeで詳細を確認してください。

文字列

externalsType によって、グローバル変数の名前（'global'、'this'、'var'、'window' を参照）、またはモジュールの名前（amd、commonjs、module、umd を参照）になります。

外部ライブラリを1つだけ定義する場合は、ショートカット構文を使用できます。

rspack.config.js

module.exports = {
  //...
  externals: 'jquery',
};

これは次と同じです。

rspack.config.js

module.exports = {
  //...
  externals: {
    jquery: 'jquery',
  },
};

${externalsType} ${libraryName} 構文を使用して、外部ライブラリに外部ライブラリタイプを指定できます。externalsType オプションで指定されたデフォルトの外部ライブラリタイプを上書きします。

たとえば、外部ライブラリがCommonJSモジュールの場合、次のように指定できます。

rspack.config.js

module.exports = {
  //...
  externals: {
    jquery: 'commonjs jquery',
  },
};

文字列配列

rspack.config.js

module.exports = {
  //...
  externals: {
    subtract: ['./math', 'subtract'],
  },
};

subtract: ['./math', 'subtract'] を使用すると、モジュールの部分を指定できます。./math がモジュールで、バンドルでは subtract 変数以下のサブセットのみが必要です。

externalsType が commonjs の場合、この例は require('./math').subtract; に変換されます。externalsType が window の場合、この例は window["./math"]["subtract"]; に変換されます。

文字列構文と同様に、配列の最初の要素に ${externalsType} ${libraryName} 構文を使用して外部ライブラリタイプを指定できます。たとえば、

rspack.config.js

module.exports = {
  //...
  externals: {
    subtract: ['commonjs ./math', 'subtract'],
  },
};

オブジェクト

警告

{ root, amd, commonjs, ... } を含むオブジェクトは、libraryTarget: 'umd' と externalsType: 'umd' の場合にのみ許可されます。他のライブラリターゲットでは許可されません。

rspack.config.js

module.exports = {
  //...
  externals: {
    react: 'react',
  },

  // or

  externals: {
    lodash: {
      commonjs: 'lodash',
      amd: 'lodash',
      root: '_', // indicates global variable
    },
  },

  // or

  externals: {
    subtract: {
      root: ['math', 'subtract'],
    },
  },
};

この構文は、外部ライブラリを利用可能にするあらゆる方法を記述するために使用されます。ここでは、lodash は AMD および CommonJS モジュールシステムでは lodash として、グローバル変数形式では _ として利用可能です。 subtract は、グローバル math オブジェクトのプロパティ subtract を介して利用可能です (例: window['math']['subtract'])。

関数

型
- function ({ context, request, contextInfo, getResolve }, callback)
- function ({ context, request, contextInfo, getResolve }) => promise

Rspack から外部化したいものの動作を制御するために、独自の関数を定義することが役立つ場合があります。例えば、webpack-node-externals は、node_modules ディレクトリからすべてのモジュールを除外します。また、パッケージを許可リストに追加するオプションも提供します。

関数が受け取ることができる引数

ctx (object): ファイルの詳細を含むオブジェクト。
- ctx.context (string): import を含むファイルのディレクトリ。
- ctx.request (string): 要求された import パス。
- ctx.contextInfo (object): 発行者に関する情報 (例: レイヤーとコンパイラ) を含みます。
- ctx.getResolve: 現在の resolver オプションを使用して resolve 関数を取得します。
callback (function (err, result, type)): モジュールをどのように外部化するべきかを示すために使用されるコールバック関数。

コールバック関数は3つの引数を取ります

err (Error): import の外部化中にエラーが発生したかどうかを示すために使用されます。エラーが発生した場合は、このパラメータのみを使用する必要があります。
result (string | string[] | object): 他の外部形式(string、string[]、またはobject) を使用して外部モジュールを記述します。
type (string): モジュールの外部型を示すオプションのパラメータ(resultパラメータですでに示されていない場合)。

例として、import パスが正規表現と一致するすべてのimportを外部化するには、次の手順を実行します。

rspack.config.js

module.exports = {
  //...
  externals: [
    function ({ context, request }, callback) {
      if (/^yourregex$/.test(request)) {
        // Externalize to a commonjs module using the request path
        return callback(null, 'commonjs ' + request);
      }

      // Continue without externalizing the import
      callback();
    },
  ],
};

異なるモジュール形式を使用したその他の例

rspack.config.js

module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a `commonjs2` module located in `@scope/library`
      callback(null, '@scope/library', 'commonjs2');
    },
  ],
};

rspack.config.js

module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a global variable called `nameOfGlobal`.
      callback(null, 'nameOfGlobal');
    },
  ],
};

rspack.config.js

module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a named export in the `@scope/library` module.
      callback(null, ['@scope/library', 'namedexport'], 'commonjs');
    },
  ],
};

rspack.config.js

module.exports = {
  externals: [
    function (ctx, callback) {
      // The external is a UMD module
      callback(null, {
        root: 'componentsGlobal',
        commonjs: '@scope/components',
        commonjs2: '@scope/components',
        amd: 'components',
      });
    },
  ],
};

正規表現

指定された正規表現と一致するすべての依存関係が出力バンドルから除外されます。

rspack.config.js

module.exports = {
  //...
  externals: /^(jquery|\$)$/i,
};

この場合、jQuery（大文字小文字を問わず）、または$という名前の依存関係はすべて外部化されます。

構文の組み合わせ

上記の構文を組み合わせて使用したい場合があります。これは、次の方法で行うことができます。

rspack.config.js

module.exports = {
  //...
  externals: [
    {
      // String
      react: 'react',
      // Object
      lodash: {
        commonjs: 'lodash',
        amd: 'lodash',
        root: '_', // indicates global variable
      },
      // [string]
      subtract: ['./math', 'subtract'],
    },
    // Function
    function ({ context, request }, callback) {
      if (/^yourregex$/.test(request)) {
        return callback(null, 'commonjs ' + request);
      }
      callback();
    },
    // Regex
    /^(jquery|\$)$/i,
  ],
};

警告

型を指定せずにexternalsを指定する場合（例：externals: { react: 'react' }ではなくexternals: { react: 'commonjs-module react' }）、デフォルトの型が使用されます。

externalsType

型: string
デフォルト: 'var'

外部のデフォルトの型を指定します。 amd、umd、system、jsonp 外部は、output.libraryTarget が同じ値に設定されている場合にのみ依存します。例えば、amd ライブラリ内では amd 外部のみを使用できます。

サポートされている型

'amd'
'amd-require'
'assign' - 'var' と同じ
'commonjs'
'commonjs-module'
'global'
'module'
'import' - ネイティブな EcmaScript モジュール（非同期モジュール）の読み込みに import() を使用します。
'module-import'
'jsonp'
'node-commonjs'
'promise' - 'var' と同じですが、結果を待機します（非同期モジュール）。
'self'
'system'
'script'
'this'
'umd'
'umd2'
'var'
'window'

rspack.config.js

module.exports = {
  //...
  externalsType: 'promise',
};

externalsType.commonjs

外部のデフォルトの型を 'commonjs' として指定します。 Rspack は、モジュールで使用される外部に対して const X = require('...') のようなコードを生成します。

例

import fs from 'fs-extra';

rspack.config.js

module.exports = {
  // ...
  externalsType: 'commonjs',
  externals: {
    'fs-extra': 'fs-extra',
  },
};

次のようなものに変換されます。

const fs = require('fs-extra');

出力バンドルには require() が含まれることに注意してください。

externalsType.global

外部のデフォルトの型を 'global' として指定します。 Rspack は、globalObject 上のグローバル変数として外部を読み取ります。

例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'global',
  externals: {
    jquery: '$',
  },
  output: {
    globalObject: 'global',
  },
};

次のようなものに変換されます。

const jq = global['$'];
jq('.my-element').animate(/* ... */);

externalsType.module

外部のデフォルトの型を 'module' として指定します。 Rspack は、モジュールで使用される外部に対して import * as X from '...' のようなコードを生成します。

最初にexperiments.outputModule を有効にしてください。そうしないと、Rspack はエラーをスローします。

例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  experiments: {
    outputModule: true,
  },
  externalsType: 'module',
  externals: {
    jquery: 'jquery',
  },
};

次のようなものに変換されます。

import * as __WEBPACK_EXTERNAL_MODULE_jquery__ from 'jquery';

const jq = __WEBPACK_EXTERNAL_MODULE_jquery__['default'];
jq('.my-element').animate(/* ... */);

出力バンドルには import ステートメントが含まれることに注意してください。

externalsType.import

外部のデフォルトの型を 'import' として指定します。 Rspack は、モジュールで使用される外部に対して import('...') のようなコードを生成します。

例

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

rspack.config.js

module.exports = {
  externalsType: 'import',
  externals: {
    jquery: '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'),
  );
  jq('.my-element').animate(/* ... */);
}

出力バンドルには import() ステートメントが含まれることに注意してください。

externalsType['module-import']

'module' と'import' を組み合わせます。 Rspack は、静的インポートの場合は 'module' に、動的インポートの場合は 'import' にインポート構文の型を自動的に検出します。

静的インポートが存在する場合は、最初にexperiments.outputModule を有効にしてください。そうしないと、Rspack はエラーをスローします。

例

import { attempt } from 'lodash';

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

rspack.config.js

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

次のようなものに変換されます。

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(/* ... */));
}

出力バンドルには import または import() ステートメントが含まれることに注意してください。

モジュールが import または import() を介してインポートされない場合、Rspack はフォールバックとして "module" 外部型を使用します。フォールバックとして異なるタイプの外部を使用する場合は、externals オプションで関数を使用して指定できます。例えば

rspack.config.js

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

externalsType['node-commonjs']

外部のデフォルトの型を 'node-commonjs' として指定します。 Rspack は、createRequire を 'module' からインポートして、モジュールで使用される外部を読み込むための require 関数を構築します。

例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

module.export = {
  experiments: {
    outputModule: true,
  },
  externalsType: 'node-commonjs',
  externals: {
    jquery: 'jquery',
  },
};

次のようなものに変換されます。

import { createRequire } from 'module';

const jq = createRequire(import.meta.url)('jquery');
jq('.my-element').animate(/* ... */);

出力バンドルには import ステートメントが含まれることに注意してください。

externalsType.promise

外部のデフォルトの型を 'promise' として指定します。 Rspack は、外部をグローバル変数として読み取り（'var' と同様）、それを await します。

例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'promise',
  externals: {
    jquery: '$',
  },
};

次のようなものに変換されます。

const jq = await $;
jq('.my-element').animate(/* ... */);

externalsType.self

外部のデフォルトの型を 'self' として指定します。 Rspack は、self オブジェクト上のグローバル変数として外部を読み取ります。

例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'self',
  externals: {
    jquery: '$',
  },
};

次のようなものに変換されます。

const jq = self['$'];
jq('.my-element').animate(/* ... */);

externalsType.script

外部のデフォルトの型を 'script' として指定します。 Rspack は、HTML <script> 要素を使用して、事前に定義されたグローバル変数を公開するスクリプトとして外部を読み込みます。スクリプトが読み込まれた後、<script> タグは削除されます。

構文

rspack.config.js

module.exports = {
  externalsType: 'script',
  externals: {
    packageName: [
      'http://example.com/script.js',
      'global',
      'property',
      'property',
    ], // properties are optional
  },
};

プロパティを指定しない場合は、ショートカット構文を使用することもできます。

rspack.config.js

module.exports = {
  externalsType: 'script',
  externals: {
    packageName: 'global@http://example.com/script.js', // no properties here
  },
};

output.publicPath は、提供された URL に追加されないことに注意してください。

例

CDN から lodash を読み込んでみましょう

rspack.config.js

module.exports = {
  // ...
  externalsType: 'script',
  externals: {
    lodash: ['https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js', '_'],
  },
};

そして、コードで使用します

import _ from 'lodash';
console.log(_.head([1, 2, 3]));

上記の例のプロパティを指定する方法を次に示します。

rspack.config.js

module.exports = {
  // ...
  externalsType: 'script',
  externals: {
    lodash: [
      'https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js',
      '_',
      'head',
    ],
  },
};

lodash を import すると、ローカル変数 head とグローバル window._ の両方が公開されます。

import head from 'lodash';
console.log(head([1, 2, 3])); // logs 1 here
console.log(window._.head(['a', 'b'])); // logs a here

ヒント

HTML <script> タグを使用してコードを読み込む場合、Rspack ランタイムは、src 属性と一致する既存の <script> タグ、または特定の data-webpack 属性を持つタグを検索しようとします。チャンクの読み込みでは、data-webpack 属性の値は '[output.uniqueName]:chunk-[chunkId]' になり、外部スクリプトの場合は '[output.uniqueName]:[global]' になります。

output.chunkLoadTimeout、output.crossOriginLoading、output.scriptType のようなオプションも、このように読み込まれた外部スクリプトに影響します。

externalsType.this

外部のデフォルトの型を 'this' として指定します。 Rspack は、this オブジェクト上のグローバル変数として外部を読み取ります。

例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'this',
  externals: {
    jquery: '$',
  },
};

次のようなものに変換されます。

const jq = this['$'];
jq('.my-element').animate(/* ... */);

externalsType.var

外部のデフォルトの型を 'var' として指定します。 Rspack は、グローバル変数として外部を読み取ります。

例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'var',
  externals: {
    jquery: '$',
  },
};

次のようなものに変換されます。

const jq = $;
jq('.my-element').animate(/* ... */);

externalsType.window

外部のデフォルトの型を 'window' として指定します。 Rspack は、window オブジェクト上のグローバル変数として外部を読み取ります。

例

import jq from 'jquery';
jq('.my-element').animate(/* ... */);

rspack.config.js

module.exports = {
  // ...
  externalsType: 'window',
  externals: {
    jquery: '$',
  },
};

次のようなものに変換されます。

const jq = window['$'];
jq('.my-element').animate(/* ... */);

externalsPresets

型: object

特定のターゲットの外部プリセットを有効にします。

externalsPresets.electron

型: boolean

メインコンテキストとプリロードコンテキストで、electron、ipc、shell などの一般的な Electron 組み込みモジュールを外部として扱い、使用時に require() を介して読み込みます。

externalsPresets.electronMain

型: boolean

メインコンテキストで、app、ipc-main、shell などの Electron 組み込みモジュールを外部として扱い、使用時に require() を介して読み込みます。

externalsPresets.electronPreload

型: boolean

プリロードコンテキストで、web-frame、ipc-renderer、shell などの Electron 組み込みモジュールを外部として扱い、使用時に require() を介して読み込みます。

externalsPresets.electronRenderer

型: boolean

レンダラーコンテキストで、web-frame、ipc-renderer、shell などの Electron 組み込みモジュールを外部として扱い、使用時に require() を介して読み込みます。

externalsPresets.node

型: boolean

fs、path、vm などの Node.js 組み込みモジュールを外部として扱い、使用時に require() を介して読み込みます。

externalsPresets.nwjs

型: boolean

NW.js のレガシー nw.gui モジュールを外部として扱い、使用時に require() を介して読み込みます。

externalsPresets.web

型: boolean

http(s)://... と std:... への参照を外部として扱い、使用時に import を介して読み込みます。(これは、外部がチャンク内の他のコードよりも前に実行されるため、実行順序を変更することに注意してください)。

externalsPresets.webAsync

型: boolean

http(s)://... と std:... への参照を外部として扱い、使用時に async import() を介して読み込みます。(この外部型は非同期モジュールであるため、実行にさまざまな影響を与えることに注意してください)。

Node.js関連のプリセットを使用してESモジュールを出力する場合、RspackはデフォルトのexternalsTypeをnode-commonjsに設定します。これにより、require()を使用する代わりに、createRequireを使用してrequire関数が構築されます。

例

nodeプリセットを使用すると、組み込みモジュールはバンドルされず、外部モジュールとして扱われ、require()を使用してロードされます。

rspack.config.js

module.exports = {
  // ...
  externalsPresets: {
    node: true,
  },
};

外部ライブラリ#

externals#

文字列#

文字列配列#

オブジェクト#

関数#

正規表現#

構文の組み合わせ#

externalsType#

externalsType.commonjs#

externalsType.global#

externalsType.module#

externalsType.import#

externalsType['module-import']#

externalsType['node-commonjs']#

externalsType.promise#

externalsType.self#

externalsType.script#

externalsType.this#

externalsType.var#

externalsType.window#

externalsPresets#

externalsPresets.electron#

externalsPresets.electronMain#

externalsPresets.electronPreload#

externalsPresets.electronRenderer#

externalsPresets.node#

externalsPresets.nwjs#

externalsPresets.web#

externalsPresets.webAsync#

外部ライブラリ

externals

文字列

文字列配列

オブジェクト

関数

正規表現

構文の組み合わせ

externalsType

externalsType.commonjs

externalsType.global

externalsType.module

externalsType.import

externalsType['module-import']

externalsType['node-commonjs']

externalsType.promise

externalsType.self

externalsType.script

externalsType.this

externalsType.var

externalsType.window

externalsPresets

externalsPresets.electron

externalsPresets.electronMain

externalsPresets.electronPreload

externalsPresets.electronRenderer

externalsPresets.node

externalsPresets.nwjs

externalsPresets.web

externalsPresets.webAsync