Tools

本章节描述了 Rsbuild 中与底层工具有关的配置。

tools.autoprefixer

  • 类型: Object | Function
  • 默认值:
{
  flexbox: 'no-2009',
  // browserslist 取决于项目中的 browserslist 配置
  // 以及 `output.overrideBrowserslist`(优先级更高) 配置
  overrideBrowserslist: browserslist,
}

通过 tools.autoprefixer 可以修改 autoprefixer 的配置。

Object 类型

tools.autoprefixer 的值为 Object 类型时,会与默认配置通过 Object.assign 合并。比如:

export default {
  tools: {
    autoprefixer: {
      flexbox: 'no-2009',
    },
  },
};

Function 类型

tools.autoprefixer 为 Function 类型时,默认配置作为第一个参数传入,可以直接修改配置对象,也可以返回一个值作为最终结果。比如:

export default {
  tools: {
    autoprefixer(config) {
      // 修改 flexbox 的配置
      config.flexbox = 'no-2009';
    },
  },
};

tools.bundlerChain

  • 类型: Function | undefined
  • 默认值: undefined

你可以通过 tools.bundlerChain 来修改默认的 webpack 和 Rspack 配置,它的值为 Function 类型,接收两个参数:

  • 第一个参数为 bundler-chain 对象实例,你可以通过这个实例来修改 webpack 和 Rspack 的配置。
  • 第二个参数为一个工具集合,包括envisProdCHAIN_ID 等。
什么是 BundlerChain

Bundler chain 是 webpack chain 的子集,其中包含一部分 webpack chain API,你可以用它来同时修改 webpack 和 Rspack 的配置。

通过 bundler chain 修改的配置,在 webpack 和 Rspack 构建时均可生效。需要注意的是,bundler chain 只支持修改 webpack 和 Rspack 间无差异部分的配置。如,修改 devtool 配置项(webpack 和 Rspack 的 devtool 属性值类型相同),或添加一个Rspack 兼容的 webpack 插件。

tools.bundlerChain 的执行时机早于 tools.webpackChain / tools.webpack / tools.rspack,因此会被其他几个配置中的修改所覆盖。

工具集合

env

  • 类型: 'development' | 'production' | 'test'

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

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

isProd

  • 类型: boolean

通过 isProd 参数可以判断当前环境是否为 production。比如:

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

target

  • 类型: 'web' | 'node' | 'web-worker'

通过 target 参数可以判断当前构建的目标运行时环境。比如:

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

isServer

  • 类型: boolean

判断当前构建的目标运行时环境是否为 node,等价于 target === 'node'

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

isWebWorker

  • 类型: boolean

判断当前构建的目标运行时环境是否为 web-worker,等价于 target === 'web-worker'

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

HtmlPlugin

  • 类型: typeof import('html-webpack-plugin')

通过这个参数你可以拿到 html-webpack-plugin 插件的实例。

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.MJS 处理 mjs 的规则
RULE.CSS 处理 css 的规则
RULE.LESS 处理 less 的规则
RULE.SASS 处理 sass 的规则
RULE.STYLUS 处理 stylus 的规则
RULE.TOML 处理 toml 的规则
RULE.YAML 处理 yaml 的规则
RULE.WASM 处理 wasm 的规则
RULE.NODE 处理 node 的规则

CHAIN_ID.ONE_OF

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

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

CHAIN_ID.USE

通过 USE.XXX 可以匹配到对应的 loader。

ID 描述
USE.LESS 对应 less-loader
USE.SASS 对应 sass-loader
USE.STYLUS 对应 stylus-loader
USE.VUE 对应 vue-loader
USE.TOML 对应 toml-loader
USE.YAML 对应 yaml-loader
USE.NODE 对应 node-loader
USE.SVGR 对应 @svgr/webpack
USE.POSTCSS 对应 postcss-loader
USE.RESOLVE_URL_LOADER_FOR_SASS 对应 resolve-url-loader

CHAIN_ID.PLUGIN

通过 PLUGIN.XXX 可以匹配到对应的 plugin。

