简体中文

tools.bundlerChain

类型：

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

默认值： undefined

rspack-chain 是一个用于配置 Rspack 的工具库。它提供了链式 API，使得配置 Rspack 变得更加灵活。通过使用 rspack-chain，你可以更方便地修改和扩展 Rspack 配置，而不需要直接操作复杂的配置对象。

你可以通过 tools.bundlerChain 来调用 rspack-chain 以修改默认的 Rspack 配置，它的值是一个函数，接收两个参数：

第一个参数为 rspack-chain 实例，你可以通过它来修改 Rspack 配置。
第二个参数为一个工具对象，包括 env、isProd、CHAIN_ID 等。

tools.bundlerChain 会早于 tools.rspack 被执行，因此会被 tools.rspack 覆盖。

TIP

Rsbuild 内置的 Rspack 配置会随着迭代而发生变化，这些变化不会反映在 semver 中，因此在升级 Rsbuild 时，你的自定义配置可能会失效。

示例

参考：RspackChain 示例。

工具对象

env

类型： 'development' | 'production' | 'test'

通过 env 参数可以判断当前环境为 development、production 还是 test，比如：

rsbuild.config.ts

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

isDev

类型： boolean

一个布尔值，表示当前是否为开发模式构建，当 mode 为 development 时，值为 true。

rsbuild.config.ts

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

isProd

类型： boolean

一个布尔值，表示当前是否为生产模式构建，当 mode 为 production 时，值为 true。

rsbuild.config.ts

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

target

类型： 'web' | 'node' | 'web-worker'

当前构建目标。

你可以为不同的构建目标设置不同的 Rspack 配置，比如：

rsbuild.config.ts

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

isServer

类型： boolean

一个布尔值，表示当前构建目标是否为 node，等价于 target === 'node'。

rsbuild.config.ts

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

isWebWorker

类型： boolean

一个布尔值，表示当前构建目标是否为 web-worker，等价于 target === 'web-worker'。

rsbuild.config.ts

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

rspack

类型： Rspack

Rspack 实例，等价于 import { rspack } from '@rsbuild/core'。

rsbuild.config.ts

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

environment

类型： EnvironmentContext

和当前环境有关的上下文信息。

rsbuild.config.ts

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

HtmlPlugin

类型： typeof import('html-rspack-plugin')

对应 html-rspack-plugin 插件的默认导出。

rsbuild.config.ts

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

CHAIN_ID

Rsbuild 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。

TIP

请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。

比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。

CHAIN_ID.RULE

ID	描述
`RULE.JS`	处理 `js` 和 `ts` 的规则
`RULE.SVG`	处理 `svg` 的规则
`RULE.CSS`	处理 `css` 的规则
`RULE.LESS`	处理 `less` 的规则
`RULE.SASS`	处理 `sass` 的规则
`RULE.WASM`	处理 `wasm` 的规则
`RULE.FONT`	处理 `font` 的规则
`RULE.IMAGE`	处理 `image` 的规则
`RULE.MEDIA`	处理 `media` 的规则
`RULE.VUE`	处理 `vue` 的规则（依赖 Vue 插件）
`RULE.SVELTE`	处理 `svelte` 的规则（依赖 Svelte 插件）
`RULE.STYLUS`	处理 `stylus` 的规则（依赖 Stylus 插件）

CHAIN_ID.ONE_OF

通过 ONE_OF.[ID] 可以匹配到规则数组中的某一类规则。

ID	描述
`ONE_OF.SVG_URL`	处理 SVG 的规则，输出为单独文件
`ONE_OF.SVG_INLINE`	处理 SVG 的规则，作为 data URI 内联到 bundle 中
`ONE_OF.SVG_ASSETS`	处理 SVG 的规则，在 data URI 和单独文件之间自动选择

CHAIN_ID.USE

通过 USE.[ID] 可以匹配到对应的 loader。

ID	描述
`USE.SWC`	对应 `builtin:swc-loader`
`USE.POSTCSS`	对应 `postcss-loader`
`USE.STYLE`	对应 `style-loader`

详见自定义 loader

CHAIN_ID.PLUGIN

通过 PLUGIN.[ID] 可以匹配到特定的 Rspack 或 webpack plugin。

详见自定义 Plugin

CHAIN_ID.MINIMIZER

通过 MINIMIZER.[ID] 可以匹配到对应的压缩工具。

ID	描述
`MINIMIZER.JS`	对应 SwcJsMinimizerRspackPlugin
`MINIMIZER.CSS`	对应 LightningCssMinimizerRspackPlugin

tools.bundlerChain

类型：

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

默认值： undefined

你可以通过 tools.bundlerChain 来调用 rspack-chain 以修改默认的 Rspack 配置，它的值是一个函数，接收两个参数：

第一个参数为 rspack-chain 实例，你可以通过它来修改 Rspack 配置。
第二个参数为一个工具对象，包括 env、isProd、CHAIN_ID 等。

tools.bundlerChain 会早于 tools.rspack 被执行，因此会被 tools.rspack 覆盖。

TIP

Rsbuild 内置的 Rspack 配置会随着迭代而发生变化，这些变化不会反映在 semver 中，因此在升级 Rsbuild 时，你的自定义配置可能会失效。

示例

参考：RspackChain 示例。

工具对象

env

类型： 'development' | 'production' | 'test'

