Skip to content

docs: use defaults table for mode-specific configuration options #8175

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
shivxmsharma wants to merge 1 commit into from
Closed

docs: use defaults table for mode-specific configuration options #8175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion src/content/configuration/cache.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,22 @@ sort: 12
contributors:
- snitin315
- chenxsan
- shivxmsharma
---

## cache

`boolean` `object`

Cache the generated webpack modules and chunks to improve build speed. `cache` is set to `type: 'memory'` in [`development` mode](/configuration/mode/#mode-development) and disabled in [`production` mode](/configuration/mode/#mode-production). `cache: true` is an alias to `cache: { type: 'memory' }`. To disable caching pass `false`:
Cache the generated webpack modules and chunks to improve build speed. `cache: true` is an alias to `cache: { type: 'memory' }`. To disable caching pass `false`:

The default value of `cache` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | -------------------- |
| `development` | `{ type: 'memory' }` |
| `production` | `false` |
| `none` | `false` |

**webpack.config.js**

Expand Down
126 changes: 108 additions & 18 deletions src/content/configuration/optimization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ contributors:
- chenxsan
- Roberto14
- hai-x
- shivxmsharma
related:
- title: "webpack 4: Code Splitting, chunk graph and the splitChunks optimization"
url: https://medium.com/webpack/webpack-4-code-splitting-chunk-graph-and-the-splitchunks-optimization-be739a861366
Expand All @@ -26,7 +27,15 @@ Webpack runs optimizations for you depending on the chosen [`mode`](/configurati

`boolean`

Tells webpack to check the incompatible types of WebAssembly modules when they are imported/exported. By default `optimization.checkWasmTypes` is enabled in `production` [mode](/configuration/mode/) and disabled elsewise.
Tells webpack to check the incompatible types of WebAssembly modules when they are imported/exported.

The default value of `optimization.checkWasmTypes` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

**webpack.config.js**

Expand Down Expand Up @@ -106,7 +115,14 @@ export default {
`boolean`

Tells webpack to find segments of the module graph which can be safely concatenated into a single module. Depends on [`optimization.providedExports`](#optimizationprovidedexports) and [`optimization.usedExports`](#optimizationusedexports).
By default `optimization.concatenateModules` is enabled in `production` [mode](/configuration/mode/) and disabled elsewise.

The default value of `optimization.concatenateModules` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

**webpack.config.js**

Expand All @@ -121,10 +137,18 @@ export default {

## optimization.emitOnErrors

`boolean = false`
`boolean`

Use the `optimization.emitOnErrors` to emit assets whenever there are errors while compiling. This ensures that erroring assets are emitted. Critical errors are emitted into the generated code and will cause errors at runtime.

The default value of `optimization.emitOnErrors` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `false` |
| `development` | `true` |
| `none` | `true` |

**webpack.config.js**

```js
Expand All @@ -140,17 +164,23 @@ W> If you are using webpack [CLI](/api/cli/), the webpack process will not exit

## optimization.avoidEntryIife

`boolean = false`
`boolean`

<Badge text="5.95.0+" />

T> IIFE (Immediately Invoked Function Expression) is a function that runs immediately after it is created. Webpack uses it to wrap code and avoid variable conflicts.
T> IIFE ...

Use `optimization.avoidEntryIife` to avoid wrapping the entry module in an IIFE when it is required (search for `"This entry needs to be wrapped in an IIFE because"` in [JavascriptModulesPlugin](https://github.com/webpack/webpack/blob/main/lib/javascript/JavascriptModulesPlugin.js)). This approach helps optimize performance for JavaScript engines and enables tree shaking when building ESM libraries.
Use `optimization.avoidEntryIife` ...

Currently, `optimization.avoidEntryIife` can only optimize a single entry module along with other modules.

By default, `optimization.avoidEntryIife` is enabled in `production` [mode](/configuration/mode/) and disabled otherwise.
The default value of `optimization.avoidEntryIife` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

**webpack.config.js**

Expand All @@ -169,7 +199,15 @@ W> The `optimization.avoidEntryIife` option can negatively affect build performa

`boolean`

Tells webpack to determine and flag chunks which are subsets of other chunks in a way that subsets don’t have to be loaded when the bigger chunk has been already loaded. By default `optimization.flagIncludedChunks` is enabled in `production` [mode](/configuration/mode/) and disabled elsewise.
Tells webpack to determine and flag chunks which are subsets of other chunks in a way that subsets don't have to be loaded when the bigger chunk has been already loaded.

The default value of `optimization.flagIncludedChunks` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

**webpack.config.js**

Expand All @@ -184,10 +222,18 @@ export default {

## optimization.innerGraph

`boolean = true`
`boolean`

`optimization.innerGraph` tells webpack whether to conduct inner graph analysis for unused exports.

The default value of `optimization.innerGraph` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

**webpack.config.js**

```js
Expand All @@ -205,7 +251,13 @@ export default {

`optimization.mangleExports` allows to control export mangling.

By default `optimization.mangleExports: 'deterministic'` is enabled in `production` [mode](/configuration/mode/) and disabled elsewise.
The default value of `optimization.mangleExports` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

The following values are supported:

Expand Down Expand Up @@ -263,10 +315,18 @@ export default {

## optimization.minimize

`boolean = true`
`boolean`

Tell webpack to minimize the bundle using the [TerserPlugin](/plugins/terser-webpack-plugin/) or the plugin(s) specified in [`optimization.minimizer`](#optimizationminimizer).

The default value of `optimization.minimize` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

**webpack.config.js**

```js
Expand Down Expand Up @@ -413,9 +473,17 @@ W> `moduleIds: total-size` has been removed in webpack 5.

## optimization.nodeEnv

`boolean = false` `string`
`boolean: false` `string`

Tells webpack to set `process.env.NODE_ENV` to a given string value. `optimization.nodeEnv` uses [DefinePlugin](/plugins/define-plugin/) unless set to `false`.

The default value of `optimization.nodeEnv` depends on the [`mode`](/configuration/mode/):

Tells webpack to set `process.env.NODE_ENV` to a given string value. `optimization.nodeEnv` uses [DefinePlugin](/plugins/define-plugin/) unless set to `false`. `optimization.nodeEnv` **defaults** to [mode](/configuration/mode/) if set, else falls back to `'production'`.
| Mode | Default |
| ------------- | --------------- |
| `production` | `'production'` |
| `development` | `'development'` |
| `none` | `false` |

Possible values:

Expand Down Expand Up @@ -475,7 +543,15 @@ export default {

`boolean`

Adds an additional hash compilation pass after the assets have been processed to get the correct asset content hashes. If `realContentHash` is set to `false`, internal data is used to calculate the hash and it can change when assets are identical. By default `optimization.realContentHash` is enabled in production [mode](/configuration/mode/) and disabled otherwise.
Adds an additional hash compilation pass after the assets have been processed to get the correct asset content hashes. If `realContentHash` is set to `false`, internal data is used to calculate the hash and it can change when assets are identical.

The default value of `optimization.realContentHash` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

**webpack.config.js**

Expand Down Expand Up @@ -579,7 +655,7 @@ export default {

## optimization.sideEffects

`boolean = true` `string: 'flag'`
`boolean` `string: 'flag'`

Tells webpack to recognise the [`sideEffects`](https://github.com/webpack/webpack/blob/main/examples/side-effects/README.md) flag in `package.json` or rules to skip over modules which are flagged to contain no side effects when exports are not used.

Expand All @@ -597,6 +673,14 @@ T> Please note that `sideEffects` should be in the npm module's `package.json` f

`optimization.sideEffects` depends on [`optimization.providedExports`](#optimizationprovidedexports) to be enabled. This dependency has a build time cost, but eliminating modules has positive impact on performance because of less code generation. Effect of this optimization depends on your codebase, try it for possible performance wins.

The default value of `optimization.sideEffects` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | -------- |
| `production` | `true` |
| `development` | `'flag'` |
| `none` | `'flag'` |

**webpack.config.js**

```js
Expand All @@ -619,8 +703,6 @@ export default {
};
```

The `'flag'` value is used by default in non-production builds.

T> `optimization.sideEffects` will also flag modules as side effect free when they contain only side effect free statements.

## optimization.splitChunks
Expand All @@ -631,11 +713,19 @@ By default webpack v4+ provides new common chunks strategies out of the box for

## optimization.usedExports

`boolean = true` `string: 'global'`
`boolean` `string: 'global'`

Tells webpack to determine used exports for each module. This depends on [`optimization.providedExports`](#optimizationprovidedexports). Information collected by `optimization.usedExports` is used by other optimizations or code generation i.e. exports are not generated for unused exports, export names are mangled to single char identifiers when all usages are compatible.
Dead code elimination in minimizers will benefit from this and can remove unused exports.

The default value of `optimization.usedExports` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

**webpack.config.js**

```js
Expand Down
13 changes: 11 additions & 2 deletions src/content/configuration/output.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ contributors:
- long76
- ahabhgk
- tanyabouman
- shivxmsharma
---

The top-level `output` key contains a set of options instructing webpack on how and where it should output your bundles, assets, and anything else you bundle or load with webpack.
Expand Down Expand Up @@ -2172,9 +2173,17 @@ W> The path must not contain an exclamation mark (`!`) as it is reserved by webp

## output.pathinfo

`boolean=true` `string: 'verbose'`
`boolean` `string: 'verbose'`

Tells webpack to include comments in bundles with information about the contained modules. This option defaults to `true` in `development` and `false` in `production` [mode](/configuration/mode/) respectively. `'verbose'` shows more information like exports, runtime requirements and bailouts.
Tells webpack to include comments in bundles with information about the contained modules. `'verbose'` shows more information like exports, runtime requirements and bailouts.

The default value of `output.pathinfo` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `false` |
| `development` | `true` |
| `none` | `false` |

W> While the data these comments can provide is useful during development when reading the generated code, it **should not** be used in production.

Expand Down
11 changes: 10 additions & 1 deletion src/content/configuration/performance.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ contributors:
- byzyk
- madhavarshney
- EugeneHlushko
- shivxmsharma
---

These options allows you to control how webpack notifies you of assets and entry points that exceed a specific file limit.
Expand Down Expand Up @@ -47,10 +48,18 @@ The example above will only give you performance hints based on `.js` files.

### performance.hints

`string = 'warning': 'error' | 'warning'` `boolean: false`
`string: 'error' | 'warning'` `boolean: false`

Turns hints on/off. In addition, tells webpack to throw either an error or a warning when hints are found.

The default value of `performance.hints` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ----------- |
| `production` | `'warning'` |
| `development` | `false` |
| `none` | `false` |

Given an asset is created that is over 250kb:

```js
Expand Down
29 changes: 29 additions & 0 deletions src/content/contribute/writers-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ sort: 1
contributors:
- pranshuchittora
- EugeneHlushko
- shivxmsharma
---

The following sections contain all you need to know about editing and formatting the content within this site. Make sure to do some research before starting your edits or additions. Sometimes the toughest part is finding where the content should live and determining whether or not it already exists.
Expand Down Expand Up @@ -205,6 +206,34 @@ When object's key can have multiple types, use `|` to list them. Here is an exam

This allows us to display the defaults, enumeration and other information.

When an option has different defaults depending on the [`mode`](/configuration/mode/), use a defaults table instead of the inline `= value` syntax:

**configuration.example.option**

`string: 'natural' | 'named' | 'deterministic'`

The default value of `configuration.example.option` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ----------------- |
| `development` | `'named'` |
| `production` | `'deterministic'` |
| `none` | `'natural'` |

If an option has a boolean default that varies by mode:

**configuration.example.flag**

`boolean`

The default value of `configuration.example.flag` depends on the [`mode`](/configuration/mode/):

| Mode | Default |
| ------------- | ------- |
| `production` | `true` |
| `development` | `false` |
| `none` | `false` |

If the object's key is dynamic, user-defined, use `<key>` to describe it:

`object = { <key> string }`
Expand Down
Loading