#Configure Rspack

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

#View Rspack config

Rsbuild provides the rsbuild inspect command to view the final Rspack config generated by Rsbuild.

You can also view it through debug mode.

#Modify config object

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

For example, registering a built-in Rspack plugin:

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

export default {
  tools: {
    rspack: {
      plugins: [
        new rspack.CircularDependencyRspackPlugin({
          // options
        }),
      ],
    },
  },
};

Or registering a community webpack plugin:

import { sentryWebpackPlugin } from '@sentry/webpack-plugin';

export default {
  tools: {
    rspack: {
      plugins: [
        sentryWebpackPlugin({
          // options
        }),
      ],
    },
  },
};

Or modify the built-in 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.

#Access Rspack API

If you need to access the API or plugins exported by @rspack/core, you can directly import the rspack object from @rsbuild/core without installing the @rspack/core package separately.

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

export default {
  tools: {
    rspack: {
      plugins: [
        new rspack.BannerPlugin({
          // ...
        }),
      ],
    },
  },
};

#Use bundler chain

rspack-chain is a utility library for configuring Rspack. It provides a chaining API, making the configuration of Rspack more flexible. By using rspack-chain, you can more easily modify and extend Rspack configurations without directly manipulating the complex configuration object.

#tools.bundlerChain

Rsbuild provides the tools.bundlerChain config to modify the rspack-chain. Its value is a function that takes two arguments:

• The first argument is an rspack-chain instance, which you can use to modify the Rspack config.
• The second argument is an utils object, including env, isProd, CHAIN_ID, etc.

Here is a basic example:

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

tools.bundlerChain can also be an async function:

export default {
  tools: {
    bundlerChain: (chain, { env }) => {
      const value = await fetchValue();
      chain.devtool(value);
    },
  },
};

#Basics

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

#About ID

In short, the rspack-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 CSS rule using CHAIN_ID.RULE.CSS:

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module.rules.delete(CHAIN_ID.RULE.CSS);
    },
  },
};

#ID types

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

#Examples

#Custom loader

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

• Add a loader to handle .md files:

export default {
  tools: {
    bundlerChain: (chain) => {
      chain.module
        .rule('md')
        .test(/\.md$/)
        .use('md-loader')
        // The package name or module path of the loader
        .loader('md-loader');
    },
  },
};

• Modify options of the built-in SWC loader:

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        .use(CHAIN_ID.USE.SWC)
        .tap((options) => {
          console.log(options);
          return options;
        });
    },
  },
};

• Remove the built-in SWC loader:

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module.rule(CHAIN_ID.RULE.JS).uses.delete(CHAIN_ID.USE.SWC);
    },
  },
};

• Insert a loader after the built-in SWC loader that executes earlier:

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        .use('my-loader')
        .after(CHAIN_ID.USE.SWC)
        // The package name or module path of the loader
        .loader('my-loader')
        .options({
          // some options
        });
    },
  },
};

Note: Rspack loaders are executed in reverse order.

• Insert a loader before the built-in SWC loader that executes later:

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        // Loader ID, not actually meaningful, just for locating
        .use('my-loader')
        .before(CHAIN_ID.USE.SWC)
        // The package name or module path of the loader
        .loader('my-loader')
        .options({
          // some options
        });
    },
  },
};

• Remove the built-in CSS handling rule:

export default {
  tools: {
    bundlerChain: (chain, { CHAIN_ID }) => {
      chain.module.rules.delete(CHAIN_ID.RULE.CSS);
    },
  },
};

#Custom 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 (env === 'development' || env === 'test') {
        // ...
      }
      if (isProd) {
        // ...
      }
      if (target === 'node') {
        // ...
      }
      if (isServer) {
        // ...
      }
      if (isWebWorker) {
        // ...
      }
    },
};

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

#Configuration modification order

Rsbuild supports modifying the Rspack configuration object through tools.rspack, tools.bundlerChain, modifyBundlerChain, etc.

The order of execution between them is:

• modifyBundlerChain
• tools.bundleChain
• modifyRspackConfig
• tools.rspack