webpack-sane-compiler

3.1.1 verified Fri May 01 auth: no javascript maintenance

A thin wrapper around webpack's compiler that provides a friendlier, event-based API with Promises, explicit begin/end/error/invalidate events, and automatic error handling for compilation failures. Version 3.1.1 supports webpack 2, 3, and 4 (webpack >=2.0.0 <5.0.0). Differentiates from raw webpack by rejecting Promises and calling watch handlers with errors when stats contain errors, plus emitting additional lifecycle events like 'begin' and 'invalidate'. Package is stable and mature with no recent releases.

Common errors

error TypeError: webpackCompiler.plugin is not a function ↓

cause Webpack 4+ deprecates plugin() method; the wrapper may still call it internally.

fix

Use webpack version <5.0.0 as per peer dependency. Alternatively, upgrade to a fork that uses hooks.

error UnhandledPromiseRejectionWarning: Error: Compilation failed with 1 error(s) ↓

cause .run() rejects the Promise on compilation errors if not caught.

fix

Add .catch() to handle rejection: compiler.run().catch(err => console.error(err.message, err.stats))

Warnings

gotcha The .watch() handler gets called with an error object if stats contain errors, unlike native webpack where you must check stats.hasErrors() ↓

fix Always handle the error parameter in watch callback; do not ignore it.

gotcha .run() rejects the Promise if the compilation has errors, even though webpack's run() returns a stats object with errors embedded ↓

fix Wrap in try/catch or use .catch() to handle rejection. Check err.stats for details.

deprecated Package is in maintenance mode; no new features have been added since 2018. Limited compatibility with webpack 5. ↓

fix Consider using webpack's built-in Compiler with hooks or migrate to 'webpackbar' or 'friendly-errors-webpack-plugin' for more modern workflows.

Install

npm install webpack-sane-compiler

yarn add webpack-sane-compiler

pnpm add webpack-sane-compiler

Imports

default
```
import saneWebpack from 'webpack-sane-compiler'
```
Package is CJS default-exported, but ESM import works with bundlers. Avoid named imports.

require

const saneWebpack = require('webpack-sane-compiler')

CommonJS require is the primary usage pattern.

Quickstart

Creates a webpack compiler, wraps it with sane-compiler, then demonstrates both .run() and .watch() usage with event listeners.

const webpack = require('webpack');
const saneWebpack = require('webpack-sane-compiler');

const webpackCompiler = webpack({
  entry: './src/index.js',
  output: { path: __dirname + '/dist', filename: 'bundle.js' }
});

const compiler = saneWebpack(webpackCompiler);

compiler
  .on('begin', () => console.log('Compilation started'))
  .on('end', ({ stats, duration }) => {
    console.log(`Compilation finished successfully (${duration}ms)`);
  })
  .on('error', (err) => {
    console.log('Compilation failed:', err.message);
  });

// Run once
compiler.run()
  .then(({ stats, duration }) => {
    console.log('First compile:', duration, 'ms');
  })
  .catch(err => console.error('Run error:', err.message));

// Or watch
const invalidate = compiler.watch({ aggregateTimeout: 300 }, (err, { stats, duration }) => {
  if (err) console.error('Watch error:', err.message);
  else console.log('Watch compiled in', duration, 'ms');
});

// After some changes
setTimeout(() => invalidate(), 5000);