#Inline static assets

Inlining static assets refers to embedding the content of a static asset directly in an HTML or JS file instead of linking to an external file. This can improve website performance by reducing the number of HTTP requests the browser needs to make to load the page.

However, inlining static assets has some disadvantages, such as increasing the size of a single file, which may lead to slower loading. Decide whether to inline assets based on your specific situation.

Rsbuild automatically inlines static assets of 4KiB or less. This guide shows how to change that threshold, force inlining, or disable it for specific assets.

#Automatic inlining

Rsbuild inlines assets whose size does not exceed the threshold (4KiB by default). These assets become Base64 strings and need no separate HTTP request. Larger assets are emitted as separate files and loaded through their own HTTP requests.

import smallImage from './static/smallImage.png';

console.log(smallImage); // "data:image/png;base64,iVBORw0KGgo..."

You can modify the threshold with the output.dataUriLimit config. For example, set the threshold for images to 5000 bytes and disable inlining for media assets:

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

#Force inlining

You can force an asset to be inlined by adding the inline query parameter when importing it, regardless of the asset's size.

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 the image size.

#Referenced from CSS file

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

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

#Disable inlining

To prevent assets from being inlined and ensure they're always loaded as separate files (regardless of their size), add the url query parameter.

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 it's smaller than the threshold.

#Referenced from CSS file

When you reference a static asset in your CSS file, you can also prevent inlining with the url query parameter.

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

#Inline JS files

In addition to inlining static assets into JS files, Rsbuild also supports inlining JS files into HTML files.

Enable output.inlineScripts to inline scripts referenced by the generated HTML during production builds. Inlined files are removed from the output directory. Async chunks remain separate files.

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

#Inline CSS files

You can also inline CSS files into HTML files.

Enable output.inlineStyles to inline stylesheets referenced by the generated HTML during production builds. Inlined files are removed from the output directory. CSS loaded by async chunks remains in separate files.

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:

TS2307: Cannot find module './logo.png?inline' or its corresponding type declarations.

To fix this, use one of the following methods:

• Method 1: If the @rsbuild/core package is installed, you can add the preset types provided by @rsbuild/core to tsconfig.json:

{
  "compilerOptions": {
    "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;
}