close
Guide
Config
Plugin
API
Community
Guide
Config
Plugin
API
Community

performance.preload

  • Type: undefined | true | PreloadOption
type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';

type Filter = Array<string | RegExp> | ((filename: string) => boolean);

interface PreloadOption {
  type?: IncludeType;
  include?: Filter;
  exclude?: Filter;
  dedupe?: boolean;
}
  • Default: undefined

Inject the <link rel="preload"> tags for the static assets generated by Rsbuild.

What is preload

The preload value of the <link> element's rel attribute lets you declare fetch requests in the HTML's <head>, specifying resources that your page will need very soon, which you want to start loading early in the page lifecycle, before browsers' main rendering machinery kicks in.

This ensures they are available earlier and are less likely to block the page's render, improving performance. Even though the name contains the term load, it doesn't load and execute the script but only schedules it to be downloaded and cached with a higher priority.

Enable preload

When performance.preload is set to true, Rsbuild will use the following default options to preload resources. This means preloading all asynchronous resources on the current page, including asynchronous JS and its associated CSS, image, font, and other resources.

const defaultOptions = {
  type: 'async-chunks',
};

For example, if you dynamically import other modules in the entry file:

index.js
import('./foo');
import('./bar');

The tags injected in HTML are as follows:

<html>
  <head>
    <title>Rsbuild App</title>
    <script defer src="/static/js/index.js"></script>
    <!-- Generated preload tags -->
    <link href="/static/js/async/src_bar_js.js" rel="preload" as="script" />
    <link href="/static/js/async/src_foo_js.js" rel="preload" as="script" />
  </head>
</html>

Inject manually

The performance.preload can only inject the preload tags for static resources generated by Rsbuild. If you need to preload other resources, you can manually add tags through html.tags :

rsbuild.config.ts
export default {
  html: {
    tags: [
      {
        tag: 'link',
        attrs: {
          rel: 'preload',
          as: 'script',
          href: 'https://example.com/some-script.js',
        },
      },
    ],
  },
};

The injected HTML tag is as follows:

<link rel="preload" as="script" href="https://example.com/some-script.js" />

Options

When the value of performance.preload is object type, the Rsbuild will enable the preload capability for the specified resource according to the current options.

preload.type

  • Type: 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks'
  • Default: 'async-chunks'

The type field controls which resources will be pre-fetched, and supports secondary filtering of specified resources through include and exclude.

Currently supported resource types are as follows:

  • async-chunks: preload all asynchronous resources (on the current page), including asynchronous JS and its associated CSS, image, font and other resources.
  • initial: preload all non-async resources (on the current page).
  • all-chunks: preload all resources (on the current page), including all asynchronous and non-asynchronous resources.
  • all-assets: preload all resources, and resources of other pages will be included in the MPA scenario.

Example

When you want to preload all image resources in png format on the current page, you can configure it as follows:

export default {
  performance: {
    preload: {
      type: 'all-chunks',
      include: [/.*\.png$/],
    },
  },
};

preload.dedupe

  • Type: boolean
  • Default: true

Whether to preload script resources that already exist in the current HTML template. By default, if a resource has been added to the current HTML via a script tag, it will not be preloaded additionally.

When set to true, Rsbuild will generate preload tags for all eligible resources, even if these resources already exist in the HTML.

export default {
  performance: {
    preload: {
      dedupe: false,
    },
  },
};