Skip to content

Commit dc17ce9

Browse files
chenjiahanchenjiahan
committed
docs: add output.manifest.generate config
1 parent 3b6594d commit dc17ce9

2 files changed

Lines changed: 266 additions & 64 deletions

File tree

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

Lines changed: 133 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,53 @@
33
- **Type:** `string | boolean`
44
- **Default:** `false`
55

6-
Whether to generate a manifest file that contains information of all assets, and the mapping relationship between [entry module](/config/source/entry) and assets.
6+
Configure how to generate the manifest file.
77

8-
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.
8+
- `true`: Generate a manifest file named `manifest.json` in the output directory.
9+
- `false`: Do not generate the manifest file.
10+
- `string`: Generate a manifest file with the specified filename or path.
11+
- `object`: Generate a manifest file with the specified options.
912

10-
## Output
13+
The manifest file contains the information of all assets, and the mapping relationship between [entry module](/config/source/entry) and assets.
1114

12-
The default output file structure of manifest is:
15+
## Basic Example
16+
17+
Enable the asset manifest:
18+
19+
```ts title="rsbuild.config.ts"
20+
export default {
21+
output: {
22+
manifest: true,
23+
},
24+
};
25+
```
26+
27+
After building, Rsbuild will generate a `dist/manifest.json` file:
28+
29+
```json title="dist/manifest.json"
30+
{
31+
"allFiles": [
32+
"/static/css/index.[hash].css",
33+
"/static/js/index.[hash].js",
34+
"/static/images/logo.[hash].png",
35+
"/index.html"
36+
],
37+
"entries": {
38+
"index": {
39+
"initial": {
40+
"js": ["/static/js/index.[hash].js"],
41+
"css": ["/static/css/index.[hash].css"]
42+
},
43+
"assets": ["/static/images/logo.[hash].png"],
44+
"html": ["/index.html"]
45+
}
46+
}
47+
}
48+
```
49+
50+
## Manifest Structure
51+
52+
By default, the manifest file will be output in the following structure:
1353

1454
```ts
1555
type FilePath = string;
@@ -37,49 +77,110 @@ type ManifestList = {
3777
};
3878
```
3979

40-
## Basic Example
80+
## Options
4181

42-
Enable asset manifest:
82+
`output.manifest` can be an object, here are all the options:
4383

44-
```js
84+
### filename
85+
86+
- **Type:** `string`
87+
- **Default:** `'manifest.json'`
88+
89+
Specify the name or path of the manifest file.
90+
91+
`filename` can be a path relative to the `dist` directory, for example, output to `dist/static/my-manifest.json`:
92+
93+
```ts title="rsbuild.config.ts"
4594
export default {
4695
output: {
47-
manifest: true,
96+
manifest: {
97+
filename: './static/my-manifest.json',
98+
},
4899
},
49100
};
50101
```
51102

52-
After building, there will be a `dist/manifest.json` file:
103+
This can be simplified as:
53104

54-
```json
55-
{
56-
"allFiles": [
57-
"/static/css/index.a11cfb11.css",
58-
"/static/js/index.c586cd5e.js",
59-
"/index.html",
60-
"/static/js/index.c586cd5e.js.LICENSE.txt"
61-
],
62-
"entries": {
63-
"index": {
64-
"initial": {
65-
"js": ["/static/js/index.c586cd5e.js"],
66-
"css": ["/static/css/index.a11cfb11.css"]
67-
},
68-
"assets": ["/static/js/index.c586cd5e.js.LICENSE.txt"],
69-
"html": ["/index.html"]
70-
}
71-
}
72-
}
105+
```ts title="rsbuild.config.ts"
106+
export default {
107+
output: {
108+
manifest: './static/my-manifest.json',
109+
},
110+
};
73111
```
74112

75-
## Set Path
113+
### generate
114+
115+
- **Type:**
116+
117+
```ts
118+
type ManifestGenerate = (params: {
119+
files: FileDescriptor[];
120+
manifestData: ManifestData;
121+
}) => Record<string, unknown>;
122+
```
76123

