From dbefeecd619e2d5cf86d3dfdcccf03c5967a7db8 Mon Sep 17 00:00:00 2001 From: neverland Date: Sat, 31 May 2025 16:50:48 +0800 Subject: [PATCH 1/2] docs: enhance HTML generation for source.entry --- website/docs/en/config/source/entry.mdx | 27 ++++++++++++++----- website/docs/en/guide/basic/html-template.mdx | 21 ++++++++++++++- website/docs/zh/config/source/entry.mdx | 17 ++++++++++-- website/docs/zh/config/tools/html-plugin.mdx | 2 +- website/docs/zh/guide/basic/html-template.mdx | 21 ++++++++++++++- 5 files changed, 76 insertions(+), 12 deletions(-) diff --git a/website/docs/en/config/source/entry.mdx b/website/docs/en/config/source/entry.mdx index 628d41c2d6..15c7359473 100644 --- a/website/docs/en/config/source/entry.mdx +++ b/website/docs/en/config/source/entry.mdx @@ -18,9 +18,15 @@ const defaultEntry = { }; ``` -Used to set the entry modules for building. +Set the entry modules for building. -The usage of `source.entry` is similar to the `entry` option in [Rspack](https://rspack.rs/config/entry). The main difference is that Rsbuild will register [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) for each entry in `source.entry` to generate the corresponding HTML files. +The value of `source.entry` is an object, the key is the entry name, and the value is the path of the entry module or a [description object](#description-object). + +If the value is a path, it can be an absolute path or a relative path, the relative path will be resolved based on [root](/config/root). + +## HTML generation + +Rsbuild will register [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) for each entry in `source.entry` and generate the corresponding HTML files. - **Example:** @@ -28,8 +34,8 @@ The usage of `source.entry` is similar to the `entry` option in [Rspack](https:/ export default { source: { entry: { - foo: './src/pages/foo/index.ts', - bar: './src/pages/bar/index.ts', + foo: './src/pages/foo/index.ts', // generate foo.html + bar: './src/pages/bar/index.ts', // generate bar.html }, }, }; @@ -50,7 +56,10 @@ The generated directory structure is as follows: └── bar.js ``` -If you do not need to generate HTML files, you can set [tools.htmlPlugin](/config/tools/html-plugin) to `false` to disable this behavior. +If you do not need to generate HTML files: + +- Set the [html](/config/source/entry#html-property) property to `false` in the entry description object to disable the HTML generation for a single entry. +- Set [tools.htmlPlugin](/config/tools/html-plugin) to `false` to disable the HTML generation for all entries. ## Description object @@ -73,7 +82,9 @@ export default { }; ``` -Rsbuild has added an `html` attribute for the description object, which is used to control whether an HTML file is generated. +### `html` property + +Rsbuild has added an `html` property for the description object, which is used to control whether an HTML file is generated. For example, the `bar` entry does not generate an HTML file: @@ -91,7 +102,9 @@ export default { }; ``` -> For the complete usage of the description object, please refer to [Rspack - Entry Description Object](https://rspack.rs/config/entry#entry-description-object). +In the above example, `foo.html` will be generated, while `bar.html` will not be generated. + +> For detailed usage of the description object, refer to [Rspack - Entry description object](https://rspack.rs/config/entry#entry-description-object). ## Set by environment diff --git a/website/docs/en/guide/basic/html-template.mdx b/website/docs/en/guide/basic/html-template.mdx index b2546606a6..96089eb48b 100644 --- a/website/docs/en/guide/basic/html-template.mdx +++ b/website/docs/en/guide/basic/html-template.mdx @@ -4,6 +4,23 @@ During the build process, Rsbuild will compile based on the HTML template and te Rsbuild provides some configs to set the HTML template. Through this chapter, you can learn the basic usage of these configs. +## HTML generation + +Rsbuild will generate an HTML file for each entry defined in [source.entry](/config/source/entry). + +```ts title="rsbuild.config.ts" +export default { + source: { + entry: { + foo: './src/pages/foo/index.ts', // generate foo.html + bar: './src/pages/bar/index.ts', // generate bar.html + }, + }, +}; +``` + +See [source.entry - HTML generation](/config/source/entry#html-generation) for more details on how to control HTML generation. + ## Set template In Rsbuild, you can use [html.template](/config/html/template) config to define the path to the custom HTML template. @@ -16,7 +33,7 @@ export default { }; ``` -If `html.template` is not set, Rsbuild will use the built-in HTML template: +If `html.template` is not set, Rsbuild will use the built-in HTML template, the content is as follows: ```html title="defaultTemplate.html" @@ -28,6 +45,8 @@ If `html.template` is not set, Rsbuild will use the built-in HTML template: ``` +In the default template, `id="<%= mountId %>"` will be replaced with `id="root"`, you can modify this value through the [html.mountId](/config/html/mount-id) option. + ## Set page title You can set the HTML `` tag through the [html.title](/config/html/title) config. diff --git a/website/docs/zh/config/source/entry.mdx b/website/docs/zh/config/source/entry.mdx index cc2b35e27f..8e2c3c218b 100644 --- a/website/docs/zh/config/source/entry.mdx +++ b/website/docs/zh/config/source/entry.mdx @@ -20,7 +20,13 @@ const defaultEntry = { 用于设置构建的入口模块。 -`source.entry` 的用法与 Rspack 的 [entry](https://rspack.rs/zh/config/entry) 选项类似，它们的主要区别在于，Rsbuild 会为 `source.entry` 中的每一个入口注册 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin)，从而生成对应的 HTML 文件。 +`source.entry` 的值是一个对象，key 是入口名称，value 是入口模块的路径，或是一个 [描述对象](#描述对象)。 + +当 value 为路径时，它可以为绝对路径或相对路径，相对路径会基于 [root](/config/root) 进行解析。 + +## HTML 生成 + +Rsbuild 会为 `source.entry` 中的每一个入口注册 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin)，并生成对应的 HTML 文件。 - **示例：** @@ -50,7 +56,10 @@ export default { └── bar.js ``` -如果你不需要生成 HTML 文件，可以将 [tools.htmlPlugin](/config/tools/html-plugin) 设置为 `false` 来禁用这一行为。 +如果你不需要生成 HTML 文件： + +- 将入口描述对象中的 [html](/config/source/entry#html-属性) 属性设置为 `false` 来禁用单个入口的 HTML 生成。 +- 将 [tools.htmlPlugin](/config/tools/html-plugin) 设置为 `false` 来禁用所有入口的 HTML 生成。 ## 描述对象 @@ -73,6 +82,8 @@ export default { }; ``` +### `html` 属性 + Rsbuild 为描述对象添加了 `html` 属性，用于控制是否生成 HTML 文件。 例如，`bar` 入口不生成 HTML 文件： @@ -91,6 +102,8 @@ export default { }; ``` +在上述例子中，构建时会生成 `foo.html` 文件，而 `bar.html` 文件不会生成。 + > 关于描述对象的完整用法，请参考 [Rspack - 入口描述对象](https://rspack.rs/zh/config/entry#%E5%85%A5%E5%8F%A3%E6%8F%8F%E8%BF%B0%E5%AF%B9%E8%B1%A1)。 ## 基于 environment 设置 diff --git a/website/docs/zh/config/tools/html-plugin.mdx b/website/docs/zh/config/tools/html-plugin.mdx index 51e3deee03..cc35282d85 100644 --- a/website/docs/zh/config/tools/html-plugin.mdx +++ b/website/docs/zh/config/tools/html-plugin.mdx @@ -62,7 +62,7 @@ export default { ## 禁用 HTML -将 `tools.htmlPlugin` 配置为 `false`，可以禁用 Rsbuild 内置的 `html-rspack-plugin` 插件，此时将不会生成 HTML 产物。 +将 `tools.htmlPlugin` 配置为 `false`，可以禁用 Rsbuild 内置的 `html-rspack-plugin` 插件，此时将不会生成 HTML 文件。 ```js export default { diff --git a/website/docs/zh/guide/basic/html-template.mdx b/website/docs/zh/guide/basic/html-template.mdx index e252ff5dd9..c120ad7393 100644 --- a/website/docs/zh/guide/basic/html-template.mdx +++ b/website/docs/zh/guide/basic/html-template.mdx @@ -4,6 +4,23 @@ Rsbuild 提供了一些配置项来对 HTML 模板进行设置。通过本章节你可以了解到这些配置项的基本用法。 +## HTML 生成 + +Rsbuild 会为 [source.entry](/config/source/entry) 中定义的每个入口生成一个 HTML 文件。 + +```ts title="rsbuild.config.ts" +export default { + source: { + entry: { + foo: './src/pages/foo/index.ts', // 生成 foo.html + bar: './src/pages/bar/index.ts', // 生成 bar.html + }, + }, +}; +``` + +参考 [source.entry - HTML 生成](/config/source/entry#html-生成) 了解如何控制 HTML 生成。 + ## 设置模板文件 在 Rsbuild 中，你可以使用 [html.template](/config/html/template) 配置项来设置自定义的 HTML 模板文件。 @@ -16,7 +33,7 @@ export default { }; ``` -未设置 `html.template` 时，Rsbuild 会使用内置的 HTML 模板： +未设置 `html.template` 时，Rsbuild 会使用内置的 HTML 模板，内容如下： ```html title="defaultTemplate.html" <!doctype html> @@ -28,6 +45,8 @@ export default { </html> ``` +在默认模板中，`id="<%= mountId %>"` 会被替换为 `id="root"`，你可以通过 [html.mountId](/config/html/mount-id) 选项来修改这个值。 + ## 设置页面标题 你可以通过 [html.title](/config/html/title) 配置项来设置 HTML 的 `<title>` 标签。 From 2f7afc16fbf65de082e697cbbc6f06d6e1fb9f03 Mon Sep 17 00:00:00 2001 From: neverland <chenjiahan.jait@bytedance.com> Date: Sat, 31 May 2025 16:52:42 +0800 Subject: [PATCH 2/2] fix --- packages/core/src/types/config.ts | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts index 7c50f8802b..0b68e30fe0 100644 --- a/packages/core/src/types/config.ts +++ b/packages/core/src/types/config.ts @@ -263,7 +263,14 @@ export interface SourceConfig { */ include?: RuleSetCondition[]; /** - * Set the entry modules. + * Set the entry modules for building. + * + * The value of `source.entry` is an object, the key is the entry name, and the + * value is the path of the entry module or a description object. + * + * If the value is a path, it can be an absolute path or a relative path, the + * relative path will be resolved based on `root`. + * * @default * { * // Rsbuild also supports other suffixes by default, such as ts,