Inline Static Assets#

Inline static assets refer to the practice of including the content of a static asset directly in a HTML or JS file, instead of linking to an external file. This can improve the performance of a website by reducing the number of HTTP requests that the browser has to make to load the page.

However, static assets inlining also has some disadvantages, such as increasing the size of a single file, which may lead to slower loading. Therefore, in the actual scenario, it is necessary to decide whether to use static assets inlining according to the specific situation.

Rsbuild will automatically inline static assets that are less than 4KiB, but sometimes you may need to manually control assets to force them to be inlined or not, and this document explains how to precisely control the inlining behavior of static assets.

Automatic Inlining#

By default, Rsbuild will inline assets when the file size of is less than a threshold (the default is 4KiB). When inlined, the asset will be converted to a Base64 encoded string and will no longer send a separate HTTP request. When the file size is greater than this threshold, it is loaded as a separate file with a separate HTTP request.

The threshold can be modified with the output.dataUriLimit config. For example, set the threshold of images to 5000 Bytes, and set media assets not to be inlined:

export default {
  output: {
    dataUriLimit: {
      image: 5000,
      media: 0,
    },
  },
};

Force Inlining#

You can force an asset to be inlined by adding the inline query when importing the asset, regardless of whether the asset's size is smaller than the size threshold.

import React from 'react';
import img from '. /foo.png?inline';

export default function Foo() {
  return <img src={img} />;
}

In the above example, the foo.png image will always be inlined, regardless of whether the size of the image is larger than the threshold.

Referenced from CSS file#

When you reference a static asset in your CSS file, you can also force inline the asset with the inline query.

.foo {
  background-image: url('. /icon.png?inline');
}

Force no inlining#

When you want to always treat some assets as separate files, no matter how small the asset is, you can add the url query to force the asset not to be inlined.

import React from 'react';
import img from '. /foo.png?url';

export default function Foo() {
  return <img src={img} />;
}

In the above example, the foo.png image will always be loaded as a separate file, even if the size of the image is smaller than the threshold.

Referenced from CSS file#

When you reference a static asset in your CSS file, you can also force the asset not to be inlined with url query.

.foo {
  background-image: url('. /icon.png?url');
}

export default {
  output: {
    inlineScripts: true,
  },
};

Inline CSS files#

You can also inline CSS files into HTML files.

Just enable the output.inlineStyles config, the generated CSS file will not be written into the output directory, but will be directly inlined to the corresponding in the HTML file.

export default {
  output: {
    inlineStyles: true,
  },
};

Type Declaration#

When you use URL queries such as ?inline and ?url in TypeScript code, TypeScript may prompt that the module is missing a type definition:

To fix this, you can add type declarations for these URL queries, please create src/env.d.ts file and add the following type declarations.

• Method 1: If the @rsbuild/core package is installed, you can directly reference the type declarations provided by @rsbuild/core:

/// <reference types="@rsbuild/core/types" />

• Method 2: Manually add the required type declarations:

declare module '*?url' {
  const content: string;
  export default content;
}
declare module '*?inline' {
  const content: string;
  export default content;
}