Compilation Hooks#

buildModule#

Triggered before a module build has started。

• Type: SyncHook<[Module]>
• Arguments:
  • Module: module instance

type Module = {
  context?: string;
  resource?: string;
  request?: string;
  userRequest?: string;
  rawRequest?: string;
  factoryMeta?: JsFactoryMeta;
  buildInfo: Record<string, any>;
  buildMeta: Record<string, any>;
  originalSource(): {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  } | null;
  identifier(): string;
  nameForCondition(): string | null;
};

executeModule#

If there exists compiled-time execution modules, this hook will be called when they are executed.

• Type: SyncHook<[ExecuteModuleArgument, ExecuteModuleContext]>
• Arguments:
  • ExecuteModuleArgument: arguments of compiled-time execution module
  • ExecuteModuleContext: context of compiled-time execution module

type ExecuteModuleArgument = {
  codeGenerationResult: {
    get(sourceType: string): string;
  };
  moduleObject: {
    id: string;
    exports: any;
    loaded: boolean;
    error?: Error;
  };
};

type ExecuteModuleContext = {
  __webpack_require__: (id: string) => any;
};

succeedModule#

Executed when a module has been built successfully.

• Type: SyncHook<[Module]>
• Arguments:
  • Module: module instance

finishModules#

Called when all modules have been built without errors.

• Type: AsyncSeriesHook<[Module[]]>
• Arguments:
  • Module[]: List of module instances

optimizeModules#

Called at the beginning of the module optimization phase.

• Type: SyncBailHook<[Module[]]>
• Arguments:
  • Module[]: list of module instances

afterOptimizeModules#

Called after modules optimization has completed.

• Type: SyncBailHook<[Module[]]>
• Arguments:
  • Module[]: list of module instances

optimizeTree#

Called before optimizing the dependency tree.

• Type: AsyncSeriesHook<[Chunk[], Module[]]>
• Arguments:
  • Chunk[]: list of chunk instances
  • Module[]: list of module instances

type Chunk = {
  name?: string;
  id?: string;
  ids: string[];
  idNameHints: string[];
  filenameTemplate?: string;
  cssFilenameTemplate?: string;
  files: Set<string>;
  runtime: Set<string>;
  hash?: string;
  contentHash: Record<string, string>;
  renderedHash?: string;
  chunkReason?: string;
  auxiliaryFiles: Set<string>;
  isOnlyInitial(): boolean;
  canBeInitial(): boolean;
  hasRuntime(): boolean;
  groupsIterable: Set<ChunkGroup>;
  getAllAsyncChunks(): Set<Chunk>;
  getAllInitialChunks(): Set<Chunk>;
  getAllReferencedChunks(): Set<Chunk>;
};

optimizeChunkModules#

Called after the tree optimization, at the beginning of the chunk modules optimization.

• Type: AsyncSeriesBailHook<[Chunk[], Module[]]>
• Arguments:
  • Chunk[]: list of chunk instances
  • Module[]: list of module instances

additionalTreeRuntimeRequirements#

Called after the tree runtime requirements collection.

• Type: SyncHook<[Chunk, Set<RuntimeGlobals>]>
• Arguments:
  • Chunk: chunk instance
  • Set<RuntimeGlobals>: runtime requirements

enum RuntimeGlobals {}

runtimeModule#

Called after a runtime module is added into the compilation.

• Type: SyncHook<[RuntimeModule, Chunk]>
• Arguments:
  • RuntimeModule: runtime module instance
  • Chunk: chunk instance

type RuntimeModule = {
  source?: {
    isRaw: boolean;
    isBuffer: boolean;
    source: Buffer;
    map?: Buffer;
  };
  moduleIdentifier: string;
  constructorName: string;
  name: string;
};

processAssets#

Process the assets before emit.

• Type: AsyncSeriesHook<Assets>
• Hook parameters:
  • name: string — a name of the plugin
  • stage: Stage — a stage to tap into (see the process assets stages below)
• Arguments:
  • assets: Assets: a plain object, where key is the asset's pathname, and the value is data of the asset represented by the Source.

type Assets = Record<
  string,
  {
    source(): string | ArrayBuffer;
    buffer(): Buffer;
    size(): number;
    map(options?: MapOptions): RawSourceMap | null;
    sourceAndMap(options?: MapOptions): SourceAndMapResult;
  }
>;

Process assets examples#

• Emit a new asset in the PROCESS_ASSETS_STAGE_ADDITIONAL stage:

compiler.hooks.thisCompilation.tap('MyPlugin', compilation => {
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: compilation.PROCESS_ASSETS_STAGE_ADDITIONAL,
    },
    assets => {
      const { RawSource } = compiler.webpack.sources;
      const source = new RawSource('This is a new asset!');
      compilation.emitAsset('new-asset.txt', source);
    },
  );
});

• Updating an existing asset:

compiler.hooks.thisCompilation.tap('MyPlugin', compilation => {
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: compilation.PROCESS_ASSETS_STAGE_ADDITIONS,
    },
    assets => {
      const asset = assets['foo.js'];
      if (!asset) {
        return;
      }

      const { RawSource } = compiler.webpack.sources;
      const oldContent = asset.source();
      const newContent = oldContent + '\nconsole.log("hello world!")';
      const source = new RawSource(newContent);

      compilation.updateAsset(assetName, source);
    },
  );
});

• Removing an asset:

compiler.hooks.thisCompilation.tap('MyPlugin', compilation => {
  compilation.hooks.processAssets.tap(
    {
      name: 'MyPlugin',
      stage: compilation.PROCESS_ASSETS_STAGE_OPTIMIZE,
    },
    assets => {
      const assetName = 'unwanted-script.js';
      if (assets[assetName]) {
        compilation.deleteAsset(assetName);
      }
    },
  );
});

