Merge branch 'main' into renovate/rspack

website/docs/en/config/dev/client.mdx

@@ -14,10 +14,7 @@ type Client = {
   port?: string | number;
   /** Specify the host for the WebSocket request */
   host?: string;
-  /**
-   * Shows overlay in the browser when there are compiler errors
-   * This feature requires the current browser version to support [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
-   */
+  /** Whether to display an error overlay in the browser when a compilation error occurs */
   overlay?: boolean;
 };
 ```
@@ -82,3 +79,27 @@ export default {
 During the HMR process, the page will make GET requests to get hot-update files, including `*.hot-update.json` and `*.hot-update.js`. These files contain the necessary information for hot updates, such as the updated modules and their code.
 
 Hot-update files are considered to be static assets. If you need to configure the URL for hot-update files, please use the [dev.assetPrefix](/config/dev/asset-prefix) option.
+
+## Error Overlay
+
+The `dev.client.overlay` option allows you to choose whether or not to enable the error overlay feature.
+
+By default, Rsbuild will display an error overlay in the browser when a compilation error occurs, providing error messages and stacks:
+
+![error overlay](https://assets.rspack.dev/rsbuild/assets/rsbuild-error-overlay.png)
+
+If you need to disable the error overlay, you can set it to `false`:
+
+```ts title="rsbuild.config.ts"
+export default {
+  dev: {
+    client: {
+      overlay: false,
+    },
+  },
+};
+```
+
+:::tip
+The error overlay feature requires the current browser to support [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
+:::

website/docs/en/config/performance/bundle-analyze.mdx

@@ -15,17 +15,38 @@ const defaultConfig = {
 };
 ```
 
-### Enable Bundle Analyze
+## Enable Bundle Analyze
 
-You have two ways to enable `webpack-bundle-analyzer` to analyze the size of the output files:
+You have two ways to enable `webpack-bundle-analyzer` to analyze the size of the output files.
 
-- Add the environment variable `BUNDLE_ANALYZE=true`, for example:
+### Via Environment Variable
 
