From 632b1094505cace413384a3b0ec1fef10af129da Mon Sep 17 00:00:00 2001
From: neverland <chenjiahan.jait@bytedance.com>
Date: Thu, 11 Apr 2024 15:02:08 +0800
Subject: [PATCH] docs: add async chunk all in one example (#2067)

---
 .../en/config/performance/chunk-split.mdx     | 34 ++++----
 .../docs/en/guide/optimization/split-chunk.md | 77 ++++++++++++++-----
 .../zh/config/performance/chunk-split.mdx     | 34 ++++----
 .../docs/zh/guide/optimization/split-chunk.md | 77 ++++++++++++++-----
 4 files changed, 148 insertions(+), 74 deletions(-)

diff --git a/packages/document/docs/en/config/performance/chunk-split.mdx b/packages/document/docs/en/config/performance/chunk-split.mdx
index ae780480bb..05bacadb25 100644
--- a/packages/document/docs/en/config/performance/chunk-split.mdx
+++ b/packages/document/docs/en/config/performance/chunk-split.mdx
@@ -35,7 +35,7 @@ interface SplitCustom {
 type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
 ```
 
-### chunkSplit.strategy
+## chunkSplit.strategy
 
 Rsbuild supports the following chunk splitting strategies:
 
@@ -48,21 +48,23 @@ Rsbuild supports the following chunk splitting strategies:
 
 ### Default Strategy
 
-Rsbuild adopts the `split-by-experience` strategy by default, which is a strategy we have developed from experience. Specifically, when the following npm packages are referenced in your project, they will automatically be split into separate chunks:
+By default, Rsbuild uses the `split-by-experience` strategy. If you want to use other chunk splitting strategies, you can specify them through the `strategy` option, for example:
 
-- `lib-polyfill.js`: includes `core-js`, `@babel/runtime`, `@swc/helpers`, `tslib`.
-- `lib-react.js`: includes `react`, `react-dom`, `scheduler`.
-- `lib-router.js`: includes `react-router`, `react-router-dom`, `history`, `@remix-run/router`.
-- `lib-lodash.js`: includes `lodash`, `lodash-es`.
-- `lib-axios.js`: includes `axios` and related packages.
+```js
+export default {
+  performance: {
+    chunkSplit: {
+      strategy: 'all-in-one',
+    },
+  },
+};
+```
 
-:::tip
-If the above npm packages are not installed or used in the project, the corresponding chunk will not be generated.
+::: tip
+Please refer to the [Chunk Splitting Practice](/guide/optimization/split-chunk) section to understand the differences between different strategies.
 :::
 
-If you want to use other splitting strategies, you can specify it via `performance.chunkSplit.strategy`.
-
-### chunkSplit.minSize
+## chunkSplit.minSize
 
 - **Type:** `number`
 - **Default:** `10000`
@@ -80,7 +82,7 @@ export default {
 };
 ```
 
-### chunkSplit.maxSize
+## chunkSplit.maxSize
 
 - **Type:** `number`
 - **Default:** `Number.POSITIVE_INFINITY`
@@ -98,7 +100,7 @@ export default {
 };
 ```
 
-### chunkSplit.forceSplitting
+## chunkSplit.forceSplitting
 
 - **Type:** `RegExp[] | Record<string, RegExp>`
 - **Default:** `[]`
@@ -125,7 +127,7 @@ This is an easier way than configuring Rspack's splitChunks directly.
 Chunks split using the `forceSplitting` configuration will be inserted into the HTML file as resources requested for the initial screen using `<script>` tags. Therefore, please split them appropriately based on the actual scenario to avoid excessive size of initial screen resources.
 :::
 
-### chunkSplit.splitChunks
+## chunkSplit.splitChunks
 
 When `performance.chunkSplit.strategy` is `custom`, you can specify the custom Rspack chunk splitting config via `performance.chunkSplit.splitChunks`. This config will be merged with the Rspack splitChunks config (the `cacheGroups` config will also be merged). For example:
 
@@ -148,7 +150,7 @@ export default {
 };
 ```
 
-### chunkSplit.override
+## chunkSplit.override
 
 When `performance.chunkSplit.strategy` is `split-by-experience`, `split-by-module`, `split-by-size` or `single-vendor`, you can specify the custom Rspack chunk splitting config via `performance.chunkSplit.override`. This config will be merged with the Rspack splitChunks config (the `cacheGroups` config will also be merged). For example:
 
diff --git a/packages/document/docs/en/guide/optimization/split-chunk.md b/packages/document/docs/en/guide/optimization/split-chunk.md
index 217e7c188d..e525567bcd 100644
--- a/packages/document/docs/en/guide/optimization/split-chunk.md
+++ b/packages/document/docs/en/guide/optimization/split-chunk.md
@@ -4,7 +4,9 @@ A great chunk splitting strategy is very important to improve the loading perfor
 
 Several [chunk splitting strategies](/guide/optimization/split-chunk) are built into Rsbuild. These should meet the needs of most applications. You can also customize the chunk splitting config to suit your own usage scenario.
 
-## Splitting Strategies
+---
+
+## Strategies
 
 > The chunk splitting config of Rsbuild is in [performance.chunkSplit](/config/performance/chunk-split).
 
@@ -17,9 +19,11 @@ Rsbuild supports the following chunk splitting strategies:
 - `single-vendor`: bundle all NPM packages into a single chunk.
 - `custom`: custom chunk splitting strategy.
 
-### split-by-experience
+---
+
+## split-by-experience
 
-#### Behavior
+### Behavior
 
 Rsbuild adopts the `split-by-experience` strategy by default, which is a strategy we have developed from experience. Specifically, when the following npm packages are referenced in your project, they will automatically be split into separate chunks:
 
@@ -31,7 +35,7 @@ Rsbuild adopts the `split-by-experience` strategy by default, which is a strateg
 
 This strategy groups commonly used packages and then splits them into separate chunks. Generally, the number of chunks is not large, which is suitable for most applications and is also our recommended strategy.
 
-#### Config
+### Config
 
 ```ts
 export default {
@@ -43,13 +47,15 @@ export default {
 };
 ```
 
-#### Notes
+### Notes
 
 - If the npm packages mentioned above are not installed or used in the project, the corresponding chunk will not be generated.
 
-### split-by-module
+---
+
+## split-by-module
 
-#### Behavior
+### Behavior
 
 Split each NPM package into a Chunk.
 
@@ -57,7 +63,7 @@ Split each NPM package into a Chunk.
 This strategy will split the node_modules in the most granular way, and at the same time, under HTTP/2, multiplexing will speed up the loading time of resources.However, in non-HTTP/2 environments, it needs to be used with caution because of HTTP head-of-line blocking problem.
 :::
 
-#### Config
+### Config
 
 ```ts
 export default {
@@ -69,19 +75,21 @@ export default {
 };
 ```
 
-#### Notes
+### Notes
 
 - This configuration will split the node_modules into smaller chunks, resulting in a large number of file requests.
 - When using HTTP/2, resource loading time will be accelerated and cache hit rate will be improved due to multiplexing.
 - When not using HTTP/2, the performance of page loading may be reduced due to HTTP head-of-line blocking. Please use with caution.
 
-### all-in-one
+---
+
+## all-in-one
 
-#### Behavior
+### Behavior
 
 This strategy puts all source code and third-party dependencies in the same Chunk.
 
-#### Config
+### Config
 
 ```ts
 export default {
@@ -93,18 +101,39 @@ export default {
 };
 ```
 
-#### Notes
+### Notes
 
 - This configuration will bundle all the generated JS code into one file (except for dynamically imported chunks).
 - The size of a single JS file may be very large, leading to a decrease in page loading performance.
 
-### single-vendor
+If you need to bundle the chunks split by dynamic import into the single file, you can set the [output.asyncChunks](https://rspack.dev/config/output#outputasyncchunks) option in Rspack to `false`：
 
-#### Behavior
+```js
+export default defineConfig({
+  performance: {
+    chunkSplit: {
+      strategy: 'all-in-one',
+    },
+  },
+  tools: {
+    rspack: {
+      output: {
+        asyncChunks: false,
+      },
+    },
+  },
+});
+```
+
+---
+
+## single-vendor
+
+### Behavior
 
 This strategy puts third-party dependencies in one Chunk, and source code in another chunk.
 
-#### Config
+### Config
 
 ```ts
 export default {
@@ -116,17 +145,19 @@ export default {
 };
 ```
 
-#### Notes
+### Notes
 
 - The size of a single vendor file may be very large, leading to a decrease in page loading performance.
 
-### split-by-size
+---
 
-#### Behavior
+## split-by-size
+
+### Behavior
 
 Under this strategy, after setting `minSize`, `maxSize` to a fixed value, Rsbuild will automatically split them without extra config.
 
-#### Config
+### Config
 
 ```ts
 export default {
@@ -140,6 +171,8 @@ export default {
 };
 ```
 
+---
+
 ## Custom Splitting Strategy
 
 In addition to using the built-in strategies, you can also customize the splitting strategy to meet more customization needs. Custom strategy is divided into two parts:
@@ -174,7 +207,7 @@ Through `forceSplitting` config, you can easily split some packages into a Chunk
 
 Chunks split using the `forceSplitting` configuration will be inserted into the HTML file as resources requested for the initial screen using `<script>` tags. Therefore, please split them appropriately based on the actual scenario to avoid excessive size of initial screen resources.
 
-### Custom Bundler `splitChunks` Config
+### Custom Config
 
 In addition to using custom grouping, you can also customize the native bundler config through `override`, such as:
 
@@ -194,6 +227,8 @@ export default {
 
 The config in `override` will be merged with the bundler config. For specific config details, please refer to [webpack - splitChunks](https://webpack.js.org/plugins/split-chunks-plugin/#splitchunkschunks) or [Rspack - splitChunks](https://rspack.dev/config/optimization#optimization-splitchunks).
 
+---
+
 ## Using Dynamic Import for Code Splitting
 
 In addition to the `chunkSplit` configurations, using dynamic import for code splitting is also an important optimization technique that can effectively reduce the initial bundle size.
diff --git a/packages/document/docs/zh/config/performance/chunk-split.mdx b/packages/document/docs/zh/config/performance/chunk-split.mdx
index b522e8dc2f..4c7ce5f4bc 100644
--- a/packages/document/docs/zh/config/performance/chunk-split.mdx
+++ b/packages/document/docs/zh/config/performance/chunk-split.mdx
@@ -35,7 +35,7 @@ interface SplitCustom {
 type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
 ```
 
-### chunkSplit.strategy
+## chunkSplit.strategy
 
 Rsbuild 支持设置以下几种拆包策略：
 
@@ -46,23 +46,25 @@ Rsbuild 支持设置以下几种拆包策略：
 - `single-vendor`: 将所有 NPM 包的代码打包到一个单独的 chunk 中。
 - `custom`: 自定义拆包配置。
 
-### 默认拆包策略
+### 默认策略
 
-Rsbuild 默认采用 `split-by-experience` 策略，这是我们根据经验制定的策略。具体来说，当你的项目中引用了以下 npm 包时，它们会自动被拆分为单独的 chunk：
+Rsbuild 默认采用 `split-by-experience` 策略，如果你想使用其他拆包策略，可以通过 `strategy` 选项来指定，比如：
 
-- `lib-polyfill.js`：包含 `core-js`，`@babel/runtime`，`@swc/helpers`，`tslib`。
-- `lib-react.js`：包含 `react`，`react-dom`，`scheduler`。
-- `lib-router.js`：包含 `react-router`，`react-router-dom`，`history`，`@remix-run/router`。
-- `lib-lodash.js`：包含 `lodash`，`lodash-es`。
-- `lib-axios.js`：包含 `axios` 以及相关的包。
+```js
+export default {
+  performance: {
+    chunkSplit: {
+      strategy: 'all-in-one',
+    },
+  },
+};
+```
 
 :::tip
-如果项目中没有安装或引用以上 npm 包，则不会生成相应的 chunk。
+请参考 [拆包最佳实践](/guide/optimization/split-chunk) 章节来了解不同策略之间的差异。
 :::
 
-如果你想使用其他拆包策略，可以通过 `performance.chunkSplit.strategy` 配置项来指定。
-
-### chunkSplit.minSize
+## chunkSplit.minSize
 
 - **类型：** `number`
 - **默认值：** `10000`
@@ -80,7 +82,7 @@ export default {
 };
 ```
 
-### chunkSplit.maxSize
+## chunkSplit.maxSize
 
 - **类型：** `number`
 - **默认值：** `Number.POSITIVE_INFINITY`
@@ -98,7 +100,7 @@ export default {
 };
 ```
 
-### chunkSplit.forceSplitting
+## chunkSplit.forceSplitting
 
 - **类型：** `RegExp[] | Record<string, RegExp>`
 - **默认值：** `[]`
@@ -125,7 +127,7 @@ export default {
 注意，通过 `forceSplitting` 配置拆分的 chunk 会通过 `<script>` 标签插入到 HTML 文件中，作为首屏请求的资源。因此，请根据实际场景来进行适当地拆分，避免首屏资源体积过大。
 :::
 
-### chunkSplit.splitChunks
+## chunkSplit.splitChunks
 
 当 `performance.chunkSplit.strategy` 为 `custom` 时，可以通过 `performance.chunkSplit.splitChunks` 配置项来指定自定义的 Rspack 拆包配置。此配置会和 Rspack 的 splitChunks 配置进行合并（cacheGroups 配置也会合并）。比如:
 
@@ -148,7 +150,7 @@ export default {
 };
 ```
 
-### chunkSplit.override
+## chunkSplit.override
 
 当 `performance.chunkSplit.strategy` 为 `split-by-experience`、`split-by-module`、`split-by-size` 或 `single-vendor` 时，可以通过 `performance.chunkSplit.override` 配置项来自定义 Rspack 拆包配置，此配置会和 Rspack 的 splitChunks 配置进行合并（cacheGroups 配置也会合并）。比如:
 
diff --git a/packages/document/docs/zh/guide/optimization/split-chunk.md b/packages/document/docs/zh/guide/optimization/split-chunk.md
index 5938a6a46e..1e8e42ccf2 100644
--- a/packages/document/docs/zh/guide/optimization/split-chunk.md
+++ b/packages/document/docs/zh/guide/optimization/split-chunk.md
@@ -4,6 +4,8 @@
 
 在 Rsbuild 中内置了多种拆包策略，可以满足大部分应用的需求，你也可以根据自己的使用场景，自定义拆包配置。
 
+---
+
 ## 拆包策略
 
 > Rsbuild 的拆包配置集中在 [performance.chunkSplit](/config/performance/chunk-split) 中。
@@ -17,9 +19,11 @@ Rsbuild 支持设置以下几种拆包策略：
 - `single-vendor`: 将所有 NPM 包的代码打包到一个单独的 chunk 中。
 - `custom`: 自定义拆包配置。
 
-### split-by-experience
+---
+
+## split-by-experience
 
-#### 分包策略
+### 分包策略
 
 Rsbuild 默认采用 `split-by-experience` 策略，这是我们根据经验制定的策略。具体来说，当你的项目中引用了以下 npm 包时，它们会自动被拆分为单独的 chunk：
 
@@ -31,7 +35,7 @@ Rsbuild 默认采用 `split-by-experience` 策略，这是我们根据经验制
 
 这种拆包策略将常用的包进行分组，然后拆分为单独的 chunk，一般 chunk 的数量不会很多，适合绝大部分应用，同时也是我们推荐的拆包策略。
 
-#### 配置
+### 配置
 
 ```ts
 export default {
@@ -43,17 +47,19 @@ export default {
 };
 ```
 
-#### 注意事项
+### 注意事项
 
 - 如果项目中没有安装或引用以上 npm 包，则不会生成相应的 chunk。
 
-### split-by-module
+---
+
+## split-by-module
 
-#### 分包策略
+### 分包策略
 
 将每一个 NPM 包拆分为一个单独的 chunk。
 
-#### 配置
+### 配置
 
 ```ts
 export default {
@@ -65,19 +71,21 @@ export default {
 };
 ```
 
-#### 注意事项
+### 注意事项
 
 - 这个配置会最细化地拆分 node_modules，产生大量的文件请求。
 - 在使用 HTTP/2 时，由于存在多路复用，会加快资源的加载时间，并提高缓存命中率。
 - 在未使用 HTTP/2 时，由于 HTTP 队头阻塞问题，会导致页面加载性能下降，请谨慎使用。
 
-### all-in-one
+---
+
+## all-in-one
 
-#### 分包策略
+### 分包策略
 
 此分包策略将所有源代码和第三方依赖打包在同一个 chunk 中。
 
-#### 配置
+### 配置
 
 ```ts
 export default {
@@ -89,18 +97,39 @@ export default {
 };
 ```
 
-#### 注意事项
+### 注意事项
 
-- 这个配置会将构建生成的 JS 代码全部打包到一个文件里（除了 dynamic import 拆分的 chunk）
+- 这个配置会将构建生成的 JS 代码全部打包到一个文件里（除了 dynamic import 拆分的 chunk）。
 - 单个 JS 文件的体积可能会非常大，使页面加载性能下降。
 
-### single-vendor
+如果你需要将 dynamic import 拆分的 chunk 也打包到单个文件中，可以将 Rspack 的 [output.asyncChunks](https://www.rspack.dev/config/output#outputasyncchunks) 选项设置为 `false`：
 
-#### 分包策略
+```js
+export default defineConfig({
+  performance: {
+    chunkSplit: {
+      strategy: 'all-in-one',
+    },
+  },
+  tools: {
+    rspack: {
+      output: {
+        asyncChunks: false,
+      },
+    },
+  },
+});
+```
+
+---
+
+## single-vendor
+
+### 分包策略
 
 此分包策略将第三方依赖打包在一个 chunk 中，源代码打包在另外的 chunk 中。
 
-#### 配置
+### 配置
 
 ```ts
 export default {
@@ -112,17 +141,19 @@ export default {
 };
 ```
 
-#### 注意事项
+### 注意事项
 
 - 单个 vendor 文件的体积可能会非常大，使页面加载性能下降。
 
-### split-by-size
+---
 
-#### 分包策略
+## split-by-size
+
+### 分包策略
 
 该策略下，设置 `minSize`、`maxSize` 为一个固定值后，Rsbuild 会自动进行拆分，无需干预。
 
-#### 配置
+### 配置
 
 ```ts
 export default {
@@ -136,6 +167,8 @@ export default {
 };
 ```
 
+---
+
 ## 自定义拆包
 
 除了使用内置的拆包策略外，你也可以通过 Rsbuild 自定义拆包功能来满足更多的定制化需求。自定义拆包分为两部分:
@@ -170,7 +203,7 @@ export default {
 
 通过 `forceSplitting` 配置拆分的 chunk 会通过 `<script>` 标签插入到 HTML 文件中，作为首屏请求的资源。因此，请根据实际场景来进行适当地拆分，避免首屏资源体积过大。
 
-### 自定义 bundler 拆包配置
+### 自定义拆包配置
 
 除了使用自定义分组外，你还可以通过 `override` 配置项来自定义底层 bundler 的拆包配置，比如:
 
@@ -190,6 +223,8 @@ export default {
 
 其中 `override` 中的配置会和 bundler 的配置进行合并，具体配置项请参考 [webpack - splitChunks](https://webpack.js.org/plugins/split-chunks-plugin/#splitchunkschunks) 或 [Rspack - splitChunks](https://rspack.dev/zh/config/optimization#optimization-splitchunks)。
 
+---
+
 ## 使用 Dynamic Import 拆包
 
 除了 `chunkSplit` 配置，使用 dynamic import 拆包也是一项重要的优化手段，它可以有效减少首屏的包体积。