diff --git a/src/content/configuration/cache.mdx b/src/content/configuration/cache.mdx
index 29416850c679..a39e0780a305 100644
--- a/src/content/configuration/cache.mdx
+++ b/src/content/configuration/cache.mdx
@@ -267,11 +267,11 @@ export default {
### cache.managedPaths
-`[string] = ['./node_modules']`
+`[string]`
W> Moved to [snapshot.managedPaths](/configuration/other-options/#managedpaths)
-`cache.managedPaths` is an array of package-manager only managed paths. Webpack will avoid hashing and timestamping them, assume the version is unique and will use it as a snapshot (for both memory and filesystem cache).
+`cache.managedPaths` is still accepted by the configuration schema (only under `type: 'filesystem'`) but ignored: webpack drops it while normalizing the configuration and only reads [`snapshot.managedPaths`](/configuration/other-options/#managedpaths), which is the effective option for package-manager managed paths.
### cache.maxAge
@@ -457,7 +457,7 @@ export default {
`string: 'memory' | 'filesystem'`
-Sets the `cache` type to either in memory or on the file system. The `memory` option is straightforward, it tells webpack to store cache in memory and doesn't allow additional configuration:
+Sets the `cache` type to either in memory or on the file system. The `memory` option is straightforward, it tells webpack to store cache in memory and only accepts the [`cache.maxGenerations`](#cachemaxgenerations) and [`cache.cacheUnaffected`](#cachecacheunaffected) options:
**webpack.config.js**
diff --git a/src/content/configuration/dev-server.mdx b/src/content/configuration/dev-server.mdx
index 364c17f99bbe..b5382bf8d4e3 100644
--- a/src/content/configuration/dev-server.mdx
+++ b/src/content/configuration/dev-server.mdx
@@ -74,7 +74,7 @@ If you're using dev-server through the Node.js API, the options in `devServer` w
W> You cannot use the second `compiler` argument (a callback) when using `WebpackDevServer`.
-W> Be aware that when [exporting multiple configurations](/configuration/configuration-types/#exporting-multiple-configurations) only the `devServer` options for the first configuration will be taken into account and used for all the configurations in the array.
+W> Be aware that when [exporting multiple configurations](/configuration/configuration-types/#exporting-multiple-configurations) the `devServer` options are taken from the first configuration that defines `devServer`; if none does, from the first configuration with a web-like target (a `web` or `universal` platform, which covers `web`, `webworker`, `electron-preload`, `electron-renderer`, `node-webkit` and an unset `target`), and otherwise from the first configuration. They are used for all the configurations in the array.
T> If you're having trouble, navigating to the `/webpack-dev-server` route will show where files are served. For example, `http://localhost:9000/webpack-dev-server`.
@@ -365,9 +365,9 @@ W> The function will not have access to the variables declared in the outer scop
### progress
-`boolean`
+`boolean` `'linear' | 'circular'`
-Prints compilation progress in percentage in the browser.
+Prints compilation progress in percentage in the browser. `'linear'` and `'circular'` additionally show a visual indicator.
**webpack.config.js**
@@ -396,11 +396,11 @@ npx webpack serve --no-client-progress
### reconnect
-`boolean = true` `number`
+`boolean` `number = 10`
-Tells dev-server the number of times it should try to reconnect the client. When `true` it will try to reconnect unlimited times.
+Tells dev-server the number of times it should try to reconnect the client, 10 by default. When `true` it will try to reconnect unlimited times; `false` disables reconnecting.
**webpack.config.js**
@@ -1262,7 +1262,7 @@ export default {
## devServer.server
-`'http' | 'https' | 'spdy'` `string` `object`
+`'http' | 'https' | 'http2'` `string` `object` `function`
@@ -1323,7 +1323,7 @@ Usage via the CLI:
npx webpack serve --server-type spdy
```
-W> This option is ignored for Node 15.0.0 and above, as [spdy is broken for those versions](https://github.com/spdy-http2/node-spdy/issues/380). The dev server will migrate over to Node's built-in HTTP/2 once [Express](https://expressjs.com/) supports it.
+W> Since webpack-dev-server v6, `'spdy'` is no longer a built-in server type: it only works as a custom server string when the `spdy` package is installed, the CLI does not accept it, and [spdy is broken for Node 15.0.0 and above](https://github.com/spdy-http2/node-spdy/issues/380). Prefer `'http2'`, which uses Node's built-in `http2` module (with HTTP/1 fallback).
Use the object syntax to provide your own certificate:
diff --git a/src/content/configuration/devtool.mdx b/src/content/configuration/devtool.mdx
index 715841cdcaf5..dca84c059dd0 100644
--- a/src/content/configuration/devtool.mdx
+++ b/src/content/configuration/devtool.mdx
@@ -22,10 +22,12 @@ Use the [`SourceMapDevToolPlugin`](/plugins/source-map-dev-tool-plugin) for a mo
## devtool
-`string = 'eval'` `Array<{ type: "all" | "javascript" | "css", use: string }>` `false`
+`string` `Array<{ type: "all" | "javascript" | "css", use: string }>` `false`
Choose a style of [source mapping](http://blog.teamtreehouse.com/introduction-source-maps) to enhance the debugging process. These values can affect build and rebuild speed dramatically.
+The default is `false`. In [`mode: 'development'`](/configuration/mode/) it defaults to `'eval'` for JavaScript (plus `'source-map'` for CSS when [`experiments.css`](/configuration/experiments/#experimentscss) is enabled), unless a `module` or `modern-module` [library type](/configuration/output/#outputlibrarytype) is emitted, in which case it stays `false`.
+
You can also provide an array of objects to configure different source map styles for different asset types:
@@ -98,7 +100,7 @@ T> Instead of using the `devtool` option you can also use `SourceMapDevToolPlugi
| `hidden-*` addition | no reference to the SourceMap added. When SourceMap is not deployed, but should still be generated, e. g. for error reporting purposes. |
| `nosources-*` addition | source code is not included in SourceMap. This can be useful when the original files should be referenced (further config options needed). |
-T> We expect a certain pattern when validate devtool name, pay attention and don't mix up the sequence of devtool string. The pattern is: `[inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map`.
+T> We expect a certain pattern when validate devtool name, pay attention and don't mix up the sequence of devtool string. The pattern is: `[inline-|hidden-|eval-][nosources-][cheap-[module-]]source-map[-debugids]`.
Some of these values are suited for development and some for production. For development you typically want fast Source Maps at the cost of bundle size, but for production you want separate Source Maps that are accurate and support minimizing.
@@ -148,7 +150,7 @@ The following options are not ideal for development nor production. They are nee
These options are typically used in production:
-`(none)` (Omit the `devtool` option or set `devtool: false`) - No SourceMap is emitted. This is a good option to start with.
+`(none)` (Set `devtool: false`, or omit the option outside of `development` mode) - No SourceMap is emitted. This is a good option to start with.
`source-map` - A full SourceMap is emitted as a separate file. It adds a reference comment to the bundle so development tools know where to find it.
diff --git a/src/content/configuration/dotenv.mdx b/src/content/configuration/dotenv.mdx
index b701b5d07b72..71c7c6600b65 100644
--- a/src/content/configuration/dotenv.mdx
+++ b/src/content/configuration/dotenv.mdx
@@ -34,7 +34,6 @@ export default {
// ...
dotenv: {
prefix: "WEBPACK_",
- dir: true,
template: [".env", ".env.local", ".env.[mode]", ".env.[mode].local"],
},
};
@@ -76,23 +75,27 @@ T> For security reasons, an empty string `''` is not allowed as a prefix, as it
### `dir`
-`boolean` `string`
+`false` `string`
-**Default:** `true`
+**Default:** the compiler [`context`](/configuration/entry-context/#context)
The directory from which `.env` files are loaded.
-- `true` - Load from the project root (context)
- `false` - Disable `.env` file loading
-- `string` - Relative path from project root or absolute path
+- `string` - Absolute path to the directory; relative paths are rejected by the configuration validation
**webpack.config.js**
```js
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
export default {
// ...
dotenv: {
- dir: "./config", // Load from ./config directory
+ dir: path.resolve(__dirname, "config"), // Load from ./config directory
},
};
```
@@ -285,10 +288,15 @@ Load environment files from a custom location with custom naming:
**webpack.config.js**
```js
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
export default {
// ...
dotenv: {
- dir: "./environments",
+ dir: path.resolve(__dirname, "environments"),
template: [".env.base", ".env.[mode]"],
},
};
diff --git a/src/content/configuration/experiments.mdx b/src/content/configuration/experiments.mdx
index a03373d0c113..43538df1ce3c 100644
--- a/src/content/configuration/experiments.mdx
+++ b/src/content/configuration/experiments.mdx
@@ -12,7 +12,7 @@ contributors:
## experiments
-`boolean: false`
+`object`
`experiments` option was introduced in webpack 5 to empower users with the ability to activate and try out experimental features.
@@ -499,7 +499,7 @@ Placing an HTML `` comment immediately before a tag
-When `experiments.html` is enabled, `.html` is added to the default `resolve.extensions` ahead of the JavaScript extensions, so a directory entry like `entry: "./src"` resolves `./src/index.html` even when `./src/index.js` also exists. This makes the build HTML-first, similar to Vite or Parcel.
+When `experiments.html` is explicitly set to `true`, `.html` is added to the default `resolve.extensions` ahead of the JavaScript extensions, so a directory entry like `entry: "./src"` resolves `./src/index.html` even when `./src/index.js` also exists. This makes the build HTML-first, similar to Vite or Parcel. With the default `'auto'` (since 5.109.0), `.html` is appended after the JavaScript extensions instead, so `./src/index.js` still wins.
```js
export default {
diff --git a/src/content/configuration/externals.mdx b/src/content/configuration/externals.mdx
index b7318bbf0a6c..b084524fdd5f 100644
--- a/src/content/configuration/externals.mdx
+++ b/src/content/configuration/externals.mdx
@@ -62,7 +62,7 @@ import $ from "jquery";
$(".my-element").animate(/* ... */);
```
-The property name `jquery` specified under `externals` in the above `webpack.config.js` indicates that the module `jquery` in `import $ from 'jquery'` should be excluded from bundling. 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).
+The property name `jquery` specified under `externals` in the above `webpack.config.js` indicates that the module `jquery` in `import $ from 'jquery'` should be excluded from bundling. 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` when neither [`output.library.type`](/configuration/output/#outputlibrarytype) nor [`output.module`](/configuration/output/#outputmodule) is set, see [externalsType](#externalstype).
While we showed an example consuming external global variable above, the external can actually be available in any of these forms: global variable, CommonJS, AMD, ES2015 Module, see more in [externalsType](#externalstype).
@@ -131,7 +131,7 @@ export default {
### object
-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.
+W> An object with `{ root, amd, commonjs, ... }` maps [externals types](#externalstype) to the external's target for each type. A [`umd`](/configuration/output/#outputlibrarytarget) library reads the `root`, `amd`, `commonjs` and `commonjs2` entries, an `amd` or `system` library reads `amd`, and for any other externals type webpack uses the entry matching the effective type.
W> Since webpack 5.109.0, an object external with no entry for the used externals type emits a build error instead of silently resolving to `undefined` at runtime.
@@ -231,6 +231,8 @@ Here're arguments the function can receive:
- `ctx` (`object`): Object containing details of the file.
- `ctx.context` (`string`): The directory of the file which contains the import.
- `ctx.request` (`string`): The import path being requested.
+ - `ctx.originalRequest` (`string`) : Same as `ctx.request`, except for an element of a context module, where it is the request as written by the user.
+ - `ctx.dependencyType` (`string`): The category of the referencing dependency, e.g. `'esm'`, `'commonjs'` or `'url'`.
- `ctx.contextInfo` (`object`): Contains information about the issuer (e.g. the layer and compiler)
- `ctx.getResolve` : Get a resolve function with the current resolver options.
- `callback` (`function (err, result, type)`): Callback function used to indicate how the module should be externalized.
@@ -397,9 +399,9 @@ export default {
## externalsType
-`string = 'var'`
+`string`
-Specify the default type of externals. `amd`, `umd`, `system` and `jsonp` externals **depend on the [`output.libraryTarget`](/configuration/output/#outputlibrarytarget)** being set to the same value e.g. you can only consume `amd` externals within an `amd` library.
+Specify the default type of externals. It defaults to [`output.library.type`](/configuration/output/#outputlibrarytype) when that is a valid externals type, otherwise to `'module-import'` when [`output.module`](/configuration/output/#outputmodule) is enabled, and to `'var'` otherwise. `amd`, `umd`, `system` and `jsonp` externals **depend on the [`output.libraryTarget`](/configuration/output/#outputlibrarytarget)** being set to the same value e.g. you can only consume `amd` externals within an `amd` library.
Supported types:
@@ -407,10 +409,15 @@ Supported types:
- [`'amd-async'`](#externalstypeamd-async) - loads the external via the asynchronous AMD `require([...])` API (async module)
- `'amd-require'`
- `'assign'` - same as `'var'`
+- `'asset'` - the external is treated as an asset URL, the module exports the request string
+- `'asset-url'` - the external is used as a URL, e.g. in a CSS `url()`
- [`'commonjs'`](#externalstypecommonjs)
+- `'commonjs2'` - same output as `'commonjs'`
- `'commonjs-module'`
+- `'commonjs-static'` - same output as `'commonjs'`
+- `'css-import'` - the external becomes a CSS `@import url(...)`
+- `'css-url'` - deprecated alias for `'asset-url'`
- [`'global'`](#externalstypeglobal)
-- `'import'` - uses `import()` to load a native EcmaScript module (async module)
- `'jsonp'`
- [`'module'`](#externalstypemodule)
- [`'import'`](#externalstypeimport)
@@ -502,7 +509,7 @@ export default {
Will generate into something like:
```js
-import fs from "fs-extra";
+const fs = require("fs-extra");
```
Note that there will be a `require()` in the output bundle.
@@ -601,8 +608,6 @@ import source v from "external-mod";
### externalsType.import
-
-
Specify the default type of externals as `'import'`. Webpack will generate code like `import('...')` for externals used in a module.
#### Example
@@ -700,7 +705,7 @@ Will generate something like below:
```js
import * as __WEBPACK_EXTERNAL_MODULE_lodash__ from "lodash";
-const lodash = __WEBPACK_EXTERNAL_MODULE_jquery__;
+const lodash = __WEBPACK_EXTERNAL_MODULE_lodash__;
const __webpack_modules__ = {
jQuery: (module) => {
@@ -1093,7 +1098,7 @@ Enable presets of externals for specific targets.
| `web` | Treat references to `http(s)://...` and `std:...` as external and load them via `import` when used. **(Note that this changes execution order as externals are executed before any other code in the chunk)**. | boolean |
| `webAsync` | Treat references to `http(s)://...` and `std:...` as external and load them via `async import()` when used **(Note that this external type is an `async` module, which has various effects on the execution)**. | boolean |
-Note that if you're going to output ES Modules with those node.js-related presets, webpack will set the default `externalsType` to [`node-commonjs`](#externalstypenode-commonjs) which would use `createRequire` to construct a require function instead of using `require()`.
+Note that if you're going to output ES Modules with those node.js-related presets, the built-in modules are externalized as [`module-import`](#externalstypemodule-import). In ES module output, [`node-commonjs`](#externalstypenode-commonjs) externals, as well as `commonjs*` externals when `externalsPresets.node` is set, use `createRequire` to construct a require function instead of using `require()`.
**Example**
diff --git a/src/content/configuration/module.mdx b/src/content/configuration/module.mdx
index 222483d48cac..361b0be1b9f4 100644
--- a/src/content/configuration/module.mdx
+++ b/src/content/configuration/module.mdx
@@ -165,11 +165,6 @@ export default {
// Avoid generating and loading a stylesheet and only embed exports from css into output javascript files.
// type: boolean, available since webpack 5.90.0
exportsOnly: true,
-
- // Customize how css export names are exported to javascript modules, such as keeping them as is, transforming them to camel case, etc.
- // type: 'as-is' | 'camel-case' | 'camel-case-only' | 'dashes' | 'dashes-only' | ((name: string) => string | string[])
- // available since webpack 5.90.4; the function form may return string[] since 5.107.0
- exportsConvention: "camel-case-only",
},
"css/auto": {
// Generator options for css/auto modules
@@ -180,12 +175,12 @@ export default {
// Customize how css export names are exported to javascript modules, such as keeping them as is, transforming them to camel case, etc.
// type: 'as-is' | 'camel-case' | 'camel-case-only' | 'dashes' | 'dashes-only' | ((name: string) => string | string[])
- // available since webpack 5.90.4; the function form may return string[] since 5.107.0
+ // available since webpack 5.91.0; the function form may return string[] since 5.107.0
exportsConvention: "camel-case-only",
// Customize the format of the local class names generated for css modules.
// type: string, besides the substitutions at File-level and Module-level in https://webpack.js.org/configuration/output/#template-strings, also include [uniqueName] and [local].
- // available since webpack 5.90.4
+ // available since webpack 5.91.0
// Since webpack 5.108.0, [hash] here resolves to the local ident hash (matching css-loader); use [modulehash] for the module hash. An inline digest/length form is also supported, e.g. [hash:base64:8].
localIdentName: "[uniqueName]-[id]-[local]",
},
@@ -198,7 +193,8 @@ export default {
json: {
// Generator options for json modules
// Use `JSON.parse` when the JSON string is longer than 20 characters.
- parse: JSONParse,
+ // type: boolean, default true
+ JSONParse: true,
},
html: {
// Generator options for html modules, requires `experiments.html`, available since webpack 5.107.0
@@ -286,31 +282,12 @@ export default {
asset: {
// Parser options for asset modules
- // The options for data url generator.
- dataUrl: {
- // Asset encoding (defaults to "base64")
- // type: 'base64' | false
- encoding: "base64",
- // Asset mimetype (getting from file extension by default).
- // type: string
- mimetype: "image/png",
+ // The condition for inlining the asset as a data URI.
+ // type: { maxSize: number } | ((source: string | Buffer, { filename, module }) => boolean)
+ dataUrlCondition: {
+ // Inline assets up to this size in bytes (default 8096)
+ maxSize: 8096,
},
-
- // Emit an output asset from this asset module. This can be set to 'false' to omit emitting e. g. for SSR.
- // type: boolean
- emit: true,
-
- // Customize filename for this asset module
- // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
- filename: "static/[path][name][ext]",
-
- // Customize publicPath for asset modules, available since webpack 5.28.0
- // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
- publicPath: "https://cdn/assets/",
-
- // Emit the asset in the specified folder relative to 'output.path', available since webpack 5.67.0
- // type: string | ((pathData: PathData, assetInfo?: AssetInfo) => string)
- outputPath: "cdn-assets/",
},
"asset/inline": {
// No parser options are supported for this module type yet
@@ -583,7 +560,7 @@ Some constructs are exempt by design: nested rules inside a local-bearing ancest
-Enable or disable renaming of `@keyframes` animation names in CSS modules.
+Enable or disable renaming of `@keyframes` animation names in CSS modules. Only available for the `css/auto`, `css/module` and `css/global` module types.
- Type: `boolean`
- Default: `true`
@@ -594,7 +571,7 @@ Enable or disable renaming of `@keyframes` animation names in CSS modules.
export default {
module: {
parser: {
- css: {
+ "css/auto": {
animation: true, // Enable @keyframes renaming
},
},
@@ -606,7 +583,7 @@ export default {
-Enable or disable renaming of `@container` names in CSS modules.
+Enable or disable renaming of `@container` names in CSS modules. Only available for the `css/auto`, `css/module` and `css/global` module types.
- Type: `boolean`
- Default: `true`
@@ -617,7 +594,7 @@ Enable or disable renaming of `@container` names in CSS modules.
export default {
module: {
parser: {
- css: {
+ "css/auto": {
container: true, // Enable @container renaming
},
},
@@ -629,7 +606,7 @@ export default {
-Enable or disable renaming of custom identifiers in CSS modules.
+Enable or disable renaming of custom identifiers in CSS modules. Only available for the `css/auto`, `css/module` and `css/global` module types.
- Type: `boolean`
- Default: `true`
@@ -642,7 +619,7 @@ T> Since webpack 5.109.0 this also scopes `view-transition-name` / `view-transit
export default {
module: {
parser: {
- css: {
+ "css/auto": {
customIdents: true, // Enable custom identifier renaming
},
},
@@ -716,7 +693,7 @@ export default {
-Enable or disable renaming of dashed identifiers, such as CSS custom properties (e.g., `--my-variable`).
+Enable or disable renaming of dashed identifiers, such as CSS custom properties (e.g., `--my-variable`). Only available for the `css/auto`, `css/module` and `css/global` module types.
- Type: `boolean`
- Default: `true`
@@ -727,7 +704,7 @@ Enable or disable renaming of dashed identifiers, such as CSS custom properties
export default {
module: {
parser: {
- css: {
+ "css/auto": {
dashedIdents: true, // Enable dashed identifier renaming
},
},
@@ -739,7 +716,7 @@ export default {
-Enable or disable renaming of `@function` names in CSS modules.
+Enable or disable renaming of `@function` names in CSS modules. Only available for the `css/auto`, `css/module` and `css/global` module types.
- Type: `boolean`
- Default: `true`
@@ -750,7 +727,7 @@ Enable or disable renaming of `@function` names in CSS modules.
export default {
module: {
parser: {
- css: {
+ "css/auto": {
function: true, // Enable @function renaming
},
},
@@ -795,7 +772,7 @@ Default resource-hint rules for assets referenced via `url(...)` in CSS. Same ru
-Enable or disable renaming of grid identifiers in CSS modules.
+Enable or disable renaming of grid identifiers in CSS modules. Only available for the `css/auto`, `css/module` and `css/global` module types.
- Type: `boolean`
- Default: `true`
@@ -806,7 +783,7 @@ Enable or disable renaming of grid identifiers in CSS modules.
export default {
module: {
parser: {
- css: {
+ "css/auto": {
grid: true, // Enable grid identifier renaming
},
},
@@ -818,8 +795,8 @@ export default {
Configure how CSS content will be exported.
-- Type: `boolean`
-- Available: 5.102.0+
+- Type: `'link' | 'text' | 'css-style-sheet' | 'style'`
+- Available: 5.103.0+
- Example:
```js
@@ -835,11 +812,12 @@ Configure how CSS content will be exported.
};
```
-Possible values: `'link' | 'text' | 'css-style-sheet'
+Possible values: `'link' | 'text' | 'css-style-sheet' | 'style'`
- `link` - extract CSS into own file and use `link` tags to inject into DOM.
- `text` - store CSS in JS file and return using default export.
- `css-style-sheet` - the default export is a constructable stylesheet (i.e. CSSStyleSheet). Useful for custom elements and shadow DOM.
+- `style` - store CSS in JS file and inject it into the DOM at runtime through a `