docs: add docs for lazy barrel (#11274)

Author: ahabhgk

website/docs/en/config/experiments.mdx

@@ -959,3 +959,37 @@ export default {
   },
 };
 ```
+
+## experiments.lazyBarrel
+
+<ApiMeta addedVersion="1.5.0" />
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to skip building unused re-export modules in side-effect-free barrel files to optimize build performance.
+
+A side-effect-free module is a module that meets one of the following conditions:
+
+- The `package.json` file of its package declares `"sideEffects": false`, see [Side effects analysis](/guide/optimization/tree-shaking#side-effects-analysis)
+- Modules explicitly marked as `false` through the [module.rule.sideEffects](/config/optimization#optimizationsideeffects) option
+
+:::info FAQ
+
+1. Can this also supports CommonJS?
+
+   Yes, theoretically this can also support CommonJS, but before that we need to improve Rspack's CJS tree shaking first, the static analyze part specifically, so currently we will only support ESM, and support CJS in the future PR.
+
+2. Why depend on `"sideEffects": false` in package.json, can Rspack automatically analyze a module is side effects free or not?
+
+   Rspack has the ability to analyze a module is side effects free or not of course, it's already used by `optimization.sideEffects` to tree shaking side effects free modules. But these analyzed modules still require checking whether their dependencies have side effects - only when all dependencies are also side effects free can the module be considered truly side effects free. However, during the make phase, dependencies must first be built before their side effects can be analyzed, and the `lazyBarrel` is intend to avoid to build those dependencies. `"sideEffects": false` in package.json or `module.rule.sideEffects` doesn't require dependency checking, as it signifies the entire package is side effects free. Therefore, `lazyBarrel` can only rely on this marker rather than automatic analysis.
+
+3. So `export * from "./x"` is not a problem any more?
+
+   No, `export * from "./x"` is still a bad practice for your build performance, `lazyBarrel` won't build the star re-export only when you import a specifier, and the side effects free barrel file's named exports contains the specifier (`export { x as A } from "./a";`, `export * as A from "./a"`, `export { a, b }`, `export const A`, `export default A (the name is default)`), which means the star re-export is not used. So Rspack will still build the star re-export if:
+   1. barrel file is not side effects free
+   2. the star re-export is used
+
+> For more details please checkout: [RFC: Lazy make for reexports in side effects free barrel file](https://github.com/web-infra-dev/rspack/discussions/11273)
+
+:::

website/docs/en/config/optimization.mdx

@@ -296,7 +296,7 @@ export default {
 };
 ```
 
