Plugin

和 loader 的区别

While loaders are used to transform certain types of modules, plugins can be leveraged to perform a wider range of tasks like bundle optimization, asset management and injection of environment variables.

• Loader 用于转换特定的模块类型；
• Plugin 可以用于执行更加广泛的任务，比如打包优化、资源管理、环境变量注入等；

常见的 plugin

• ClearWebpackPlugin
• HTMLWebpackPlugin
• DefinePlugin（内置插件）
• CopyWebpackPlugin

实现原理

• webpack 本质是一个事件流机制，核心模块：tapable（Sync ＋ Async）Hooks 构造出＝＝＝ Compiler（编译）＋ Compilation（创建 bundles）
• compiler 对象代表了完整的 webpack 环境配置。这个对象在启动 webpack 时被一次性建立，并配置好所有可操作的设置，包括 options、loader 和 plugin。当在 webpack 环境中应用一个插件时，插件将收到此 compiler 对象的引用。可以使用它来访问 webpack 的主环境
• compilation 对象代表了一次资源版本构建。当运行 webpack 开发环境时，每当检测到一个文件变化，就会创建一个新的 compilation，从而生成一个新的编译资源。一个 compilation 对象表现了当前的模块资源、编译生成资源、变化的文件、以及被跟踪依赖的状态的信息。compilation 对象也提供了很多关键时机的回调，以供插件做自定义处理时选择使用
• 创建一个插件函数，在其 prototype 上定义 apply 方法，指定一个 webpack 自身的事件钩子
• 函数内部处理 webpack 内部实例的特定数据
• 处理完成后，调用 webpack 提供的回调函数

function MyWebpackPlugin() {}

MyWebpackPlugin.prototype.apply = function () {
  compiler.plugin("webpackEventHook", function (compiler) {
    // 插件功能 之后调用webpack提供的回调
    callback();
  });
};

Tapable

The tapable package expose many Hook classes, which can be used to create hooks for plugins.

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

Installation

npm install --save tapable

Usage

All Hook constructors take one optional argument, which is a list of argument names as strings.

const hook = new SyncHook(["arg1", "arg2", "arg3"]);

The best practice is to expose all hooks of a class in a hooks property:

class Car {
  constructor() {
    this.hooks = {
      accelerate: new SyncHook(["newSpeed"]),
      brake: new SyncHook(),
      calculateRoutes: new AsyncParallelHook([
        "source",
        "target",
        "routesList",
      ]),
    };
  }

  /* ... */
}

Other people can now use these hooks:

const myCar = new Car();

// Use the tap method to add a consument
myCar.hooks.brake.tap("WarningLampPlugin", () => warningLamp.on());

It's required to pass a name to identify the plugin/reason.

You may receive arguments:

myCar.hooks.accelerate.tap("LoggerPlugin", (newSpeed) =>
  console.log(`Accelerating to ${newSpeed}`)
);

For sync hooks, tap is the only valid method to add a plugin. Async hooks also support async plugins:

myCar.hooks.calculateRoutes.tapPromise(
  "GoogleMapsPlugin",
  (source, target, routesList) => {
    // return a promise
    return google.maps.findRoute(source, target).then((route) => {
      routesList.add(route);
    });
  }
);
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();
    });
  }
);

// You can still use sync plugins
myCar.hooks.calculateRoutes.tap(
  "CachedRoutesPlugin",
  (source, target, routesList) => {
    const cachedRoute = cache.get(source, target);
    if (cachedRoute) routesList.add(cachedRoute);
  }
);

The class declaring these hooks need to call them:

class Car {
  /**
   * You won't get returned value from SyncHook or AsyncParallelHook,
   * to do that, use SyncWaterfallHook and AsyncSeriesWaterfallHook respectively
   **/

  setSpeed(newSpeed) {
    // following call returns undefined even when you returned values
    this.hooks.accelerate.call(newSpeed);
  }

  useNavigationSystemPromise(source, target) {
    const routesList = new List();
    return this.hooks.calculateRoutes
      .promise(source, target, routesList)
      .then((res) => {
        // res is undefined for AsyncParallelHook
        return routesList.getRoutes();
      });
  }

  useNavigationSystemAsync(source, target, callback) {
    const routesList = new List();
    this.hooks.calculateRoutes.callAsync(source, target, routesList, (err) => {
      if (err) return callback(err);
      callback(null, routesList.getRoutes());
    });
  }
}

The Hook will compile a method with the most efficient way of running your plugins. It generates code depending on:

• The number of registered plugins (none, one, many)
• The kind of registered plugins (sync, async, promise)
• The used call method (sync, async, promise)
• The number of arguments
• Whether interception is used

This ensures fastest possible execution.

Hook types

Each hook can be tapped with one or several functions. How they are executed depends on the hook type:

• Basic hook (without “Waterfall”, “Bail” or “Loop” in its name). This hook simply calls every function it tapped in a row.

• Waterfall. A waterfall hook also calls each tapped function in a row. Unlike the basic hook, it passes a return value from each function to the next function.

