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

performance.prefetch

  • Type: undefined | true | PrefetchOptions
interface PrefetchOptions {
  type?: ResourceHintsIncludeType;
  include?: ResourceHintsFilter;
  exclude?: ResourceHintsFilter;
}
  • Default: undefined

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

What is prefetch

The prefetch keyword for the rel attribute of the <link> element provides a hint to browsers that the user is likely to need the target resource for future navigation, and therefore the browser can likely improve the user experience by preemptively fetching and caching the resource.

Enable prefetch

When performance.prefetch is set to true, Rsbuild will use the following default options to prefetch resources. This means prefetching 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 prefetch tags -->
    <link href="/static/js/async/src_bar_js.js" rel="prefetch" />
    <link href="/static/js/async/src_foo_js.js" rel="prefetch" />
  </head>
</html>

Inject manually

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

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

The injected HTML tag is as follows:

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

Options

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

prefetch.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: {
    prefetch: {
      type: 'all-chunks',
      include: [/\.png$/],
    },
  },
};
TIP

If a script has been directly referenced via HTML <script> tag, it will not be prefetched.

prefetch.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: {
    prefetch: {
      // 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: {
    prefetch: {
      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: {
    prefetch: {
      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: {
    prefetch: {
      include: [/\.png$/, '\\.jpg'],
    },
  },
};

prefetch.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.

ON THIS PAGE