Skip to content

Commit

Permalink
docs: update assetsRetry configuration introduce (#5746)
Browse files Browse the repository at this point in the history 
Co-authored-by: neverland <chenjiahan.jait@bytedance.com>
  • Loading branch information
@9aoy @chenjiahan
9aoy and chenjiahan committed May 16, 2024
1 parent 4a9c0c7 commit 69f1b82
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 452 deletions.
232 changes: 6 additions & 226 deletions packages/document/builder-doc/docs/en/config/output/assetsRetry.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ export type AssetsRetryOptions = {
};
```

- **Default:** `undefined`

Since the ability will inject some extra runtime code into HTML, we have disabled this ability by default. If you need to enable it, you can configure it in the form of an object, for example:

```js
Expand All @@ -48,16 +50,11 @@ export const defaultAssetsRetryOptions: AssetsRetryOptions = {
};
```

At the same time, you can also customize your retry logic using the following configurations.

### assetsRetry.domain
### Example

- **Type:** `string[]`
- **Default:** `[]`
You can also customize your retry logic using the `assetsRetry` options.

Specifies the retry domain when assets fail to load. In the `domain` array, the first item is the currently used domain, and the following items are backup domains. When a asset request for a domain fails, Builder will find that domain in the array and replace it with the next domain in the array.

For example:
For example, setting `assetsRetry.domain` to specify the retry domain when assets fail to load.

```js
export default {
Expand All @@ -73,221 +70,4 @@ After adding the above configuration, when assets fail to load from the `cdn1.co

If the assets request for `cdn2.com` also fails, the request will fallback to `cdn3.com`.

### assetsRetry.type

- **Type:** `string[]`
- **Default:** `['script', 'link', 'img']`

Used to specify the HTML tag types that need to be retried. By default, script tags, link tags, and img tags are processed, corresponding to JS code, CSS code, and images.

For example, only script tags and link tags are processed:

```js
export default {
output: {
assetsRetry: {
type: ['script', 'link'],
},
},
};
```

### assetsRetry.max

- **Type:** `number`
- **Default:** `3`

The maximum number of retries for a single asset. For example:

```js
export default {
output: {
assetsRetry: {
max: 5,
},
},
};
```

### assetsRetry.test

- **Type:** `string | ((url: string) => boolean) | undefined`
- **Default:** `undefined`

The test function of the asset to be retried. For example:

```js
export default {
output: {
assetsRetry: {
test: /cdn\.example\.com/,
},
},
};
```

### assetsRetry.crossOrigin

- **Type:** `undefined | boolean | 'anonymous' | 'use-credentials'`
- **Default:** `same as html.crossorigin`

When initiating a retry for assets, Builder will recreate the `<script>` tags. This option allows you to set the `crossorigin` attribute for these tags.

By default, the value of `assetsRetry.crossOrigin` will be consistent with the `html.crossorigin` configuration, so no additional configuration is required. If you need to configure the recreated tags separately, you can use this option, for example:

```js
export default {
output: {
assetsRetry: {
crossOrigin: true,
},
},
};
```

### assetsRetry.onRetry

- **Type:** `undefined | (options: AssetsRetryHookContext) => void`

The callback function when the asset is being retried. For example:

```js
export default {
output: {
assetsRetry: {
onRetry: ({ times, domain, url, tagName }) => {
console.log(
`Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}`,
);
},
},
},
};
```

### assetsRetry.onSuccess

- **Type:** `undefined | (options: AssetsRetryHookContext) => void`

The callback function when the asset is successfully retried. For example:

```js
export default {
output: {
assetsRetry: {
onSuccess: ({ times, domain, url, tagName }) => {
console.log(
`Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}`,
);
},
},
},
};
```

### assetsRetry.onFail

- **Type:** `undefined | (options: AssetsRetryHookContext) => void`

The callback function when the asset is failed to be retried. For example:

```js
export default {
output: {
assetsRetry: {
onFail: ({ times, domain, url, tagName }) => {
console.log(
`Retry ${times} times, domain: ${domain}, url: ${url}, tagName: ${tagName}`,
);
},
},
},
};
```

### assetsRetry.inlineScript

- **Type:** `boolean`
- **Default:** `true`

Whether to inline the runtime JavaScript code of `assetsRetry` into the HTML file.

If you don't want to insert the code in the HTML file, you can set `assetsRetry.inlineScript` to `false`:

```js
export default {
output: {
assetsRetry: {
inlineScript: false,
},
},
};
```

After adding the above configuration, the runtime code of `assetsRetry` will be extracted into a separate `assets-retry.[version].js` file and output to the dist directory.

The downside is that `assets-retry.[version].js` itself may fail to load. If this happens, the assets retry will not work. Therefore, we prefer to inline the runtime code into the HTML file.

### Notes

When you use `assetsRetry`, the Builder injects some runtime code into the HTML and serializes the `assetsRetry` config, inserting it into the runtime code. Therefore, you need to be aware of the following:

- Avoid configuring sensitive information in `assetsRetry`, such as internal tokens.
- Avoid referencing variables or methods outside of `onRetry`, `onSuccess`, and `onFail`.
- Avoid using syntax with compatibility issues in `onRetry`, `onSuccess` and `onFail` as these functions are inlined directly into the HTML.

Here's an example of incorrect usage:

```js
import { someMethod } from 'utils';

export default {
output: {
assetsRetry: {
onRetry() {
// Incorrect usage, includes sensitive information
const privateToken = 'a-private-token';

// Incorrect usage, uses an external method
someMethod(privateToken);
},
},
},
};
```

### Limitation

`assetsRetry` may not work in the following scenarios:

#### Micro-frontend application

If your project is a micro-frontend application (such as a Garfish sub-application), the assets retry may not work because micro-frontend sub-applications are typically not loaded directly based on the `<script>` tag.

If you need to retry assets in micro-frontend scenarios, please contact the developers of the micro-frontend framework to find a solution.

#### Dynamic import resources

Currently, `assetsRetry` cannot work on dynamically imported resources. This feature is being supported.

#### Resources in custom templates

`assetsRetry` listens to the page error event to know whether the current resource fails to load and needs to be retried. Therefore, if the resource in the custom template is executed earlier than `assetsRetry`, then `assetsRetry` cannot listen to the event that the resource fails to load, so it cannot retry.

If you want `assetsRetry` to work on resources in custom templates, you can refer to [Custom Insertion Example](https://github.com/jantimon/html-webpack-plugin/tree/main/examples/custom-insertion-position) to modify [html.inject](https://modernjs.dev/builder/en/api/config-html.html) configuration and custom template.

```diff
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>custom template</title>
+ <%= htmlWebpackPlugin.tags.headTags %>
<script src="//example.com/assets/a.js"></script>
</head>
<body>
<div id="root" />
+ <%= htmlWebpackPlugin.tags.bodyTags %>
</body>
</html>
```
`assetsRetry` is implemented based on the Assets Retry plugin of Rsbuild and provides the same configuration options. You can refer to [Rsbuild - Assets Retry Plugin](https://rsbuild.dev/plugins/list/plugin-assets-retry#options) to understand all available configuration options.
Loading

0 comments on commit 69f1b82

Please sign in to comment.