• Bail. A bail hook allows exiting early. When any of the tapped function returns anything, the bail hook will stop executing the remaining ones.

• Loop. When a plugin in a loop hook returns a non-undefined value the hook will restart from the first plugin. It will loop until all plugins return undefined.

Additionally, hooks can be synchronous or asynchronous. To reflect this, there’re “Sync”, “AsyncSeries”, and “AsyncParallel” hook classes:

• Sync. A sync hook can only be tapped with synchronous functions (using myHook.tap()).

• AsyncSeries. An async-series hook can be tapped with synchronous, callback-based and promise-based functions (using myHook.tap(), myHook.tapAsync() and myHook.tapPromise()). They call each async method in a row.

• AsyncParallel. An async-parallel hook can also be tapped with synchronous, callback-based and promise-based functions (using myHook.tap(), myHook.tapAsync() and myHook.tapPromise()). However, they run each async method in parallel.

The hook type is reflected in its class name. E.g., AsyncSeriesWaterfallHook allows asynchronous functions and runs them in series, passing each function’s return value into the next function.

Interception

All Hooks offer an additional interception API:

myCar.hooks.calculateRoutes.intercept({
  call: (source, target, routesList) => {
    console.log("Starting to calculate routes");
  },
  register: (tapInfo) => {
    // tapInfo = { type: "promise", name: "GoogleMapsPlugin", fn: ... }
    console.log(`${tapInfo.name} is doing its job`);
    return tapInfo; // may return a new tapInfo object
  },
});

call: (...args) => void Adding call to your interceptor will trigger when hooks are triggered. You have access to the hooks arguments.

tap: (tap: Tap) => void Adding tap to your interceptor will trigger when a plugin taps into a hook. Provided is the Tap object. Tap object can't be changed.

loop: (...args) => void Adding loop to your interceptor will trigger for each loop of a looping hook.

register: (tap: Tap) => Tap | undefined Adding register to your interceptor will trigger for each added Tap and allows to modify it.

Context

Plugins and interceptors can opt-in to access an optional context object, which can be used to pass arbitrary values to subsequent plugins and interceptors.

myCar.hooks.accelerate.intercept({
  context: true,
  tap: (context, tapInfo) => {
    // tapInfo = { type: "sync", name: "NoisePlugin", fn: ... }
    console.log(`${tapInfo.name} is doing it's job`);

    // `context` starts as an empty object if at least one plugin uses `context: true`.
    // If no plugins use `context: true`, then `context` is undefined.
    if (context) {
      // Arbitrary properties can be added to `context`, which plugins can then access.
      context.hasMuffler = true;
    }
  },
});

myCar.hooks.accelerate.tap(
  {
    name: "NoisePlugin",
    context: true,
  },
  (context, newSpeed) => {
    if (context && context.hasMuffler) {
      console.log("Silence...");
    } else {
      console.log("Vroom!");
    }
  }
);

HookMap

A HookMap is a helper class for a Map with Hooks

const keyedHook = new HookMap((key) => new SyncHook(["arg"]));

keyedHook.for("some-key").tap("MyPlugin", (arg) => {
  /* ... */
});
keyedHook.for("some-key").tapAsync("MyPlugin", (arg, callback) => {
  /* ... */
});
keyedHook.for("some-key").tapPromise("MyPlugin", (arg) => {
  /* ... */
});

const hook = keyedHook.get("some-key");
if (hook !== undefined) {
  hook.callAsync("arg", (err) => {
    /* ... */
  });
}

Hook/HookMap interface

Public:

interface Hook {
  tap: (name: string | Tap, fn: (context?, ...args) => Result) => void;
  tapAsync: (
    name: string | Tap,
    fn: (context?, ...args, callback: (err, result: Result) => void) => void
  ) => void;
  tapPromise: (
    name: string | Tap,
    fn: (context?, ...args) => Promise<Result>
  ) => void;
  intercept: (interceptor: HookInterceptor) => void;
}

interface HookInterceptor {
  call: (context?, ...args) => void;
  loop: (context?, ...args) => void;
  tap: (context?, tap: Tap) => void;
  register: (tap: Tap) => Tap;
  context: boolean;
}

interface HookMap {
  for: (key: any) => Hook;
  intercept: (interceptor: HookMapInterceptor) => void;
}

interface HookMapInterceptor {
  factory: (key: any, hook: Hook) => Hook;
}

interface Tap {
  name: string;
  type: string;
  fn: Function;
  stage: number;
  context: boolean;
  before?: string | Array;
}

Protected (only for the class containing the hook):

interface Hook {
  isUsed: () => boolean;
  call: (...args) => Result;
  promise: (...args) => Promise<Result>;
  callAsync: (...args, callback: (err, result: Result) => void) => void;
}

interface HookMap {
  get: (key: any) => Hook | undefined;
  for: (key: any) => Hook;
}

MultiHook

A helper Hook-like class to redirect taps to multiple other hooks:

const { MultiHook } = require("tapable");

this.hooks.allHooks = new MultiHook([this.hooks.hookA, this.hooks.hookB]);