docs: enhance output.asyncChunks documentation and examples (#12500)

chenjiahan · web-flow · commit fb80ef1cf580 · 2025-12-18T18:41:39.000+08:00
* docs: enhance `output.asyncChunks` documentation and examples

* docs: update
diff --git a/packages/rspack/src/config/types.ts b/packages/rspack/src/config/types.ts
@@ -652,7 +652,13 @@ export type Output = {
 	hashSalt?: HashSalt;
 
 	/**
-	 * Create async chunks that are loaded on demand.
+	 * Controls whether dynamically imported modules are emitted as separate async chunks or bundled into
+	 * existing chunks.
+	 * - `true`: Modules loaded via `import()` are split into independent async chunks. These chunks are
+	 * emitted as separate files and are loaded on demand at runtime. This enables code splitting and keeps
+	 * the initial bundle smaller.
+	 * - `false`: Dynamically imported modules are bundled into existing chunks instead of being emitted as
+	 * separate files. No additional async chunk files are generated.
 	 * @default true
 	 * */
 	asyncChunks?: AsyncChunks;
diff --git a/website/docs/en/config/output.mdx b/website/docs/en/config/output.mdx
@@ -33,7 +33,18 @@ The name of the file to be output by the Asset module. This value can be overrid
 - **Type:** `boolean`
 - **Default:** `true`
 
-Create async chunks that are loaded on demand.
+Controls whether dynamically imported modules are emitted as separate async chunks or bundled into existing chunks.
+
+- `true`: Modules loaded via `import()` are split into independent async chunks. These chunks are emitted as separate files and are loaded on demand at runtime. This enables code splitting and keeps the initial bundle smaller.
+- `false`: Dynamically imported modules are bundled into existing chunks instead of being emitted as separate files. No additional async chunk files are generated.
+
+```js title="rspack.config.mjs"
+export default {
+  output: {
+    asyncChunks: false,
+  },
+};
+```
 
 ## output.charset
 
diff --git a/website/docs/en/guide/optimization/code-splitting.mdx b/website/docs/en/guide/optimization/code-splitting.mdx
@@ -32,11 +32,11 @@ console.log('bar.js');
 Building this project produces three chunks: `src_bar_js.js`, `src_foo_js.js`, and `main.js`. Inspecting them shows that `shared.js` exists in both `src_bar_js.js` and `src_foo_js.js`. We will cover how to remove duplicated modules later.
 
 :::tip
-Refer to [Module methods - Dynamic import()](/api/runtime-api/module-methods#dynamic-import) for the detailed dynamic import API, as well as how to use dynamic expressions and magic comments in dynamic import.
-:::
 
-:::info
-Although `shared.js` exists in two chunks, it is executed only once, so you don't have to worry about multiple instances.
+1. Refer to [Module methods - Dynamic import()](/api/runtime-api/module-methods#dynamic-import) for the detailed dynamic import API, as well as how to use dynamic expressions and magic comments in dynamic import.
+2. Although `shared.js` exists in two chunks, it is executed only once, so you don't have to worry about multiple instances.
+3. Use the [output.asyncChunks option](/config/output/#outputasyncchunks) to control whether dynamically imported modules generate independent async chunks.
+
 :::
 
 ## Entry point
@@ -79,13 +79,13 @@ Entrypoint index = index.js
 
 Similarly, examining the output shows that they all include the repeated `shared.js`.
 
-## SplitChunksPlugin
+## Configuring chunk splitting
 
 The splitting approach above is intuitive, but most modern browsers support concurrent network requests. If we split a single-page application into one chunk per page, the browser still has to fetch a large chunk when users switch pages, which wastes that concurrency. Instead, we can break the chunk into smaller ones and request those smaller chunks at the same time to use the browser's network capacity more effectively.
 
 Rspack defaults to splitting files in the `node_modules` directory and duplicate modules, extracting these modules from their original Chunk into a separate new Chunk. Why does `shared.js` still appear repeatedly in our example above? The `shared.js` file here is very small, and splitting such a small module into its own Chunk can actually slow down loading.
 
-We can configure the minimum split size to 0 to allow `shared.js` to be extracted on its own.
+We can configure the minimum split size through [splitChunks.minSize](/plugins/webpack/split-chunks-plugin#splitchunksminsize) to 0 to allow `shared.js` to be extracted on its own.
 
 ```diff title="rspack.config.mjs"
 export default {
@@ -104,7 +104,7 @@ After rebuilding, you will find that `shared.js` has been extracted separately,
 
 ### Force the splitting of certain modules
 
-We can specify certain modules to be forcibly grouped into a single Chunk, for example, the following configuration:
+We can use [`optimization.splitChunks.cacheGroups.{cacheGroup}.name`](/plugins/webpack/split-chunks-plugin#splitchunkscachegroupscachegroupname) to force specific modules to be grouped into the same chunk, for example, with the following configuration:
 
 ```js title="rspack.config.mjs"
 export default {
diff --git a/website/docs/zh/config/output.mdx b/website/docs/zh/config/output.mdx
@@ -33,7 +33,18 @@ Asset module 输出的文件名称。这个值可以被 [rules[].generator.filen
 - **类型：** `boolean`
 - **默认值：** `true`
 
-是否创建按需加载的异步 chunk。
+用于控制通过动态导入加载的模块，是被输出为独立的异步 chunk，还是被打包进已有的 chunk 中。
+
+- `true`：通过 `import()` 加载的模块会被拆分为独立的异步 chunk。这些 chunk 会作为单独的文件输出，并在运行时按需加载。这样可以启用代码拆分，减小初始包体积。
+- `false`：通过动态导入加载的模块不会生成单独的文件，而是被直接打包进现有的 chunk 中。此时不会额外生成异步 chunk 文件。
+
+```js title="rspack.config.mjs"
+export default {
+  output: {
+    asyncChunks: false,
+  },
+};
+```
 
 ## output.charset
 
diff --git a/website/docs/zh/guide/optimization/code-splitting.mdx b/website/docs/zh/guide/optimization/code-splitting.mdx
@@ -32,11 +32,11 @@ console.log('bar.js');
 此时我们执行构建，会得到 3 个 Chunk ，`src_bar_js.js`，`src_foo_js.js` 以及 `main.js`，如果我们查看他们，会发现 `src_bar_js.js` 和 `src_foo_js.js` 中有重复的部分：`shared.js`，我们后面会介绍为何存在重复模块，以及如何去除重复模块。
 
 :::tip
-参考 [模块方法 - Dynamic import()](/api/runtime-api/module-methods#dynamic-import) 了解详细的 dynamic import API，以及如何在 dynamic import 中使用动态表达式和 magic comments。
-:::
 
-:::info
-虽然 `shared.js` 在 2 个 Chunk 中重复出现，但它只会被执行一次，不用担心重复模块会重复执行的问题。
+1. 参考 [模块方法 - Dynamic import()](/api/runtime-api/module-methods#dynamic-import) 了解详细的 dynamic import API，以及如何在 dynamic import 中使用动态表达式和 magic comments。
+2. 虽然 `shared.js` 在 2 个 chunks 中重复出现，但它只会被执行一次，不用担心重复模块会重复执行的问题。
+3. 使用 [output.asyncChunks 选项](/config/output/#outputasyncchunks) 可以控制动态导入的模块是否生成独立的异步 chunk。
+
 :::
 
 ## 分割入口起点（entry point）
@@ -79,13 +79,13 @@ Entrypoint index = index.js
 
 同样的，如果你查看他们会发现他们都会包含有重复的 `shared.js`。
 
-## SplitChunksPlugin
+## 配置 Chunk 拆分
 
-上面的代码分割是很符合直觉的分割逻辑，但现代浏览器大多支持并发网络请求，如果我们将一个 SPA 应用中每一个页面分为一个 Chunk ，当用户切换页面的时候请求一个较大体积的 Chunk ，这显然不能很好利用到浏览器的并发网络请求能力，因此我们可以将 Chunk 拆分成更小的多个 Chunk ，需要请求这个 Chunk 的时候，我们改为同时请求这些更小的 Chunk ，这样会让浏览器请求更加高效。
+上面的代码分割是很符合直觉的分割逻辑，但现代浏览器大多支持并发网络请求，如果我们将一个 SPA 应用中每一个页面分为一个 Chunk ，当用户切换页面的时候请求一个较大体积的 Chunk，这显然不能很好利用到浏览器的并发网络请求能力，因此我们可以将 Chunk 拆分成更小的多个 Chunk ，需要请求这个 Chunk 的时候，我们改为同时请求这些更小的 Chunk ，这样会让浏览器请求更加高效。
 
 Rspack 默认会对 `node_modules` 目录下的文件以及重复模块进行拆分，将这些模块从他们所属的原 Chunk 抽离到单独的新 Chunk 中。那为何我们上面例子中，`shared.js` 还是在多个 Chunk 中重复出现了呢？这是因为我们例子中的 `shared.js` 体积很小，如果对一个很小的模块单独拆成一个 Chunk 让浏览器加载，可能反而会让加载更慢。
 
-我们可以配置最小拆分体积为 0 ，来让 `shared.js` 被单独抽离。
+我们可以通过 [splitChunks.minSize](/plugins/webpack/split-chunks-plugin#splitchunksminsize) 配置最小拆分体积为 0，来让 `shared.js` 被单独抽离。
 
 ```diff title="rspack.config.mjs"
 export default {
@@ -104,7 +104,7 @@ export default {
 
 ### 强制拆分某些模块
 
-我们可以通过 `optimization.splitChunks.cacheGroups.{cacheGroup}.name` 强制将指定模块分到一个 Chunk 中去，例如如下配置：
+我们可以通过 [`optimization.splitChunks.cacheGroups.{cacheGroup}.name`](/plugins/webpack/split-chunks-plugin#splitchunkscachegroupscachegroupname) 强制将指定模块分到一个 Chunk 中去，例如如下配置：
 
 ```js title="rspack.config.mjs"
 export default {
