Skip to content

Commit 8dd2a8c

Browse files
authored
docs(configuration): document external script (#3898)
1 parent 1308d6e commit 8dd2a8c

File tree

1 file changed

+74
-0
lines changed

1 file changed

+74
-0
lines changed

src/content/configuration/externals.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,7 @@ Supported types:
321321
- `'system'`
322322
- `'promise'` - same as `'var'` but awaits the result (async module)
323323
- `'import'` - uses `import()` to load a native EcmaScript module (async module)
324+
- `'script'` - load script exposing predefined global variables with HTML `<script>` element
324325

325326
__webpack.config.js__
326327

@@ -330,3 +331,76 @@ module.exports = {
330331
externalsType: 'promise'
331332
};
332333
```
334+
335+
### `script`
336+
337+
External script can be loaded from any URL when [`externalsType`](#externalstype) is set to `'script'`. The `<script>` tag would be removed after the script has been loaded.
338+
339+
#### Syntax
340+
341+
```javascript
342+
module.exports = {
343+
externals: {
344+
packageName: ['http://example.com/script.js', 'global', 'property', 'property'] // properties are optional
345+
}
346+
};
347+
```
348+
349+
You can also use the shortcut syntax if you're not going to specify any properties:
350+
351+
```javascript
352+
module.exports = {
353+
externals: {
354+
packageName: 'global@http://example.com/script.js' // no properties here
355+
}
356+
};
357+
```
358+
359+
T> [`output.publicPath`](/configuration/output/#outputpublicpath) won't be added to the provided URL.
360+
361+
#### Example
362+
363+
Let's load a `lodash` from CDN:
364+
365+
__webpack.config.js__
366+
367+
```js
368+
module.exports = {
369+
// ...
370+
externalsType: 'script',
371+
externals: {
372+
lodash: ['https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js', '_'],
373+
}
374+
};
375+
```
376+
377+
Then use it in code:
378+
379+
```js
380+
import _ from 'lodash';
381+
console.log(_.head([1, 2, 3]));
382+
```
383+
384+
Here's how we specify properties for the above example:
385+
386+
```js
387+
module.exports = {
388+
// ...
389+
externalsType: 'script',
390+
externals: {
391+
lodash: ['https://cdn.jsdelivr.net/npm/lodash@4.17.19/lodash.min.js', '_', 'head'],
392+
}
393+
};
394+
```
395+
396+
Both local variable `head` and global `window._` will be exposed when you `import` `lodash`:
397+
398+
```js
399+
import head from 'lodash';
400+
console.log(head([1, 2, 3])); // logs 1 here
401+
console.log(window._.head(['a', 'b'])); // logs a here
402+
```
403+
404+
T> When loading code with HTML `<script>` tags, the webpack runtime will try to find an existing `<script>` tag that matches the `src` attribute or has a specific `data-webpack` attribute. For chunk loading `data-webpack` attribute would have value of `'[output.uniqueName]:chunk-[chunkId]'` while external script has value of `'[output.uniqueName]:[global]'`.
405+
406+
T> Options like `output.chunkLoadTimeout`, `output.crossOriginLoading` and `output.scriptType` will also have effect on the external scripts loaded this way.

0 commit comments

Comments
 (0)