@rsbuild/plugin-assets-retry 1.2.3 → 1.4.0

package/README.md

@@ -37,7 +37,7 @@ bun add @rsbuild/plugin-assets-retry -D
 You can register the plugin in the `rsbuild.config.ts` file:
 
 ```ts
-import { pluginAssetsRetry } from "@rsbuild/plugin-assets-retry";
+import { pluginAssetsRetry } from '@rsbuild/plugin-assets-retry';
 
 export default {
   plugins: [pluginAssetsRetry()],
@@ -59,33 +59,43 @@ type AssetsRetryHookContext = {
   isAsyncChunk: boolean;
 };
 
-type AssetsRetryOptions = {
+type RuntimeRetryOptions = {
   type?: string[];
   domain?: string[];
   max?: number;
-  test?: string | ((url: string) => boolean);
-  crossOrigin?: boolean | "anonymous" | "use-credentials";
-  inlineScript?: boolean;
+  test?: string | RegExp | ((url: string) => boolean);
+  crossOrigin?: boolean | 'anonymous' | 'use-credentials';
   delay?: number | ((context: AssetsRetryHookContext) => number);
   onRetry?: (context: AssetsRetryHookContext) => void;
   onSuccess?: (context: AssetsRetryHookContext) => void;
   onFail?: (context: AssetsRetryHookContext) => void;
 };
+
+type AssetsRetryOptions =
+  | ({
+      inlineScript?: boolean;
+      minify?: boolean;
+    } & RuntimeRetryOptions)
+  | {
+      inlineScript?: boolean;
+      minify?: boolean;
+      rules: RuntimeRetryOptions[];
+    };
 ```
 
 - **Default:**
 
 ```ts
 const defaultAssetsRetryOptions = {
-  type: ["script", "link", "img"],
-  domain: [],
   max: 3,
-  test: "",
+  type: ['script', 'link', 'img'],
+  domain: [],
   crossOrigin: false,
+  test: '',
   delay: 0,
-  onRetry: () => {},
-  onSuccess: () => {},
-  onFail: () => {},
+  addQuery: false,
+  inlineScript: true,
+  minify: rsbuildConfig.mode === 'production',
 };
 ```
 
