Master Webpack Plugins: A Deep Dive into Tapable Hooks and Their Usage

Introduction

After using Webpack for a long time, you may be curious about its essential ecosystem components—loaders and plugins. This guide shows how to write your own plugins and understand Webpack's plugin mechanism.

1. Tapable

Webpack works like a production line where each processing step has a single responsibility and depends on the previous step. Plugins are inserted into this line to manipulate resources at specific moments. Tapable organizes this line by broadcasting events; plugins listen to events they care about, allowing orderly extension of the system.

Tapable, the core library of Webpack, provides the event system. Objects such as compiler and compilation inherit from Tapable and expose registered hooks and their execution order.

2. Tapable Hooks

const {
  SyncHook,
  SyncBailHook,
  SyncWaterfallHook,
  SyncLoopHook,
  AsyncParallelHook,
  AsyncParallelBailHook,
  AsyncSeriesHook,
  AsyncSeriesBailHook,
  AsyncSeriesWaterfallHook
} = require("tapable");

The nine hook types are divided into synchronous and asynchronous categories, each with distinct behavior. For example, a simple synchronous hook can be created as follows:

const sync = new SyncHook(['arg']); // 'arg' is a placeholder
sync.tap('Test', (arg1, arg2) => {
  console.log(arg1, arg2); // a, undefined
});
sync.call('a', '2');

The tap method registers a callback, and call triggers the hook. The number of arguments passed to call must match the number defined when the hook was instantiated.

Hook usage summary:

SyncHook – synchronous serial, ignore return value. SyncBailHook – synchronous serial, stop when a non‑null return occurs. SyncWaterfallHook – synchronous serial, passes previous return to next. SyncLoopHook – synchronous serial, repeats while callback returns true. AsyncParallelHook – asynchronous parallel, ignore return value. AsyncParallelBailHook – asynchronous parallel, stop when a non‑null return occurs. AsyncSeriesHook – asynchronous serial, ignore callback arguments. AsyncSeriesBailHook – asynchronous serial, stop when callback argument is non‑null. AsyncSeriesWaterfallHook – asynchronous serial, passes previous callback data to next.

3. Registering Event Callbacks

Three registration methods exist: tap, tapAsync, and tapPromise. The async variants cannot be used with hooks that start with Sync. Example of tapAsync usage:

myCar.hooks.calculateRoutes.tapAsync("BingMapsPlugin", (source, target, routesList, callback) => {
  bing.findRoute(source, target, (err, route) => {
    if (err) return callback(err);
    routesList.add(route);
    // call the callback
    callback();
  });
});

4. Triggering Events

Trigger methods correspond to registration methods: call for tap, callAsync for tapAsync, and promise for tapPromise. Use the matching trigger to ensure proper execution flow.

5. How Webpack Uses Tapable

Plugin Example from the Official Docs

class HelloWorldPlugin {
  apply(compiler) {
    compiler.hooks.done.tap('Hello World Plugin', (compilation) => {
      console.log('Hello World!');
    });
  }
}
module.exports = HelloWorldPlugin;

The plugin defines an apply method, receives the compiler instance, and taps into the done hook to run code after the compilation finishes. To use the plugin, import it in webpack.config.js and add a new instance to the plugins array.

// webpack.config.js
var HelloWorldPlugin = require('hello-world');
module.exports = {
  // ... other configuration ...
  plugins: [new HelloWorldPlugin({ options: true })]
};

Webpack iterates over the plugins array, calling apply on each plugin object (or invoking the function directly if the plugin is a function). This registration happens before the compilation run, ensuring that listeners are set up before events are emitted.

During the compilation process, Webpack calls the registered hooks in a specific order. For example, the done hook is triggered via callAsync after the compilation finishes, executing all listeners that were registered on that hook.

Plugin Registration Flowchart

6. Summary

Tapable is the core library that drives Webpack's event flow. Its hook design decouples implementation from process, enabling plug‑and‑play modules. Both the Compiler and Compilation objects are Tapable instances, making a solid understanding of Tapable essential for mastering Webpack. For deeper insight, explore the Tapable GitHub repository.