feat: add htmlPlugin and rspackConfig template parameters (#2938)

web-infra-dev · Jul 16, 2024 · ee6a98b · ee6a98b
1 parent 7df1009
commit ee6a98b
Show file tree

Hide file tree

Showing 12 changed files with 91 additions and 46 deletions.
diff --git a/e2e/cases/html/inject/static/index.html b/e2e/cases/html/inject/static/index.html
@@ -3,12 +3,12 @@
   <head>
     <meta charset="utf-8" />
     <title>custom template</title>
-    <%= htmlWebpackPlugin.tags.headTags %>
+    <%= htmlPlugin.tags.headTags %>
     <script src="//example.com/assets/a.js"></script>
   </head>
   <body>
     <div id="test-template">text</div>
     <div id="root" />
-    <%= htmlWebpackPlugin.tags.bodyTags %>
+    <%= htmlPlugin.tags.bodyTags %>
   </body>
 </html>
diff --git 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('<title>foo</title>');
 });
 
-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
@@ -1,6 +1,6 @@
 <!doctype html>
 <html>
   <head>
-    <title><%= htmlWebpackPlugin.options.title %></title>
+    <title><%= htmlPlugin.options.title %></title>
   </head>
 </html>
diff --git a/examples/react/index.html b/examples/react/index.html
diff --git 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
@@ -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
@@ -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<string>;
+      css: Array<string>;
+      favicon?: string;
+    };
   };
 };
 ```

diff --git 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<string>;
+      css: Array<string>;
+      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
 <html>
   <head>
-    <%= htmlWebpackPlugin.tags.headTags %>
+    <%= htmlPlugin.tags.headTags %>
   </head>
   <body>
-    <%= htmlWebpackPlugin.tags.bodyTags %>
+    <%= htmlPlugin.tags.bodyTags %>
   </body>
 </html>
 ```

diff --git 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
   <head>
     <meta charset="utf-8">
     <title>custom template</title>
-+   <%= htmlWebpackPlugin.tags.headTags %>
++   <%= htmlPlugin.tags.headTags %>
     <script src="https://example.com/assets/a.js"></script>
   </head>
   <body>
     <div id="root" />
-+    <%= htmlWebpackPlugin.tags.bodyTags %>
++    <%= htmlPlugin.tags.bodyTags %>
   </body>
 </html>
 ```
diff --git 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<string>;
+      css: Array<string>;
+      favicon?: string;
+    };
   };
 };
 ```

diff --git 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<string>;
+      css: Array<string>;
+      favicon?: string;
+    };
   };
 };
 ```
@@ -235,15 +242,15 @@ Rsbuild 通过 Pug 插件来支持 Pug 模板引擎，请阅读 [@rsbuild/plugin
 前端应用的产物最终都会直接或间接地被 HTML 入口引用，但大多数时候直接向 HTML 注入标签都并非首选。
 :::
 
-模版文件中可以通过 `htmlWebpackPlugin.tags` 变量来访问需要最终注入到 HTML 的所有标签：
+模版文件中可以通过 `htmlPlugin.tags` 变量来访问需要最终注入到 HTML 的所有标签：
 
 ```html
 <html>
   <head>
-    <%= htmlWebpackPlugin.tags.headTags %>
+    <%= htmlPlugin.tags.headTags %>
   </head>
   <body>
-    <%= htmlWebpackPlugin.tags.bodyTags %>
+    <%= htmlPlugin.tags.bodyTags %>
   </body>
 </html>
 ```

diff --git 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 事件来获悉当前资源是否加
   <head>
     <meta charset="utf-8">
     <title>custom template</title>
-+   <%= htmlWebpackPlugin.tags.headTags %>
++   <%= htmlPlugin.tags.headTags %>
     <script src="https://example.com/assets/a.js"></script>
   </head>
   <body>
     <div id="root" />
-+    <%= htmlWebpackPlugin.tags.bodyTags %>
++    <%= htmlPlugin.tags.bodyTags %>
   </body>
 </html>
 ```