Plugin Hooks

This section describes the lifetime hooks provided by Builder plugin.

Overview

Common Hooks

  • modifyBuilderConfig: Modify raw config of Builder.
  • modifyBundlerChain (experimental): Modify config of webpack or Rspack via the bundler chain api.
  • modifyWebpackChain: Modify webpack-chain.
  • modifyWebpackConfig: Modify raw config of webpack.
  • modifyRspackConfig: Modify raw config of Rspack.
  • 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.

Other Hooks

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

Common Hooks

modifyBuilderConfig

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

  • Type
type ModifyWebpackChainUtils = {
  mergeBuilderConfig: typeof mergeBuilderConfig;
};

function ModifyBuilderConfig(
  callback: (
    config: BuilderConfig,
    utils: ModifyWebpackChainUtils,
  ) => PromiseOrNot<BuilderConfig | void>,
): void;
  • Example
export default () => ({
  setup: api => {
    api.modifyBuilderConfig((config, { mergeBuilderConfig }) => {
      config.html = config.html || {};
      config.html.title = 'Hello World!';
      return mergeBuilderConfig(config, {
        source: { preEntry: 'foo.js' },
      });
    });
  },
});

modifyBundlerChain experimental

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

modifyBundlerChain is used to call the bundler chain to modify the webpack / Rspack configuration. You can use this hook when using webpack-provider or rspack-provider.

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

  • Type
type ModifyBundlerChainUtils = {
  env: NodeEnv;
  isProd: boolean;
  target: BuilderTarget;
  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;
  }
};

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);
    });
  },
});

modifyWebpackChain

Modify the webpack config through the webpack chain. This method is only called when using webpack-provider.

  • Type
type ModifyWebpackChainUtils = {
  env: NodeEnv;
  isProd: boolean;
  target: BuilderTarget;
  webpack: typeof import('webpack');
  isServer: boolean;
  isWebWorker: boolean;
  CHAIN_ID: ChainIdentifier;
  HtmlPlugin: typeof import('html-webpack-plugin');
};

function ModifyWebpackChain(
  callback: (
    chain: WebpackChain,
    utils: ModifyWebpackChainUtils,
  ) => Promise<void> | void,
): void;
  • Example
export default () => ({
  setup: api => {
    api.modifyWebpackChain((chain, utils) => {
      if (utils.env === 'development') {
        chain.devtool('eval');
      }
    });
  },
});

modifyWebpackConfig

To modify the final webpack config object, you can directly modify the config object, or return a new object to replace the previous object. This method is only called when using webpack-provider.

This method is called later than the modifyWebpackChain hook.

  • Type
type ModifyWebpackConfigUtils = {
  env: NodeEnv;
  isProd: boolean;
  target: BuilderTarget;
  webpack: typeof import('webpack');
  isServer: boolean;
  isWebWorker: boolean;
  CHAIN_ID: ChainIdentifier;
  HtmlPlugin: typeof import('html-webpack-plugin');
  addRules: (rules: RuleSetRule | RuleSetRule[]) => void;
  prependPlugins: (
    plugins: WebpackPluginInstance | WebpackPluginInstance[],
  ) => void;
  appendPlugins: (
    plugins: WebpackPluginInstance | WebpackPluginInstance[],
  ) => void;
  removePlugin: (pluginName: string) => void;
};

function ModifyWebpackConfig(
  callback: (
    config: WebpackConfig,
    utils: ModifyWebpackConfigUtils,
  ) => Promise<WebpackConfig | void> | WebpackConfig | void,
): void;
  • Example
export default () => ({
  setup: api => {
    api.modifyWebpackConfig((config, utils) => {
      if (utils.env === 'development') {
        config.devtool = 'eval';
      }
    });
  },
});

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. This method is only called when using rspack-provider.

  • Type
type ModifyRspackConfigUtils = {
  env: NodeEnv;
  isProd: boolean;
  target: BuilderTarget;
  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';
      }
    });
  },
});

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 builder.startDevServer, builder.build, or builder.createCompiler.

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

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

  • If the current bundler is Rspack, you will get the Rspack 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 builder.startDevServer, builder.build, or builder.createCompiler.

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

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

  • If the current bundler is Rspack, you will get the Rspack 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 webpack, you will get a webpack configuration array.

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

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

  • 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 webpack, you will get webpack Stats.

  • If the current bundler is Rspack, you will get Rspack 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 }) => Promise<void> | void,
): void;
  • Example
export default () => ({
  setup: api => {
    api.onDevCompileDone(({ isFirstCompile }) => {
      if (isFirstCompile) {
        console.log('first compile!');
      } else {
        console.log('re-compile!');
      }
    });
  },
});

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!');
    });
  },
});