docs: add output.manifest.generate config (#4290)

website/docs/en/config/output/manifest.mdx

@@ -3,13 +3,53 @@
 - **Type:** `string | boolean`
 - **Default:** `false`
 
-Whether to generate a manifest file that contains information of all assets, and the mapping relationship between [entry module](/config/source/entry) and assets.
+Configure how to generate the manifest file.
 
-When `output.manifest` is set to `true`, Rsbuild will generate a `manifest.json` file after building. When the value of `output.manifest` is a string, it will be used as the manifest file name or path.
+- `true`: Generate a manifest file named `manifest.json` in the output directory.
+- `false`: Do not generate the manifest file.
+- `string`: Generate a manifest file with the specified filename or path.
+- `object`: Generate a manifest file with the specified options.
 
-## Output
+The manifest file contains the information of all assets, and the mapping relationship between [entry module](/config/source/entry) and assets.
 
-The default output file structure of manifest is:
+## Basic Example
+
+Enable the asset manifest:
+
+```ts title="rsbuild.config.ts"
+export default {
+  output: {
+    manifest: true,
+  },
+};
+```
+
+After building, Rsbuild will generate a `dist/manifest.json` file:
+
+```json title="dist/manifest.json"
+{
+  "allFiles": [
+    "/static/css/index.[hash].css",
+    "/static/js/index.[hash].js",
+    "/static/images/logo.[hash].png",
+    "/index.html"
+  ],
+  "entries": {
+    "index": {
+      "initial": {
+        "js": ["/static/js/index.[hash].js"],
+        "css": ["/static/css/index.[hash].css"]
+      },
+      "assets": ["/static/images/logo.[hash].png"],
+      "html": ["/index.html"]
+    }
+  }
+}
+```
+
+## Manifest Structure
+
+By default, the manifest file will be output in the following structure:
 
 ```ts
 type FilePath = string;
@@ -37,49 +77,110 @@ type ManifestList = {
 };
 ```
 
-## Basic Example
+## Options
 
-Enable asset manifest:
+`output.manifest` can be an object, here are all the options:
 
-```js
+### filename
+
+- **Type:** `string`
+- **Default:** `'manifest.json'`
+
+Specify the name or path of the manifest file.
+
+`filename` can be a path relative to the `dist` directory, for example, output to `dist/static/my-manifest.json`:
+
+```ts title="rsbuild.config.ts"
 export default {
   output: {
-    manifest: true,
+    manifest: {
+      filename: './static/my-manifest.json',
+    },
   },
 };
 ```
 
-After building, there will be a `dist/manifest.json` file:
+This can be simplified as:
 
-```json
-{
-  "allFiles": [
-    "/static/css/index.a11cfb11.css",
-    "/static/js/index.c586cd5e.js",
-    "/index.html",
-    "/static/js/index.c586cd5e.js.LICENSE.txt"
-  ],
-  "entries": {
-    "index": {
-      "initial": {
-        "js": ["/static/js/index.c586cd5e.js"],
-        "css": ["/static/css/index.a11cfb11.css"]
-      },
-      "assets": ["/static/js/index.c586cd5e.js.LICENSE.txt"],
-      "html": ["/index.html"]
-    }
-  }
-}
+```ts title="rsbuild.config.ts"
+export default {
+  output: {
+    manifest: './static/my-manifest.json',
+  },
+};
 ```
 
-## Set Path
+### generate
+
+- **Type:**
+
+```ts
+type ManifestGenerate = (params: {
+  files: FileDescriptor[];
+  manifestData: ManifestData;
+}) => Record<string, unknown>;
+```
 
-`output.manifest` can be a path relative to the `dist` directory, for example, output to `dist/static/my-manifest.json`:
+- **Default:** `undefined`
+- **Version:** `>= 1.2.0`
 
-```js
+With the `manifest.generate` function, you can customize the content of the manifest file. The function receives the following parameters:
+
+- `files`: The description information of all output files.
+- `manifestData`: The default manifest data.
+
+For example, only keep the `allAssets` field:
+
+```ts title="rsbuild.config.ts"
 export default {
   output: {
-    manifest: './static/my-manifest.json',
+    manifest: {
+      generate: ({ manifestData }) => {
+        return {
+          allAssets: manifestData.allFiles,
+        };
+      },
+    },
   },
 };
 ```
+
+You can also customize the content of the manifest file based on `files`. The `files` structure is as follows:
+
+```ts
+interface FileDescriptor {
+  name: string;
+  path: string;
+  isAsset: boolean;
+  isChunk: boolean;
+  isInitial: boolean;
+  isModuleAsset: boolean;
+  chunk?: import('@rspack/core').Chunk;
+}
+```
+
+Here is an example of `files`:
+
+```ts
+const files = [
+  {
+    name: 'index.js',
+    path: '/static/js/index.[hash].js',
+    isAsset: false,
+    isChunk: true,
+    isInitial: true,
+    isModuleAsset: false,
+    chunk: {
+      // Chunk info...
+    },
+  },
+  {
+    name: 'index.html',
+    path: '/index.html',
+    isAsset: true,
+    isChunk: false,
+    isInitial: false,
+    isModuleAsset: false,
+  },
+];
+```

website/docs/zh/config/output/manifest.mdx

@@ -1,13 +1,53 @@
 # output.manifest
 
-- **类型：** `string | boolean`
+- **类型：** `string | boolean | ManifestObjectConfig`
 - **默认值：** `false`
 
-是否生成 manifest 文件，该文件包含所有构建产物的信息、以及[入口模块](/config/source/entry)与构建产物间的映射关系。
+配置如何生成 manifest 文件。
 
-当 `output.manifest` 设置为 `true` 时，Rsbuild 会在构建后生成一个 `manifest.json` 文件。当 `output.manifest` 的值是一个字符串时，它将作为 manifest 文件的名称或路径。
+- `true`: 生成一个名为 `manifest.json` 的文件。
+- `false`: 不生成 manifest 文件。
+- `string`: 生成一个指定名称或路径的 manifest 文件。
+- `object`: 生成一个指定选项的 manifest 文件。
 
-## 输出内容
+manifest 文件包含所有构建产物的信息、以及 [入口模块](/config/source/entry) 与构建产物间的映射关系。
+
+## 基础示例
+
+添加以下配置来开启：
+
+```ts title="rsbuild.config.ts"
+export default {
+  output: {
+    manifest: true,
+  },
+};
+```
+
+构建完成后，Rsbuild 会生成 `dist/manifest.json` 文件：
+
+```json title="dist/manifest.json"
+{
+  "allFiles": [
+    "/static/css/index.[hash].css",
+    "/static/js/index.[hash].js",
+    "/static/images/logo.[hash].png",
+    "/index.html"
+  ],
+  "entries": {
+    "index": {
+      "initial": {
+        "js": ["/static/js/index.[hash].js"],
+        "css": ["/static/css/index.[hash].css"]
+      },
+      "assets": ["/static/images/logo.[hash].png"],
+      "html": ["/index.html"]
+    }
+  }
+}
+```
+
+## Manifest 结构
 
 manifest 文件默认输出的结构为：
 
@@ -37,49 +77,110 @@ type ManifestList = {
 };
 ```
 
-## 基础示例
+## 选项
 
-添加以下配置来开启：
+`output.manifest` 可以是一个对象，以下是所有可选项：
+
+### filename
+
+- **类型：** `string`
+- **默认值：** `'manifest.json'`
+
+指定 manifest 文件的名称或路径。
 
-```js
+`filename` 可以是一个相对于 `dist` 目录的路径，比如输出为 `dist/static/my-manifest.json`：
+
+```ts title="rsbuild.config.ts"
 export default {
   output: {
-    manifest: true,
+    manifest: {
+      filename: './static/my-manifest.json',
+    },
   },
 };
 ```
 
-当构建完成后，会自动生成 `dist/manifest.json` 文件：
+这可以简写为：
 
-```json
-{
-  "allFiles": [
-    "/static/css/index.a11cfb11.css",
-    "/static/js/index.c586cd5e.js",
-    "/index.html",
-    "/static/js/index.c586cd5e.js.LICENSE.txt"
-  ],
-  "entries": {
-    "index": {
-      "initial": {
-        "js": ["/static/js/index.c586cd5e.js"],
-        "css": ["/static/css/index.a11cfb11.css"]
-      },
-      "assets": ["/static/js/index.c586cd5e.js.LICENSE.txt"],
-      "html": ["/index.html"]
-    }
-  }
-}
+```ts title="rsbuild.config.ts"
+export default {
+  output: {
+    manifest: './static/my-manifest.json',
+  },
+};
+```
+
+### generate
+
+- **类型：**
+
+```ts
+type ManifestGenerate = (params: {
+  files: FileDescriptor[];
+  manifestData: ManifestData;
+}) => Record<string, unknown>;
 ```
 
-## 设置路径
+- **默认值：** `undefined`
+- **版本：** `>= 1.2.0`
+
+通过 `manifest.generate` 函数可以自定义 manifest 文件的内容。该函数接收以下参数：
 
-`output.manifest` 可以是一个相对于 `dist` 目录的路径，比如输出为 `dist/static/my-manifest.json`：
+- `files`: 所有输出的文件的描述信息。
+- `manifestData`: 默认的 manifest 数据。
 
-```js
+例如，仅保留 `allAssets` 字段：
+
+```ts title="rsbuild.config.ts"
 export default {
   output: {
-    manifest: './static/my-manifest.json',
+    manifest: {
+      generate: ({ manifestData }) => {
+        return {
+          allAssets: manifestData.allFiles,
+        };
+      },
+    },
   },
 };
 ```
+
+你也可以基于 `files` 来自定义 manifest 文件的内容，`files` 的结构如下：
+
+```ts
+interface FileDescriptor {
+  name: string;
+  path: string;
+  isAsset: boolean;
+  isChunk: boolean;
+  isInitial: boolean;
+  isModuleAsset: boolean;
+  chunk?: import('@rspack/core').Chunk;
+}
+```
+
+下面是 `files` 的一个示例：
+
+```ts
+const files = [
+  {
+    name: 'index.js',
+    path: '/static/js/index.[hash].js',
+    isAsset: false,
+    isChunk: true,
+    isInitial: true,
+    isModuleAsset: false,
+    chunk: {
+      // Chunk info...
+    },
+  },
+  {
+    name: 'index.html',
+    path: '/index.html',
+    isAsset: true,
+    isChunk: false,
+    isInitial: false,
+    isModuleAsset: false,
+  },
+];
+```