Rsbuild supports import static assets, including images, fonts, audio and video.
Static assets are files that are part of a web application and do not change, even when the application is being used. Examples of static assets include images, fonts, medias, stylesheets, and JavaScript files. These assets are typically stored on a web server or CDN, and delivered to the user's web browser when the Web application is accessed. Because they do not change, static assets can be cached by the browser, which helps to improve the performance of the Web application.
The following are the formats supported by Rsbuild by default:
If you need to import assets in other formats, please refer to Extend Asset Types.
SVG image is a special case. Rsbuild support convert SVG to React components, so SVG is processed separately. For details, see SVGR Plugin.
In JS files, you can import static assets in relative paths:
Import with alias are also supported:
In CSS files, you can reference static assets in relative paths:
Import with alias are also supported:
The result of importing static assets depends on the file size:
For a more detailed introduction to asset inlining, please refer to the Static Asset Inlining chapter.
When static assets are imported, they will be output to the dist directory. You can:
Please read Output Files for details.
The URL returned after importing a asset will automatically include the path prefix:
For example, you can set output.assetPrefix
to https://example.com
:
The public folder at the project root can be used to place some static assets. These assets will not be bundled by Rsbuild.
/
.For example, you can place files such as robots.txt
, manifest.json
, or favicon.ico
in the public folder.
In the HTML template, you can refer to the files in the public folder as follows. The assetPrefix
is the URL prefix of the static assets.
In JavaScript code, you can splice the URL via process.env.ASSET_PREFIX
:
Rsbuild provides the server.publicDir option which can be used to customize the name and behavior of the public folder, as well as to disable it.
dist
). Please be careful to avoid name conflicts with the output files. When files in the public
folder have the same name as outputs, the outputs have higher priority and will overwrite the files with the same name in the public
folder. This feature can be disabled by setting server.publicDir.copyOnBuild
to false.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.
@rsbuild/core
package is installed, you can directly reference the type declarations provided by @rsbuild/core
: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.
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:
After adding the above configuration, you can import *.pdf
files in your code, for example:
For more information about asset modules, please refer to Rspack - Asset modules.
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:
.png
files using the exclude
method.When using image assets, you can choose a appropriate image format according to the pros and cons in the table below.
Format | Pros | Cons | Scenarios |
---|---|---|---|
PNG | Lossless compression, no loss of picture details, no distortion, support for translucency | Not suitable for pictures with complex color tables | Suitable for pictures with few colors and well-defined borders, suitable for logos, icons, transparent images and other scenes |
JPG | Rich colors | Lossy compression, which will cause image distortion, does not support transparency | Suitable for pictures with a large number of colors, gradients, and overly complex pictures, suitable for portrait photos, landscapes and other scenes |
WebP | Supports both lossy and lossless compression, supports transparency, and is much smaller than PNG and JPG | iOS compatibility is not good | Pixel images of almost any scene, and the hosting environment that supports WebP, should prefer WebP image format |
SVG | Lossless format, no distortion, supports transparency | Not suitable for complex graphics | Suitable for vector graphics, suitable for icons |