Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit a4927e1

Browse filesBrowse files
tanhauhautanhauhau
committed
explain more for externalsType
1 parent 991ad16 commit a4927e1
Copy full SHA for a4927e1

File tree

Expand file treeCollapse file tree

1 file changed

+221
-22
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+221
-22
lines changed

‎src/content/configuration/externals.mdx

Copy file name to clipboardExpand all lines: src/content/configuration/externals.mdx
+221-22Lines changed: 221 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -59,22 +59,41 @@ import $ from 'jquery';
5959
$('.my-element').animate(/* ... */);
6060
```
6161

62-
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:
62+
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).
6363

64-
- **root**: The library should be available as a global variable (e.g. via a script tag).
65-
- **commonjs**: The library should be available as a CommonJS module.
66-
- **commonjs2**: Similar to the above but where the export is `module.exports.default`.
67-
- **amd**: Similar to `commonjs` but using AMD module system.
64+
The bundle with external dependencies can be used in various module contexts, such as [CommonJS, AMD, global and ES2015 modules](/concepts/modules).
65+
66+
The external library may be available in any of these forms: global variable, CommonJS, AMD, ES2015 Module, see more in [externalsType](#externalstype).
6867

6968
The following syntaxes are accepted...
7069

7170
### string
7271

73-
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).
72+
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`).
73+
74+
You can also use the shortcut syntax if you're defining only 1 external:
75+
76+
```javascript
77+
module.exports = {
78+
//...
79+
externals: 'jquery',
80+
};
81+
```
82+
83+
equals to
7484

75-
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.
85+
```javascript
86+
module.exports = {
87+
//...
88+
externals: {
89+
jquery: 'jquery',
90+
},
91+
};
92+
```
7693

