webpack plugin compat

1.0.4 verified Sat Apr 25 auth: no javascript

A compatibility layer for the webpack plugin API that simplifies supporting both v4 and pre-v4 versions (v3/v2). Current version 1.0.4 adds support for Tapable v2.0. Key differentiators: transparent event name mapping (spaces/hyphens to camelCase), HookMap support via space-delimited tokens, special-cased parser events, and a unified reg/tap API that works across webpack versions. Maintained by the Dojo toolkit team.

Common errors

error TypeError: Cannot read properties of undefined (reading 'tap') ↓

cause Trying to use `tap` directly from the main import without going through `.for()` or the 'for' submodule.

fix

Use import { tap } from 'webpack-plugin-compat/for' and then tap.for('myPlugin').

error Error: HookMap not found for 'evaluate typeof require' ↓

cause The event name includes spaces intended for HookMap matching, but no matching HookMap exists on the plugin object.

fix

Ensure the HookMap is registered via reg(plugin, 'evaluateTypeof', ...) or remove spaces from the event name.

error Module not found: Can't resolve 'webpack-plugin-compat/for' ↓

cause The submodule path 'webpack-plugin-compat/for' is not resolved correctly, possibly due to symlinks or missing package exports.

fix

Ensure your package manager resolves the package correctly. Try using a direct import: const { tap } = require('webpack-plugin-compat').for('name');

Warnings

gotcha The `tap` function is NOT available as a top-level export; you must import from 'webpack-plugin-compat/for' or use `.for('name')` after importing the main module. ↓

fix Use `import { tap } from 'webpack-plugin-compat/for'` or `const { tap } = require('webpack-plugin-compat/for');`

gotcha Event names are automatically camelCased for webpack v4+. For example, 'my-event' becomes 'myEvent'. This may cause unexpected collisions or mismatches if you rely on exact naming. ↓

fix Use camelCase event names explicitly to avoid ambiguity, or use HookMap tokens for space-delimited names.

breaking In v1.0.4, support for Tapable v2.0 was added. Plugins relying on Tapable v1 internals may break. ↓

fix Ensure your code is compatible with Tapable v2 (e.g., no direct access to Tapable internals).

deprecated Pre-v4 webpack (v2, v3) are no longer actively maintained. Using this package for new development is discouraged; migrate to webpack 5+. ↓

fix Upgrade to webpack 5+ and remove this dependency.

Install

npm install webpack-plugin-compat

yarn add webpack-plugin-compat

pnpm add webpack-plugin-compat

Imports

Tapable

wrong

const Tapable = require('webpack-plugin-compat')

correct

import { Tapable } from 'webpack-plugin-compat'

Named export; requires destructuring from package.

reg

wrong

const { reg } = require('webpack-plugin-compat').for('myPlugin')

correct

import { reg } from 'webpack-plugin-compat'

reg is a top-level export; do not chain .for() on import.

tap

wrong

import { tap } from 'webpack-plugin-compat';

correct

import { tap } from 'webpack-plugin-compat/for';
const tapNamed = tap.for('myPlugin');

tap is available only via the 'for' submodule. Import from 'webpack-plugin-compat/for' or use tap.for() after import.

Quickstart

Demonstrates basic usage: creating a Tapable plugin object, registering a SyncHook, tapping it with a named plugin, and calling the hook.

import { Tapable, reg } from 'webpack-plugin-compat';
import { tap } from 'webpack-plugin-compat/for';

// Create a plugin instance (Tapable is dummy in webpack v4, real in v3)
const plugin = new Tapable();

// Register a hook (noop in webpack v3)
reg(plugin, 'myHook', ['Sync', 'arg1', 'arg2']);

// Tap into the hook (requires a plugin name via .for)
const tapWithName = tap.for('myPlugin');
tapWithName(plugin, 'myHook', (arg1, arg2) => {
  console.log(arg1, arg2);
});

// Trigger the hook
plugin.hooks.myHook.call('hello', 'world');