docs: add template migration guide (#1136)

web-infra-dev · Jan 1, 2024 · 906baf9 · 906baf9
1 parent 5494488
commit 906baf9
Show file tree

Hide file tree

Showing 8 changed files with 83 additions and 15 deletions.
diff --git a/packages/document/docs/en/config/html/template-parameters.mdx b/packages/document/docs/en/config/html/template-parameters.mdx
@@ -5,9 +5,9 @@
 
 ```ts
 type DefaultParameters = {
-  mountId: string; // corresponding to html.mountId config
+  mountId: string; // the value of html.mountId config
   entryName: string; // entry name
-  assetPrefix: string; // corresponding to output.assetPrefix config
+  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/jantimon/html-webpack-plugin for details

diff --git a/packages/document/docs/en/guide/basic/html-template.md b/packages/document/docs/en/guide/basic/html-template.md
@@ -98,10 +98,10 @@ In HTML templates, you can use a variety of template parameters. The template pa
 
 ```ts
 type DefaultParameters = {
-  mountId: string; // corresponding to html.mountId config
+  mountId: string; // the value of html.mountId config
   entryName: string; // entry name
-  assetPrefix: string; // corresponding to output.assetPrefix config
-  compilation: Compilation; // Compilation object corresponding to Rspack
+  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/jantimon/html-webpack-plugin for details
   htmlWebpackPlugin: {

diff --git a/packages/document/docs/en/guide/migration/cra.mdx b/packages/document/docs/en/guide/migration/cra.mdx
@@ -50,6 +50,25 @@ export default defineConfig({
 });
 ```
 
+## HTML Template
+
+CRA uses the `public/index.html` file as the default HTML template. In Rsbuild, you can specify the HTML template through [html.template](/config/html/template):
+
+```ts title="rsbuild.config.ts"
+export default defineConfig({
+  html: {
+    template: './public/index.html',
+  },
+});
+```
+
+In the HTML template, if you are using the `%PUBLIC_URL%` variable from CRA, replace it with Rsbuild's [assetPrefix variable](/config/html/template-parameters) and use a forward slash for concatenation:
+
+```diff
+-  <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
++  <link rel="icon" href="<%= assetPrefix %>/favicon.ico" />
+```
+
 This completes the basic migration from CRA to Rsbuild. You can now run the `npm run start` command to try starting the dev server.
 
 ## Using SVGR

diff --git a/packages/document/docs/en/guide/migration/vue-cli.mdx b/packages/document/docs/en/guide/migration/vue-cli.mdx
@@ -54,17 +54,32 @@ export default defineConfig({
       index: './src/main.js',
     },
   },
-  html: {
-    // Set the id of the HTML root element to 'app'
-    mountId: 'app',
-  },
 });
 ```
 
 :::tip
 If your project is based on Vue 2, use `import { pluginVue2 } from '@rsbuild/plugin-vue2';`.
 :::
 
+## HTML Template
+
+Vue CLI uses the `public/index.html` file as the default HTML template. In Rsbuild, you can specify the HTML template through [html.template](/config/html/template):
+
+```ts title="rsbuild.config.ts"
+export default defineConfig({
+  html: {
+    template: './public/index.html',
+  },
+});
+```
+
+In the HTML template, if you are using the `BASE_URL` variable from Vue CLI, replace it with Rsbuild's [assetPrefix variable](/config/html/template-parameters) and use a forward slash for concatenation:
+
+```diff
+-  <link rel="icon" href="<%= BASE_URL %>favicon.ico">
++  <link rel="icon" href="<%= assetPrefix %>/favicon.ico">
+```
+
 This completes the basic migration from Vue CLI to Rsbuild. You can now run the `npm run serve` command to try starting the dev server.
 
 ## Configuration Migration

diff --git a/packages/document/docs/zh/config/html/template-parameters.mdx b/packages/document/docs/zh/config/html/template-parameters.mdx
@@ -7,7 +7,7 @@
 type DefaultParameters = {
   mountId: string; // 对应 html.mountId 配置
   entryName: string; // 入口名称
-  assetPrefix: string; // 对应 output.assetPrefix 配置
+  assetPrefix: string; // 对应 dev.assetPrefix 和 output.assetPrefix 配置
   compilation: Compilation; // Rspack 的 compilation 对象
   // htmlWebpackPlugin 内置的参数
   // 详见 https://github.com/jantimon/html-webpack-plugin

diff --git a/packages/document/docs/zh/guide/basic/html-template.md b/packages/document/docs/zh/guide/basic/html-template.md
@@ -100,7 +100,7 @@ export default {
 type DefaultParameters = {
   mountId: string; // 对应 html.mountId 配置
   entryName: string; // 入口名称
-  assetPrefix: string; // 对应 output.assetPrefix 配置
+  assetPrefix: string; // 对应 dev.assetPrefix 和 output.assetPrefix 配置
   compilation: Compilation; // 对应 Rspack 的 compilation 对象
   // htmlWebpackPlugin 内置的参数
   // 详见 https://github.com/jantimon/html-webpack-plugin

diff --git a/packages/document/docs/zh/guide/migration/cra.mdx b/packages/document/docs/zh/guide/migration/cra.mdx
@@ -50,6 +50,25 @@ export default defineConfig({
 });
 ```
 
+## HTML 模板
+
+CRA 默认使用 `public/index.html` 文件作为 HTML 模板。在 Rsbuild 中，你可以通过 [html.template](/config/html/template) 来指定 HTML 模板：
+
+```ts title="rsbuild.config.ts"
+export default defineConfig({
+  html: {
+    template: './public/index.html',
+  },
+});
+```
+
+在 HTML 模板中，如果使用了 CRA 的 `%PUBLIC_URL%` 变量，请替换为 Rsbuild 的 [assetPrefix 变量](/config/html/template-parameters)，并使用斜杠进行连接：
+
+```diff
+-  <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
++  <link rel="icon" href="<%= assetPrefix %>/favicon.ico" />
+```
+
 这样就完成了从 CRA 到 Rsbuild 的基本迁移，此时你可以执行 `npm run start` 命令来尝试启动开发服务器。
 
 ## 使用 SVGR

diff --git a/packages/document/docs/zh/guide/migration/vue-cli.mdx b/packages/document/docs/zh/guide/migration/vue-cli.mdx
@@ -56,17 +56,32 @@ export default defineConfig({
       index: './src/main.js',
     },
   },
-  html: {
-    // 设置 HTML 根节点的 id 为 'app'
-    mountId: 'app',
-  },
 });
 ```
 
 :::tip
 如果你的项目是基于 Vue 2 的，请使用 `import { pluginVue2 } from '@rsbuild/plugin-vue2';`。
 :::
 
+## HTML 模板
+
+Vue CLI 默认使用 `public/index.html` 文件作为 HTML 模板。在 Rsbuild 中，你可以通过 [html.template](/config/html/template) 来指定 HTML 模板：
+
+```ts title="rsbuild.config.ts"
+export default defineConfig({
+  html: {
+    template: './public/index.html',
+  },
+});
+```
+
+在 HTML 模板中，如果使用了 Vue CLI 的 `BASE_URL` 变量，请替换为 Rsbuild 的 [assetPrefix 变量](/config/html/template-parameters)，并使用斜杠进行连接：
+
+```diff
+-  <link rel="icon" href="<%= BASE_URL %>favicon.ico">
++  <link rel="icon" href="<%= assetPrefix %>/favicon.ico">
+```
+
 这样就完成了从 Vue CLI 到 Rsbuild 的基本迁移，此时你可以执行 `npm run serve` 命令来尝试启动开发服务器。
 
 ## 配置迁移