webpack-shell-plugin-next

2.3.3 verified Sat Apr 25 auth: no javascript

Run shell commands before, during, and after webpack 5 builds. Current stable version 2.3.3, with regular updates. Supports TypeScript types and provides fine-grained lifecycle hooks (onBuildStart, onBuildEnd, onBuildExit, onWatchRun, etc.) with blocking and parallel execution control. Differentiator: actively maintained fork of the original webpack-shell-plugin, compatible only with webpack 5 (v2.x) and offering more hooks and TypeScript support.

Common errors

error TypeError: WebpackShellPluginNext is not a constructor ↓

cause ESM import used incorrectly; package is CommonJS.

fix

Replace import WebpackShellPluginNext from 'webpack-shell-plugin-next' with const WebpackShellPluginNext = require('webpack-shell-plugin-next').

error Cannot find module 'webpack-shell-plugin-next' ↓

cause Missing npm install or wrong peer dependency webpack version.

fix

Run npm install --save-dev webpack-shell-plugin-next and ensure webpack 5 is installed.

error Error: the scripts option should be an array of strings ↓

cause Configuration for a lifecycle hook was passed as a string or invalid type.

fix

Ensure each lifecycle hook's scripts property is an array, e.g., onBuildStart: { scripts: ['command'] }.

error Error: blocking and parallel cannot both be true ↓

cause Both blocking and parallel options set to true in a lifecycle config.

fix

Set at most one of them to true, or leave both false (defaults to serial non-blocking).

Warnings

breaking v2.0.0 dropped webpack 4 support. Only webpack 5 is supported. ↓

fix Upgrade to webpack 5 or use v1.x (webpack-shell-plugin-next@1) for webpack 4.

breaking v2.0.0 changed configuration structure: lifecycle hooks now expect an object (with scripts array) instead of a flat array. ↓

fix Change from `onBuildStart: ['echo start']` to `onBuildStart: { scripts: ['echo start'] }`.

deprecated The `onBeforeBuild` and `onBuildError` hooks are deprecated in v2. Use `onBuildStart` and `onFailedBuild` instead. ↓

fix Replace `onBeforeBuild` with `onBuildStart`, `onBuildError` with `onFailedBuild`.

gotcha Using both `blocking: true` and `parallel: true` together throws an error: they are mutually exclusive. ↓

fix Set only one of them to true, or both to false.

gotcha The `onBuildExit` hook also fires in watch mode when webpack finishes updating the bundle, not just on exit. ↓

fix Use `onBeforeNormalRun` or `onDoneWatch` for more precise control.

Install

npm install webpack-shell-plugin-next

yarn add webpack-shell-plugin-next

pnpm add webpack-shell-plugin-next

Imports

WebpackShellPluginNext
wrong
```
import WebpackShellPluginNext from 'webpack-shell-plugin-next';
```
correct
```
const WebpackShellPluginNext = require('webpack-shell-plugin-next');
```
This package is CommonJS-only (no ESM export). In TypeScript, use the require syntax or set 'esModuleInterop' to true if using import.

WebpackShellPluginNext

wrong

import { WebpackShellPluginNext } from 'webpack-shell-plugin-next';

correct

import WebpackShellPluginNext = require('webpack-shell-plugin-next');

TypeScript users should use import x = require() for CommonJS modules; named import is not available.

Plugin configuration object

wrong

new WebpackShellPluginNext({ onBuildStart: ['echo start'] })

correct

new WebpackShellPluginNext({ onBuildStart: { scripts: ['echo start'], blocking: true } })

Since v2, lifecycle hooks expect a configuration object with 'scripts' array, not an array of strings directly.

Quickstart

Configures the plugin with multiple lifecycle hooks, blocking/parallel options, environment variables, and logging control.

const WebpackShellPluginNext = require('webpack-shell-plugin-next');

module.exports = {
  plugins: [
    new WebpackShellPluginNext({
      onBuildStart: {
        scripts: ['echo "Build starting..."'],
        blocking: true,
        parallel: false
      },
      onBuildEnd: {
        scripts: ['echo "Build completed!"'],
        blocking: false,
        parallel: true
      },
      onBuildExit: {
        scripts: ['echo "Exiting webpack"']
      },
      onWatchRun: {
        scripts: ['echo "Watch mode triggered"'],
        blocking: false
      },
      env: { NODE_ENV: 'production' },
      logging: true,
      swallowError: false
    })
  ]
};