close
  • 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:

      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>