feat: add data-rsbuild-assets-retry attribute to retry scripts

[LuciferChiu]

✨ Features

Add Data Attribute to Retry Scripts for HTML Template Filtering

This release adds a unique data-rsbuild-assets-retry attribute to retry scripts, enabling developers to easily identify and position them in custom HTML templates.

Key Changes:

• Added ASSETS_RETRY_DATA_ATTRIBUTE constant for type-safe attribute access
• Enhanced script generation with unique data attributes:
  • data-rsbuild-assets-retry="inline" for inline scripts
  • data-rsbuild-assets-retry="external" for external scripts
• Exported the constant for use in custom HTML templates
• Updated documentation with usage examples and best practices
• Added comprehensive tests to verify the functionality

Usage Example:

// In HTML templates
<%= htmlWebpackPlugin.tags.headTags.filter(tag => tag.attributes['data-rsbuild-assets-retry']) %>

Benefits:

• Better control over script positioning in custom HTML templates
• Type safety through exported constants
• Improved loading order by placing retry scripts at the top
• Easy identification of retry scripts vs. regular scripts

Testing:

• All existing tests pass (30/30)
• New tests added for both inline and external script modes
• Verified data attribute presence and values
• Code formatting applied with Biome

This enhancement addresses the common need for precise control over retry script placement in custom HTML templates while maintaining backward compatibility.

[Copilot]

Pull Request Overview

This PR adds a data attribute to retry scripts so they can be easily filtered in custom HTML templates.

• Introduces a new ASSETS_RETRY_DATA_ATTRIBUTE constant
• Updates inline and external script tags to include data-rsbuild-assets-retry
• Adds tests and documentation showing how to filter by the new attribute

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
test/basic/dataAttribute.test.ts	Adds Playwright tests verifying the presence and values of the data attribute on retry scripts
src/index.ts	Defines ASSETS_RETRY_DATA_ATTRIBUTE and applies it to script tags
README.zh-CN.md	Documents the new data attribute usage in the Chinese README
README.md	Documents the new data attribute usage in the English README

Comments suppressed due to low confidence (5)

src/index.ts:24

• [nitpick] This comment is in Chinese while the rest of the code and README are in English; consider translating it to English to maintain consistency.

// 唯一标识符，用于在 HTML 模板中筛选重试脚本

README.md:494

• [nitpick] If you intend to output the filtered tags in a template, you probably need <%= instead of <% to actually render the result.

<% htmlWebpackPlugin.tags.headTags.filter(tag => tag.attributes['data-rsbuild-assets-retry'] === 'inline') %>

README.zh-CN.md:492

• [nitpick] In this Chinese README example, use <%= rather than <% to ensure the filtered array is actually injected into the render output.

<% htmlWebpackPlugin.tags.headTags.filter(tag => tag.attributes['data-rsbuild-assets-retry'] === 'inline') %>

test/basic/dataAttribute.test.ts:7

• import.meta.dirname is not a standard property and may be undefined at runtime; consider using path.dirname(fileURLToPath(import.meta.url)) for a reliable directory path.

    cwd: import.meta.dirname,

src/index.ts:141

• [nitpick] The indentation of this attribute key does not match the surrounding object keys; aligning it with src: url will improve readability.

              [ASSETS_RETRY_DATA_ATTRIBUTE]: 'external',

[LuciferChiu]

@SoonIter Please help with the code review.

[chenjiahan]

Can you explain why we need to implement this? I think for most scenarios, the plugin need to ensure that the retry script is the first script, and it should not be left to the user to handle this.

[LuciferChiu]

@chenjiahan

real production example :

    // asstes retry
    <%= htmlWebpackPlugin.tags.headTags.filter(tag => tag.attributes['data-rsbuild-assets-retry']) %>

	// some runtime scripts（like unpkg）
    <script async src="react.js"></script>
    <script src="logger.js"></script>
    <script type="module" src="xxx"></script>

    // other scripts that depend on the above runtime scripts. 
    <%= htmlWebpackPlugin.tags.headTags.filter(tag => !tag.attributes['data-rsbuild-assets-retry']) %>

If I want react script can retry, What should I do ?
I can't implement this using the current main version(1.3.0).

[chenjiahan]

Get👌 this makes sense