close
Guide
Config
Plugin
API
Community
Guide
Config
Plugin
API
Community

tools.bundlerChain

  • Type:
type BundlerChainFn = (
  chain: RspackChain,
  utils: ModifyBundlerChainUtils,
) => Promise<void> | void;

  • Default: undefined

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.

You can use rspack-chain to modify the default Rspack config through tools.bundlerChain. Its value is a function that takes two arguments:

  • The first argument is a 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.

tools.bundlerChain will be executed earlier than tools.rspack, so it will be overridden by tools.rspack.

TIP

The built-in Rspack config in Rsbuild may change with iterations, and these changes won't be reflected in semver. Therefore, your custom config may become invalid when you upgrade Rsbuild.

Examples

Please refer to: RspackChain examples.

Utils

env

  • Type: 'development' | 'production' | 'test'

The env parameter can be used to determine whether the current environment is development, production or test. For example:

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

isDev

  • Type: boolean

Used to determine whether the current build is a development build, such as:

export default {
  tools: {
    bundlerChain: (config, { isDev }) => {
      if (isDev) {
        config.devtool = 'eval-cheap-source-map';
      }
      return config;
    },
  },
};

isProd

  • Type: boolean

Used to determine whether the current build is a production build, such as:

export default {
  tools: {
    bundlerChain: (chain, { isProd }) => {
      if (isProd) {
        chain.devtool('source-map');
      }
    },
  },
};

target

  • Type: 'web' | 'node' | 'web-worker'

The target parameter can be used to determine the build target environment. For example:

export default {
  tools: {
    bundlerChain: (chain, { target }) => {
      if (target === 'node') {
        // ...
      }
    },
  },
};

isServer

  • Type: boolean

Determines whether the target environment is node, equivalent to target === 'node'.

export default {
  tools: {
    bundlerChain: (chain, { isServer }) => {
      if (isServer) {
        // ...
      }
    },
  },
};

isWebWorker

  • Type: boolean

Determines whether the target environment is web-worker, equivalent to target === 'web-worker'.

export default {
  tools: {
    bundlerChain: (chain, { isWebWorker }) => {
      if (isWebWorker) {
        // ...
      }
    },
  },
};

HtmlPlugin

  • Type: typeof import('html-rspack-plugin')

The instance of html-rspack-plugin:

export default {
  tools: {
    bundlerChain: (chain, { HtmlPlugin }) => {
      console.log(HtmlPlugin);
    },
  },
};

CHAIN_ID

Some common Chain IDs are predefined in the Rsbuild, and you can use these IDs to locate the built-in Rule or Plugin.

TIP

Please note that some of the rules or plugins listed below are not available by default. They will only be included in the Rspack or webpack configuration when you enable specific options or register certain plugins.

For example, the RULE.STYLUS rule exists only when the Stylus plugin is registered.

CHAIN_ID.RULE

ID Description
RULE.JS Rule for js and ts
RULE.SVG Rule for svg
RULE.CSS Rule for css
RULE.LESS Rule for less
RULE.SASS Rule for sass
RULE.YAML Rule for yaml
RULE.WASM Rule for WASM
RULE.FONT Rule for font
RULE.IMAGE Rule for image
RULE.MEDIA Rule for media
RULE.VUE Rule for vue (requires Vue plugin)
RULE.SVELTE Rule for svelte (requires Svelte plugin)
RULE.STYLUS Rule for stylus (requires Stylus plugin)

CHAIN_ID.ONE_OF

ONE_OF.[ID] can match a certain type of rule in the rule array.

ID Description
ONE_OF.SVG_URL Rules for SVG, output as a separate file
ONE_OF.SVG_INLINE Rules for SVG, inlined into bundles as data URIs
ONE_OF.SVG_ASSETS Rules for SVG, automatic choice between data URI and separate file

CHAIN_ID.USE

USE.[ID] can match a certain loader.

ID Description
USE.SWC correspond to builtin:swc-loader
USE.STYLE correspond to style-loader
USE.POSTCSS correspond to postcss-loader
USE.LESS correspond to less-loader (requires Less plugin)
USE.SASS correspond to sass-loader (requires Sass plugin)
USE.RESOLVE_URL correspond to resolve-url-loader (requires Sass plugin)
USE.VUE correspond to vue-loader (requires Vue plugin)
USE.SVGR correspond to svgr-loader (requires Svgr plugin)
USE.BABEL correspond to babel-loader (requires Babel plugin)
USE.SVELTE correspond to svelte-loader (requires Svelte plugin)
USE.STYLUS correspond to stylus-loader (requires Stylus plugin)

CHAIN_ID.PLUGIN

PLUGIN.[ID] can match a certain Rspack or Webpack plugin.

ID Description
PLUGIN.HTML correspond to HtmlRspackPlugin, you need to concat the entry name when using: ${PLUGIN.HTML}-${entryName}
PLUGIN.BUNDLE_ANALYZER correspond to WebpackBundleAnalyzer
PLUGIN.VUE_LOADER_PLUGIN correspond to VueLoaderPlugin

CHAIN_ID.MINIMIZER

MINIMIZER.[ID] can match a certain minimizer.

ID Description
MINIMIZER.JS correspond to SwcJsMinimizerRspackPlugin
MINIMIZER.CSS correspond to LightningCssMinimizerRspackPlugin