77-
`output.manifest` can be a path relative to the `dist` directory, for example, output to `dist/static/my-manifest.json`:
124+
- **Default:** `undefined`
125+
- **Version:** `>= 1.2.0`
78126

79-
```js
127+
With the `manifest.generate` function, you can customize the content of the manifest file. The function receives the following parameters:
128+
129+
- `files`: The description information of all output files.
130+
- `manifestData`: The default manifest data.
131+
132+
For example, only keep the `allAssets` field:
133+
134+
```ts title="rsbuild.config.ts"
80135
export default {
81136
output: {
82-
manifest: './static/my-manifest.json',
137+
manifest: {
138+
generate: ({ manifestData }) => {
139+
return {
140+
allAssets: manifestData.allFiles,
141+
};
142+
},
143+
},
83144
},
84145
};
85146
```
147+
148+
You can also customize the content of the manifest file based on `files`. The `files` structure is as follows:
149+
150+
```ts
151+
interface FileDescriptor {
152+
name: string;
153+
path: string;
154+
isAsset: boolean;
155+
isChunk: boolean;
156+
isInitial: boolean;
157+
isModuleAsset: boolean;
158+
chunk?: import('@rspack/core').Chunk;
159+
}
160+
```
161+
162+
Here is an example of `files`:
163+
164+
```ts
165+
const files = [
166+
{
167+
name: 'index.js',
168+
path: '/static/js/index.[hash].js',
169+
isAsset: false,
170+
isChunk: true,
171+
isInitial: true,
172+
isModuleAsset: false,
173+
chunk: {
174+
// Chunk info...
175+
},
176+
},
177+
{
178+
name: 'index.html',
179+
path: '/index.html',
180+
isAsset: true,
181+
isChunk: false,
182+
isInitial: false,
183+
isModuleAsset: false,
184+
},
185+
];
186+
```

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

Lines changed: 133 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,53 @@
11
# output.manifest
22

3-
- **类型：** `string | boolean`
3+
- **类型：** `string | boolean | ManifestObjectConfig`
44
- **默认值：** `false`
55

6-
是否生成 manifest 文件，该文件包含所有构建产物的信息、以及[入口模块](/config/source/entry)与构建产物间的映射关系。
6+
配置如何生成 manifest 文件。
77

8-
当 `output.manifest` 设置为 `true` 时，Rsbuild 会在构建后生成一个 `manifest.json` 文件。当 `output.manifest` 的值是一个字符串时，它将作为 manifest 文件的名称或路径。
8+
- `true`: 生成一个名为 `manifest.json` 的文件。
9+
- `false`: 不生成 manifest 文件。
10+
- `string`: 生成一个指定名称或路径的 manifest 文件。
11+
- `object`: 生成一个指定选项的 manifest 文件。
912

10-
## 输出内容
13+
manifest 文件包含所有构建产物的信息、以及 [入口模块](/config/source/entry) 与构建产物间的映射关系。
14+
15+
## 基础示例
16+
17+
添加以下配置来开启：
18+
19+
```ts title="rsbuild.config.ts"
20+
export default {
21+
output: {
22+
manifest: true,
23+
},
24+
};
25+
```
26+
27+
构建完成后，Rsbuild 会生成 `dist/manifest.json` 文件：
28+
29+
```json title="dist/manifest.json"
30+
{
31+
"allFiles": [
32+
"/static/css/index.[hash].css",
33+
"/static/js/index.[hash].js",
34+
"/static/images/logo.[hash].png",
35+
"/index.html"
36+
],
37+
"entries": {
38+
"index": {
39+
"initial": {
40+
"js": ["/static/js/index.[hash].js"],
41+
"css": ["/static/css/index.[hash].css"]
42+
},
43+
"assets": ["/static/images/logo.[hash].png"],
44+
"html": ["/index.html"]
45+
}
46+
}
47+
}
48+
```
49+
50+
## Manifest 结构
1151

1252
manifest 文件默认输出的结构为：
1353

@@ -37,49 +77,110 @@ type ManifestList = {
3777
};
3878
```
3979

