Skip to content
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

docs: improve default value, types and examples for optimization #8339

Merged
merged 1 commit into from
Nov 5, 2024
Merged

docs: improve default value, types and examples for optimization #8339

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
173 changes: 137 additions & 36 deletions website/docs/en/config/optimization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,74 @@ Rspack will select appropriate optimization configuration based on the [`mode`](

## optimization.moduleIds

<PropertyType type="'natural' | 'named' | 'deterministic'" />
<PropertyType
type="'natural' | 'named' | 'deterministic'"
defaultValueList={[
{ defaultValue: "'deterministic'", mode: 'production' },
{ defaultValue: "'named'", mode: 'development' },
]}
/>

Tells Rspack which algorithm to use when generating module ids.

The following string values are supported:

| option | description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `natural` | Use numeric ids in order of usage. |
| `named` | Use meaningful, easy-to-debug content as id. |
| `deterministic` | Use the hashed module identifier as the id to benefit from long-term caching. By default a minimum length of 3 digits is used. |

```js title=rspack.config.js
module.exports = {
optimization: {
moduleIds: 'deterministic',
},
};
```

| option | description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `natural` | Use numeric ids in order of usage. |
| `named` | Use meaningful, easy-to-debug content as id. This option is enabled by default in development mode. |
| `deterministic` | Use the hashed module identifier as the id to benefit from long-term caching. This option is enabled by default in production mode. |
The `deterministic` option is useful for long term caching, and results in smaller bundles compared to hashed. Length of the numeric value is chosen to fill a maximum of 80% of the id space. By default a minimum length of 3 digits is used when `optimization.moduleIds` is set to `deterministic`.

## optimization.chunkIds

<PropertyType type="'named' | 'deterministic'" />
<PropertyType
type="'named' | 'deterministic'"
defaultValueList={[
{ defaultValue: "'named'", mode: 'development' },
{ defaultValue: "'deterministic'", mode: 'production' },
]}
/>

Tells Rspack which algorithm to use when generating chunk ids.

The following string values are supported:

| option | description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `'named'` | Readable ids for better debugging. |
| `'deterministic'` | Short numeric ids which will not be changing between compilation. Good for long term caching. By default a minimum length of 3 digits is used. |

```js title=rspack.config.js
module.exports = {
optimization: {
chunkIds: 'deterministic',
},
};
```

## optimization.mergeDuplicateChunks

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Whether to merge chunks which contain the same modules. Setting `optimization.mergeDuplicateChunks` to `false` will disable this optimization.

| option | description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `'named'` | Readable ids for better debugging. This option is enabled by default in development mode |
| `'deterministic'` | Short numeric ids which will not be changing between compilation. Good for long term caching. This option is enabled by default in production mode. |
```js title=rspack.config.js
module.exports = {
optimization: {
mergeDuplicateChunks: false,
},
};
```

## optimization.minimize

Expand All @@ -36,14 +88,16 @@ Rspack will select appropriate optimization configuration based on the [`mode`](
{ defaultValue: 'false', mode: 'development' },
]}
/>
Whether to minimize the bundle.

## optimization.mergeDuplicateChunks

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />
Whether to use the minimizer declared in [`optimization.minimizer`](#optimizationminimizer) to minimize the bundle.

Whether to merge chunks which contain the same modules. Setting optimization.mergeDuplicateChunks
to false will disable this optimization.
```js title=rspack.config.js
module.exports = {
optimization: {
minimize: true,
},
};
```

## optimization.minimizer

Expand All @@ -57,33 +111,27 @@ to false will disable this optimization.
]}
/>

Customize the minimizer. By default, [`rspack.SwcJsMinimizerRspackPlugin`](/plugins/rspack/swc-js-minimizer-rspack-plugin)
and [`rspack.LightningCssMinimizerRspackPlugin`](/plugins/rspack/lightning-css-minimizer-rspack-plugin) are used.
Customize the minimizer. By default, [`rspack.SwcJsMinimizerRspackPlugin`](/plugins/rspack/swc-js-minimizer-rspack-plugin) and [`rspack.LightningCssMinimizerRspackPlugin`](/plugins/rspack/lightning-css-minimizer-rspack-plugin) are used.

When `optimization.minimizer` is specified, the default minimizers will be disabled.