@@ -103,11 +113,11 @@ For example:
 defineConfig({
   plugins: [
     pluginAssetsRetry({
-      domain: ["cdn1.com", "cdn2.com", "cdn3.com"],
-    })
+      domain: ['cdn1.com', 'cdn2.com', 'cdn3.com'],
+    }),
   ],
   output: {
-    assetPrefix: "https://cdn1.com", // or "//cdn1.com"
+    assetPrefix: 'https://cdn1.com', // or "//cdn1.com"
   },
 });
 ```
@@ -127,7 +137,7 @@ For example, only script tags and link tags are processed:
 
 ```js
 pluginAssetsRetry({
-  type: ["script", "link"],
+  type: ['script', 'link'],
 });
 ```
 
@@ -182,7 +192,7 @@ The callback function when the asset is being retried. For example:
 pluginAssetsRetry({
   onRetry: ({ times, domain, url, tagName, isAsyncChunk }) => {
     console.log(
-      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`
+      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`,
     );
   },
 });
@@ -198,7 +208,7 @@ The callback function when the asset is successfully retried. For example:
 pluginAssetsRetry({
   onSuccess: ({ times, domain, url, tagName, isAsyncChunk }) => {
     console.log(
-      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`
+      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`,
     );
   },
 });
@@ -214,7 +224,7 @@ The callback function when the asset is failed to be retried. For example:
 pluginAssetsRetry({
   onFail: ({ times, domain, url, tagName, isAsyncChunk }) => {
     console.log(
-      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`
+      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`,
     );
   },
 });
@@ -242,7 +252,7 @@ When set to `true`, `retry=${times}` will be added to the query when requesting,
 
 When you want to customize query, you can pass a function, for example:
 
-- **Example:** All assets requested do not contain query:
+- **Example 1:** All assets requested do not contain query:
 
 ```js
 pluginAssetsRetry({
@@ -254,7 +264,7 @@ pluginAssetsRetry({
 });
 ```
 
-- **Example:** If there is a query in some of the requested assets, you can read it with `originalQuery`:
+- **Example 2:** If there is a query in some of the requested assets, you can read it with `originalQuery`:
 
 ```js
 pluginAssetsRetry({
@@ -321,7 +331,81 @@ Or pass a function that receives `AssetsRetryHookContext` and returns the delay
 ```js
 // Calculate delay based on retry attempts
 pluginAssetsRetry({
-  delay: (ctx) => (ctx.times + 1) * 1000,
+  delay: ctx => (ctx.times + 1) * 1000,
+});
+```
+
+### rules
+
+- **Type:** `RuntimeRetryOptions[]`
+- **Default:** `undefined`
+
+Configure multiple retry rules with different options. Each rule will be evaluated in order, and the first matching rule will be used for retry logic. This is useful when you have different retry requirements for different types of assets or domains.
+
+When using `rules`, the plugin will:
+
+1. Check each rule in order by `test` `domain` `type`
+
+2. If the rule is matched, the rule's configuration will be used to retry
+
+3. If no rule is matched, the resource will not be retried
+
+Each rule supports all the same options as the top-level configuration, including `type`, `domain`, `max`, `test`, `crossOrigin`, `delay`, `onRetry`, `onSuccess`, and `onFail`.
+
+- **Example 1:** Different retry strategies for different CDNs:
+
+```js
+pluginAssetsRetry({
+  rules: [
+    {
+      // Rule for primary CDN
+      test: /cdn1\.example\.com/,
+      domain: ['cdn1.example.com', 'cdn1-backup.example.com'],
+      max: 3,
+      delay: 1000,
+    },
+    {
+      // Rule for secondary CDN with more retries
+      test: /cdn2\.example\.com/,
+      domain: ['cdn2.example.com', 'cdn2-backup.example.com'],
+      max: 5,
+      delay: 500,
+    },
+    {
+      // Default rule for other assets
+      domain: ['default.example.com', 'default-backup.example.com'],
+      max: 2,
+    },
+  ],
+});
+```
+
+- **Example 2:** Different retry strategies for different asset types:
+
+```js
+pluginAssetsRetry({
+  rules: [
+    {
+      // Critical JavaScript files get more retries
+      type: ['script'],
+      // Or test: /\.js$/,
+      max: 5,
+      delay: 1000,
+      onFail: ({ url }) => console.error(`Critical JS failed: ${url}`),
+    },
+    {
+      // CSS files get fewer retries
+      test: /\.css$/,
+      max: 2,
+      delay: 500,
+    },
+    {
+      // Images get minimal retries
+      test: /\.(png|jpg|gif|svg)$/,
+      max: 1,
+      delay: 0,
+    },
+  ],
 });
 ```
 
@@ -336,12 +420,12 @@ When you use Assets Retry plugin, the Rsbuild injects some runtime code into the
 Here's an example of incorrect usage:
 
 ```js
-import { someMethod } from "utils";
+import { someMethod } from 'utils';
 
 pluginAssetsRetry({
   onRetry() {
     // Incorrect usage, includes sensitive information
-    const privateToken = "a-private-token";
+    const privateToken = 'a-private-token';
 
     // Incorrect usage, uses an external method
     someMethod(privateToken);
@@ -353,6 +437,10 @@ pluginAssetsRetry({
 
 Assets Retry plugin may not work in the following scenarios:
 
+### Sync script tag loaded resources
+
+`<script src="..."></script>` tags load resources synchronously, and retrying them does not guarantee the order of resource loading. Therefore, the Assets Retry plugin will not retry resources loaded by synchronous script tags. It will only retry resources loaded by async/defer script tags.
+
 ### Module Federation
 
 For remote modules loaded by Module Federation, you can use the [@module-federation/retry-plugin](https://www.npmjs.com/package/@module-federation/retry-plugin) from Module Federation 2.0 to implement static asset retries.
@@ -385,6 +473,32 @@ If you want Assets Retry plugin to work on resources in custom templates, you ca
 </html>
 ```
 
+#### Identifying retry scripts in HTML templates
+
+The Assets Retry plugin adds a unique `data-rsbuild-assets-retry` attribute to retry scripts, allowing you to easily identify them in custom HTML templates.
+
+You can import the attribute constant:
+
+```js
+import { ASSETS_RETRY_DATA_ATTRIBUTE } from '@rsbuild/plugin-assets-retry';
+```
+
+The attribute values are:
+- `"inline"` for inline scripts (when `inlineScript: true`)
+- `"external"` for external scripts (when `inlineScript: false`)
+
+Example usage in HTML templates:
+
+```html
+<!-- Filter retry scripts -->
+<%= htmlWebpackPlugin.tags.headTags.filter(tag => tag.attributes['data-rsbuild-assets-retry'] === 'inline') %>
+
+<!-- Filter non-retry scripts -->
+<%= htmlWebpackPlugin.tags.headTags.filter(tag => !tag.attributes['data-rsbuild-assets-retry']) %>
+```
+
+This allows you to place retry scripts at the top of your HTML head for optimal loading order.
+
 ## License
 
 [MIT](./LICENSE).

package/README.zh-CN.md

@@ -35,7 +35,7 @@ bun add @rsbuild/plugin-assets-retry -D
 你可以在 `rsbuild.config.ts` 文件中注册插件：
 
 ```ts
-import { pluginAssetsRetry } from "@rsbuild/plugin-assets-retry";
+import { pluginAssetsRetry } from '@rsbuild/plugin-assets-retry';
 
 export default {
   plugins: [pluginAssetsRetry()],
@@ -57,33 +57,43 @@ type AssetsRetryHookContext = {
   isAsyncChunk: boolean;
 };
 
-type AssetsRetryOptions = {
+type RuntimeRetryOptions = {
   type?: string[];
   domain?: string[];
   max?: number;
   test?: string | ((url: string) => boolean);
-  crossOrigin?: boolean | "anonymous" | "use-credentials";
-  inlineScript?: boolean;
+  crossOrigin?: boolean | 'anonymous' | 'use-credentials';
   delay?: number | ((context: AssetsRetryHookContext) => number);
   onRetry?: (context: AssetsRetryHookContext) => void;
   onSuccess?: (context: AssetsRetryHookContext) => void;
   onFail?: (context: AssetsRetryHookContext) => void;
 };
+
+type AssetsRetryOptions =
+  | ({
+      inlineScript?: boolean;
+      minify?: boolean;
+    } & RuntimeRetryOptions)
+  | {
+      inlineScript?: boolean;
+      minify?: boolean;
+      rules: RuntimeRetryOptions[];
+    };
 ```
 
 - **默认值：**
 
 ```ts
-const defaultOptions = {
-  type: ["script", "link", "img"],
-  domain: [],
+const defaultAssetsRetryOptions = {
   max: 3,
-  test: "",
+  type: ['script', 'link', 'img'],
+  domain: [],
   crossOrigin: false,
+  test: '',
   delay: 0,
-  onRetry: () => {},
-  onSuccess: () => {},
-  onFail: () => {},
+  addQuery: false,
+  inlineScript: true,
+  minify: rsbuildConfig.mode === 'production',
 };
 ```
 
@@ -101,11 +111,11 @@ const defaultOptions = {
 defineConfig({
   plugins: [
     pluginAssetsRetry({
-      domain: ["cdn1.com", "cdn2.com", "cdn3.com"],
-    })
+      domain: ['cdn1.com', 'cdn2.com', 'cdn3.com'],
+    }),
   ],
   output: {
-    assetPrefix: "https://cdn1.com", // 或者 "//cdn1.com"
+    assetPrefix: 'https://cdn1.com', // 或者 "//cdn1.com"
   },
 });
 ```
@@ -125,7 +135,7 @@ defineConfig({
 
 ```js
 pluginAssetsRetry({
-  type: ["script", "link"],
+  type: ['script', 'link'],
 });
 ```
 
@@ -180,7 +190,7 @@ pluginAssetsRetry({
 pluginAssetsRetry({
   onRetry: ({ times, domain, url, tagName, isAsyncChunk }) => {
     console.log(
-      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`
+      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`,
     );
   },
 });
@@ -196,7 +206,7 @@ pluginAssetsRetry({
 pluginAssetsRetry({
   onSuccess: ({ times, domain, url, tagName, isAsyncChunk }) => {
     console.log(
-      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`
+      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`,
     );
   },
 });
@@ -212,7 +222,7 @@ pluginAssetsRetry({
 pluginAssetsRetry({
   onFail: ({ times, domain, url, tagName, isAsyncChunk }) => {
     console.log(
-      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`
+      `Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}, isAsyncChunk: ${isAsyncChunk}`,
     );
   },
 });