ID 描述
PLUGIN.HTML 对应 HtmlPlugin,使用时需要拼接 entry 名称:${PLUGIN.HTML}-${entryName}
PLUGIN.APP_ICON 对应 AppIconPlugin
PLUGIN.INLINE_HTML 对应 InlineChunkHtmlPlugin
PLUGIN.BUNDLE_ANALYZER 对应 WebpackBundleAnalyzer
PLUGIN.ASSETS_RETRY 对应 Rsbuild 中的 webpack 静态资源重试插件 WebpackAssetsRetryPlugin
PLUGIN.VUE_LOADER_PLUGIN 对应 VueLoaderPlugin
PLUGIN.AUTO_SET_ROOT_SIZE 对应 Rsbuild 中的自动设置根字体大小插件 AutoSetRootSizePlugin

CHAIN_ID.MINIMIZER

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

ID 描述
MINIMIZER.JS 对应 TerserWebpackPluginSwcJsMinimizerRspackPlugin
MINIMIZER.CSS 对应 CssMinimizerWebpackPlugin

使用示例

使用示例可参考:WebpackChain 使用示例

tools.cssLoader

  • 类型: Object | Function
  • 默认值: undefined

通过 tools.cssLoader 可以修改 css-loader 的配置项。默认配置如下:

{
  modules: {
    auto: true,
    exportLocalsConvention: 'camelCase',
    localIdentName: config.output.cssModules.localIdentName,
    // isServer 表示 node (SSR) 构建
    // isWebWorker 表示 web worker 构建
    exportOnlyLocals: isServer || isWebWorker,
  },
  // 默认在开发环境下启用 CSS 的 Source Map
  sourceMap: isDev,
  // importLoaders 在编译 css 文件时为 `1`,在编译 sass/less 文件时为 `2`
  importLoaders: 1 || 2,
}
TIP

在使用 Rspack 作为打包工具时,仅支持在 disableCssExtract 时使用该配置。

修改 CSS Modules 相关配置,推荐使用 output.cssModules 配置项。

Object 类型

当此值为 Object 类型时,会与默认配置进行深层合并 (deep merge)。比如:

export default {
  tools: {
    cssLoader: {
      modules: {
        exportOnlyLocals: true,
      },
    },
  },
};

Function 类型

当此值为 Function 类型时,默认配置作为第一个参数传入,你可以直接修改配置对象,也可以返回一个对象作为最终配置。比如:

export default {
  tools: {
    cssLoader: (config) => {
      config.modules.exportOnlyLocals = true;
      return config;
    },
  },
};

tools.htmlPlugin

  • 类型: false | Object | Function
  • 默认值:
const defaultHtmlPluginOptions = {
  inject, // 对应 html.inject 配置项
  favicon, // 对应 html.favicon 配置项
  filename, // 基于 output.distPath 和 entryName 生成
  template, // 默认为内置的 HTML 模板路径
  templateParameters, // 对应 html.templateParameters 配置项
  chunks: [entryName],
  minify: {
    // 基于 output.disableMinimize 生成
    removeComments: false,
    useShortDoctype: true,
    keepClosingSlash: true,
    collapseWhitespace: true,
    removeRedundantAttributes: true,
    removeScriptTypeAttributes: true,
    removeStyleLinkTypeAttributes: true,
    removeEmptyAttributes: true,
    minifyJS,
    minifyCSS: true,
    minifyURLs: true,
  },
};

通过 tools.htmlPlugin 可以修改 html-webpack-plugin 的配置项。

Object 类型

tools.htmlPlugin 的值为 Object 类型时,会与默认配置通过 Object.assign 合并。

export default {
  tools: {
    htmlPlugin: {
      scriptLoading: 'blocking',
    },
  },
};

Function 类型

tools.htmlPlugin 为 Function 类型时:

  • 第一个参数是默认配置的对象,可以直接修改该对象。
  • 第二个参数是也是一个对象,包含了 entry 的名称和 entry 的值。
  • 函数可以 return 一个新的对象作为最终的配置。
export default {
  tools: {
    htmlPlugin(config, { entryName, entryValue }) {
      if (entryName === 'main') {
        config.scriptLoading = 'blocking';
      }
    },
  },
};

Boolean 类型

tools.htmlPlugin 配置为 false,可以禁用默认的 html-webpack-plugin 插件。

export default {
  tools: {
    htmlPlugin: false,
  },
};

