简体中文

Plugin Hooks

本章节描述了 Rsbuild 插件提供的生命周期钩子。

概览

Common Hooks

modifyRsbuildConfig：修改传递给 Rsbuild 的配置项。
modifyRspackConfig：修改最终的 Rspack 配置对象。
modifyBundlerChain：通过 chain api 修改 Rspack / webpack 配置对象。
onBeforeCreateCompiler：在创建 compiler 实例前调用。
onAfterCreateCompiler：在创建 compiler 实例后、执行构建前调用。

Build Hooks：仅在执行 build 方法构建生产环境产物时调用。

onBeforeBuild：在执行生产环境构建前调用。
onAfterBuild：在执行生产环境构建后调用，可以获取到构建结果信息。

Dev Server Hooks：仅在执行 startDevServer 方法运行开发服务器时调用。

onBeforeStartDevServer：在启动开发服务器前调用。
onAfterStartDevServer：在启动开发服务器后调用。
onDevCompileDone：在每次开发环境构建结束后调用。

Prod Server Hooks：仅在执行 preview 方法运行生产预览服务器时调用。

onBeforeStartProdServer：在启动开发服务器前调用。
onAfterStartProdServer：在启动开发服务器后调用。

Other Hooks

onExit：在进程即将退出时调用。

Common Hooks

modifyRsbuildConfig

修改传递给 Rsbuild 的配置项，你可以直接修改传入的 config 对象，也可以返回一个新的对象来替换传入的对象。

类型：

type ModifyRsbuildConfigUtils = {
  mergeRsbuildConfig: typeof mergeRsbuildConfig;
};

function ModifyRsbuildConfig(
  callback: (
    config: RsbuildConfig,
    utils: ModifyRsbuildConfigUtils,
  ) => PromiseOrNot<RsbuildConfig | void>,
): void;

示例：

export default () => ({
  setup: (api) => {
    api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
      config.html = config.html || {};
      config.html.title = 'Hello World!';
      return mergeRsbuildConfig(config, {
        source: { preEntry: 'foo.js' },
      });
    });
  },
});

modifyRspackConfig

修改最终的 Rspack 配置对象，你可以直接修改传入的 config 对象，也可以返回一个新的对象来替换传入的对象。

类型：

type ModifyRspackConfigUtils = {
  env: NodeEnv;
  isProd: boolean;
  target: RsbuildTarget;
  isServer: boolean;
  isWebWorker: boolean;
  rspack: typeof import('@rspack/core');
};

function ModifyRspackConfig(
  callback: (
    config: RspackConfig,
    utils: ModifyRspackConfigUtils,
  ) => Promise<RspackConfig | void> | RspackConfig | void,
): void;

示例：

export default () => ({
  setup: (api) => {
    api.modifyRspackConfig((config, utils) => {
      if (utils.env === 'development') {
        config.devtool = 'eval';
      }
    });
  },
});

modifyBundlerChain

什么是 BundlerChain

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

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

modifyBundlerChain 用于调用 bundler chain 来修改 Rspack 的配置。

类型：

type ModifyBundlerChainUtils = {
  env: NodeEnv;
  isProd: boolean;
  target: RsbuildTarget;
  isServer: boolean;
  isWebWorker: boolean;
  CHAIN_ID: ChainIdentifier;
  HtmlPlugin: typeof import('html-webpack-plugin');
  bundler: {
    // 取决于 bundler 类型
    BannerPlugin: typeof webpack.BannerPlugin | typeof rspack.BannerPlugin;
    DefinePlugin: typeof webpack.DefinePlugin | typeof rspack.DefinePlugin;
    ProvidePlugin: typeof webpack.ProvidePlugin | typeof rspack.ProvidePlugin;
  };
};

function ModifyBundlerChain(
  callback: (
    chain: BundlerChain,
    utils: ModifyBundlerChainUtils,
  ) => Promise<void> | void,
): void;

示例：

import { BundleAnalyzerPlugin } from 'webpack-bundle-analyzer';

export default () => ({
  setup: (api) => {
    api.modifyBundlerChain((chain, utils) => {
      if (utils.env === 'development') {
        chain.devtool('eval');
      }

      chain.plugin('bundle-analyze').use(BundleAnalyzerPlugin);
    });
  },
});

onBeforeCreateCompiler

onBeforeCreateCompiler 是在创建底层 Compiler 实例前触发的回调函数，当你执行 rsbuild.startDevServer、rsbuild.build 或 rsbuild.createCompiler 时，都会调用此钩子。

你可以通过 bundlerConfigs 参数获取到底层打包工具的最终配置数组：

如果当前打包工具为 Rspack，则获取到的是 Rspack 配置数组。
如果当前打包工具为 webpack，则获取到的是 webpack 配置数组。
配置数组中可能包含一份或多份配置，这取决于你是否开启了 SSR 等功能。

你可以通过 bundlerConfigs 参数获取到底层打包工具的最终配置对象。

类型：

function OnBeforeCreateCompiler(
  callback: (params: {
    bundlerConfigs: WebpackConfig[] | RspackConfig[];
  }) => Promise<void> | void,
): void;

示例：

