#Import static assets

Rslib supports import static assets, including images, fonts, audio and video.

#Assets format

The following are the formats supported by Rslib by default:

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

To import assets in other formats, refer to Extend Asset Types.

#Import assets in JavaScript file

In JavaScript files, you can directly import static assets with relative paths through import:

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

console.log(logo); // "/static/logo.[hash].png"

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

Import with alias is also available:

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

console.log(logo); // "/static/logo.[hash].png"

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

When the format is set to cjs or esm, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and transforms the source file into a JavaScript file and a static asset file that is emitted according to output.distPath by default with preserving the import or require statements for static assets.

The following is an example of usage, assuming the source code is as follows:

src/index.ts

src/assets/logo.svg

import logo from './assets/logo.svg';

console.log(logo);

Based on the configuration in the output structure in the configuration file, the following outputs will be emitted:

bundle

bundleless

dist/index.mjs

dist/static/svg/logo.svg

import logo_namespaceObject from './static/svg/logo.svg';

console.log(logo_namespaceObject);

dist/index.mjs

dist/assets/logo.mjs

dist/static/svg/logo.svg

import logo from './assets/logo.mjs';

console.log(logo);

import logo_namespaceObject from '../static/svg/logo.svg';
export { logo_namespaceObject as default };

#Import assets in CSS file

In CSS files, you can import static assets with relative paths:

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

Import with alias are also supported:

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

When the format is set to cjs or esm, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and preserves relative reference paths in CSS outputs by default via setting output.assetPrefix to "auto".

The following is an example of usage, assuming the source code is as follows:

src/index.css

src/assets/logo.png

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

The following output will be emitted:

dist/index.css

dist/static/image/logo.png

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

#Ignore some assets imported in CSS

If you need to import a static asset with an absolute path in a CSS file:

@font-face {
  font-family: DingTalk;
  src: url('/image/font/foo.ttf');
}

By default, the built-in css-loader in Rslib will resolve absolute paths in url() and look for the specified modules. If you want to skip resolving absolute paths, you can configure tools.cssLoader to filter out the specified paths. The filtered paths are preserved as they are in the code.

export default {
  tools: {
    cssLoader: {
      url: {
        filter: (url) => {
          if (/\/image\/font/.test(url)) {
            return false;
          }
          return true;
        },
      },
    },
  },
};

#Inline static assets

When the format is set to cjs or esm, Rslib treats the output as an mid-level artifact that will be consumed by other build tools again and sets output.dataUriLimit to 0 by default to not inline any static assets.

#Build output directory

Once static assets are imported, they will automatically be output to the build output directory. You can:

• Modify the filename of the outputs through output.filename. For example, add a hash value to the filename of the outputs, which is usually used when there are files with the same name to avoid filename conflicts.

export default {
  output: {
    filename: {
      svg: '[name].[contenthash:8].svg',
      font: '[name].[contenthash:8][ext]',
      image: '[name].[contenthash:8][ext]',
      media: '[name].[contenthash:8][ext]',
      assets: '[name].[contenthash:8][ext]',
    },
  },
};

• Change the output path of the outputs through output.distPath. For example, emit static assets output to the dist/resource directory.

export default {
  output: {
    distPath: {
      svg: 'resource/svg',
      font: 'resource/font',
      image: 'resource/image',
      media: 'resource/media',
      assets: 'resource/assets',
    },
  },
};

#Type declaration

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

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

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 @rslib/core package is installed, you can reference the preset types provided by @rslib/core:

/// <reference types="@rslib/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 static assets type of Rslib does not meet your needs, you can extend the additional static assets type in the following ways.

#Use source.assetsInclude

By using the source.assetsInclude config, you can specify additional file types to be treated as static assets.

export default {
  source: {
    assetsInclude: /\.pdf$/,
  },
};

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

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

console.log(myFile);

#Use tools.rspack

You can modify the built-in Rspack configuration and add custom static assets handling rules via tools.rspack.

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

export default {
  tools: {
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.pdf$/,
          // Convert assets to separate files and keep import statements
          type: 'asset/resource',
          generator: {
            importMode: 'preserve',
          },
        },
      ]);
    },
  },
};

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