close
Guide
Config
Plugin
API
Community
Version
Guide
Config
Plugin
API
Community

performance.preload

  • Type: undefined | true | PreloadOptions
interface PrefetchOptions {
  type?: ResourceHintsIncludeType;
  include?: ResourceHintsFilter;
  exclude?: ResourceHintsFilter;
  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 async resources on the current page, including async 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

performance.preload can be set to an object to specify the options.

preload.type

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

Specify which types of resources will be included. Currently supported values are as follows:

  • async-chunks: Includes all async resources on the current page, such as async JS chunks, and its associated CSS, images, fonts, and other static resources.
  • initial: Includes all non-async resources on the current page.
  • all-chunks: Includes all async and non-async resources on the current page.
  • all-assets: Includes all resources from all pages.

For example, to include all png images on the current page, configure it as follows:

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

preload.include

  • Type:
type ResourceHintsFilter =
  | string
  | RegExp
  | ((filename: string) => boolean)
  | Array<string | RegExp | ((filename: string) => boolean)>;
  • Default: undefined

A extra filter to determine which resources to include.

  • When include is a regular expression, it will be used directly to match the filename:
rsbuild.config.ts
export default {
  performance: {
    preload: {
      // Match all .png files
      include: /\.png$/,
    },
  },
};
  • When include is a string, it will be converted to a regular expression to match the filename:
rsbuild.config.ts
export default {
  performance: {
    preload: {
      include: '\\.png', // equivalent to `new RegExp('\\.png')`
    },
  },
};
  • When include is a function, it will be called with the filename as an argument:
rsbuild.config.ts
export default {
  performance: {
    preload: {
      include: (filename) => filename.endsWith('.png'),
    },
  },
};
  • When include is an array, it can contain multiple filters, and the filename only needs to match one of the filters to be included:
rsbuild.config.ts
export default {
  performance: {
    preload: {
      include: [/\.png$/, '\\.jpg'],
    },
  },
};

preload.exclude

  • Type:
type ResourceHintsFilter =
  | string
  | RegExp
  | ((filename: string) => boolean)
  | Array<string | RegExp | ((filename: string) => boolean)>;
  • Default: undefined

A extra filter to determine which resources to exclude, the usage is similar to include.

preload.dedupe

  • Type: boolean
  • Default: true

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

rsbuild.config.ts
export default {
  performance: {
    preload: {
      dedupe: false,
    },
  },
};
ON THIS PAGE