@@ -240,7 +250,7 @@ type AddQuery =
 
 当你想要自定义 query 时，可以传入一个函数，比如：
 
-- **示例：** 请求的所有资源都不含 query：
+- **示例 1：** 请求的所有资源都不含 query：
 
 ```js
 pluginAssetsRetry({
@@ -252,7 +262,7 @@ pluginAssetsRetry({
 });
 ```
 
-- **示例：** 当请求的某些资源中含有 query 时，可以使用 `originalQuery` 读取：
+- **示例 2：** 当请求的某些资源中含有 query 时，可以使用 `originalQuery` 读取：
 
 ```js
 pluginAssetsRetry({
@@ -319,7 +329,81 @@ pluginAssetsRetry({
 ```js
 // 通过次数来计算延迟时间
 pluginAssetsRetry({
-  delay: (ctx) => (ctx.times + 1) * 1000,
+  delay: ctx => (ctx.times + 1) * 1000,
+});
+```
+
+### rules
+
+- **类型：** `RuntimeRetryOptions[]`
+- **默认值：** `undefined`
+
+配置多个重试规则，每个规则可以有不同的选项。规则会按顺序进行评估，第一个匹配的规则将用于重试逻辑。这在你对不同类型的资源或域名有不同的重试需求时非常有用。
+
+使用 `rules` 时，插件会：
+
+1. 按顺序通过 `test` `domain` `type` 检查每个规则
+
+2. 如果匹配到规则，会使用规则的配置进行重试
+
+3. 如果没有匹配到规则，则不会重试该资源
+
+每个规则支持与顶层配置相同的所有选项，包括 `type`、`domain`、`test`、`max`、`crossOrigin`、`delay`、`onRetry`、`onSuccess` 和 `onFail`。
+
+- **示例 1：** 不同 CDN 的不同重试策略：
+
+```js
+pluginAssetsRetry({
+  rules: [
+    {
+      // 主 CDN 的规则
+      test: /cdn1\.example\.com/,
+      domain: ['cdn1.example.com', 'cdn1-backup.example.com'],
+      max: 3,
+      delay: 1000,
+    },
+    {
+      // 次要 CDN 的规则，更多重试次数
+      test: /cdn2\.example\.com/,
+      domain: ['cdn2.example.com', 'cdn2-backup.example.com'],
+      max: 5,
+      delay: 500,
+    },
+    {
+      // 其他资源的默认规则
+      domain: ['default.example.com', 'default-backup.example.com'],
+      max: 2,
+    },
+  ],
+});
+```
+
+- **示例 2：** 不同资源类型的不同重试策略：
+
+```js
+pluginAssetsRetry({
+  rules: [
+    {
+      // 关键 JavaScript 文件获得更多重试次数
+      test: /\.js$/,
+      // 或者 type: ['script'],
+      max: 5,
+      delay: 1000,
+      onFail: ({ url }) => console.error(`关键 JS 失败: ${url}`),
+    },
+    {
+      // CSS 文件获得较少的重试次数
+      test: /\.css$/,
+      max: 2,
+      delay: 500,
+    },
+    {
+      // 图片获得最少的重试次数
+      test: /\.(png|jpg|gif|svg)$/,
+      max: 1,
+      delay: 0,
+    },
+  ],
 });
 ```
 
@@ -334,12 +418,12 @@ pluginAssetsRetry({
 以下是一个错误示例：
 
 ```js
