From ee6a98bc388db58f7ce7275dae668466b0dda27c Mon Sep 17 00:00:00 2001 From: neverland Date: Tue, 16 Jul 2024 20:56:09 +0800 Subject: [PATCH] feat: add `htmlPlugin` and `rspackConfig` template parameters (#2938) --- e2e/cases/html/inject/static/index.html | 4 +-- e2e/cases/html/title/index.test.ts | 2 +- .../html/title/src/plugin-options-title.html | 2 +- examples/react/index.html | 0 examples/react/rsbuild.config.ts | 3 +++ packages/core/src/plugins/html.ts | 26 +++++++++++++----- .../en/config/html/template-parameters.mdx | 21 ++++++++++----- website/docs/en/guide/basic/html-template.mdx | 27 ++++++++++++------- .../en/plugins/list/plugin-assets-retry.mdx | 4 +-- .../zh/config/html/template-parameters.mdx | 19 ++++++++----- website/docs/zh/guide/basic/html-template.mdx | 25 ++++++++++------- .../zh/plugins/list/plugin-assets-retry.mdx | 4 +-- 12 files changed, 91 insertions(+), 46 deletions(-) create mode 100644 examples/react/index.html diff --git a/e2e/cases/html/inject/static/index.html b/e2e/cases/html/inject/static/index.html index ec28ea5916..8cac2c082d 100644 --- a/e2e/cases/html/inject/static/index.html +++ b/e2e/cases/html/inject/static/index.html @@ -3,12 +3,12 @@ custom template - <%= htmlWebpackPlugin.tags.headTags %> + <%= htmlPlugin.tags.headTags %>
text
- <%= htmlWebpackPlugin.tags.bodyTags %> + <%= htmlPlugin.tags.bodyTags %> diff --git a/e2e/cases/html/title/index.test.ts b/e2e/cases/html/title/index.test.ts index 80ac15702d..d805e428ca 100644 --- a/e2e/cases/html/title/index.test.ts +++ b/e2e/cases/html/title/index.test.ts @@ -76,7 +76,7 @@ test('should generate title correctly when using custom HTML template', async () expect(html).toContain('foo'); }); -test('should generate title correctly when using htmlWebpackPlugin.options.title', async () => { +test('should generate title correctly when using htmlPlugin.options.title', async () => { const rsbuild = await build({ cwd: __dirname, rsbuildConfig: { diff --git a/e2e/cases/html/title/src/plugin-options-title.html b/e2e/cases/html/title/src/plugin-options-title.html index 24c873dacc..1776c404e1 100644 --- a/e2e/cases/html/title/src/plugin-options-title.html +++ b/e2e/cases/html/title/src/plugin-options-title.html @@ -1,6 +1,6 @@ - <%= htmlWebpackPlugin.options.title %> + <%= htmlPlugin.options.title %> diff --git a/examples/react/index.html b/examples/react/index.html new file mode 100644 index 0000000000..e69de29bb2 diff --git a/examples/react/rsbuild.config.ts b/examples/react/rsbuild.config.ts index c9962d33f3..c81dd2c0e2 100644 --- a/examples/react/rsbuild.config.ts +++ b/examples/react/rsbuild.config.ts @@ -3,4 +3,7 @@ import { pluginReact } from '@rsbuild/plugin-react'; export default defineConfig({ plugins: [pluginReact()], + html: { + template: './index.html', + }, }); diff --git a/packages/core/src/plugins/html.ts b/packages/core/src/plugins/html.ts index 717edb6e1e..ba8fb0f6d3 100644 --- a/packages/core/src/plugins/html.ts +++ b/packages/core/src/plugins/html.ts @@ -131,18 +131,32 @@ function getTemplateParameters( ): HtmlRspackPlugin.Options['templateParameters'] { return (compilation, assets, assetTags, pluginOptions) => { const { mountId, templateParameters } = config.html; + const rspackConfig = compilation.options; + const htmlPlugin = { + tags: assetTags, + files: assets, + options: pluginOptions, + }; + const defaultOptions = { mountId, entryName, assetPrefix, compilation, - webpackConfig: compilation.options, - htmlWebpackPlugin: { - tags: assetTags, - files: assets, - options: pluginOptions, - }, + htmlPlugin, + rspackConfig, + /** + * compatible with html-webpack-plugin + * @deprecated may be removed in a future major version, use `rspackConfig` instead + */ + webpackConfig: rspackConfig, + /** + * compatible with html-webpack-plugin + * @deprecated may be removed in a future major version, use `htmlPlugin` instead + */ + htmlWebpackPlugin: htmlPlugin, }; + return reduceConfigsWithContext({ initial: defaultOptions, config: templateParameters, diff --git a/website/docs/en/config/html/template-parameters.mdx b/website/docs/en/config/html/template-parameters.mdx index 2d9267a8d4..969b1fba2d 100644 --- a/website/docs/en/config/html/template-parameters.mdx +++ b/website/docs/en/config/html/template-parameters.mdx @@ -5,16 +5,23 @@ ```ts type DefaultParameters = { - mountId: string; // the value of html.mountId config + mountId: string; // the value of `html.mountId` config entryName: string; // entry name assetPrefix: string; // the value of dev.assetPrefix or output.assetPrefix configs compilation: Compilation; // Compilation object of Rspack - // htmlWebpackPlugin built-in parameters - // See https://github.com/rspack-contrib/html-rspack-plugin for details - htmlWebpackPlugin: { - tags: object; - files: object; - options: object; + rspackConfig: Rspack.Configuration; // Rspack config object + // generated by html-rspack-plugin + htmlPlugin: { + tags: { + headTags: HtmlTagObject[]; + bodyTags: HtmlTagObject[]; + }; + files: { + publicPath: string; + js: Array; + css: Array; + favicon?: string; + }; }; }; ``` diff --git a/website/docs/en/guide/basic/html-template.mdx b/website/docs/en/guide/basic/html-template.mdx index 4dfc16783a..bc3ef27817 100644 --- a/website/docs/en/guide/basic/html-template.mdx +++ b/website/docs/en/guide/basic/html-template.mdx @@ -117,16 +117,23 @@ In HTML templates, you can use a variety of template parameters. The template pa ```ts type DefaultParameters = { - mountId: string; // the value of html.mountId config + mountId: string; // the value of `html.mountId` config entryName: string; // entry name assetPrefix: string; // the value of dev.assetPrefix or output.assetPrefix configs compilation: Compilation; // Compilation object of Rspack - // htmlWebpackPlugin built-in parameters - // See https://github.com/rspack-contrib/html-rspack-plugin for details - htmlWebpackPlugin: { - tags: object; - files: object; - options: object; + rspackConfig: Rspack.Configuration; // Rspack config object + // generated by html-rspack-plugin + htmlPlugin: { + tags: { + headTags: HtmlTagObject[]; + bodyTags: HtmlTagObject[]; + }; + files: { + publicPath: string; + js: Array; + css: Array; + favicon?: string; + }; }; }; ``` @@ -235,15 +242,15 @@ The `html.tags` option can be configured to insert any tags into the final gener The artifacts of the web application will eventually be referenced directly or indirectly by HTML entries, but most of the time injecting tags directly into HTML is not preferred. ::: -All tags that need to be injected into HTML can be accessed in the template file via the variable `htmlWebpackPlugin.tags`. +All tags that need to be injected into HTML can be accessed in the template file via the variable `htmlPlugin.tags`. ```html - <%= htmlWebpackPlugin.tags.headTags %> + <%= htmlPlugin.tags.headTags %> - <%= htmlWebpackPlugin.tags.bodyTags %> + <%= htmlPlugin.tags.bodyTags %> ``` diff --git a/website/docs/en/plugins/list/plugin-assets-retry.mdx b/website/docs/en/plugins/list/plugin-assets-retry.mdx index aa0506f562..312289a25e 100644 --- a/website/docs/en/plugins/list/plugin-assets-retry.mdx +++ b/website/docs/en/plugins/list/plugin-assets-retry.mdx @@ -320,12 +320,12 @@ If you want Assets Retry plugin to work on resources in custom templates, you ca custom template -+ <%= htmlWebpackPlugin.tags.headTags %> ++ <%= htmlPlugin.tags.headTags %>
-+ <%= htmlWebpackPlugin.tags.bodyTags %> ++ <%= htmlPlugin.tags.bodyTags %> ``` diff --git a/website/docs/zh/config/html/template-parameters.mdx b/website/docs/zh/config/html/template-parameters.mdx index f40a442ed8..9efa4e4702 100644 --- a/website/docs/zh/config/html/template-parameters.mdx +++ b/website/docs/zh/config/html/template-parameters.mdx @@ -9,12 +9,19 @@ type DefaultParameters = { entryName: string; // 入口名称 assetPrefix: string; // 对应 dev.assetPrefix 和 output.assetPrefix 配置 compilation: Compilation; // Rspack 的 compilation 对象 - // htmlWebpackPlugin 内置的参数 - // 详见 https://github.com/rspack-contrib/html-rspack-plugin - htmlWebpackPlugin: { - tags: object; - files: object; - options: object; + rspackConfig: Rspack.Configuration; // Rspack 的配置对象 + // html-rspack-plugin 生成的参数 + htmlPlugin: { + tags: { + headTags: HtmlTagObject[]; + bodyTags: HtmlTagObject[]; + }; + files: { + publicPath: string; + js: Array; + css: Array; + favicon?: string; + }; }; }; ``` diff --git a/website/docs/zh/guide/basic/html-template.mdx b/website/docs/zh/guide/basic/html-template.mdx index 18795caeaf..7d483aa08c 100644 --- a/website/docs/zh/guide/basic/html-template.mdx +++ b/website/docs/zh/guide/basic/html-template.mdx @@ -121,12 +121,19 @@ type DefaultParameters = { entryName: string; // 入口名称 assetPrefix: string; // 对应 dev.assetPrefix 和 output.assetPrefix 配置 compilation: Compilation; // 对应 Rspack 的 compilation 对象 - // htmlWebpackPlugin 内置的参数 - // 详见 https://github.com/rspack-contrib/html-rspack-plugin - htmlWebpackPlugin: { - tags: object; - files: object; - options: object; + rspackConfig: Rspack.Configuration; // Rspack 的配置对象 + // html-rspack-plugin 生成的参数 + htmlPlugin: { + tags: { + headTags: HtmlTagObject[]; + bodyTags: HtmlTagObject[]; + }; + files: { + publicPath: string; + js: Array; + css: Array; + favicon?: string; + }; }; }; ``` @@ -235,15 +242,15 @@ Rsbuild 通过 Pug 插件来支持 Pug 模板引擎，请阅读 [@rsbuild/plugin 前端应用的产物最终都会直接或间接地被 HTML 入口引用，但大多数时候直接向 HTML 注入标签都并非首选。 ::: -模版文件中可以通过 `htmlWebpackPlugin.tags` 变量来访问需要最终注入到 HTML 的所有标签： +模版文件中可以通过 `htmlPlugin.tags` 变量来访问需要最终注入到 HTML 的所有标签： ```html - <%= htmlWebpackPlugin.tags.headTags %> + <%= htmlPlugin.tags.headTags %> - <%= htmlWebpackPlugin.tags.bodyTags %> + <%= htmlPlugin.tags.bodyTags %> ``` diff --git a/website/docs/zh/plugins/list/plugin-assets-retry.mdx b/website/docs/zh/plugins/list/plugin-assets-retry.mdx index 1b46d01f8d..0d88b4c1d0 100644 --- a/website/docs/zh/plugins/list/plugin-assets-retry.mdx +++ b/website/docs/zh/plugins/list/plugin-assets-retry.mdx @@ -320,12 +320,12 @@ Assets Retry 插件通过监听页面 error 事件来获悉当前资源是否加 custom template -+ <%= htmlWebpackPlugin.tags.headTags %> ++ <%= htmlPlugin.tags.headTags %>
-+ <%= htmlWebpackPlugin.tags.bodyTags %> ++ <%= htmlPlugin.tags.bodyTags %> ```