Config#

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.

Config Categories#

Rsbuild Configs are divided into the following categories:

• Dev: Config related to local development.
• Html: Config related to HTML.
• Tools: Config related to the low-level tools.
• Server：Config related to Rsbuild Server, which will take effect during local development and preview.
• Source: Config related to source code parsing and compilation.
• Output: Config related to output.
• Performance: Config related to performance.

You can find detailed descriptions of all configs on the Config page.

Configuration Usage#

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:

• rsbuild.config.ts
• rsbuild.config.js
• rsbuild.config.mjs
• rsbuild.config.cjs
• rsbuild.config.mts
• rsbuild.config.cts

We recommend using the .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:

import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  source: {
    alias: {
      '@common': './src/common',
    },
  },
});

If you are developing a non-TypeScript project, you can use the .js format for the configuration file:

module.exports = {
  source: {
    alias: (opts) => {
      opts['@common'] = './src/common';
    },
  },
};

Using Environment Variables#

In the configuration file, you can use Node.js environment variables such as process.env.NODE_ENV to dynamically set different configurations:

import { defineConfig } from '@rsbuild/core';

export default defineConfig({
  source: {
    alias: {
      '@request':
        process.env.NODE_ENV === 'development'
          ? './src/request.dev.js'
          : './src/request.prod.js',
    },
  },
});

Export Function#

Rsbuild supports the export of a function in the config file, where you can dynamically compute the config and return it to Rsbuild.

import { defineConfig } from '@rsbuild/core';

export default defineConfig(({ env, command }) => ({
  source: {
    alias: {
      '@foo': env === 'development' ? './src/foo.dev.ts' : './src/foo.prod.ts',
    },
  },
}));

The function accepts the following parameters:

• env: the value of process.env.NODE_ENV.
  • When running rsbuild dev, the value of env is development.
  • When running rsbuild build or rsbuild preview, the value of env is production.
• command: the current command being run, such as dev, build, preview.

Export Async Function#

Rsbuild also supports the export of an async function in the config file, where you can perform some async operations:

import { defineConfig } from '@rsbuild/core';

export default defineConfig(async ({ env, command }) => {
  const result = await someAsyncFunction();

  return {
    html: {
      title: result,
    },
  };
});

Merge Configurations#

You can use the mergeRsbuildConfig function exported by @rspack/core to merge multiple configurations.

import { defineConfig, mergeRsbuildConfig } from '@rsbuild/core';

const config1 = defineConfig({
  dev: { port: '8080' },
});
const config2 = defineConfig({
  dev: { port: '8081' },
});

// { dev: { port: '8081' }
export default mergeRsbuildConfig(config1, config2);

Debug the config#

You can enable Rsbuild's debug mode by adding the DEBUG=rsbuild environment variable when executing a build.

DEBUG=rsbuild pnpm dev

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.config.js file to see the complete content of the Rsbuild config.

For a complete introduction to debug mode, see the Debug Mode chapter.