-`flag` 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.
+`flag` tells Rspack to recognise the sideEffects flag in package.json or [module.rule.sideEffects](/config/module#rulesideeffects) to skip over modules which are flagged to contain no side effects when exports are not used.
 
 `true` tells Rspack not only recognise the sideEffects flag, but also analyse modules which are not flagged explicitly, and determine if they have side effects or not.
 

website/docs/zh/config/experiments.mdx

@@ -834,8 +834,8 @@ import imageUrl from 'https://example.com/image.png';
 
 <ApiMeta addedVersion="1.3.14" />
 
-- **类型:** `false | RegExp[]`
-- **默认值:** `false`
+- **类型：** `false | RegExp[]`
+- **默认值：** `false`
 
 默认情况下，Rspack 使用原生文件系统从磁盘读取文件。
 但你也可以通过更换 inputFileSystem，使用其他类型的文件系统。例如，可以用 memfs 替代默认文件系统来支持虚拟模块。
@@ -908,17 +908,17 @@ export default {
 
 <ApiMeta addedVersion="1.4.1" />
 
-- **类型:** `boolean`
-- **默认值:** `false`
+- **类型：** `boolean`
+- **默认值：** `false`
 
 实验性功能 [`module.parser.javascript.inlineConst`](/config/module#moduleparserjavascriptinlineconst) 的开关，开启后才能使用。
 
 ## experiments.inlineEnum
 
 <ApiMeta addedVersion="1.4.1" />
 
-- **类型:** `boolean`
-- **默认值:** `false`
+- **类型：** `boolean`
+- **默认值：** `false`
 
 实验性功能 [`builtin:swc-loader rspackExperiments.collectTypeScriptInfo.exportedEnum`](/guide/features/builtin-swc-loader#rspackexperimentscollecttypescriptinfoexportedenum) 的开关，开启后才能使用。
 
@@ -928,8 +928,8 @@ export default {
 
 <ApiMeta addedVersion="1.4.1" />
 
-- **类型:** `boolean`
-- **默认值:** `false`
+- **类型：** `boolean`
+- **默认值：** `false`
 
 实验性功能 [`module.parser.javascript.typeReexportsPresence`](/config/module#moduleparserjavascripttypereexportspresence) 的开关，开启后才能使用。
 
@@ -959,3 +959,37 @@ export default {
   },
 };
 ```
+
+## experiments.lazyBarrel
+
+<ApiMeta addedVersion="1.5.0" />
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否跳过无副作用的重导出模块（barrel file）中未被使用到的模块的构建，以优化构建性能。
+
+无副作用模块是指满足以下条件之一的模块：
+
+- 其所属包的 `package.json` 文件中声明了 `"sideEffects": false`，详见 [副作用分析](/guide/optimization/tree-shaking#副作用分析)
+- 通过 [module.rule.sideEffects](/config/optimization#optimizationsideeffects) 选项显式标记为 `false` 的模块
+
+:::info FAQ
+
+1. `lazyBarrel` 是否支持 CommonJS？
+
+   是的，理论上这个功能也可以支持 CommonJS，但在那之前我们需要先改进 Rspack 对 CJS 的 tree shaking 能力，特别是静态分析部分。所以目前我们只会支持 ESM，后续 PR 再支持 CJS。
+
+2. 为什么依赖 package.json 中的 `"sideEffects": false` 标记？Rspack 不能自动分析模块是否无副作用吗？
+
+   Rspack 当然具备分析模块是否无副作用的能力，这个能力已经被用在 `optimization.sideEffects` 来 tree shaking 无副作用的模块。但这些被分析出来的模块仍然需要检查它们的依赖是否有副作用：只有当所有依赖也都是无副作用时，该模块才能被认为是真正无副作用的。然而在 make 阶段，必须先构建依赖才能分析它们的副作用，而 `lazyBarrel` 正是为了避免构建这些依赖。package.json 中的 `"sideEffects": false` 或 `module.rule.sideEffects` 标记不需要检查依赖，它表示整个包都是无副作用的，所以 `lazyBarrel` 只能使用这个标记，而不是自动分析。
+
+3. 所以 `export * from "./x"` 不再是问题了？
+
+   不，`export * from "./x"` 对构建性能来说仍然是个不好的实践。`lazyBarrel` 只会在以下情况不构建 star re-export：当你导入一个 specifier 时，且这个无副作用的重导出模块（barrel file）的具名导出中包含该 specifier（`export { x as A } from "./a";`、`export * as A from "./a"`、`export { a, b }`、`export const A`、`export default A (the name is default)`），这意味着 star re-export 没有被使用。所以 Rspack 在以下情况仍然会构建 star re-export：
+   1. 重导出模块（barrel file）不是无副作用的
+   2. star re-export 被使用了
+
+> 更多详细内容可查看：[RFC: Lazy make for reexports in side effects free barrel file](https://github.com/web-infra-dev/rspack/discussions/11273)
+
+:::

website/docs/zh/config/optimization.mdx

@@ -307,7 +307,7 @@ export default {
 };
 ```
 
-配置为 `flag` 会让 Rspack 仅识别 package.json 中的 `sideEffects` 标志或者 `module.rules`（模块配置中的规则），以跳过那些被标记为没有副作用但未被使用的模块。
+配置为 `flag` 会让 Rspack 仅识别 package.json 中的 `sideEffects` 标志或者 [`module.rule.sideEffects`](/config/module#rulesideeffects)（模块配置中的规则），以跳过那些被标记为没有副作用但未被使用的模块。
 
 配置为 `true` 会让 Rspack 除了识别用户主动标记以外，还会尝试分析未被标记的 module 源码是否包含副作用。