```js title=rspack.config.js
const terserPlugin = require('terser-webpack-plugin');
const TerserPlugin = require('terser-webpack-plugin');

module.exports = {
context: __dirname,
target: 'node',
entry: {
main: './index.js',
},
optimization: {
minimize: true,
minimizer: [new terserPlugin()],
minimizer: [new TerserPlugin()],
},
};
```

Use the built-in minimizer with custom options:
Use Rspack's built-in minimizer with custom options:

```js title=rspack.config.js
const rspack = require('@rspack/core');

module.exports = {
// ...
optimization: {
minimize: process.env.NODE_ENV === 'production',
// when `optimization.minimizer` is specified, the default minimizers are disabled by default
// but you can use '...', it represents the default minimizers
minimizer: [
Expand All @@ -108,20 +156,65 @@ module.exports = {

<PropertyType type="boolean" defaultValueList={[{ defaultValue: 'true' }]} />

Remove empty chunks generated in the compilation.
Detect and remove empty chunks generated in the compilation. Setting `optimization.removeEmptyChunks` to `false` will disable this optimization.

```js title=rspack.config.js
module.exports = {
optimization: {
removeEmptyChunks: false,
},
};
```

## optimization.runtimeChunk

<PropertyType
type="boolean | string | ((entrypoint: { name: string }) => string)"
type="boolean | string | { name: string } | { name: (entrypoint: { name: string }) => string }"
defaultValueList={[{ defaultValue: 'false' }]}
/>

Used to control how the runtime chunk is generated.
Used to control how the Rspack's [runtime](/misc/glossary#runtime) chunk is generated.

Defaults to `false`, which means the runtime code is inlined into the entry chunks.

Setting it to `true` or `'multiple'` will add an additional chunk containing only the runtime for each entry point. This setting is an alias for:

```js title=rspack.config.js
module.exports = {
optimization: {
runtimeChunk: {
name: entrypoint => `runtime~${entrypoint.name}`,
},
},
};
```

Setting it to `'single'` will extract the runtime code of all entry points into a single separate chunk. This setting is an alias for:

Setting it to `true` or `'multiple'` will add an additional chunk containing only the runtime for each entry point.
```js title=rspack.config.js
module.exports = {
optimization: {
runtimeChunk: 'runtime',
},
};
```

By setting `optimization.runtimeChunk` to an object it can provide the `name` property which stands for the name for the runtime chunks.

```js title=rspack.config.js
module.exports = {
optimization: {
runtimeChunk: {
// this will generate a chunk named `my-name.js`
name: 'my-name',
},
},
};
```

Setting it to `'single'` will extract the runtime code of all entry points into a single separate chunk.
:::tip
Imported modules are initialized for each runtime chunk separately, so if you include multiple entry chunks on a page, beware of this behavior. You will need to set `optimization.runtimeChunk` to `'single'` or use another configuration that ensures the page only contains one runtime instance.
:::

## optimization.realContentHash

Expand Down Expand Up @@ -362,4 +455,12 @@ When [mode](/config/mode) is set to `'none'`, `optimization.nodeEnv` defaults to
]}
/>

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.
Use the `optimization.emitOnErrors` to emit assets whenever there are errors while compiling. This ensures that erroring assets are emitted. The errors are emitted into the generated code and will cause errors at runtime.

```js title=rspack.config.js
module.exports = {
optimization: {
emitOnErrors: true,
},
};
```
8 changes: 4 additions & 4 deletions website/docs/en/misc/glossary.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,5 @@
# Glossary

{
// TODO: A glossary is usually alphabetized
}

Below are some common terms used with Rspack and webpack.

## asset
Expand Down Expand Up @@ -66,6 +62,10 @@ The module graph is a graph data structure that represents relationships between

A plugin is a program module that can be used to extend the functionality of Rspack by means of extensibility hooks. It can be used to customize the build process, or to integrate with other tools. Rspack provides lots of hooks which you can use to customize the build process.

## runtime

The runtime is all the code Rspack needs to connect your modularized application while it's running in the browser or other environments. It contains the loading and resolving logic needed to connect your modules as they interact.

## scope hoisting

Scope hoisting is a technique that concat modules into a single scope when possible, rather than wrapping each module in a separate function. It can make minification more effective and improve runtime performance by reduce module lookup cost.
Expand Down
Loading
Loading