docs: add some examples for prefetch / preload (#2302)

chenjiahan · web-flow · commit b3e94893370f · 2024-05-10T10:25:43.000+08:00
diff --git a/website/docs/en/config/performance/prefetch.mdx b/website/docs/en/config/performance/prefetch.mdx
@@ -16,33 +16,80 @@ interface PrefetchOption {
 
 - **Default:** `undefined`
 
-Configure the [`<link rel="prefetch">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/prefetch) tag for the static assets generated by Rsbuild.
+Inject the [`<link rel="prefetch">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/prefetch) tags for the static assets generated by Rsbuild.
 
 ## What is prefetch
 
 The prefetch keyword for the rel attribute of the `<link>` element provides a hint to browsers that the user is likely to need the target resource for future navigation, and therefore the browser can likely improve the user experience by preemptively fetching and caching the resource.
 
-## Boolean Type
+## Enable prefetch
 
-When setting `performance.prefetch` to `true`, Rsbuild will prefetch resources according to the following configuration:
+When `performance.prefetch` is set to `true`, Rsbuild will use the following default options to prefetch resources. This means prefetching all asynchronous resources on the current page, including asynchronous JS and its associated CSS, image, font, and other resources.
 
 ```js
-{
+const defaultOptions = {
   type: 'async-chunks',
-}
+};
+```
+
+For example, if you dynamically import other modules in the entry file:
+
+```js title="index.js"
+import('./foo');
+import('./bar');
+```
+
+The tags injected in HTML are as follows:
+
+```html
+<html>
+  <head>
+    <title>Rsbuild App</title>
+    <script defer src="/static/js/index.js"></script>
+    <!-- Generated prefetch tags -->
+    <link href="/static/js/async/src_bar_js.js" rel="prefetch" />
+    <link href="/static/js/async/src_foo_js.js" rel="prefetch" />
+  </head>
+</html>
+```
+
+## Inject Manually
+
+The `performance.prefetch` can only inject the prefetch tags for static resources generated by Rsbuild. If you need to prefetch other resources, you can manually add tags through [html.tags](/config/html/tags) :
+
+```js title="rsbuild.config.ts"
+export default {
+  html: {
+    tags: [
+      {
+        tag: 'link',
+        attrs: {
+          rel: 'prefetch',
+          href: 'https://example.com/some-script.js',
+        },
+      },
+    ],
+  },
+};
+```
+
+The injected HTML tag is as follows:
+
+```html
+<link rel="prefetch" href="https://example.com/some-script.js" />
 ```
 
-## Object Type
+## Options
 
-When the value of `performance.prefetch` is `object` type, the Rsbuild will enable the prefetch capability for the specified resource according to the current configuration.
+When the value of `performance.prefetch` is `object` type, the Rsbuild will enable the prefetch capability for the specified resource according to the current options.
 
 ### prefetch.type
 
 The `type` field controls which resources will be pre-fetched, and supports secondary filtering of specified resources through `include` and `exclude`.
 
 Currently supported resource types are as follows:
 
-- `async-chunks`: prefetch all asynchronous resources (on the current page), including asynchronous js and its associated css, image, font and other resources.
+- `async-chunks`: prefetch all asynchronous resources (on the current page), including asynchronous JS and its associated CSS, image, font and other resources.
 - `initial`: prefetch all non-async resources (on the current page). It should be noted that if the current script has been added to the html template, no additional pre-fetching will be performed.
 - `all-chunks`: prefetch all resources (on the current page), including all asynchronous and non-asynchronous resources.
 - `all-assets`: prefetch all resources, and resources of other pages will be included in the MPA scenario.
diff --git a/website/docs/en/config/performance/preload.mdx b/website/docs/en/config/performance/preload.mdx
@@ -16,35 +16,83 @@ interface PreloadOption {
 
 - **Default:** `undefined`
 
-Configure the [`<link rel="preload">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload) tag for the static assets generated by Rsbuild.
+Inject the [`<link rel="preload">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload) tags for the static assets generated by Rsbuild.
 
 ## What is preload
 
 The preload value of the `<link>` element's rel attribute lets you declare fetch requests in the HTML's `<head>`, specifying resources that your page will need very soon, which you want to start loading early in the page lifecycle, before browsers' main rendering machinery kicks in.
 
 This ensures they are available earlier and are less likely to block the page's render, improving performance. Even though the name contains the term load, it doesn't load and execute the script but only schedules it to be downloaded and cached with a higher priority.
 
-## Boolean Type
+## Enable preload
 
-When setting `performance.preload` to `true`, Rsbuild will preload resources according to the following configuration:
+When `performance.preload` is set to `true`, Rsbuild will use the following default options to preload resources. This means preloading all asynchronous resources on the current page, including asynchronous JS and its associated CSS, image, font, and other resources.
 
 ```js
-{
+const defaultOptions = {
   type: 'async-chunks',
-}
+};
+```
+
+For example, if you dynamically import other modules in the entry file:
+
+```js title="index.js"
+import('./foo');
+import('./bar');
+```
+
+The tags injected in HTML are as follows:
+
+```html
+<html>
+  <head>
+    <title>Rsbuild App</title>
+    <script defer src="/static/js/index.js"></script>
+    <!-- Generated preload tags -->
+    <link href="/static/js/async/src_bar_js.js" rel="preload" as="script" />
+    <link href="/static/js/async/src_foo_js.js" rel="preload" as="script" />
+  </head>
+</html>
+```
+
+## Inject Manually
+
+The `performance.preload` can only inject the preload tags for static resources generated by Rsbuild. If you need to preload other resources, you can manually add tags through [html.tags](/config/html/tags) :
+
+```js title="rsbuild.config.ts"
+export default {
+  html: {
+    tags: [
+      {
+        tag: 'link',
+        attrs: {
+          rel: 'preload',
+          as: 'script',
+          href: 'https://example.com/some-script.js',
+        },
+      },
+    ],
+  },
+};
+```
+
+The injected HTML tag is as follows:
+
+```html
+<link rel="preload" as="script" href="https://example.com/some-script.js" />
 ```
 
-## Object Type
+## Options
 
-When the value of `performance.preload` is `object` type, the Rsbuild will enable the preload capability for the specified resource according to the current configuration.
+When the value of `performance.preload` is `object` type, the Rsbuild will enable the preload capability for the specified resource according to the current options.
 
 ### preload.type
 
 The `type` field controls which resources will be pre-fetched, and supports secondary filtering of specified resources through `include` and `exclude`.
 
 Currently supported resource types are as follows:
 
-- `async-chunks`: preload all asynchronous resources (on the current page), including asynchronous js and its associated css, image, font and other resources.
+- `async-chunks`: preload all asynchronous resources (on the current page), including asynchronous JS and its associated CSS, image, font and other resources.
 - `initial`: preload all non-async resources (on the current page). It should be noted that if the current script has been added to the html template, no additional pre-fetching will be performed.
 - `all-chunks`: preload all resources (on the current page), including all asynchronous and non-asynchronous resources.
 - `all-assets`: preload all resources, and resources of other pages will be included in the MPA scenario.
diff --git a/website/docs/zh/config/performance/prefetch.mdx b/website/docs/zh/config/performance/prefetch.mdx
@@ -16,40 +16,87 @@ interface PrefetchOption {
 
 - **默认值：** `undefined`
 
-为 Rsbuild 构建生成的静态资源配置 [`<link rel="prefetch">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/prefetch) 标签。
+为 Rsbuild 构建生成的静态资源注入 [`<link rel="prefetch">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/prefetch) 标签。
 
 ## 什么是 prefetch
 
 `<link>` 元素的 rel 属性中的 prefetch 关键字是为了提示浏览器，用户未来的浏览有可能需要加载目标资源，所以浏览器有可能通过事先获取和缓存对应资源，优化用户体验。
 
-## Boolean 类型
+## 启用 prefetch
 
-当设置 `performance.prefetch` 为 `true`，Rsbuild 将根据如下配置对资源进行预获取:
+当设置 `performance.prefetch` 为 `true` 时，Rsbuild 将使用以下默认选项，对资源进行预获取，这表示 prefetch 当前页面的所有异步资源，包含异步 JS 及其关联的 CSS、image、font 等资源。
 
 ```js
-{
+const defaultOptions = {
   type: 'async-chunks',
-}
+};
+```
+
+比如，在入口文件中动态引入了其他模块：
+
+```js title="index.js"
+import('./foo');
+import('./bar');
+```
+
+在 HTML 中注入的标签为：
+
+```html
+<html>
+  <head>
+    <title>Rsbuild App</title>
+    <script defer src="/static/js/index.js"></script>
+    <!-- 生成的 prefetch 标签 -->
+    <link href="/static/js/async/src_bar_js.js" rel="prefetch" />
+    <link href="/static/js/async/src_foo_js.js" rel="prefetch" />
+  </head>
+</html>
+```
+
+## 手动注入
+
+`performance.prefetch` 只能为 Rsbuild 构建生成的静态资源注入 prefetch 标签，如果你需要 prefetch 其他资源，可以通过 [html.tags](/config/html/tags) 手动添加标签：
+
+```js title="rsbuild.config.ts"
+export default {
+  html: {
+    tags: [
+      {
+        tag: 'link',
+        attrs: {
+          rel: 'prefetch',
+          href: 'https://example.com/some-script.js',
+        },
+      },
+    ],
+  },
+};
+```
+
+注入的 HTML 标签如下：
+
+```html
+<link rel="prefetch" href="https://example.com/some-script.js" />
 ```
 
-## Object 类型
+## 选项
 
-当 `performance.prefetch` 的值为 object 类型时，Rsbuild 会根据当前配置对指定资源开启 prefetch 能力。
+当 `performance.prefetch` 的值为 object 类型时，Rsbuild 会根据当前选项对指定资源开启 prefetch 能力。
 
 ### prefetch.type
 
 `type` 字段控制了哪些资源会被预获取，同时支持通过 `include` 和 `exclude` 对指定资源进行二次过滤。
 
 目前支持的资源类型如下：
 
-- `async-chunks`: 预获取所有异步资源（当前页面），包含异步 JS 及其关联的 CSS、image、font 等资源。
-- `initial`: 预获取所有非异步资源（当前页面）。需要注意的是，如果当前脚本已经被添加到 HTML 模版中，则不会进行额外的预获取。
-- `all-chunks`: 预获取所有资源（当前页面），包含所有异步和非异步资源。
-- `all-assets`: 预获取所有资源，MPA 场景下会包含其他页面的资源。
+- `async-chunks`: prefetch 所有异步资源（当前页面），包含异步 JS 及其关联的 CSS、image、font 等资源。
+- `initial`: prefetch 所有非异步资源（当前页面）。需要注意的是，如果当前脚本已经被添加到 HTML 模版中，则不会进行额外的预获取。
+- `all-chunks`: prefetch 所有资源（当前页面），包含所有异步和非异步资源。
+- `all-assets`: prefetch 所有资源，MPA 场景下会包含其他页面的资源。
 
 ### 示例
 
-当你希望对当前页面中所有 png 格式的图片资源进行预获取时，可以配置如下：
+当你希望对当前页面中所有 png 格式的图片资源进行 prefetch 时，可以配置如下：
 
 ```js
 export default {
diff --git a/website/docs/zh/config/performance/preload.mdx b/website/docs/zh/config/performance/preload.mdx
@@ -16,42 +16,90 @@ interface PreloadOption {
 
 - **默认值：** `undefined`
 
-为 Rsbuild 构建生成的静态资源配置 [`<link rel="preload">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/preload) 标签。
+为 Rsbuild 构建生成的静态资源注入 [`<link rel="preload">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/preload) 标签。
 
 ## 什么是 preload
 
 `<link>` 元素的 rel 属性的 preload 值允许你在 HTML 的 `<head>` 中声明获取请求，指定页面很快就需要的资源，这些资源是你希望在页面生命周期的早期就开始加载的，早于浏览器的主要渲染机制启动。
 
 这可以确保它们更早可用，并且不太可能阻塞页面的渲染，从而提高性能。尽管名称中包含 "load" 一词，但它并不加载和执行脚本，而只是安排脚本以更高的优先级进行下载和缓存。
 
-## Boolean 类型
+## 启用 preload
 
-当设置 `performance.preload` 为 `true`，Rsbuild 将根据如下配置对资源进行预加载:
+当设置 `performance.preload` 为 `true` 时，Rsbuild 将使用以下默认选项，对资源进行预获取，这表示 preload 当前页面的所有异步资源，包含异步 JS 及其关联的 CSS、image、font 等资源。
 
 ```js
-{
+const defaultOptions = {
   type: 'async-chunks',
-}
+};
+```
+
+比如，在入口文件中动态引入了其他模块：
+
+```js title="index.js"
+import('./foo');
+import('./bar');
+```
+
+在 HTML 中注入的标签为：
+
+```html
+<html>
+  <head>
+    <title>Rsbuild App</title>
+    <script defer src="/static/js/index.js"></script>
+    <!-- 生成的 preload 标签 -->
+    <link href="/static/js/async/src_bar_js.js" rel="preload" as="script" />
+    <link href="/static/js/async/src_foo_js.js" rel="preload" as="script" />
+  </head>
+</html>
+```
+
+## 手动注入
+
+`performance.preload` 只能为 Rsbuild 构建生成的静态资源注入 preload 标签，如果你需要 preload 其他资源，可以通过 [html.tags](/config/html/tags) 手动添加标签：
+
+```js title="rsbuild.config.ts"
+export default {
+  html: {
+    tags: [
+      {
+        tag: 'link',
+        attrs: {
+          rel: 'preload',
+          as: 'script',
+          href: 'https://example.com/some-script.js',
+        },
+      },
+    ],
+  },
+};
+```
+
+注入的 HTML 标签如下：
+
+```html
+<link rel="preload" as="script" href="https://example.com/some-script.js" />
 ```
 
-## Object 类型
+## 选项
 
-当 `performance.preload` 的值为 object 类型时，Rsbuild 会根据当前配置对指定资源开启 preload 能力。
+当 `performance.preload` 的值为 object 类型时，Rsbuild 会根据当前选项对指定资源开启 preload 能力。
 
 ### preload.type
 
 `type` 字段控制了哪些资源会被预加载，同时支持通过 `include` 和 `exclude` 对指定资源进行二次过滤。
 
 目前支持的资源类型如下：
 
-- `async-chunks`: 预加载所有异步资源（当前页面），包含异步 JS 及其关联的 CSS、image、font 等资源。
-- `initial`: 预加载所有非异步资源（当前页面）。需要注意的是，如果当前脚本已经被添加到 HTML 模版中，则不会进行额外的预加载。
-- `all-chunks`: 预加载所有资源（当前页面），包含所有异步和非异步资源。
-- `all-assets`: 预加载所有资源，MPA 场景下会包含其他页面的资源。
+- `async-chunks`: preload 所有异步资源（当前页面），包含异步 JS 及其关联的 CSS、image、font 等资源。
+- `initial`: preload 所有非异步资源（当前页面）。需要注意的是，如果当前脚本已经被添加到 HTML 模版中，则不会进行额外的预加载。
+- `all-chunks`: preload 所有资源（当前页面），包含所有异步和非异步资源。
+- `all-assets`: preload 所有资源，MPA 场景下会包含其他页面的资源。
 
 ### 示例
 
-当你希望对当前页面中所有 png 格式的图片资源进行预加载时，可以配置如下：
+当你希望对当前页面中所有 png 格式的图片资源进行 preload 时，可以配置如下：
 
 ```js
 export default {