77-
For example, if you want to externalise a library as a [CommonJS module](#externalstypecommonjs), you can specify
94+
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.
95+
96+
For example, if the external library is a [CommonJS module](#externalstypecommonjs), you can specify
7897

7998
```javascript
8099
module.exports = {
@@ -96,11 +115,11 @@ module.exports = {
96115
};
97116
```
98117

99-
`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;`
118+
`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.
100119

101-
Similar to the [string syntax](#string), you can specify the external library type with the `[externalsType] [externals]` syntax.
120+
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"];`
102121

103-
For example
122+
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:
104123

105124
```javascript
106125
module.exports = {
@@ -113,7 +132,7 @@ module.exports = {
113132

114133
### object
115134

116-
W> An object with `{ root, amd, commonjs, ... }` is only allowed for [`libraryTarget: 'umd'`](/configuration/output/#outputlibrarytarget). It's not allowed for other library targets.
135+
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.
117136

118137
```javascript
119138
module.exports = {
@@ -163,8 +182,8 @@ Here're arguments the function can receive:
163182
The callback function takes three arguments:
164183

165184
- `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.
166-
- `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))
167-
- `type` (`string`): Optional parameter that indicates the module type (if it has not already been indicated in the `result` parameter).
185+
- `result` (`string` `[string]` `object`): Describes the external module with the other external formats ([`string`](#string), [`[string]`](#string-1), or [`object`](#object))
186+
- `type` (`string`): Optional parameter that indicates the module [external type](#externalstype) (if it has not already been indicated in the `result` parameter).
168187

169188
As an example, to externalize all imports where the import path matches a regular expression you could do the following:
170189

@@ -330,23 +349,23 @@ Supported types:
330349

331350
- `'amd'`
332351
- `'amd-require'`
333-
- `'assign'`
352+
- `'assign'` - same as `'var'`
334353
- [`'commonjs'`](#externalstypecommonjs)
335354
- `'commonjs-module'`
336-
- `'global'`
355+
- [`'global'`](#externalstypeglobal)
337356
- `'import'` - uses `import()` to load a native EcmaScript module (async module)
338357
- `'jsonp'`
339358
- [`'module'`](#externalstypemodule)
340359
- [`'node-commonjs'`](#externalstypenode-commonjs)
341-
- `'promise'` - same as `'var'` but awaits the result (async module)
342-
- `'self'`
360+
- [`'promise'`](#externalstypepromise) - same as `'var'` but awaits the result (async module)
361+
- [`'self'`](#externalstypeself)
343362
- `'system'`
344363
- [`'script'`](#externalstypescript)
345-
- `'this'`
364+
- [`'this'`](#externalstypethis)
346365
- `'umd'`
347366
- `'umd2'`
348-
- `'var'`
349-
- `'window'`
367+
- [`'var'`](#externalstypevar)
368+
- [`'window'`](#externalstypewindow)
350369

351370
**webpack.config.js**
352371

@@ -385,6 +404,36 @@ into something like:
385404
const fs = require('fs-extra');
386405
```
387406

407+
### externalsType.global
408+
409+
Specify the default type of externals as `'global'`. Webpack will read the external as a global variable on the `global` object.
410+
411+
#### Example
412+
413+
```javascript
414+
import jq from 'jquery';
415+
jq('.my-element').animate(/* ... */);
416+
```
417+
418+
**webpack.config.js**
419+
420+
```javascript
421+
module.exports = {
422+
// ...
423+
externalsType: 'global',
424+
externals: {
425+
jquery: '$',
426+
},
427+
};
428+
```
429+
430+
Will compile into something like
431+
432+
```javascript
433+
const jq = global['$'];
434+
jq('.my-element').animate(/* ... */);
435+
```
436+
388437
### externalsType.module
389438

390439
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 = {
415464
};
416465
```
417466

467+
### externalsType.promise
468+
469+
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.
470+
471+
#### Example
472+
473+
```javascript
474+
import jq from 'jquery';
475+
jq('.my-element').animate(/* ... */);
476+
```
477+
478+
**webpack.config.js**
479+
480+
```javascript
481+
module.exports = {
482+
// ...
483+
externalsType: 'promise',
484+
externals: {
485+
jquery: '$',
486+
},
487+
};
488+
```
489+
490+
Will compile into something like
491+
492+
```javascript
493+
const jq = await $;
494+
jq('.my-element').animate(/* ... */);
495+
```
496+
497+
### externalsType.self
498+
499+
Specify the default type of externals as `'self'`. Webpack will read the external as a global variable on the `self` object.
500+
501+
#### Example
502+
503+
```javascript
504+
import jq from 'jquery';
505+
jq('.my-element').animate(/* ... */);
506+
```
507+
508+
**webpack.config.js**
509+
510+
```javascript
511+
module.exports = {
512+
// ...
513+
externalsType: 'self',
514+
externals: {
515+
jquery: '$',
516+
},
517+
};
518+
```
519+
520+
Will compile into something like
521+
522+
```javascript
523+
const jq = self['$'];
524+
jq('.my-element').animate(/* ... */);
525+
```
526+
418527
### externalsType.script
419528

420-
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.
529+
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.
421530

422531
#### Syntax
423532

@@ -499,6 +608,96 @@ T> When loading code with HTML `<script>` tags, the webpack runtime will try to
499608

500609
T> Options like `output.chunkLoadTimeout`, `output.crossOriginLoading` and `output.scriptType` will also have effect on the external scripts loaded this way.
501610

611+
### externalsType.this
612+
613+
Specify the default type of externals as `'this'`. Webpack will read the external as a global variable on the `this` object.
614+
615+
#### Example
616+
617+
```javascript
618+
import jq from 'jquery';
619+
jq('.my-element').animate(/* ... */);
620+
```
621+
622+
**webpack.config.js**
623+
624+
```javascript
625+
module.exports = {
626+
// ...
627+
externalsType: 'this',
628+
externals: {
629+
jquery: '$',
630+
},
631+
};
632+
```
633+
634+
Will compile into something like
635+
636+
```javascript
637+
const jq = this['$'];
638+
jq('.my-element').animate(/* ... */);
639+
```
640+
641+
### externalsType.var
642+
643+
Specify the default type of externals as `'var'`. Webpack will read the external as a global variable.
644+
645+
#### Example
646+
647+
```javascript
648+
import jq from 'jquery';
649+
jq('.my-element').animate(/* ... */);
650+
```
651+
652+
**webpack.config.js**
653+
654+
```javascript
655+
module.exports = {
656+
// ...
657+
externalsType: 'var',
658+
externals: {
659+
jquery: '$',
660+
},
661+
};
662+
```
663+
664+
Will compile into something like
665+
666+
```javascript
667+
const jq = $;
668+
jq('.my-element').animate(/* ... */);
669+
```
670+
671+
### externalsType.window
672+
673+
Specify the default type of externals as `'window'`. Webpack will read the external as a global variable on the `window` object.
674+
675+
#### Example
676+
677+
```javascript
678+
import jq from 'jquery';
679+
jq('.my-element').animate(/* ... */);
680+
```
681+
682+
**webpack.config.js**
683+
684+
```javascript
685+
module.exports = {
686+
// ...
687+
externalsType: 'window',
688+
externals: {
689+
jquery: '$',
690+
},
691+
};
692+
```
693+
694+
Will compile into something like
695+
696+
```javascript
697+
const jq = window['$'];
698+
jq('.my-element').animate(/* ... */);
699+
```
700+
502701
## externalsPresets
503702

504703
`object`

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.