docs: add options for cleanDistPath (#4381)

Author: chenjiahan

packages/core/src/types/config.ts

@@ -942,12 +942,14 @@ export type ManifestConfig = string | boolean | ManifestObjectConfig;
 
 export type CleanDistPathObject = {
   /**
-   * Whether to clean the dist path.
+   * Whether to clean up all files under the output directory before the build starts.
    * @default 'auto'
    */
   enable?: boolean | 'auto';
   /**
-   * The files to keep in the dist path.
+   * Specify the files to keep in the output directory.
+   * If the file's absolute path matches the regular expression in `keep`, the file will not be removed.
+   * @default undefined
    */
   keep?: RegExp[];
 };
@@ -1009,7 +1011,7 @@ export interface OutputConfig {
    */
   legalComments?: LegalComments;
   /**
-   * Whether to clean all files in the dist path before starting compilation.
+   * Whether to clean up all files under the output directory before the build starts.
    * @default 'auto'
    */
   cleanDistPath?: CleanDistPath;

website/docs/en/config/output/clean-dist-path.mdx

@@ -1,13 +1,18 @@
 # output.cleanDistPath
 
-- **Type:** `boolean | 'auto'`
+- **Type:**
+
+```ts
+type CleanDistPath = boolean | 'auto' | CleanDistPathObject;
+```
+
 - **Default:** `'auto'`
 
 Whether to clean up all files under the output directory before the build starts (the output directory defaults to `dist`).
 
 ## Default behavior
 
-The default value of `output.cleanDistPath` is `'auto'`. If the output directory is a subdir of the project root path, Rsbuild will automatically clean all files under the build directory.
+The default value of `output.cleanDistPath` is `'auto'`. If the output directory is a subdir of the project root path, Rsbuild will automatically clean all files under the output directory.
 
 When [output.distPath.root](/config/output/dist-path) is an external directory, or equals to the project root directory, `cleanDistPath` is not enabled by default, to avoid accidentally deleting files from other directories.
 
@@ -44,3 +49,48 @@ export default {
   },
 };
 ```
+
+## Options
+
+`output.cleanDistPath` supports configuration as an object to achieve more granular control.
+
+### enable
+
+- **Type:** `boolean | 'auto'`
+- **Default:** `'auto'`
+
+Whether to clean up all files under the output directory before the build starts.
+
+```js
+export default {
+  output: {
+    // Equivalent to `cleanDistPath: true`
+    cleanDistPath: {
+      enable: true,
+    },
+  },
+};
+```
+
+### keep
+
+- **Type:** `RegExp[]`
+- **Default:** `undefined`
+
+Specify the files to keep in the output directory. If the file's absolute path matches the regular expression in `keep`, the file will not be removed.
+
+For example, to keep the `dist/foo.json` file:
+
+```js
+export default {
+  output: {
+    cleanDistPath: {
+      keep: [/dist[\\/]foo.json/],
+    },
+  },
+};
+```
+
+:::tip
+In the regular expression example, we use `[\\/]` to match the path separator because different operating systems use different path separators. Using `[\\/]` ensures that the paths can be matched in macOS, Linux and Windows.
+:::

website/docs/en/config/source/include.mdx

@@ -70,7 +70,7 @@ export default {
 The above two methods match the absolute paths of files using "path prefixes" and "regular expressions" respectively. It is worth noting that all referenced modules in the project will be matched. Therefore, you should avoid using overly loose values for matching to prevent compilation performance issues or compilation errors.
 
 :::tip
-In the regular expression example above, we use `[\\/]` to match the path separator because different operating systems use different path separators. Using `[\\/]` ensures that the paths can be matched in macOS, Linux and Windows.
+In the regular expression example, we use `[\\/]` to match the path separator because different operating systems use different path separators. Using `[\\/]` ensures that the paths can be matched in macOS, Linux and Windows.
 :::
 
 ## Compile sub dependencies

website/docs/zh/config/output/clean-dist-path.mdx

@@ -1,6 +1,11 @@
 # output.cleanDistPath
 
-- **类型：** `boolean | 'auto'`
+- **类型：**
+
+```ts
+type CleanDistPath = boolean | 'auto' | CleanDistPathObject;
+```
+
 - **默认值：** `'auto'`
 
 是否在构建开始前清理产物目录下的所有文件（产物目录默认为 `dist`）。
@@ -44,3 +49,48 @@ export default {
   },
 };
 ```
+
+## 选项
+
+`output.cleanDistPath` 支持配置为对象，以实现更细粒度的控制。
+
+### enable
+
+- **类型：** `boolean | 'auto'`
+- **默认值：** `'auto'`
+
+是否在构建开始前清理产物目录下的所有文件。
+
+```js
+export default {
+  output: {
+    // 等价于 `cleanDistPath: true`
+    cleanDistPath: {
+      enable: true,
+    },
+  },
+};
+```
+
+### keep
+
+- **类型：** `RegExp[]`
+- **默认值：** `undefined`
+
+指定在产物目录下保留的文件。如果文件的绝对路径可以匹配到 `keep` 中的正则表达式，则该文件不会被删除。
+
+例如，保留 `dist/foo.json` 文件：
+
+```js
+export default {
+  output: {
+    cleanDistPath: {
+      keep: [/dist[\\/]foo.json/],
+    },
+  },
+};
+```
+
+:::tip
+在正则表达式的例子中，我们使用 `[\\/]` 来匹配路径分隔符，这是因为不同的操作系统使用了不同的路径分隔符，使用 `[\\/]` 可以保证 macOS、Linux 和 Windows 的路径都被匹配到。
+:::

website/docs/zh/config/source/include.mdx

@@ -70,7 +70,7 @@ export default {
 上述两种方法分别通过 "路径前缀" 和 "正则表达式" 来匹配文件的绝对路径，值得留意的是，项目中所有被引用的模块都会经过匹配，因此你不能使用过于松散的值进行匹配，避免造成编译性能问题或编译异常。
 
 :::tip
-在上述正则表达式的例子中，我们使用 `[\\/]` 来匹配路径分隔符，这是因为不同的操作系统使用了不同的路径分隔符，使用 `[\\/]` 可以保证 macOS、Linux 和 Windows 的路径都被匹配到。
+在正则表达式的例子中，我们使用 `[\\/]` 来匹配路径分隔符，这是因为不同的操作系统使用了不同的路径分隔符，使用 `[\\/]` 可以保证 macOS、Linux 和 Windows 的路径都被匹配到。
 :::
 
 ## 编译间接依赖