禁用 JS / CSS 压缩

默认情况下,Rsbuild 会在生产环境构建时压缩 HTML 内的 JavaScript / CSS 代码,从而提升页面性能。此能力通常在使用自定义模版或插入自定义脚本时会有帮助。然而,当开启 output.enableInlineScriptsoutput.enableInlineStyles 时,会出现对 inline JavaScript / CSS 代码重复压缩的情况,对构建性能会有一定影响。你可以通过修改 tools.htmlPlugin.minify 配置项来修改默认的压缩行为。

export default {
  tools: {
    htmlPlugin: (config) => {
      if (typeof config.minify === 'object') {
        config.minify.minifyJS = false;
        config.minify.minifyCSS = false;
      }
    },
  },
};

tools.less

  • 类型: Object | Function
  • 默认值:
const defaultOptions = {
  lessOptions: {
    javascriptEnabled: true,
  },
  // 默认在开发环境下启用 CSS 的 Source Map
  sourceMap: isDev,
};

你可以通过 tools.less 修改 less-loader 的配置。

Object 类型

tools.less 的值为 Object 类型时,会与默认配置通过 Object.assign 进行浅层合并,值得注意的是,lessOptions 会通过 deepMerge 进行深层合并。

export default {
  tools: {
    less: {
      lessOptions: {
        javascriptEnabled: false,
      },
    },
  },
};

Function 类型

tools.less 为 Function 类型时,默认配置作为第一个参数传入,可以直接修改配置对象,也可以返回一个值作为最终结果,第二个参数提供了一些可以直接调用的工具函数:

export default {
  tools: {
    less(config) {
      // 修改 lessOptions 配置
      config.lessOptions = {
        javascriptEnabled: false,
      };
    },
  },
};

修改 Less 版本

在某些场景下,如果你需要使用特定的 Less 版本,而不是使用 Rsbuild 内置的 Less v4,可以在项目中安装需要使用的 Less 版本,并通过 less-loaderimplementation 选项设置。

export default {
  tools: {
    less: {
      implementation: require('less'),
    },
  },
};

工具函数

addExcludes

  • 类型: (excludes: RegExp | RegExp[]) => void

用来指定 less-loader 不编译哪些文件,你可以传入一个或多个正则表达式来匹配 less 文件的路径。例如:

export default {
  tools: {
    less(config, { addExcludes }) {
      addExcludes(/node_modules/);
    },
  },
};

tools.postcss

  • 类型: Object | Function
  • 默认值:
const defaultOptions = {
  postcssOptions: {
    plugins: [
      require('postcss-flexbugs-fixes'),
      require('autoprefixer')({ flexbox: 'no-2009' }),
    ],
    // 默认在开发环境下启用 CSS 的 Source Map
    sourceMap: isDev,
  },
};

Rsbuild 默认集成 PostCSS,你可以通过 tools.postcsspostcss-loader 进行配置。

Function 类型

值为 Function 类型时,内部默认配置作为第一参数传入,可以直接修改配置对象不做返回,也可以返回一个对象作为最终结果;第二个参数为修改 postcss-loader 配置的工具函数集合。

例如,需要在原有插件的基础上新增一个 PostCSS 插件,在 postcssOptions.plugins 数组中 push 一个新的插件即可:

export default {
  tools: {
    postcss: (opts) => {
      opts.postcssOptions.plugins.push(require('postcss-px-to-viewport'));
    },
  },
};

需要给 PostCSS 插件传递参数时,可以通过函数参数的形式进行传入:

export default {
  tools: {
    postcss: (opts) => {
      const viewportPlugin = require('postcss-px-to-viewport')({
        viewportWidth: 375,
      });
      opts.postcssOptions.plugins.push(viewportPlugin);
    },
  },
};

tools.postcss 可以返回一个配置对象,并完全替换默认配置:

export default {
  tools: {
    postcss: () => {
      return {
        postcssOptions: {
          plugins: [require('postcss-px-to-viewport')],
        },
      };
    },
  },
};

Object 类型

当此值为 Object 类型时,与默认配置通过 Object.assign 合并。注意 Object.assign 是浅拷贝,会完全覆盖内置的 plugins 数组,请谨慎使用。

