Introduction

webpack-plugin-compat is a compatibility layer for the webpack plugin api that simplifies the task of supporting both v4 and pre-v4 versions of webpack. This plugin provides a compatibility api that can be used with all current versions of webpack.

Plugin objects

Before webpack V4, objects that supported the plugin API were instances of Tapable. In V4, any Javascript object can support the plugin API via the hooks property. This compatibility layer exports an object named Tapable which in V3 is a reference to the Tapable class defined by webpack and in V4 is just a dummy class with no properties or methods. There is no requirement that the dummy class be used for V4 plugins. It is provided only for API compatibility.

Event name mapping

Plugin event names are passed to the underlying plugin api unmodified for pre-v4 versions of webpack. For v4 and above, event names are canonicalized by removing spaces and hyphens, and camal casing the result, expect as noted below for HookMaps.

For example, my-event-name will be mapped to myEventName.

V4 HookMaps

Webpack v4 introduced the concept of HookMaps. This plugin support HookMaps using space delimited tokens in the event name. The plugin will try to map one or more tokens from the event name to a HookMap name, and if a match is found, then that HookMap will be used.

tap(plugin, 'evaluate typeof require', function() {/*...*/});

is the same as using the v4 plugin APIs

plugin.hooks.for('evaluateTypeof').tap('require', function() {/*...*/});

if plugin.hooks contains a HookMap named evaluateTypeof. If the plugin does not contain a HookMap named evaluateTypeof, then the result will be the same as invoking

plugin.hooks.tap('evaluateTypeofRequire', function() {/*...*/});

Special case event names

For compatibility with pre-v4 behavior, this plugin maps the following event names when using webpack v4 and up.

Note: If you encounter any other event names that require mapping for pre-v4 compatibility, feel free to create a pull-request.

• parser -> parser javascript/auto

The API

reg

The reg function registers an event hook.

const {Tapable, reg} = require('webpack-plugin-conpat');
const plugin = new Tapable();
reg(plugin, 'myHook', ['Sync', 'arg1', 'arg2']);

is equivilent to the following v4 code

// Webpack v4
const {SyncHook} = require('tapable');
const plugin = {hooks: {}};
plugin.hooks.myHook = new SyncHook(['arg1', 'arg2']);

Multiple event hooks can be registered with a single reg call.

reg(plugin, {
	myHook: ['Sync', 'arg1', 'arg2'],
	myOtherHook: ['SyncBail', 'arg']
});

The reg function is a noop in pre-v4 webpack.

Supported hook types are:

• Sync
• SyncBail
• SyncWaterfall
• AsyncSeries
• AsyncSeriesWaterfall
• AsyncParalell
• AsyncParallelBail

tap

The tap function adds a consumer to an event. Note: the tap function is only available when a plugin name is provided using the for method.

const {Tapable, reg, tap} = require('webpack-plugin-conpat').for('myPlugin');
const plugin = new Tapable();
reg(plugin, 'my event', ['Sync', 'arg1', 'arg2']);
tap(plugin, 'my event', (arg1, arg2) => {
	console.log(arg1 + arg2);
});

This is equivilent to the following in webpack v4

// Webpack v4
const {SyncHook} = require('tapable');
const plugin = {hooks: {}};
plugin.hooks.myEvent = new SyncHook(['arg1', 'arg2']);
plugin.hooks.myEvent.tap('myPlugin', (arg1, arg2) => {
	console.log(arg1 + arg2);
});

and the following in webpack v3

// Webpack v3
const {Tapable} = require('tapable');
const plugin = new Tapable();
plugin.plugin('my event', (arg1, arg2) => {
	console.log(arg1 + arg2);
});

You may optionally specify a context for the callback, and an options object (ignored in V3).

tap(plugin, 'my event', callback, this, {stage:100});

And you can tap multiple events for the same plugin object with a single call

tap(plugin, {
	'my event': () => {/*...*/},
	'my other event': () => {/*...*/}
}, this);

Using array notation instead of object notation, you may specify multiple events names for the same event callback

tap(compiler, [
	[['run', 'watch-run'], () => {/*...*/}],
	['compilation', () => {/*...*/}]
], context);

callXXX

Event-type specific call functions (e.g. callSync, etc.) to invokde event callbacks. Supported flavors are:

• callSync
• callSyncBail
• callSyncWaterfall
• callAsyncSeries
• callAsyncSeriesWaterfall
• callAsyncParallel
• callAsyncParallelBail

const {Tapable, reg, tap, callSync} = require('webpack-plugin-conpat').for('myPlugin');
const plugin = new Tapable();
reg(plugin, 'my event', ['Sync', 'arg1', 'arg2']);
tap(plugin, 'my event', (arg1, arg2) => {
	console.log(arg1 + arg2);
});
callSync(plugin, 'my event', '1', '2');

In webpack v4, the event type signified by the call function name must match the type of the event hook.