docs: update preconnect and dns-prefetch configurations (#4149)

e2e/cases/performance/preconnect/rsbuild.config.ts

@@ -1,6 +1,7 @@
+import { defineConfig } from '@rsbuild/core';
 import { pluginReact } from '@rsbuild/plugin-react';
 
-export default {
+export default defineConfig({
   plugins: [pluginReact()],
   performance: {
     preconnect: [
@@ -13,4 +14,4 @@ export default {
       },
     ],
   },
-};
+});

packages/core/src/plugins/resourceHints.ts

@@ -1,13 +1,8 @@
 import { HtmlPreloadOrPrefetchPlugin } from '../rspack/preload/HtmlPreloadOrPrefetchPlugin';
-import type {
-  DnsPrefetchOption,
-  HtmlBasicTag,
-  PreconnectOption,
-  RsbuildPlugin,
-} from '../types';
+import type { HtmlBasicTag, PreconnectOption, RsbuildPlugin } from '../types';
 
 const generateLinks = (
-  options: PreconnectOption[] | DnsPrefetchOption[],
+  options: PreconnectOption[],
   rel: 'preconnect' | 'dns-prefetch',
 ): HtmlBasicTag[] =>
   options.map((option) => ({

packages/core/src/types/config.ts

@@ -490,16 +490,18 @@ export type PrintFileSizeOptions = {
 };
 
 export interface PreconnectOption {
+  /**
+   * The URL of the resource to preconnect to.
+   */
   href: string;
+  /**
+   * Whether to add `crossorigin` attribute to the `<link>` element.
+   */
   crossorigin?: boolean;
 }
 
 export type Preconnect = Array<string | PreconnectOption>;
 
-export interface DnsPrefetchOption {
-  href: string;
-}
-
 export type DnsPrefetch = string[];
 
 export type PreloadIncludeType =

scripts/dictionary.txt

@@ -81,6 +81,7 @@ pmmmwh
 postcssrc
 preact
 prebundle
+preconnecting
 preflights
 prefresh
 preprocessors

website/docs/en/config/performance/dns-prefetch.mdx

@@ -1,13 +1,11 @@
 # performance.dnsPrefetch
 
-- **Type:** `undefined | string[]`
+- **Type:** `string[] | undefined`
 - **Default:** `undefined`
 
-Used to configure the [dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) attribute.
+Injects [`<link rel="dns-prefetch">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) tags into the HTML file.
 
-After this property is set, the domain name can be resolved before the resource is requested, reducing request latency and improving loading performance.
-
-## Why DNS Prefetch
+## When to use
 
 When a browser requests a resource from a (third party) server, that cross-origin's domain name must be resolved to an IP address before the browser can issue the request. This process is known as DNS resolution. While DNS caching can help to reduce this latency, DNS resolution can add significant latency to requests.
 

website/docs/en/config/performance/preconnect.mdx

@@ -1,19 +1,32 @@
 # performance.preconnect
 
-- **Type:** `undefined | Array<string | PreconnectOption>`
+- **Type:**
 
 ```ts
-interface PreconnectOption {
-  href: string;
-  crossorigin?: boolean;
-}
+type Preconnect =
+  | Array<
+      | string
+      | {
+          href: string;
+          crossorigin?: boolean;
+        }
+    >
+  | undefined;
 ```
 
 - **Default:** `undefined`
 
-Specifies that the user agent should preemptively connect to the target resource's origin, refer to [preconnect](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect).
+Injects [`<link rel="preconnect">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect) tags into the HTML file.
 
-Configuring this property will establish a connection with the server. If the site is HTTPS, this process includes DNS resolution, TCP connection establishment, and TLS handshake. Combining Preconnect and DnsPrefetch can further reduce the delay of cross-domain requests.
+## When to use
+
+The `preconnect` keyword for the rel attribute of the `<link>` element is a hint to browsers that the user is likely to need resources from the target resource's origin, and therefore the browser can likely improve the user experience by preemptively initiating a connection to that origin.
+
+Preconnecting speeds up future loads from a given origin by preemptively performing part or all of the handshake (DNS+TCP for HTTP, and DNS+TCP+TLS for HTTPS origins).
+
+`<link rel="preconnect">` will provide a benefit to any future cross-origin HTTP request, navigation or subresource. It has no benefit on same-origin requests because the connection is already open.
+
+If a page needs to make connections to many third-party domains, preconnecting them all can be counterproductive. The `<link rel="preconnect">` hint is best used for only the most critical connections. For the others, just use [`<link rel="dns-prefetch">`](/config/performance/dns-prefetch) to save time on the first step — the DNS lookup.
 
 ## Example
 
@@ -30,3 +43,55 @@ The generated HTML tag is:
 ```html
 <link ref="preconnect" href="https://example.com" />
 ```
+
+## Options
+
+### href
+
+- **Type:** `string`
+- **Default:** `undefined`
+
+Specify the URL to preconnect to.
+
+```js
+export default {
+  performance: {
+    // Equivalent to `preconnect: ['https://example.com/'],`
+    preconnect: [
+      {
+        href: 'https://example.com/',
+      },
+    ],
+  },
+};
+```
+
+### crossorigin
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Specify whether to add the `crossorigin` attribute.
+
+```js
+export default {
+  performance: {
+    preconnect: [
+      {
+        href: 'https://example.com/',
+        crossorigin: true,
+      },
+    ],
+  },
+};
+```
+
+The generated HTML tag is:
+
+```html
+<link rel="preconnect" href="https://example.com" crossorigin />
+```
+
+:::tip
+Refer to this [link](https://webmasters.stackexchange.com/questions/89466/when-should-i-use-the-crossorigin-attribute-on-a-preconnect-link) to understand the use cases of the `crossorigin` attribute.
+:::

website/docs/zh/config/performance/dns-prefetch.mdx

@@ -1,11 +1,11 @@
 # performance.dnsPrefetch
 
-- **类型：** `undefined | string[]`
+- **Type:** `string[] | undefined`
 - **默认值：** `undefined`
 
-用于配置 [dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) 属性。
+注入 [`<link rel="dns-prefetch">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) 标签到 HTML 文件中。
 
-## 为什么需要 DNS prefetch
+## 何时使用
 
 当浏览器从（第三方）服务器请求资源时，必须先将该跨源域名解析为 IP 地址，然后浏览器才能发出请求。此过程称为 DNS 解析。虽然 DNS 缓存可以帮助减少此延迟，但 DNS 解析可能会给请求增加明显的延迟。
 

website/docs/zh/config/performance/preconnect.mdx

@@ -1,19 +1,30 @@
 # performance.preconnect
 
-- **类型：** `undefined | Array<string | PreconnectOption>`
+- **类型：**
 
 ```ts
-interface PreconnectOption {
-  href: string;
-  crossorigin?: boolean;
-}
+type Preconnect =
+  | Array<
+      | string
+      | {
+          href: string;
+          crossorigin?: boolean;
+        }
+    >
+  | undefined;
 ```
 
 - **默认值：** `undefined`
 
-为哪些资源配置 [preconnect](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect) 属性。
+注入 [`<link rel="preconnect">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/preconnect) 标签到 HTML 文件中。
 
-配置该属性会预先建立与服务器的连接，如果站点是 HTTPS 的，则此过程包括 DNS 解析，建立 TCP 连接以及执行 TLS 握手。将 Preconnect 和 DnsPrefetch 结合使用可进一步减少跨域请求的延迟。
+## 何时使用
+
+`<link>` 元素的 rel 属性的 `preconnect` 关键字是对浏览器的一种提示，即用户很可能需要来自目标来源的资源，因此浏览器很可能通过抢先启动与该源的连接来改善用户体验。通过抢先执行部分或全部握手（HTTP 为 DNS+TCP，HTTPS 为 DNS+TCP+TLS），预连接可加快未来从给定源加载的速度。
+
+`<link rel="preconnect">` 将为未来的跨源 HTTP 请求、导航或子资源带来好处。它对同源请求没有好处，因为连接已经打开。
+
+如果一个页面需要与许多第三方域建立连接，将它们全部预连接可能会适得其反。`<link rel="preconnect">` 提示最好只用于最关键的连接。对于其他连接，只需使用 [`<link rel="dns-prefetch">`](/config/performance/dns-prefetch)，以节省第一步 DNS 查询的时间。
 
 ## 示例
 
@@ -30,3 +41,55 @@ export default {
 ```html
 <link ref="preconnect" href="https://example.com" />
 ```
+
+## 选项
+
+### href
+
+- **类型：** `string`
+- **默认值：** `undefined`
+
+指定要预连接的 URL。
+
+```js
+export default {
+  performance: {
+    // 等价于 `preconnect: ['https://example.com/'],`
+    preconnect: [
+      {
+        href: 'https://example.com/',
+      },
+    ],
+  },
+};
+```
+
+### crossorigin
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+指定是否添加 `crossorigin` 属性。
+
+```js
+export default {
+  performance: {
+    preconnect: [
+      {
+        href: 'https://example.com/',
+        crossorigin: true,
+      },
+    ],
+  },
+};
+```
+
+生成的 HTML 标签如下：
+
+```html
+<link rel="preconnect" href="https://example.com" crossorigin />
+```
+
+:::tip
+参考该 [链接](https://webmasters.stackexchange.com/questions/89466/when-should-i-use-the-crossorigin-attribute-on-a-preconnect-link) 了解 `crossorigin` 属性的使用场景。
+:::