-```bash
-BUNDLE_ANALYZE=true pnpm build
+Add the environment variable `BUNDLE_ANALYZE=true`, for example:
+
+```json title="package.json"
+{
+  "scripts": {
+    "build:analyze": "BUNDLE_ANALYZE=true rsbuild build"
+  }
+}
+```
+
+Since the Windows system does not support the above usage, you can also use [cross-env](https://www.npmjs.com/package/cross-env) to set environment variables. This ensures compatibility across different systems:
+
+```json title="package.json"
+{
+  "scripts": {
+    "build:analyze": "cross-env BUNDLE_ANALYZE=true rsbuild build"
+  },
+  "devDependencies": {
+    "cross-env": "^7.0.0"
+  }
+}
 ```
 
-- Configure `performance.bundleAnalyze` to enable it permanently:
+### Via Configuration
+
+Configure `performance.bundleAnalyze` to enable it permanently:
 
 ```js
 export default {
@@ -35,6 +56,8 @@ export default {
 };
 ```
 
+### Analysis Result
+
 After enabling it, Rsbuild will generate an HTML file that analyzes the size of the output files, and print the following log in the Terminal:
 
 ```bash
@@ -45,7 +68,7 @@ You can manually open the file in the browser and view the detail of the bundle
 
 ![](https://assets.rspack.dev/rsbuild/assets/bundle-analyzer-example.png)
 
-### Override Default Configuration
+## Override Default Configuration
 
 You can override the default configuration through `performance.bundleAnalyze`, such as enabling the server mode:
 
@@ -62,15 +85,15 @@ export default {
 };
 ```
 
-### Size Types
+## Size Types
 
 In the `webpack-bundle-analyzer` panel, you can control size types in the upper left corner (default is `Parsed`):
 
 - `Stat`: The size obtained from the `stats` object of the bundler, which reflects the size of the code before minification.
 - `Parsed`: The size of the file on the disk, which reflects the size of the code after minification.
 - `Gzipped`: The file size requested in the browser reflects the size of the code after minification and gzip.
 
-### Generate stats.json
+## Generate stats.json
 
 By setting `generateStatsFile` to true, stats JSON file will be generated in bundle output directory.
 
@@ -84,7 +107,7 @@ export default {
 };
 ```
 
-### Notes
+## Notes
 
 1. Enabling the server mode will cause the `build` process to not exit normally.
 2. Enabling `bundleAnalyzer` will reduce build speed. Therefore, this configuration should not be enabled during daily development, and it is recommended to enable it on demand through the `BUNDLE_ANALYZE` environment variable.

website/docs/en/guide/basic/html-template.mdx

@@ -214,15 +214,11 @@ Rsbuild supports the [Pug](https://pugjs.org/) template engine via a plugin. See
 
 ## Injecting Tags
 
-The `html.tags` option can be configured to insert any tags into the final generated HTML product.
+You can insert any tags into the HTML files generated by Rsbuild by configuring [html.tags](/config/html/tags).
 
-:::warning Usage Cases
-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 `htmlPlugin.tags`.
+In the HTML template, the `htmlPlugin.tags` variable gives you access to all the tags inserted into the HTML:
 
-```html
+```html title="index.html"
 <html>
   <head>
     <%= htmlPlugin.tags.headTags %>
@@ -233,86 +229,33 @@ All tags that need to be injected into HTML can be accessed in the template file
 </html>
 ```
 
-The purpose of `html.tags` is to adjust these template variables and thus modify the HTML, as defined in [API References](/config/html/tags).
-
-### Tag Object
+The purpose of the `html.tags` is to update these tag variables to modify the tags in the HTML. Here is a basic example:
 
 ```ts
 export default {
-  output: {
-    assetPrefix: 'https://example.com/'
-  },
   html: {
     tags: [
-      { tag: 'script', attrs: { src: 'a.js' } },
-      { tag: 'script', attrs: { src: 'b.js' }, append: false },
-      { tag: 'link', attrs: { href: 'style.css', rel: 'stylesheet' }, append: true }
-      { tag: 'link', attrs: { href: 'page.css', rel: 'stylesheet' }, publicPath: false }
-      { tag: 'script', attrs: { src: 'c.js' }, head: false },
-      { tag: 'meta', attrs: { name: 'referrer', content: 'origin' } },
+      { tag: 'script', attrs: { src: 'https://cdn.example.com/my-script.js' } },
     ],
   },
 };
 ```
 
-The final insertion position of the tag is determined by the `head` and `append` options, and two elements with the same configuration will be inserted into the same area and hold their relative positions to each other.
-
-The `publicPath` configuration is enabled by default for tags, the value of [output.assetPrefix](/config/output/asset-prefix) will be stitched to the `src` property of the `script` tag that represents the path.
-
-So the HTML output built with the above configuration will look like this.
+- The generated HTML file looks like this:
 
 ```html
 <html>
   <head>
-    <script src="https://example.com/b.js"></script>
-    <link href="https://example.com/style.css" rel="stylesheet" />
-    <link href="page.css" rel="stylesheet" />
+    <script src="https://cdn.example.com/my-script.js"></script>
     <!-- some other headTags... -->
-    <script src="https://example.com/a.js"></script>
-    <meta name="referrer" content="origin" />
   </head>
   <body>
     <!-- some other bodyTags... -->
-    <script src="https://example.com/c.js"></script>
   </body>
 </html>
 ```
 
-### Tags Handler
-
-`html.tags` also accepts a callback function, which is often used to modify the list of tags or to ensure their relative position while inserting them.
-
-```ts
-export default {
-  html: {
-    tags: [
-      (tags) => {
-        tags.splice(0, 1);
-      },
-      { tag: 'script', attrs: { src: 'a.js' }, head: false },
-      { tag: 'script', attrs: { src: 'b.js' }, append: false },
-      { tag: 'script', attrs: { src: 'c.js' } },
-      (tags) => [...tags, { tag: 'script', attrs: { src: 'd.js' } }],
-    ],
-  },
-};
-```
-
-And you will get:
-
-```html
-<html>
-  <head>
-    <!-- some other headTags... -->
-    <script src="https://example.com/c.js"></script>
-    <script src="https://example.com/d.js"></script>
-  </head>
-  <body>
-    <!-- some other bodyTags... -->
-    <script src="https://example.com/a.js"></script>
-  </body>
-</html>
-```
+> For more usage, please refer to: [html.tags](/config/html/tags).
 
 ## HTML Plugin
 

website/docs/en/guide/debug/rsdoctor.mdx

@@ -16,12 +16,27 @@ import { PackageManagerTabs } from '@theme';
 
 2. Add `RSDOCTOR=true` env variable before the CLI command:
 
-```bash
-# dev
-RSDOCTOR=true rsbuild dev
+```json title="package.json"
+{
+  "scripts": {
+    "dev:rsdoctor": "RSDOCTOR=true rsbuild dev",
+    "build:rsdoctor": "RSDOCTOR=true rsbuild build"
+  }
+}
+```
+
+Since the Windows system does not support the above usage, you can also use [cross-env](https://www.npmjs.com/package/cross-env) to set environment variables. This ensures compatibility across different systems:
 
-# build
-RSDOCTOR=true rsbuild build
+```json title="package.json"
+{
+  "scripts": {
+    "dev:rsdoctor": "cross-env RSDOCTOR=true rsbuild dev",
+    "build:rsdoctor": "cross-env RSDOCTOR=true rsbuild build"
+  },
+  "devDependencies": {
+    "cross-env": "^7.0.0"
+  }
+}
 ```
 
 After running the above commands, Rsbuild will automatically register the Rsdoctor plugin, and after the build is completed, it will open the build analysis page. For complete features, please refer to [Rsdoctor document](https://rsdoctor.dev/).

website/docs/en/guide/migration/rsbuild-0-x.mdx

@@ -334,7 +334,8 @@ export default {
 
 ```diff
 export default {
-  dev: {
+-  dev: {
++  server: {
 -   startUrl: true,
 +   open: true,
   }

website/docs/en/plugins/list/plugin-react.mdx

@@ -163,8 +163,25 @@ pluginReact({
 
 Set `REACT_PROFILER=true` when running build script:
 
-```bash
-REACT_PROFILER=true npx rsbuild build
+```json title="package.json"
+{
+  "scripts": {
+    "build:profiler": "REACT_PROFILER=true rsbuild build"
+  }
+}
+```
+
+Since the Windows system does not support the above usage, you can also use [cross-env](https://www.npmjs.com/package/cross-env) to set environment variables. This ensures compatibility across different systems:
+
+```json title="package.json"
+{
+  "scripts": {
+    "build:profiler": "cross-env REACT_PROFILER=true rsbuild build"
+  },
+  "devDependencies": {
+    "cross-env": "^7.0.0"
+  }
+}
 ```
 
 > See the [React docs](https://legacy.reactjs.org/docs/optimizing-performance.html#profiling-components-with-the-devtools-profiler) for details about profiling using the React DevTools.

website/docs/zh/config/dev/client.mdx

@@ -14,10 +14,7 @@ type Client = {
   port?: string | number;
   /** 指定 WebSocket 请求的 host */
   host?: string;
-  /**
-   * 当出现编译错误时，在浏览器中显示遮盖
-   * 该功能需要当前浏览器版本支持 [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
-   */
+  /** 当出现编译错误时，是否在浏览器中显示 error overlay */
   overlay?: boolean;
 };
 ```
@@ -82,3 +79,27 @@ export default {
 在热更新过程中，页面会发起 GET 请求来获取 hot-update 文件，包括 `*.hot-update.json` 和 `*.hot-update.js`。这些文件包含了热更新所需的信息，比如被更新的模块、模块的代码等。
 
 hot-update 文件属于静态资源，如果你需要配置 hot-update 文件的 URL，请使用 [dev.assetPrefix](/config/dev/asset-prefix) 选项。
+
+## Error overlay
+
+通过 `dev.client.overlay` 选项，可以选择是否启用 error overlay。
+
+默认情况下，当编译发生错误时，Rsbuild会在浏览器中显示 error overlay，并提供错误信息和错误堆栈：
+
+![error overlay](https://assets.rspack.dev/rsbuild/assets/rsbuild-error-overlay.png)
+
+如果需要禁用 error overlay，可以将其设置为 `false`：
+
+```ts title="rsbuild.config.ts"
+export default {
+  dev: {
+    client: {
+      overlay: false,
+    },
+  },
+};
+```
+
+:::tip
+Error overlay 功能需要当前浏览器版本支持 [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)。
+:::