From 412dc50aa7ff93268923805d9835983aa26e71ee Mon Sep 17 00:00:00 2001
From: Tan Li Hau <lhtan93@gmail.com>
Date: Fri, 5 Aug 2022 15:29:28 +0800
Subject: [PATCH] explain more for externalsType

---
 src/content/configuration/externals.mdx | 244 +++++++++++++++++++++---
 1 file changed, 222 insertions(+), 22 deletions(-)

diff --git a/src/content/configuration/externals.mdx b/src/content/configuration/externals.mdx
index cfbba48fe6f8..1038e0efa6ea 100644
--- a/src/content/configuration/externals.mdx
+++ b/src/content/configuration/externals.mdx
@@ -59,22 +59,41 @@ import $ from 'jquery';
 $('.my-element').animate(/* ... */);
 ```
 
-The bundle with external dependencies can be used in various module contexts, such as [CommonJS, AMD, global and ES2015 modules](/concepts/modules). The external library may be available in any of these forms:
+The property name `jquery` indicates that the module `jquery` in `import $ from 'jquery'` should be excluded. In order to replace this module, the value `jQuery` will be used to retrieve a global `jQuery` variable, as the default external library type is `var`, see [externalsType](#externalstype).
 
-- **root**: The library should be available as a global variable (e.g. via a script tag).
-- **commonjs**: The library should be available as a CommonJS module.
-- **commonjs2**: Similar to the above but where the export is `module.exports.default`.
-- **amd**: Similar to `commonjs` but using AMD module system.
+The bundle with external dependencies can be used in various module contexts, such as [CommonJS, AMD, global and ES2015 modules](/concepts/modules).
+
+The external library may be available in any of these forms: global variable, CommonJS, AMD, ES2015 Module, see more in [externalsType](#externalstype).
 
 The following syntaxes are accepted...
 
 ### string
 
-See the example above. The property name `jquery` indicates that the module `jquery` in `import $ from 'jquery'` should be excluded. In order to replace this module, the value `jQuery` will be used to retrieve a global `jQuery` variable. In other words, when a string is provided it will be treated as `root` (defined above and below).
+Depending on the [externalsType](#externalstype), this could be the name of the global variable (see [`'global'`](#externalstypeglobal), [`'this'`](#externalstypethis), [`'var'`](#externalstypevar), [`'window'`](#externalstypewindow)) or the name of the module (see `amd`, [`commonjs`](#externalstypecommonjs), [`module`](#externalstypemodule), `umd`).
+
+You can also use the shortcut syntax if you're defining only 1 external:
 
-You can specify [external library type](#externalstype) to the external using the `[externalsType] [externals]` syntax. This will override the default external library type specified in the [externalsType](#externalstype) option.
+```javascript
+module.exports = {
+  //...
+  externals: 'jquery',
+};
+```
 
-For example, if you want to externalise a library as a [CommonJS module](#externalstypecommonjs), you can specify
+equals to 
+
+```javascript
+module.exports = {
+  //...
+  externals: {
+    jquery: 'jquery',
+  },
+};
+```
+
+You can specify the [external library type](#externalstype) to the external using the `${externalsType} ${path}` syntax. This will override the default external library type specified in the [externalsType](#externalstype) option.
+
+For example, if the external library is a [CommonJS module](#externalstypecommonjs), you can specify
 
 ```javascript
 module.exports = {
@@ -96,11 +115,11 @@ module.exports = {
 };
 ```
 
-`subtract: ['./math', 'subtract']` allows you select part of a commonjs module, where `./math` is the module and your bundle only requires the subset under the `subtract` variable. This example would translate to `require('./math').subtract;`
+`subtract: ['./math', 'subtract']` allows you select part of a module, where `./math` is the module and your bundle only requires the subset under the `subtract` variable.
 
-Similar to the [string syntax](#string), you can specify the external library type with the `[externalsType] [externals]` syntax.
+When the `externalsType` is `commonjs`, this example would translate to `require('./math').subtract;`. When the `externalsType` is `window`, this example would translate to `window["./math"]["subtract"];`
 
-For example
+Similar to the [string syntax](#string), you can specify the external library type with the `${externalsType} ${path}` syntax, in the first item of the array, for example:
 
 ```javascript
 module.exports = {
@@ -113,7 +132,7 @@ module.exports = {
 
 ### object
 
-W> An object with `{ root, amd, commonjs, ... }` is only allowed for [`libraryTarget: 'umd'`](/configuration/output/#outputlibrarytarget). It's not allowed for other library targets.
+W> An object with `{ root, amd, commonjs, ... }` is only allowed for [`libraryTarget: 'umd'`](/configuration/output/#outputlibrarytarget) and [`externalsType: 'umd'`](#externalstype). It's not allowed for other library targets.
 
 ```javascript
 module.exports = {
@@ -163,8 +182,8 @@ Here're arguments the function can receive:
 The callback function takes three arguments:
 
 - `err` (`Error`): Used to indicate if there has been an error while externalizing the import. If there is an error, this should be the only parameter used.
-- `result` (`string` `[string]` `object`): Describes the external module. Can accept a string in the format `${type} ${path}`, or one of the other standard external formats ([`string`](#string), [`[string]`](#string-1), or [`object`](#object))
-- `type` (`string`): Optional parameter that indicates the module type (if it has not already been indicated in the `result` parameter).
+- `result` (`string` `[string]` `object`): Describes the external module with the other external formats ([`string`](#string), [`[string]`](#string-1), or [`object`](#object))
+- `type` (`string`): Optional parameter that indicates the module [external type](#externalstype) (if it has not already been indicated in the `result` parameter).
 
 As an example, to externalize all imports where the import path matches a regular expression you could do the following:
 
@@ -330,23 +349,23 @@ Supported types:
 
 - `'amd'`
 - `'amd-require'`
-- `'assign'`
+- `'assign'` - same as `'var'`
 - [`'commonjs'`](#externalstypecommonjs)
 - `'commonjs-module'`
-- `'global'`
+- [`'global'`](#externalstypeglobal)
 - `'import'` - uses `import()` to load a native EcmaScript module (async module)
 - `'jsonp'`
 - [`'module'`](#externalstypemodule)
 - [`'node-commonjs'`](#externalstypenode-commonjs)
-- `'promise'` - same as `'var'` but awaits the result (async module)
-- `'self'`
+- [`'promise'`](#externalstypepromise) - same as `'var'` but awaits the result (async module)
+- [`'self'`](#externalstypeself)
 - `'system'`
 - [`'script'`](#externalstypescript)
-- `'this'`
+- [`'this'`](#externalstypethis)
 - `'umd'`
 - `'umd2'`
-- `'var'`
-- `'window'`
+- [`'var'`](#externalstypevar)
+- [`'window'`](#externalstypewindow)
 
 **webpack.config.js**
 
@@ -385,6 +404,36 @@ into something like:
 const fs = require('fs-extra');
 ```
 
+### externalsType.global
+
+Specify the default type of externals as `'global'`. Webpack will read the external as a global variable on the `global` object.
+
+#### Example
+
+```javascript
+import jq from 'jquery'
+jq('.my-element').animate(/* ... */);
+```
+
+**webpack.config.js**
+
+```javascript
+module.exports = {
+  // ...
+  externalsType: 'global',
+  externals: {
+    jquery: '$',
+  },
+};
+```
+
+Will compile into something like
+
+```javascript
+const jq = global['$'];
+jq('.my-element').animate(/* ... */);
+```
+
 ### externalsType.module
 
 Specify the default type of externals as `'module'`. Webpack will generate code like `import * as X from '...'` for externals used in a module.
@@ -415,9 +464,69 @@ module.export = {
 };
 ```
 
+### externalsType.promise
+
+Specify the default type of externals as `'promise'`. Webpack will read the external as a global variable (similar to [`'var'`](#externalstypevar)) and `await` for it.
+
+#### Example
+
+```javascript
+import jq from 'jquery'
+jq('.my-element').animate(/* ... */);
+```
+
+**webpack.config.js**
+
+```javascript
+module.exports = {
+  // ...
+  externalsType: 'promise',
+  externals: {
+    jquery: '$',
+  },
+};
+```
+
+Will compile into something like
+
+```javascript
+const jq = await $;
+jq('.my-element').animate(/* ... */);
+```
+
+### externalsType.self
+
+Specify the default type of externals as `'self'`. Webpack will read the external as a global variable on the `self` object.
+
+#### Example
+
+```javascript
+import jq from 'jquery'
+jq('.my-element').animate(/* ... */);
+```
+
+**webpack.config.js**
+
+```javascript
+module.exports = {
+  // ...
+  externalsType: 'self',
+  externals: {
+    jquery: '$',
+  },
+};
+```
+
+Will compile into something like
+
+```javascript
+const jq = self['$'];
+jq('.my-element').animate(/* ... */);
+```
+
 ### externalsType.script
 
-Specify the default type of externals as `'script'`. Webpack will Load the external as a script exposing predefined global variables with HTML `<script>` element. The `<script>` tag would be removed after the script has been loaded.
+Specify the default type of externals as `'script'`. Webpack will load the external as a script exposing predefined global variables with HTML `<script>` element. The `<script>` tag would be removed after the script has been loaded.
 
 #### Syntax
 
@@ -499,6 +608,97 @@ T> When loading code with HTML `<script>` tags, the webpack runtime will try to
 
 T> Options like `output.chunkLoadTimeout`, `output.crossOriginLoading` and `output.scriptType` will also have effect on the external scripts loaded this way.
 
+### externalsType.this
+
+Specify the default type of externals as `'this'`. Webpack will read the external as a global variable on the `this` object.
+
+#### Example
+
+```javascript
+import jq from 'jquery'
+jq('.my-element').animate(/* ... */);
+```
+
+**webpack.config.js**
+
+```javascript
+module.exports = {
+  // ...
+  externalsType: 'this',
+  externals: {
+    jquery: '$',
+  },
+};
+```
+
+Will compile into something like
+
+```javascript
+const jq = this['$'];
+jq('.my-element').animate(/* ... */);
+```
+
+### externalsType.var
+
+Specify the default type of externals as `'var'`. Webpack will read the external as a global variable.
+
+#### Example
+
+```javascript
+import jq from 'jquery'
+jq('.my-element').animate(/* ... */);
+```
+
+**webpack.config.js**
+
+```javascript
+module.exports = {
+  // ...
+  externalsType: 'var',
+  externals: {
+    jquery: '$',
+  },
+};
+```
+
+Will compile into something like
+
+```javascript
+const jq = $;
+jq('.my-element').animate(/* ... */);
+```
+
+
+### externalsType.window
+
+Specify the default type of externals as `'window'`. Webpack will read the external as a global variable on the `window` object.
+
+#### Example
+
+```javascript
+import jq from 'jquery'
+jq('.my-element').animate(/* ... */);
+```
+
+**webpack.config.js**
+
+```javascript
+module.exports = {
+  // ...
+  externalsType: 'window',
+  externals: {
+    jquery: '$',
+  },
+};
+```
+
+Will compile into something like
+
+```javascript
+const jq = window['$'];
+jq('.my-element').animate(/* ... */);
+```
+
 ## externalsPresets
 
 `object`