Configure Rspack#

Rsbuild supports directly modifying the Rspack configuration object, and also 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, 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#

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's 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 HTML plugin using CHAIN_ID.PLUGIN.HTML:

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

ID Types#

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

Examples#

Configure 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);
    },
  },
};

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 (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