Plugin Hooks#

This section describes the lifetime hooks provided by Rsbuild plugin.

Overview#

Common Hooks

• modifyRsbuildConfig: Modify raw config of Rsbuild.
• modifyRspackConfig: Modify raw config of Rspack.
• modifyBundlerChain: Modify config of Rspack or webpack via the bundler chain api.
• onBeforeCreateCompiler: Called before creating compiler instance.
• onAfterCreateCompiler: Called after the compiler object is created, but before the build is executed.

Build Hooks: Called only when the build method is executed to build the production outputs.

• onBeforeBuild: Called before the production build is executed.
• onAfterBuild: Called after executing the production build, you can get the build stats.

Dev Server Hooks: Called only when the startDevServer method is executed to run the development server.

• onBeforeStartDevServer: Called before starting the development server.
• onAfterStartDevServer: Called after starting the development server.
• onDevCompileDone: Called after each development compile.

Prod Server Hooks: Called only when the preview method is executed to run the production preview server.

• onBeforeStartProdServer: Called before starting the production server.
• onAfterStartProdServer: Called after starting the production server.

Other Hooks

• onExit: Called when the process is going to exit.

Common Hooks#

modifyRsbuildConfig#

Modify the config passed to the Rsbuild, you can directly modify the config object, or return a new object to replace the previous object.

• Type:

type ModifyRsbuildConfigUtils = {
  mergeRsbuildConfig: typeof mergeRsbuildConfig;
};

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

• Example:

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#

To modify the final Rspack config object, you can directly modify the config object, or return a new object to replace the previous object.

• Type:

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;

• Example:

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

modifyBundlerChain#

Bundler chain is a subset of webpack chain, which contains part of the webpack chain API that you can use to modify both Rspack and webpack configuration.

modifyBundlerChain is used to call the bundler chain to modify the Rspack configuration.

This hook only supports modifying the configuration of the non-differentiated parts of Rspack and webpack. For example, modifying the devtool configuration option (Rspack and webpack have the same devtool property value type), or adding an Rspack-compatible webpack plugin.

• Type:

type ModifyBundlerChainUtils = {
  env: NodeEnv;
  isProd: boolean;
  target: RsbuildTarget;
  isServer: boolean;
  isWebWorker: boolean;
  CHAIN_ID: ChainIdentifier;
  HtmlPlugin: typeof import('html-webpack-plugin');
  bundler: {
    // Depends on bundler type
    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;

• Example:

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 is a callback function that is triggered after the Compiler instance has been created, but before the build process begins. This hook is called when you run rsbuild.startDevServer, rsbuild.build, or rsbuild.createCompiler.

You can access the Compiler instance object through the compiler parameter:

• If the current bundler is Rspack, you will get the Rspack Compiler object.

• If the current bundler is webpack, you will get the webpack Compiler object.

• Type:

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

• Example:

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

onAfterCreateCompiler#

onAfterCreateCompiler is a callback function that is triggered after the compiler instance has been created, but before the build process. This hook is called when you run rsbuild.startDevServer, rsbuild.build, or rsbuild.createCompiler.

You can access the Compiler instance object through the compiler parameter:

• If the current bundler is Rspack, you will get the Rspack Compiler object.

• If the current bundler is webpack, you will get the webpack Compiler object.

• Type:

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

• Example:

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

Build Hooks#

onBeforeBuild#

onBeforeBuild is a callback function that is triggered before the production build is executed. You can access the final configuration array of the underlying bundler through the `bundlerConfigs' parameter:

• If the current bundler is Rspack, you will get an Rspack configuration array.

• If the current bundler is webpack, you will get a webpack configuration array.

• The configuration array can contain one or more configurations, depending on the current target config of Rsbuild.

• Type:

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

• Example:

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

onAfterBuild#

onAfterBuild is a callback function that is triggered after running the production build. You can access the build result information via the `stats' parameter:

• If the current bundler is Rspack, you will get Rspack Stats.

• If the current bundler is webpack, you will get webpack Stats.

• Type:

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

• Example:

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

Dev Server Hooks#

onBeforeStartDevServer#

Called before starting the development server.

• Type:

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

• Example:

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

onAfterStartDevServer#

Called after starting the development server, you can get the port number through the port parameter.

• Type:

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

• Example:

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

onDevCompileDone#

Called after each development environment build, you can use isFirstCompile to determine whether it is the first build.

• Type:

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

• Example:

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

Prod Server Hooks#

onBeforeStartProdServer#

Called before starting the production preview server.

• Type:

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

• Example:

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

onAfterStartProdServer#

Called after starting the production preview server, you can get the port number through the port parameter.

• Type:

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

• Example:

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

Other Hooks#

onExit#

Called when the process is going to exit, this hook can only execute synchronous code.

• Type:

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

• Example:

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