export default () => ({
  setup: (api) => {
    api.onBeforeCreateCompiler(({ bundlerConfigs }) => {
      console.log('the bundler config is ', bundlerConfigs);
    });
  },
});

onAfterCreateCompiler

onAfterCreateCompiler 是在创建 Compiler 实例后、执行构建前触发的回调函数，当你执行 rsbuild.startDevServer、rsbuild.build 或 rsbuild.createCompiler 时，都会调用此钩子。

你可以通过 compiler 参数获取到 Compiler 实例对象:

如果当前打包工具为 Rspack，则获取到的是 Rspack Compiler 对象。
如果当前打包工具为 webpack，则获取到的是 webpack Compiler 对象。
类型：

function OnAfterCreateCompiler(callback: (params: {
  compiler: Compiler | MultiCompiler;
}) => Promise<void> | void;): void;

示例：

export default () => ({
  setup: (api) => {
    api.onAfterCreateCompiler(({ compiler }) => {
      console.log('the compiler is ', compiler);
    });
  },
});

Build Hooks

onBeforeBuild

onBeforeBuild 是在执行生产环境构建前触发的回调函数，你可以通过 bundlerConfigs 参数获取到底层打包工具的最终配置数组：

如果当前打包工具为 Rspack，则获取到的是 Rspack 配置数组。
如果当前打包工具为 webpack，则获取到的是 webpack 配置数组。
配置数组中可能包含一份或多份配置，这取决于 Rsbuild 当前 target 配置的值。
类型：

function OnBeforeBuild(
  callback: (params: {
    bundlerConfigs?: WebpackConfig[] | RspackConfig[];
  }) => Promise<void> | void,
): void;

示例：

export default () => ({
  setup: (api) => {
    api.onBeforeBuild(({ bundlerConfigs }) => {
      console.log('the bundler config is ', bundlerConfigs);
    });
  },
});

onAfterBuild

onAfterBuild 是在执行生产环境构建后触发的回调函数，你可以通过 stats 参数获取到构建结果信息：

如果当前打包工具为 Rspack，则获取到的是 Rspack Stats。
如果当前打包工具为 webpack，则获取到的是 webpack Stats。
类型：

function OnAfterBuild(
  callback: (params: { stats?: Stats | MultiStats }) => Promise<void> | void,
): void;

示例：

export default () => ({
  setup: (api) => {
    api.onAfterBuild(({ stats }) => {
      console.log(stats?.toJson());
    });
  },
});

Dev Server Hooks

onBeforeStartDevServer

在启动开发服务器前调用。

类型：

function OnBeforeStartDevServer(callback: () => Promise<void> | void): void;

示例：

export default () => ({
  setup: (api) => {
    api.onBeforeStartDevServer(() => {
      console.log('before start!');
    });
  },
});

onAfterStartDevServer

在启动开发服务器后调用，你可以通过 port 参数获得开发服务器监听的端口号。

类型：

function OnAfterStartDevServer(
  callback: (params: { port: number }) => Promise<void> | void,
): void;

示例：

export default () => ({
  setup: (api) => {
    api.onAfterStartDevServer(({ port }) => {
      console.log('this port is: ', port);
    });
  },
});

onDevCompileDone

在每次开发环境构建结束后调用，你可以通过 isFirstCompile 来判断是否为首次构建。

类型：

function OnDevCompileDone(
  callback: (params: {
    isFirstCompile: boolean;
    stats: Stats | MultiStats;
  }) => Promise<void> | void,
): void;

示例：

export default () => ({
  setup: (api) => {
    api.onDevCompileDone(({ isFirstCompile }) => {
      if (isFirstCompile) {
        console.log('first compile!');
      } else {
        console.log('re-compile!');
      }
    });
  },
});

Prod Server Hooks

onBeforeStartProdServer

在启动生产预览服务器前调用。

类型：

function OnBeforeStartProdServer(callback: () => Promise<void> | void): void;

示例：

export default () => ({
  setup: (api) => {
    api.onBeforeStartProdServer(() => {
      console.log('before start!');
    });
  },
});

onAfterStartProdServer

在启动生产预览服务器后调用，你可以通过 port 参数获得生产服务器监听的端口号。

类型：

function OnAfterStartProdServer(
  callback: (params: { port: number }) => Promise<void> | void,
): void;

示例：

export default () => ({
  setup: (api) => {
    api.onAfterStartProdServer(({ port }) => {
      console.log('this port is: ', port);
    });
  },
});

Other Hooks

onExit

在进程即将退出时调用，这个钩子只能执行同步代码。

类型：

function OnExit(callback: () => void): void;

示例：

export default () => ({
  setup: (api) => {
    api.onExit(() => {
      console.log('exit!');
    });
  },
});

Plugin Hooks#

概览#

Common Hooks#

modifyRsbuildConfig#

modifyRspackConfig#

modifyBundlerChain#

onBeforeCreateCompiler#

onAfterCreateCompiler#

Build Hooks#

onBeforeBuild#

onAfterBuild#

Dev Server Hooks#

onBeforeStartDevServer#

onAfterStartDevServer#

onDevCompileDone#

Prod Server Hooks#

onBeforeStartProdServer#

onAfterStartProdServer#

Other Hooks#

onExit#