Process assets stages#

Here's the list of supported stages. Rspack will execute these stages sequentially from top to bottom. Please select the appropriate stage based on the operation you need to perform.

• PROCESS_ASSETS_STAGE_ADDITIONAL — add additional assets to the compilation.
• PROCESS_ASSETS_STAGE_PRE_PROCESS — basic preprocessing of the assets.
• PROCESS_ASSETS_STAGE_DERIVED — derive new assets from the existing assets.
• PROCESS_ASSETS_STAGE_ADDITIONS — add additional sections to the existing assets e.g. banner or initialization code.
• PROCESS_ASSETS_STAGE_OPTIMIZE — optimize existing assets in a general way.
• PROCESS_ASSETS_STAGE_OPTIMIZE_COUNT — optimize the count of existing assets, e.g. by merging them.
• PROCESS_ASSETS_STAGE_OPTIMIZE_COMPATIBILITY — optimize the compatibility of existing assets, e.g. add polyfills or vendor prefixes.
• PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE — optimize the size of existing assets, e.g. by minimizing or omitting whitespace.
• PROCESS_ASSETS_STAGE_DEV_TOOLING — add development tooling to the assets, e.g. by extracting a source map.
• PROCESS_ASSETS_STAGE_OPTIMIZE_INLINE — optimize the numbers of existing assets by inlining assets into other assets.
• PROCESS_ASSETS_STAGE_SUMMARIZE — summarize the list of existing assets.
• PROCESS_ASSETS_STAGE_OPTIMIZE_HASH — optimize the hashes of the assets, e.g. by generating real hashes of the asset content.
• PROCESS_ASSETS_STAGE_OPTIMIZE_TRANSFER — optimize the transfer of existing assets, e.g. by preparing a compressed (gzip) file as separate asset.
• PROCESS_ASSETS_STAGE_ANALYSE — analyze the existing assets.
• PROCESS_ASSETS_STAGE_REPORT — creating assets for the reporting purposes.

afterProcessAssets#

Called after the processAssets hook had finished without error.

• Type: SyncHook<Assets>
• Arguments:
  • Assets: list of asset instances

afterSeal#

Called after the seal phase.

• Type: AsyncSeriesHook<[]>

chunkHash#

Triggered to emit the hash for each chunk.

• Type: SyncHook<[Chunk, Hash]>
• Arguments:
  • Chunk: chunk instance
  • Hash: chunk hash instance

type Hash = {
  update(data: string | Buffer, inputEncoding?: string): Hash;
  digest(encoding?: string): string | Buffer;
};

chunkAsset#

Triggered when an asset from a chunk was added to the compilation.

• Type: SyncHook<[Chunk, string]>
• Arguments:
  • Chunk: chunk instance
  • string: asset filename

childCompiler#

Executed after setting up a child compiler.

• Type: SyncHook<[Compiler, string, number]>
• Arguments:
  • Compiler: child compiler instance
  • string: child compiler name
  • number: child compiler index

statsPreset#

This hook is like a list of actions that gets triggered when a preset is used. It takes in an options object. When a plugin manages a preset, it should change settings in this object carefully without replacing existing ones.

• Type: SyncHook<[Partial<StatsOptions>, CreateStatsOptionsContext]>
• Arguments:
  • Partial<StatsOptions>: stats options
  • CreateStatsOptionsContext: stats context

type StatsOptions = {
  // `stats` in compiler options
};

type CreateStatsOptionsContext = {
  forToString?: boolean;
  [key: string]: any;
};

Here's an illustrative plugin example:

compilation.hooks.statsPreset.for('my-preset').tap('MyPlugin', options => {
  if (options.all === undefined) options.all = true;
});

This plugin ensures that for the preset "my-preset", if the all option is undefined, it defaults to true.

statsNormalize#

This hook is used to transform an options object into a consistent format that can be easily used by subsequent hooks. It also ensures that missing options are set to their default values.

• Type: SyncHook<[Partial<StatsOptions>, CreateStatsOptionsContext]>
• Arguments:
  • Partial<StatsOptions>: stats options
  • CreateStatsOptionsContext: stats context

Here's an illustrative plugin example:

compilation.hooks.statsNormalize.tap('MyPlugin', options => {
  if (options.myOption === undefined) options.myOption = [];

  if (!Array.isArray(options.myOption)) options.myOptions = [options.myOptions];
});

In this plugin, if the myOption is missing, it sets it to []. Additionally, it ensures that myOption is always an array even if it was originally defined as a single value.

statsFactory#

This hook provides access to the StatsFactory class for specific options.

• Type: SyncHook<[StatsFactory, StatsOptions]>
• Arguments:
  • StatsFactory: stats factory instance, see Stats Factory Hooks for more details
  • StatsOptions: stats options

type StatsFactory = {
  hooks: StatsFactoryHooks;
  create(
    type: string,
    data: any,
    baseContext: Omit<StatsFactoryContext, 'type'>,
  ): void;
};

statsPrinter#

This hook provides access to the StatsPrinter class for specific options.

• Type: SyncHook<[StatsPrinter, StatsOptions]>
• Arguments:
  • StatsPrinter: stats printer instance, see Stats Printer Hooks for more details.
  • StatsOptions: stats options

type StatsPrinter = {
  hooks: StatsPrinterHooks;
  print(
    type: string,
    object: {
      [key: string]: any;
    },
    baseContext?: {
      [key: string]: any;
    },
  ): string;
};