Skip to content

Commit 46b6d4e

Browse files
Merge remote-tracking branch 'origin/main' into claude/html-webpack-plugin-deprecation-spdnlg
2 parents 0dd93d7 + f2b7266 commit 46b6d4e

8 files changed

Lines changed: 422 additions & 13 deletions

File tree

‎src/content/awesome-webpack.mdx‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -157,8 +157,7 @@ _People passionate about Webpack (In no particular order)_
157157
- [Define Variable Webpack Plugin](https://github.com/bios21/define-variable-webpack-plugin) - Enhancement of DefinePlugin to store defined things in actual variables. -- _Maintainer_ `Lilian Saget-Lethias` [![Github][githubicon]](https://github.com/bios21) [![Twitter][twittericon]](https://twitter.com/lsagetlethias)
158158
- [Shell Script Webpack Plugin](https://github.com/drewloomer/hook-shell-script-webpack-plugin) - A plugin for running arbitrary shell scripts when [compiler hooks](https://webpack.js.org/api/compiler-hooks/) are triggered. -- _Maintainer_ `Drew Loomer` [![Github][githubicon]](https://github.com/drewloomer) [![Twitter][twittericon]](https://twitter.com/drewloomer)
159159
- [Stylelint Webpack Plugin](https://github.com/webpack/stylelint-webpack-plugin): A Stylelint plugin for webpack. -- _Maintainer_: `Ricardo Gobbo de Souza` [![Github][githubicon]](https://github.com/ricardogobbosouza)
160-
- [ESLint Webpack Plugin](https://github.com/webpack-contrib/eslint-webpack-plugin): A ESLint plugin for webpack
161-
. -- _Maintainer_: `Ricardo Gobbo de Souza` [![Github][githubicon]](https://github.com/ricardogobbosouza)
160+
- [Diagnostics Webpack Plugin](https://github.com/webpack/diagnostics-webpack-plugin): Runs ESLint, Stylelint and other diagnostic tools over your sources during the build, replacing ESLint Webpack Plugin and Stylelint Webpack Plugin. -- _Maintainer_: `Ricardo Gobbo de Souza` [![Github][githubicon]](https://github.com/ricardogobbosouza)
162161
- [Exclude Assets Webpack Plugin](https://github.com/klaytonfaria/webpack-exclude-assets-plugin): A plugin to exclude assets from webpack output based on a path RegExp pattern. -- _Maintainer_: `Klayton Faria` [![Github][githubicon]](https://github.com/klaytonfaria)
163162
- [Webpack Shell Plugin Next](https://github.com/s00d/webpack-shell-plugin-next): A plugin allows you to run any shell commands before or after webpack builds. -- _Maintainer_: `Kuzmin Pavel` [![Github][githubicon]](https://github.com/s00d)
164163
- [Gettext Webpack Plugin](https://github.com/juanluispaz/gettext-webpack-plugin): Embed localization into your bundle using gettext. -- _Maintainer_: `Juan Luis Paz` [![Github][githubicon]](https://github.com/juanluispaz)

‎src/content/configuration/output.mdx‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -330,6 +330,181 @@ export default {
330330
};
331331
```
332332

333+
## output.copy
334+
335+
<Badge text="5.111.0+" />
336+
337+
`string` `[string, object]`
338+
339+
Copy files and directories into [`output.path`](#outputpath) as part of the build. A copied file becomes an asset like any other, so [`output.clean`](#outputclean) keeps it, [stats](/configuration/stats/) reports it, and in [watch mode](/configuration/watch/) editing a source file copies it again without rebuilding the rest.
340+
341+
```js
342+
export default {
343+
// ...
344+
output: {
345+
copy: "static",
346+
},
347+
};
348+
```
349+
350+
A string is shorthand for the `from` of a single pattern. Pass an array to copy from more than one place, mixing strings and pattern objects:
351+
352+
```js
353+
export default {
354+
// ...
355+
output: {
356+
copy: [
357+
// A directory keeps the structure below itself.
358+
"static",
359+
// Several sources into one destination, in order.
360+
{ from: ["licenses/*.txt", "vendor/licenses/*.txt"], to: "licenses" },
361+
// A filename template renames, flattens and hashes.
362+
{ from: "img", to: "i", filename: "[name].[contenthash][ext]" },
363+
],
364+
},
365+
};
366+
```
367+
368+
Every copied asset carries `copied: true` and the `sourceFilename` it came from in its [asset info](/api/stats/#asset-objects), so a later plugin can tell the copied assets from the generated ones.
369+
370+
W> A pattern that matches nothing warns, and copying a file onto an asset the compilation itself emits is an error — give the copy another name with `filename` or `to`. Within one `output.copy`, a later pattern may deliberately copy over what an earlier one wrote.
371+
372+
### Copy patterns
373+
374+
A pattern is a `from` plus the options below.
375+
376+
| Option | Type | Default | Description |
377+
| --------------------- | ------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
378+
| `context` | `string` | see below | Directory `from` is resolved from, and the directory the copied paths keep their structure below. |
379+
| `filename` | `string` `function (pathData, assetInfo) => string` | `'[path][base]'` | Name of the copied file inside `to`, as a [filename template](#template-strings). |
380+
| `from` | `string` `[string]` | required | Glob or path to copy from. A glob separates with `/`, matches dot files, and takes `*`, `**`, `?`, `[]` and `{}`. |
381+
| `globOptions` | `object` | | How the glob in `from` matches — see [glob options](#glob-options). |
382+
| `info` | `object` `function (file) => object` | | [Asset info](/api/stats/#asset-objects) of the copied file, merged over the info the copy already carries. |
383+
| `preservePermissions` | `boolean` | `false` | Whether the copy keeps the permissions of the file it came from. Has no effect on Windows. |
384+
| `preserveTimestamps` | `boolean` | `false` | Whether the copy keeps the access and modification times of the file it came from, rather than the time it was written. |
385+
| `to` | `string` `function (file) => string` | [`output.path`](#outputpath) | Directory the files are copied to, relative to `output.path`. |
386+
| `transform` | `function (content, absoluteFilename) => string \| Buffer` `object` | | Modifies the content on the way through — see [transforming content](#transforming-content). |
387+
388+
`context` defaults to the compiler [`context`](/configuration/entry-context/#context), and to what `from` names when `from` is not a glob — so `from: 'static'` copies the tree below `static/` rather than into a `static/` directory. Setting it explicitly roots every `from` of the pattern at one directory, which is how several globs keep a shared structure:
389+
390+
```js
391+
export default {
392+
// ...
393+
output: {
394+
copy: [
395+
// "vendor/a/x.js" lands at "lib/a/x.js", not at "lib/x.js".
396+
{ from: ["a/**/*.js", "b/**/*.js"], context: "vendor", to: "lib" },
397+
],
398+
},
399+
};
400+
```
401+
402+
`to` and `info` may each be a function of the file being copied, which receives `{ absoluteFilename, sourceFilename, filename }` — `filename` being the name the file has so far, relative to `to`:
403+
404+
```js
405+
export default {
406+
// ...
407+
output: {
408+
copy: [
409+
{
410+
from: "assets",
411+
to: (file) => (file.filename.endsWith(".css") ? "css" : "media"),
412+
info: (file) => ({ immutable: file.filename.endsWith(".png") }),
413+
},
414+
],
415+
},
416+
};
417+
```
418+
419+
### Glob options
420+
421+
`globOptions` says how the glob in `from` matches.
422+
423+
| Option | Type | Default | Description |
424+
| ---------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
425+
| `caseSensitive` | `boolean` | `true` | Whether the glob matches the case of a file name. |
426+
| `deep` | `number` | no limit | How many directory levels below the base of the glob are read, where `1` reads only the base itself. |
427+
| `dot` | `boolean` | `true` | Whether the glob reaches a file or directory whose name starts with a dot without naming it. |
428+
| `followSymlinks` | `boolean` | `true` | Whether a symbolic link is resolved and copied as what it points at. `false` copies the link itself, unresolved. |
429+
| `ignore` | `[string]` | | Globs of files which are not copied, resolved like `from`. A directory one of them matches is skipped whole. |
430+
431+
```js
432+
export default {
433+
// ...
434+
output: {
435+
copy: [
436+
{
437+
from: "static/**/*.html",
438+
to: "pages",
439+
globOptions: { dot: false, deep: 2, ignore: ["**/draft-*.html"] },
440+
},
441+
],
442+
},
443+
};
444+
```
445+
446+
### Transforming content
447+
448+
`transform` rewrites a file on the way through. It receives the content as a `Buffer` and the absolute path it was read from, and may return a string, a `Buffer`, or a promise of either:
449+
450+
```js
451+
export default {
452+
// ...
453+
output: {
454+
copy: [
455+
{
456+
from: "config.json",
457+
to: "runtime",
458+
transform: (content) =>
459+
content.toString().replace("__API__", "https://example.com"),
460+
},
461+
],
462+
},
463+
};
464+
```
465+
466+
The result is cached on the content of the file. When the transform depends on anything else, say so with the object form so the cache misses when that changes:
467+
468+
```js
469+
export default {
470+
// ...
471+
output: {
472+
copy: [
473+
{
474+
from: "config.json",
475+
transform: {
476+
transformer: (content) =>
477+
content.toString().replace("__API__", apiUrl),
478+
cache: { keys: { apiUrl } },
479+
},
480+
},
481+
],
482+
},
483+
};
484+
```
485+
486+
`cache` also takes `false` to skip caching, or a function receiving `(defaultKeys, absoluteFilename)` and returning the keys to cache under.
487+
488+
T> A symbolic link copied as a link (`globOptions.followSymlinks: false`) has its target as its whole content, so a `transform` never sees it.
489+
490+
### Copying with the plugin
491+
492+
`output.copy` covers the patterns; [`CopyPlugin`](/plugins/copy-plugin/) is the same copying with two more options on it — `concurrency` and the `processAssets` `stage` the files are copied at. Reach for it when you need either:
493+
494+
```js
495+
import webpack from "webpack";
496+
497+
export default {
498+
// ...
499+
plugins: [
500+
new webpack.CopyPlugin({
501+
patterns: ["static"],
502+
concurrency: 50,
503+
}),
504+
],
505+
};
506+
```
507+
333508
## output.crossOriginLoading
334509

335510
`boolean = false` `string: 'anonymous' | 'use-credentials'`

‎src/content/configuration/performance.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ contributors:
99
- EugeneHlushko
1010
- shivxmsharma
1111
- bjohansebas
12+
- alexander-akait
1213
---
1314

1415
These options allows you to control how webpack notifies you of assets and entry points that exceed a specific file limit.
@@ -34,6 +35,7 @@ Besides the size budget ([`maxAssetSize`](#performancemaxassetsize) and [`maxEnt
3435
| What weighs a chunk | [`largeModules`](#performancelargemodules), [`inlinedAssets`](#performanceinlinedassets), [`sourceMaps`](#performancesourcemaps), [`broadContexts`](#performancebroadcontexts) |
3536
| Code hazards | [`evalUsage`](#performanceevalusage), [`pureAnnotations`](#performancepureannotations), [`topLevelThis`](#performancetoplevelthis), [`mixedExports`](#performancemixedexports) |
3637
| Configuration | [`unusedConfig`](#performanceunusedconfig), [`osDependentRules`](#performanceosdependentrules) |
38+
| What tools can read | [`analyzableBailouts`](#performanceanalyzablebailouts) |
3739
| Build itself | [`cacheEffectiveness`](#performancecacheeffectiveness), [`hotspots`](#performancehotspots), [`circularDependencies`](#performancecirculardependencies) |
3840

3941
Most of them are reported through [`performance.hints`](#performancehints), so they are silent while `hints` is `false`.
@@ -80,6 +82,42 @@ export default {
8082

8183
T> Turning everything on at once is a good way to audit a project, but several checks walk the module graph and cost build time. Once you have read the report, keep the handful that matter to you enabled and leave the rest off.
8284

85+
### performance.analyzableBailouts
86+
87+
<Badge text="5.111.0+" />
88+
89+
`boolean = false`
90+
91+
Report references in [`output.module`](/configuration/output/#outputmodule) builds that kept webpack's runtime form, naming what stopped each from being written as a literal `import()` or `new URL()`. The reasons are grouped and counted rather than listed one module at a time, and the check is silent outside ESM output, where nothing claims to be analyzable in the first place.
92+
93+
An ESM build normally names each chunk and asset outright, so another bundler, a CDN's module preloader or an import-map generator can follow the reference without running webpack's runtime. Where something prevents that, webpack falls back to `__webpack_require__.e(id)` or a URL built from `__webpack_require__.p` — correct, but opaque to every tool but webpack. Until this check, that fallback was reported only through `stats.optimizationBailout`, which nothing shows by default.
94+
95+
What each reason means, and what lifts it:
96+
97+
| Reason mentions | What to change |
98+
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99+
| [`output.chunkFormat`](/configuration/output/#outputchunkformat) is not `module` | chunks are not read through a native `import()` at all; set it to `"module"` |
100+
| [`output.importFunctionName`](/configuration/output/#outputimportfunctionname) | the call site is a named function rather than `import()`; leave it at `"import"` |
101+
| a worker loads its chunks with something other than `import` | set [`output.workerChunkLoading`](/configuration/output/#outputworkerchunkloading) to `"import"`, or the entry's `chunkLoading` likewise |
102+
| [`devtool`](/configuration/devtool/) wraps the module in `eval()` | `import.meta` does not parse there, and a specifier written inside the `eval()` string is invisible to a lexer even when webpack does write it out; use a non-`eval` devtool when the output has to be analyzable |
103+
| `__webpack_public_path__` is reassigned | the path is only known at runtime, so no literal can be written; set [`output.publicPath`](/configuration/output/#outputpublicpath) instead |
104+
| [`output.publicPath`](/configuration/output/#outputpublicpath) needs a base | a relative public path is read differently from each chunk; a root-absolute or absolute one, or `"auto"`, reads the same everywhere |
105+
| entries disagree on `baseUri`, or one is not absolute | give the entries that share a module the same absolute `baseUri` |
106+
| the compilation emits no JavaScript for a chunk | the chunk belongs to another build, as a Module Federation remote does; nothing to change here |
107+
| a hot update could move the name | only while [HMR](/concepts/hot-module-replacement/) is on; production output is unaffected |
108+
109+
```js
110+
export default {
111+
// ...
112+
experiments: { outputModule: true },
113+
output: { module: true },
114+
performance: {
115+
hints: "warning",
116+
analyzableBailouts: true,
117+
},
118+
};
119+
```
120+
83121
### performance.assetFilter
84122

85123
`function(assetFilename) => boolean`

0 commit comments

Comments
 (0)