通过 env 参数可以判断当前环境为 development、production 还是 test，比如：

rsbuild.config.ts

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

isDev

类型： boolean

一个布尔值，表示当前是否为开发模式构建，当 mode 为 development 时，值为 true。

rsbuild.config.ts

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

isProd

类型： boolean

一个布尔值，表示当前是否为生产模式构建，当 mode 为 production 时，值为 true。

rsbuild.config.ts

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

target

类型： 'web' | 'node' | 'web-worker'

当前构建目标。

你可以为不同的构建目标设置不同的 Rspack 配置，比如：

rsbuild.config.ts

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

isServer

类型： boolean

一个布尔值，表示当前构建目标是否为 node，等价于 target === 'node'。

rsbuild.config.ts

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

isWebWorker

类型： boolean

一个布尔值，表示当前构建目标是否为 web-worker，等价于 target === 'web-worker'。

rsbuild.config.ts

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

rspack

类型： Rspack

Rspack 实例，等价于 import { rspack } from '@rsbuild/core'。

rsbuild.config.ts

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

environment

类型： EnvironmentContext

和当前环境有关的上下文信息。

rsbuild.config.ts

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

HtmlPlugin

类型： typeof import('html-rspack-plugin')

对应 html-rspack-plugin 插件的默认导出。

rsbuild.config.ts

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

CHAIN_ID

Rsbuild 中预先定义了一些常用的 Chain ID，你可以通过这些 ID 来定位到内置的 Rule 或 Plugin。

TIP

请留意，下列的一部分 Rule 或 Plugin 并不是默认存在的，当你开启特定配置项、或是注册某些插件后，它们才会被包含在 Rspack 或 webpack 配置中。

比如，RULE.STYLUS 仅在注册了 Stylus 插件后才会存在。

CHAIN_ID.RULE

ID	描述
`RULE.JS`	处理 `js` 和 `ts` 的规则
`RULE.SVG`	处理 `svg` 的规则
`RULE.CSS`	处理 `css` 的规则
`RULE.LESS`	处理 `less` 的规则
`RULE.SASS`	处理 `sass` 的规则
`RULE.WASM`	处理 `wasm` 的规则
`RULE.FONT`	处理 `font` 的规则
`RULE.IMAGE`	处理 `image` 的规则
`RULE.MEDIA`	处理 `media` 的规则
`RULE.VUE`	处理 `vue` 的规则（依赖 Vue 插件）
`RULE.SVELTE`	处理 `svelte` 的规则（依赖 Svelte 插件）
`RULE.STYLUS`	处理 `stylus` 的规则（依赖 Stylus 插件）

CHAIN_ID.ONE_OF

通过 ONE_OF.[ID] 可以匹配到规则数组中的某一类规则。

ID	描述
`ONE_OF.SVG_URL`	处理 SVG 的规则，输出为单独文件
`ONE_OF.SVG_INLINE`	处理 SVG 的规则，作为 data URI 内联到 bundle 中
`ONE_OF.SVG_ASSETS`	处理 SVG 的规则，在 data URI 和单独文件之间自动选择

CHAIN_ID.USE

通过 USE.[ID] 可以匹配到对应的 loader。

ID	描述
`USE.SWC`	对应 `builtin:swc-loader`
`USE.POSTCSS`	对应 `postcss-loader`
`USE.STYLE`	对应 `style-loader`

详见自定义 loader

CHAIN_ID.PLUGIN

通过 PLUGIN.[ID] 可以匹配到特定的 Rspack 或 webpack plugin。

详见自定义 Plugin

CHAIN_ID.MINIMIZER

通过 MINIMIZER.[ID] 可以匹配到对应的压缩工具。

ID	描述
`MINIMIZER.JS`	对应 SwcJsMinimizerRspackPlugin
`MINIMIZER.CSS`	对应 LightningCssMinimizerRspackPlugin

#tools.bundlerChain

#示例

#工具对象

#env

#isDev

#isProd

#target

#isServer

#isWebWorker

#rspack

#environment

#HtmlPlugin

#CHAIN_ID

#CHAIN_ID.RULE

#CHAIN_ID.ONE_OF

#CHAIN_ID.USE

#CHAIN_ID.PLUGIN

#CHAIN_ID.MINIMIZER

#tools.bundlerChain

#示例

#工具对象

#env

#isDev

#isProd

#target

#isServer

#isWebWorker

#rspack

#environment

#HtmlPlugin

#CHAIN_ID

#CHAIN_ID.RULE

#CHAIN_ID.ONE_OF

#CHAIN_ID.USE

#CHAIN_ID.PLUGIN

#CHAIN_ID.MINIMIZER

tools.bundlerChain

示例

工具对象

env

isDev

isProd

target

isServer

isWebWorker

rspack

environment

HtmlPlugin

CHAIN_ID

CHAIN_ID.RULE

CHAIN_ID.ONE_OF

CHAIN_ID.USE

CHAIN_ID.PLUGIN

CHAIN_ID.MINIMIZER

tools.bundlerChain

示例

工具对象

env

isDev

isProd

target

isServer

isWebWorker

rspack

environment

HtmlPlugin

CHAIN_ID

CHAIN_ID.RULE

CHAIN_ID.ONE_OF

CHAIN_ID.USE

CHAIN_ID.PLUGIN

CHAIN_ID.MINIMIZER