From a0e518ecf18c63a321b290b1fef3ac782763e9b5 Mon Sep 17 00:00:00 2001 From: neverland Date: Sun, 29 Dec 2024 19:54:46 +0800 Subject: [PATCH] docs: add `output.manifest.generate` config (#4290) --- website/docs/en/config/output/manifest.mdx | 165 +++++++++++++++++---- website/docs/zh/config/output/manifest.mdx | 165 +++++++++++++++++---- 2 files changed, 266 insertions(+), 64 deletions(-) diff --git a/website/docs/en/config/output/manifest.mdx b/website/docs/en/config/output/manifest.mdx index 999efb3d5b..dfc73897df 100644 --- a/website/docs/en/config/output/manifest.mdx +++ b/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; +``` -`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, + }, +]; +``` diff --git a/website/docs/zh/config/output/manifest.mdx b/website/docs/zh/config/output/manifest.mdx index 79f1feca81..2ca6757ba7 100644 --- a/website/docs/zh/config/output/manifest.mdx +++ b/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; ``` -## 设置路径 +- **默认值：** `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, + }, +]; +```