> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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](/config/output/module.md) 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](/config/html/tags.md)
- `<script>` tags added via [api.modifyHtmlTags](/plugins/dev/hooks.md#modifyhtmltags)

## Optional values

### defer

By default, the `<script>` tag generated by Rsbuild will automatically set the [`defer` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#defer) to avoid blocking the parsing and rendering of the page.

```html
<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`.

```ts title="rsbuild.config.ts"
export default {
  html: {
    scriptLoading: 'module',
  },
};
```

```html
<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.

```ts title="rsbuild.config.ts"
export default {
  html: {
    inject: 'body',
    scriptLoading: 'blocking',
  },
};
```

When you need to set `blocking`, it is recommended to set [html.inject](/config/html/inject.md) to `'body'` to avoid page rendering being blocked.

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