Import Static Assets#

Rsbuild supports import static assets, including images, fonts, and medias.

Assets Format#

The following are the formats supported by Rsbuild by default:

• image: png, jpg, jpeg, gif, svg, bmp, webp, ico, apng, avif, tif, tiff, jfif, pjpeg, pjp.
• fonts: woff, woff2, eot, ttf, otf, ttc.
• audio: mp3, wav, flac, aac, m4a, opus.
• video: mp4, webm, ogg, mov.

If you need to import assets in other formats, please refer to Extend Asset Types.

Import Assets in JS file#

In JS files, you can directly import static assets in relative paths:

// Import the logo.png image in the static directory
import logo from './static/logo.png';

export default = () => <img src={logo} />;

Import with alias are also supported:

import logo from '@/static/logo.png';

export default = () => <img src={logo} />;

Import Assets in CSS file#

In CSS files, you can reference static assets in relative paths:

.logo {
  background-image: url('../static/logo.png');
}

Import with alias are also supported:

.logo {
  background-image: url('@/static/logo.png');
}

Import Results#

The result of importing static assets depends on the file size:

• When the file size is greater than 10KB, a URL will be returned, and the file will be output to the dist directory.
• When the file size is less than 10KB, it will be automatically inlined to Base64 format.

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

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

For a more detailed introduction to asset inlining, please refer to the Static Asset Inlining chapter.

Output Files#

When static assets are imported, they will be output to the dist directory. You can:

• Modify the output filename through output.filename.
• Modify the output path through output.distPath.

Please read Output Files for details.

URL Prefix#

The URL returned after importing a asset will automatically include the path prefix:

• In development, using dev.assetPrefix to set the path prefix.
• In production, using output.assetPrefix to set the path prefix.

For example, you can set output.assetPrefix to https://modern.com:

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

console.log(logo); // "https://modern.com/static/logo.6c12aba3.png"

Type Declaration#

When you import static assets in TypeScript code, TypeScript may prompt that the module is missing a type definition:

To fix this, you need to add a type declaration file for the static assets, please create a src/env.d.ts file, and add the corresponding type declaration.

• 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:

// Taking png images as an example
declare module '*.png' {
  const content: string;
  export default content;
}

After adding the type declaration, if the type error still exists, you can try to restart the current IDE, or adjust the directory where env.d.ts is located, making sure the TypeScript can correctly identify the type definition.

Extend Asset Types#

If the built-in asset types in Rsbuild cannot meet your requirements, you can modify the built-in Rspack configuration and extend the asset types you need using tools.rspack.

For example, if you want to treat *.pdf files as assets and directly output them to the dist directory, you can add the following configuration:

export default {
  tools: {
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.pdf$/,
          // converts asset to a separate file and exports the URL address.
          type: 'asset/resource',
        },
      ]);
    },
  },
};

After adding the above configuration, you can import *.pdf files in your code, for example:

import myFile from './static/myFile.pdf';

console.log(myFile); // "/static/myFile.6c12aba3.pdf"

For more information about asset modules, please refer to Rspack - Asset modules.

Custom Rules#

In some scenarios, you may need to bypass the built-in assets processing rules of Rsbuild and add some custom rules.

Taking PNG image as an example, you need to:

1. Modify the built-in Rspack config via tools.bundlerChain to exclude .png files using the exclude method.
2. Add custom asset processing rules via tools.rspack.

export default {
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      chain.module
        // Use `CHAIN_ID.RULE.IMAGE` to locate the built-in image rule
        .rule(CHAIN_ID.RULE.IMAGE)
        .exclude.add(/\.png$/);
    },
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.png$/,
          // Add a custom loader to handle png images
          loader: 'custom-png-loader',
        },
      ]);
    },
  },
};

Image Format#

When using image assets, you can choose a appropriate image format according to the pros and cons in the table below.