export default {
  tools: {
    postcss: {
      // 由于使用 `Object.assign` 合并,因此默认的 postcssOptions 会被覆盖。
      postcssOptions: {
        plugins: [require('postcss-px-to-viewport')],
      },
    },
  },
};

工具函数

addPlugins

  • 类型: (plugins: PostCSSPlugin | PostCSSPlugin[]) => void

用于添加额外的 PostCSS 插件,你可以传入单个 PostCSS 插件,也可以传入 PostCSS 插件数组。

export default {
  tools: {
    postcss: (config, { addPlugins }) => {
      // 添加一个插件
      addPlugins(require('postcss-preset-env'));
      // 批量添加插件
      addPlugins([require('postcss-preset-env'), require('postcss-import')]);
    },
  },
};
TIP

Rsbuild 中使用的 PostCSS 版本为 v8,当你引入社区中的 PostCSS 插件时,请注意版本是否适配,部分旧版本插件可能无法在 PostCSS v8 下运行。

tools.sass

  • 类型: Object | Function
  • 默认值:
const defaultOptions = {
  // 默认在开发环境下启用 CSS 的 Source Map
  sourceMap: isDev,
};

你可以通过 tools.sass 修改 sass-loader 的配置。

Object 类型

tools.sass 的值为 Object 类型时,会与默认配置通过 Object.assign 进行浅层合并,值得注意的是,sassOptions 会通过 deepMerge 进行深层合并。

export default {
  tools: {
    sass: {
      sourceMap: true,
    },
  },
};

Function 类型

tools.sass 为 Function 类型时,默认配置作为第一个参数传入,可以直接修改配置对象,也可以返回一个值作为最终结果,第二个参数提供了一些可以直接调用的工具函数:

export default {
  tools: {
    sass(config) {
      // 修改 sourceMap 配置
      config.additionalData = async (content, loaderContext) => {
        // ...
      };
    },
  },
};

修改 Sass 版本

在某些场景下,如果你需要使用特定的 Sass 版本,而不是使用 Rsbuild 内置的 Dart Sass v1,可以在项目中安装需要使用的 Sass 版本,并通过 sass-loaderimplementation 选项设置。

export default {
  tools: {
    sass: {
      implementation: require('sass'),
    },
  },
};

工具函数

addExcludes

  • 类型: (excludes: RegExp | RegExp[]) => void

用来指定 sass-loader 不编译哪些文件,你可以传入一个或多个正则表达式来匹配 sass 文件的路径。例如:

export default {
  tools: {
    sass(config, { addExcludes }) {
      addExcludes(/node_modules/);
    },
  },
};

tools.styleLoader

  • 类型: Object | Function
  • 默认值: {}

通过 tools.styleLoader 可以设置 style-loader 的配置项。

值得注意的是,Rsbuild 默认不会开启 style-loader,你可以通过 output.disableCssExtract 配置项来开启它。

Object 类型

当此值为 Object 类型时,与默认配置通过 Object.assign 合并。比如:

export default {
  tools: {
    styleLoader: {
      insert: 'head',
    },
  },
};

Function 类型

当此值为 Function 类型时,默认配置作为第一个参数传入,你可以直接修改配置对象,也可以返回一个对象作为最终配置。比如:

export default {
  tools: {
    styleLoader: (config) => {
      config.insert = 'head';
      return config;
    },
  },
};

tools.rspack

  • 类型: Object | Function | undefined
  • 默认值: undefined
  • 打包工具: 仅支持 Rspack

tools.rspack 选项用于配置原生的 Rspack

Object 类型

tools.rspack 可以配置为一个对象,这个对象将会和内置的 Rspack 配置通过 webpack-merge 进行深层合并。

比如添加 resolve.alias 配置:

export default {
  tools: {
    rspack: {
      resolve: {
        alias: {
          '@util': 'src/util',
        },
      },
    },
  },
};

Function 类型

tools.rspack 也可以配置为一个函数,这个函数接收一个参数,即内置的 Rspack 配置对象,你可以对这个对象进行修改,然后返回一份新的配置。比如:

export default {
  tools: {
    rspack: (config) => {
      config.resolve.alias['@util'] = 'src/util';
      return config;
    },
  },
};
TIP