-import { someMethod } from "utils";
+import { someMethod } from 'utils';
 
 pluginAssetsRetry({
   onRetry() {
     // 错误用法，包含了敏感信息
-    const privateToken = "a-private-token";
+    const privateToken = 'a-private-token';
 
     // 错误用法，使用了外部的方法
     someMethod(privateToken);
@@ -351,6 +435,10 @@ pluginAssetsRetry({
 
 以下场景 Assets Retry 插件可能无法生效：
 
+### 同步 script 标签加载的资源
+
+`<script src="..."></script>` 标签加载的资源是同步加载的，如果进行重试无法保证资源加载的顺序，因此 Assets Retry 插件不会对同步加载的 script 标签进行重试。只会对 async/defer 的 script 标签进行重试。
+
 ### 模块联邦
 
 对于模块联邦加载的远程模块，你可以使用模块联邦 2.0 的 [@module-federation/retry-plugin](https://www.npmjs.com/package/@module-federation/retry-plugin) 来实现静态资源重试。
@@ -383,6 +471,32 @@ Assets Retry 插件通过监听页面 error 事件来获悉当前资源是否加
 </html>
 ```
 
+#### 在 HTML 模板中识别重试脚本
+
+Assets Retry 插件为重试脚本添加了唯一的 `data-rsbuild-assets-retry` 属性，使您可以在自定义 HTML 模板中轻松识别它们。
+
+您可以导入属性常量：
+
+```js
+import { ASSETS_RETRY_DATA_ATTRIBUTE } from '@rsbuild/plugin-assets-retry';
+```
+
+属性值包括：
+- `"inline"` 用于内联脚本（当 `inlineScript: true` 时）
+- `"external"` 用于外部脚本（当 `inlineScript: false` 时）
+
+在 HTML 模板中的使用示例：
+
+```html
+<!-- 筛选重试脚本 -->
+<%= htmlWebpackPlugin.tags.headTags.filter(tag => tag.attributes['data-rsbuild-assets-retry'] === 'inline') %>
+
+<!-- 筛选非重试脚本 -->
+<%= htmlWebpackPlugin.tags.headTags.filter(tag => !tag.attributes['data-rsbuild-assets-retry']) %>
+```
+
+这允许您将重试脚本放置在 HTML 头部的顶部以获得最佳的加载顺序。
+
 ## License
 
 [MIT](./LICENSE).