Rsbuild provides a wide range of configuration options and sets a common default value for each option, which can meet the requirements of most use cases. Therefore, in most cases, you don't need to declare any Rsbuild configurations and can use it out of the box.
If you need to customize build behaviors, you can use these configuration options.
The configuration structure of Rsbuild looks like this:
You can find detailed descriptions of all configs on the Configure Overview page.
When you use the CLI of Rsbuild, Rsbuild will automatically read the configuration file in the root directory of the current project and resolve it in the following order:
We recommend using the .mjs
or .ts
format for the configuration file and importing the defineConfig
utility function from @rsbuild/core
. It provides friendly TypeScript type hints and autocompletion, which can help you avoid errors in the configuration.
For example, in rsbuild.config.ts
, you can define the Rsbuild source.alias configuration:
If you are developing a non-TypeScript project, you can use the .mjs
format for the configuration file:
When you use the .ts
, .mts
, and .cts
extensions, Rsbuild will use jiti to load configuration files, providing interoperability between ESM and CommonJS. The behavior of module resolution differs slightly from the native behavior of Node.js.
Rsbuild CLI uses the --config
option to specify the config file, which can be set to a relative path or an absolute path.
For example, if you need to use the rsbuild.prod.config.mjs
file when running build
, you can add the following scripts to package.json
:
You can also abbreviate the --config
option to -c
:
In the configuration file, you can use Node.js environment variables such as process.env.NODE_ENV
to dynamically set different configurations:
Rsbuild supports the export of a function in the config file, where you can dynamically compute the config and return it to Rsbuild.
The exported config function must provide a return value. If you do not need to return any config, you can return an empty object.
The function accepts the following parameters:
string
process.env.NODE_ENV
The current running environment.
rsbuild dev
, the default value of env is development
.rsbuild build
or rsbuild preview
, the default value of env is production
.string
process.env.NODE_ENV
The current value of the CLI parameter --env-mode
.
For example, when running rsbuild build --env-mode test
, the value of envMode
is test
.
string
The current running CLI command, such as dev
, build
, preview
.
Rsbuild also supports the export of an async function in the config file, where you can perform some async operations:
You can use the mergeRsbuildConfig function exported by @rsbuild/core
to merge multiple configurations.
You can enable Rsbuild's debug mode by adding the DEBUG=rsbuild
environment variable when executing a build.
In debug mode, Rsbuild will write the Rsbuild config to the dist directory, which is convenient for developers to view and debug.
Open the generated /dist/.rsbuild/rsbuild.config.mjs
file to see the complete content of the Rsbuild config.
For a complete introduction to debug mode, see the Debug Mode chapter.