tools.rspack 函数返回的对象会直接作为最终使用的 Rspack 配置,不会再与内置的 Rspack 配置进行合并。

工具集合

这个函数的第二个参数是一个对象,包含了一些工具函数和属性,详情如下:

env

  • 类型: 'development' | 'production' | 'test'

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

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

isProd

  • 类型: boolean

通过 isProd 参数可以判断当前环境是否为 production。比如:

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

target

  • 类型: 'web' | 'node' | 'web-worker'

通过 target 参数可以判断当前构建的目标运行时环境。比如:

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

isServer

  • 类型: boolean

判断当前构建的目标运行时环境是否为 node,等价于 target === 'node'

export default {
  tools: {
    rspack: (config, { isServer }) => {
      if (isServer) {
        // ...
      }
      return config;
    },
  },
};

isWebWorker

  • 类型: boolean

判断当前构建的目标运行时环境是否为 web-worker,等价于 target === 'web-worker'

export default {
  tools: {
    rspack: (config, { isWebWorker }) => {
      if (isWebWorker) {
        // ...
      }
      return config;
    },
  },
};

rspack

  • 类型: typeof import('@rspack/core')

通过这个参数你可以拿到 Rspack 实例。比如:

export default {
  tools: {
    rspack: (config, { rspack }) => {
      config.plugins.push(new rspack.BannerPlugin());
      return config;
    },
  },
};

addRules

  • 类型: (rules: RuleSetRule | RuleSetRule[]) => void

添加额外的 Rspack rules

示例:

export default {
  tools: {
    rspack: (config, { addRules }) => {
      // 添加单条规则
      addRules({
        test: /\.foo/,
        loader: require.resolve('foo-loader'),
      });

      // 以数组形式添加多条规则
      addRules([
        {
          test: /\.foo/,
          loader: require.resolve('foo-loader'),
        },
        {
          test: /\.bar/,
          loader: require.resolve('bar-loader'),
        },
      ]);
    },
  },
};

prependPlugins

  • 类型: (plugins: RspackPluginInstance | RspackPluginInstance[]) => void

在内部 Rspack 插件数组头部添加额外的插件,数组头部的插件会优先执行。

export default {
  tools: {
    rspack: (config, { prependPlugins }) => {
      // 添加单个插件
      prependPlugins(new PluginA());

      // 以数组形式添加多个插件
      prependPlugins([new PluginA(), new PluginB()]);
    },
  },
};

appendPlugins

  • 类型: (plugins: RspackPluginInstance | RspackPluginInstance[]) => void

在内部 Rspack 插件数组尾部添加额外的插件,数组尾部的插件会在最后执行。

export default {
  tools: {
    rspack: (config, { appendPlugins }) => {
      // 添加单个插件
      appendPlugins([new PluginA()]);

      // 以数组形式添加多个插件
      appendPlugins([new PluginA(), new PluginB()]);
    },
  },
};

removePlugin

  • 类型: (name: string) => void

删除内部的 Rspack 插件,参数为该插件的 constructor.name

例如,删除内部的 webpack-bundle-analyzer

export default {
  tools: {
    rspack: (config, { removePlugin }) => {
      removePlugin('BundleAnalyzerPlugin');
    },
  },
};

mergeConfig

  • 类型: (...configs: RspackConfig[]) => RspackConfig

用于合并多份 Rspack 配置,等价于 webpack-merge

export default {
  tools: {
    rspack: (config, { mergeConfig }) => {
      return mergeConfig(config, {
        devtool: 'eval',
      });
    },
  },
};

getCompiledPath

  • 类型: (name: string) => string

获取 Rsbuild 内置依赖的所在路径,例如:

  • sass
  • sass-loader
  • less
  • less-loader
  • babel-loader
  • url-loader
  • file-loader
  • ...

该方法通常在需要与 Rsbuild 复用同一份依赖时会被用到。

TIP

Rsbuild 内部依赖会随着版本迭代而发生变化,例如产生大版本变更。在非必要的情况下,请避免使用此 API。

export default {
  tools: {
    rspack: (config, { getCompiledPath }) => {
      const loaderPath = getCompiledPath('less-loader');
      // ...
    },
  },
};