Configure Rspack#

Rsbuild supports directly modifying the Rspack configuration object, and also supports modifying the built-in Rspack configuration of Rsbuild through the bundler-chain.

Modify Config Object#

You can use the tools.rspack option of Rsbuild to modify the Rspack config object.

For example, register Rspack plugins or webpack plugins:

export default {
  tools: {
    rspack: {
      plugins: [SomeWebpackPlugin()],
    },
  },
};

Or modify the Rspack config with a function:

export default {
  tools: {
    rspack: (config, { env }) => {
      if (env === 'development') {
        config.devtool = 'cheap-module-eval-source-map';
      }
      return config;
    },
  },
};

Please refer to the tools.rspack documentation for detailed usage.

Use Bundler Chain#

Bundler chain is a subset of webpack chain, which contains part of the webpack chain API. You can use it to modify the builtin Rspack config.

Compared with modifying the Rspack configuration object, bundler-chain is more powerful. It not only supports chain calls, but also allows you to modify of builtin rules or plugins based on ids.

tools.bundlerChain#

Rsbuild provides the tools.bundlerChain configuration option to modify the bundler chain.

The value of tools.bundlerChain is a Function type that accepts two parameters:

• The first parameter is the bundler-chain instance, which can be used to modify the default bundler configuration.
• The second parameter is utils that includes env, isProd, CHAIN_ID, and more.

Here's a basic example:

export default {
  tools: {
    bundlerChain: (chain, { env }) => {
      if (env === 'development') {
        chain.devtool('cheap-module-eval-source-map');
      }
    },
  },
};

Basics#

Before using the bundler chain to modify the Rspack configuration, it is recommended to familiarize yourself with some basics.

How the Bundler Chain Locates Objects Quickly#

In short, the bundler chain requires users to set a unique ID for each rule, loader, plugin, and minimizer. With this ID, you can easily find the desired object from deeply nested objects.

Rsbuild exports all internally defined IDs through the CHAIN_ID object, so you can quickly locate the loader or plugin you want to modify using these exported IDs, without the need for complex traversal in the Rspack configuration object.

For example, you can remove the built-in HTML plugin using CHAIN_ID.PLUGIN.HTML:

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      //
      chain.plugins.delete(CHAIN_ID.PLUGIN.HTML);
    },
  },
};

Types of Bundler Chain IDs#

The CHAIN_ID object contains various IDs, which correspond to the following configurations:

Examples#

Configure loader#

Here are examples of adding, modifying, and deleting Rspack loaders.

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      // Add loader
      chain.module
        .rule('md')
        .test(/\.md$/)
        .use('md-loader')
        .loader('md-loader');

      // Modify loader
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        .use(CHAIN_ID.USE.BABEL)
        .tap((options) => {
          options.plugins.push('babel-plugin-abc');
          return options;
        });

      // Delete loader
      chain.module.rule(CHAIN_ID.RULE.JS).uses.delete(CHAIN_ID.USE.BABEL);
    },
  },
};

Configure Plugin#

Here are examples of adding, modifying, and deleting Rspack plugins.

export default {
  tools: {
    bundlerChain: (chain, { bundler, CHAIN_ID }) => {
      // Add plugin
      chain.plugin('custom-define').use(bundler.DefinePlugin, [
        {
          'process.env': {
            NODE_ENV: JSON.stringify(process.env.NODE_ENV),
          },
        },
      ]);

      // Modify plugin
      chain.plugin(CHAIN_ID.PLUGIN.HMR).tap((options) => {
        options[0].fullBuildTimeout = 200;
        return options;
      });

      // Delete plugin
      chain.plugins.delete(CHAIN_ID.PLUGIN.HMR);
    },
  },
};

Modify based on environment#

In the tools.bundlerChain function, you can access various environment identifiers in the second parameter, such as development/production build, SSR build, Web Worker build, to achieve configuration modifications for different environments.

export default {
  tools: {
    bundlerChain: (chain, { env, isProd, target, isServer, isWebWorker }) => {
      if (utils.env === 'development' || utils.env === 'test') {
        // ...
      }
      if (utils.isProd) {
        // ...
      }
      if (utils.target === 'node') {
        // ...
      }
      if (utils.isServer) {
        // ...
      }
      if (utils.isWebWorker) {
        // ...
      }
    },
  },
};

The above are some common configuration examples. For the complete bundler-chain API, please refer to the webpack-chain documentation.