Skip to content

Commit

Permalink
docs: remove outdated builtin config docs (#7372)
Browse files Browse the repository at this point in the history
* docs: remove builtin in optimization doc

* docs: remove builtin.html

* docs: fix optimization.sideEffects default value

* fix: unused tip

* fix
  • Loading branch information
SyMind authored Jul 31, 2024
1 parent 6a5343d commit 890ddd3
Show file tree
Hide file tree
Showing 8 changed files with 25 additions and 65 deletions.
23 changes: 12 additions & 11 deletions website/docs/en/config/optimization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -125,13 +125,8 @@ Setting it to `'single'` will extract the runtime code of all entry points into

## optimization.sideEffects

<PropertyType
type="boolean | 'flag'"
defaultValueList={[
{ defaultValue: 'true', mode: 'production' },
{ defaultValue: 'false', mode: 'development' },
]}
/>
- **Type:** `boolean | 'flag'`
- **Default:** [production mode](config/mode#production) is `true`[development mode](config/mode#development) is `'flag'`

```json
{
Expand All @@ -143,9 +138,13 @@ Setting it to `'single'` will extract the runtime code of all entry points into

Tells Rspack to recognise the sideEffects flag in package.json or rules to skip over modules which are flagged to contain no side effects when exports are not used.

`optimization.sideEffects` depended on `builtins.treeShaking` to be enabled.
:::tip
Please note that `sideEffects` should be in the npm module's `package.json` file and doesn't mean that you need to set `sideEffects` to `false` in your own project's `package.json` which requires that npm module.
:::

This configuration 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.
`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.

```js title=rspack.config.js
module.exports = {
Expand All @@ -156,7 +155,7 @@ module.exports = {
};
```

If you only want Rspack use the manual `sideEffects` flag via (package.json and module.rule.sideEffects) and don't analyse code:
If you only want Rspack use the manual `sideEffects` flag via (`package.json` and `module.rule.sideEffects`) and don't analyse source code:

```js title=rspack.config.js
module.exports = {
Expand All @@ -167,7 +166,9 @@ module.exports = {
};
```

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

:::tip
When `optimization.sideEffects` is true , Rspack will also flag modules as side effect free when they contain only side effect free statements.
:::

Expand Down
7 changes: 0 additions & 7 deletions website/docs/en/guide/tech/solid.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,6 @@ const config = {
},
],
},
builtins: {
html: [
{
template: './index.html',
},
],
},
};
module.exports = config;
```
7 changes: 0 additions & 7 deletions website/docs/en/guide/tech/svelte.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,6 @@ const config = {
},
],
},
builtins: {
html: [
{
template: './index.html',
},
],
},
};
module.exports = config;
```
7 changes: 0 additions & 7 deletions website/docs/en/guide/tech/vue.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -165,13 +165,6 @@ module.exports = {
},
],
},
builtins: {
html: [
{
template: './index.html',
},
],
},
};
```

Expand Down
25 changes: 13 additions & 12 deletions website/docs/zh/config/optimization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -124,13 +124,8 @@ module.exports = {

## optimization.sideEffects

<PropertyType.CN
type="boolean | 'flag'"
defaultValueList={[
{ defaultValue: 'true', mode: 'production' },
{ defaultValue: 'false', mode: 'development' },
]}
/>
- **类型:** `boolean | 'flag'`
- **默认值:** [production 模式](config/mode#production)`true`[development 模式](config/mode#development)`'flag'`

```json
{
Expand All @@ -140,9 +135,13 @@ module.exports = {
}
```

告诉 Rspack 识别 package.json 中的 `sideEffects` 标志或者 `module.rules`(模块配置中的规则),当模块导出都未被使用且模块本身没有副作用时跳过模块及其子树
告诉 Rspack 识别 package.json 中的 `sideEffects` 标志或者 `module.rules`(模块配置中的规则),以跳过那些被标记为没有副作用但未被使用的模块

`optimization.sideEffects` 依赖于 `builtins.treeShaking` 的启用。这种配置项开启后有额外的构建时间开销,但移除模块对性能有积极影响,因为这意味着更少的代码生成。这种优化的效果取决于你的代码库。
:::tip
请注意,如果你的项目需要使用 npm 模块的话,`sideEffects` 应该在 npm 模块的 `package.json` 文件中,并需要在你自己的项目的 `package.json` 中将 `sideEffects` 设置为 `false`
:::

`optimization.sideEffects` 依赖于启用 [`optimization.providedExports`](#optimizationprovidedexports)。这在构建时会有一定的成本,但消除模块对性能有积极的影响,因为生成的代码更少。这个优化的效果取决于你的代码库,尝试使用它来获得可能的性能提升。

```js title=rspack.config.js
module.exports = {
Expand All @@ -153,7 +152,7 @@ module.exports = {
};
```

如果你只想使用通过`package.json``module.rule.sideEffects` 配置的 `sideEffects`,而不想分析代码:
如果你只希望 Rspack 使用手动指定的 `sideEffects` 标志(通过 `package.json``module.rule.sideEffects`),而不分析源代码,可以这样配置:

```js title=rspack.config.js
module.exports = {
Expand All @@ -164,8 +163,10 @@ module.exports = {
};
```

:::info Tip
`optimization.sideEffects``true` 时,Rspack 会在一个模块中所有的语句(statement)都没有副作用时标记该模块为无副作用。
默认情况下,`'flag'` 值在非生产环境构建中使用。

:::tip
`optimization.sideEffects``true` 时,如果模块中只包含无副作用的语句,Rspack 也会将它们标记为无副作用。
:::

## optimization.realContentHash
Expand Down
7 changes: 0 additions & 7 deletions website/docs/zh/guide/tech/solid.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,6 @@ const config = {
},
],
},
builtins: {
html: [
{
template: './index.html',
},
],
},
};
module.exports = config;
```
7 changes: 0 additions & 7 deletions website/docs/zh/guide/tech/svelte.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,6 @@ const config = {
},
],
},
builtins: {
html: [
{
template: './index.html',
},
],
},
};
module.exports = config;
```
7 changes: 0 additions & 7 deletions website/docs/zh/guide/tech/vue.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -163,13 +163,6 @@ const config = {
},
],
},
builtins: {
html: [
{
template: './index.html',
},
],
},
};
module.exports = config;
```
Expand Down

0 comments on commit 890ddd3

Please sign in to comment.