40-
## 基础示例
80+
## 选项
4181

42-
添加以下配置来开启：
82+
`output.manifest` 可以是一个对象，以下是所有可选项：
83+
84+
### filename
85+
86+
- **类型：** `string`
87+
- **默认值：** `'manifest.json'`
88+
89+
指定 manifest 文件的名称或路径。
4390

44-
```js
91+
`filename` 可以是一个相对于 `dist` 目录的路径，比如输出为 `dist/static/my-manifest.json`：
92+
93+
```ts title="rsbuild.config.ts"
4594
export default {
4695
output: {
47-
manifest: true,
96+
manifest: {
97+
filename: './static/my-manifest.json',
98+
},
4899
},
49100
};
50101
```
51102

52-
当构建完成后，会自动生成 `dist/manifest.json` 文件：
103+
这可以简写为：
53104

54-
```json
55-
{
56-
"allFiles": [
57-
"/static/css/index.a11cfb11.css",
58-
"/static/js/index.c586cd5e.js",
59-
"/index.html",
60-
"/static/js/index.c586cd5e.js.LICENSE.txt"
61-
],
62-
"entries": {
63-
"index": {
64-
"initial": {
65-
"js": ["/static/js/index.c586cd5e.js"],
66-
"css": ["/static/css/index.a11cfb11.css"]
67-
},
68-
"assets": ["/static/js/index.c586cd5e.js.LICENSE.txt"],
69-
"html": ["/index.html"]
70-
}
71-
}
72-
}
105+
```ts title="rsbuild.config.ts"
106+
export default {
107+
output: {
108+
manifest: './static/my-manifest.json',
109+
},
110+
};
111+
```
112+
113+
### generate
114+
115+
- **类型：**
116+
117+
```ts
118+
type ManifestGenerate = (params: {
119+
files: FileDescriptor[];
120+
manifestData: ManifestData;
121+
}) => Record<string, unknown>;
73122
```
74123

75-
## 设置路径
124+
- **默认值：** `undefined`
125+
- **版本：** `>= 1.2.0`
126+
127+
通过 `manifest.generate` 函数可以自定义 manifest 文件的内容。该函数接收以下参数：
76128

77-
`output.manifest` 可以是一个相对于 `dist` 目录的路径，比如输出为 `dist/static/my-manifest.json`：
129+
- `files`: 所有输出的文件的描述信息。
130+
- `manifestData`: 默认的 manifest 数据。
78131

79-
```js
132+
例如，仅保留 `allAssets` 字段：
133+
134+
```ts title="rsbuild.config.ts"
80135
export default {
81136
output: {
82-
manifest: './static/my-manifest.json',
137+
manifest: {
138+
generate: ({ manifestData }) => {
139+
return {
140+
allAssets: manifestData.allFiles,
141+
};
142+
},
143+
},
83144
},
84145
};
85146
```
147+
148+
你也可以基于 `files` 来自定义 manifest 文件的内容，`files` 的结构如下：
149+
150+
```ts
151+
interface FileDescriptor {
152+
name: string;
153+
path: string;
154+
isAsset: boolean;
155+
isChunk: boolean;
156+
isInitial: boolean;
157+
isModuleAsset: boolean;
158+
chunk?: import('@rspack/core').Chunk;
159+
}
160+
```
161+
162+
下面是 `files` 的一个示例：
163+
164+
```ts
165+
const files = [
166+
{
167+
name: 'index.js',
168+
path: '/static/js/index.[hash].js',
169+
isAsset: false,
170+
isChunk: true,
171+
isInitial: true,
172+
isModuleAsset: false,
173+
chunk: {
174+
// Chunk info...
175+
},
176+
},
177+
{
178+
name: 'index.html',
179+
path: '/index.html',
180+
isAsset: true,
181+
isChunk: false,
182+
isInitial: false,
183+
isModuleAsset: false,
184+
},
185+
];
186+
```

0 commit comments

Comments
 (0)