English

简体中文

html.scriptLoading

Type: 'defer' | 'blocking' | 'module'
Default: 'defer'

Specifies how <script> tags generated by Rsbuild are loaded.

'defer': Adds the defer attribute so scripts load in parallel and run after the document has been parsed.
'module': Adds type="module" to enable ES modules semantics.
'blocking': No defer or async, scripts execute immediately in order.

TIP

If output.module is enabled, the value is always 'module'.

Note

The scriptLoading option only applies to <script> tags automatically generated by Rsbuild. It does not affect:

<script> tags that already exist in the HTML template
<script> tags added via html.tags
<script> tags added via api.modifyHtmlTags

Optional values

defer

By default, the <script> tag generated by Rsbuild will automatically set the defer attribute to avoid blocking the parsing and rendering of the page.

<head>
  <script defer src="/static/js/main.js"></script>
</head>
<body></body>

TIP

When the browser encounters a <script> tag with the defer attribute, it will download the script file asynchronously without blocking the parsing and rendering of the page. After the page is parsed and rendered, the browser executes the <script> tags in the order they appear in the document.

module

When scriptLoading is set to module, the script can support ES modules syntax, and the browser will automatically delay the execution of these scripts by default, which is similar to defer.

rsbuild.config.ts

export default {
  html: {
    scriptLoading: 'module',
  },
};

<head>
  <script type="module" src="/static/js/main.js"></script>
</head>
<body></body>

blocking

Setting scriptLoading to blocking will remove the defer attribute, and the script is executed synchronously, which means it will block the browser's parsing and rendering process until the script file is downloaded and executed.

rsbuild.config.ts

export default {
  html: {
    inject: 'body',
    scriptLoading: 'blocking',
  },
};

When you need to set blocking, it is recommended to set html.inject to 'body' to avoid page rendering being blocked.

<head></head>
<body>
  <script src="/static/js/main.js"></script>
</body>

html.scriptLoading

Type: 'defer' | 'blocking' | 'module'
Default: 'defer'

Specifies how <script> tags generated by Rsbuild are loaded.

'defer': Adds the defer attribute so scripts load in parallel and run after the document has been parsed.
'module': Adds type="module" to enable ES modules semantics.
'blocking': No defer or async, scripts execute immediately in order.

TIP

If output.module is enabled, the value is always 'module'.

Note

The scriptLoading option only applies to <script> tags automatically generated by Rsbuild. It does not affect:

<script> tags that already exist in the HTML template
<script> tags added via html.tags
<script> tags added via api.modifyHtmlTags

Optional values

defer

By default, the <script> tag generated by Rsbuild will automatically set the defer attribute to avoid blocking the parsing and rendering of the page.

<head>
  <script defer src="/static/js/main.js"></script>
</head>
<body></body>

TIP

module

When scriptLoading is set to module, the script can support ES modules syntax, and the browser will automatically delay the execution of these scripts by default, which is similar to defer.

rsbuild.config.ts

export default {
  html: {
    scriptLoading: 'module',
  },
};

<head>
  <script type="module" src="/static/js/main.js"></script>
</head>
<body></body>

blocking

rsbuild.config.ts

export default {
  html: {
    inject: 'body',
    scriptLoading: 'blocking',
  },
};

When you need to set blocking, it is recommended to set html.inject to 'body' to avoid page rendering being blocked.

<head></head>
<body>
  <script src="/static/js/main.js"></script>
</body>

#html.scriptLoading

#Note

#Optional values

#defer

#module

#blocking

#html.scriptLoading

#Note

#Optional values

#defer

#module

#blocking

html.scriptLoading

Note

Optional values

defer

module

blocking

html.scriptLoading

Note

Optional values

defer

module

blocking