README

webpack-sane-compiler

A webpack compiler wrapper that provides a nicer API.

Installation

$ npm install webpack-sane-compiler --save-dev

The current version works with webpack v2, v3 and v4.

Usage

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

const webpackCompiler = webpack(/* config */);
const compiler = saneWebpack(webpackCompiler);

Alternatively, you may pass a config directly instead of a webpack compiler:

const compiler = saneWebpack(/* config */);

The compiler inherits from EventEmitter and emits the following events:

Name	Description	Arguments
begin	Emitted when a compilation starts
error	Emitted when the compilation fails	(err: Error)
end	Emitted when the compilation completes successfully	({ stats: WebpackStats, duration: Number })
invalidate	Emitted when the function return by .watch is called

compiler
.on('begin', () => console.log('Compilation started'))
.on('end', ({ stats, duration }) => {
    console.log(`Compilation finished successfully (${duration}ms)`);
    console.log('Stats', stats);
})
.on('invalidate', () => {
    console.log('Compilation canceled. Starting new compilation.')
})
.on('error', (err) => {
    console.log('Compilation failed')
    console.log(err.message);
    err.stats && console.log(err.stats.toString());
})

.run()

Returns a Promise that fulfils with a stats object or is rejected with an error.

This is similar to webpack's run() method, except that it returns a promise which gets rejected if stats contains errors.

compiler.run()
.then(({ stats, duration }) => {
    // stats is the webpack stats
    // duration is the time it took to compile
})
.catch((err) => {
    // err = {
    //   message: 'Error message',
    //   [stats]: <webpack-stats>
    // }
});

.watch([options], [handler])

Starts watching for changes and compiles on-the-fly.
Returns a function that, when called, will stop an ongoing compilation and start a new one.

Calls handler everytime the compilation fails or succeeds. This is similar to webpack's watch() method, except that handler gets called with an error if stats contains errors.

Available options:

Name	Description	Type	Default
poll	Use polling instead of native watchers	boolean	false
aggregateTimeout	Wait so long for more changes (ms)	err	200

const invalidate = compiler.watch((err, { stats, duration }) => {
    // err = {
    //   message: 'Error message',
    //   [stats]: <webpack-stats>
    // }
    // stats is the webpack stats
    // duration is the time it took to compile
});

if (someReasonToTriggerARecompilation) {
    invalidate();
}

.unwatch()

Stops watching for changes.
Returns a promise that fulfills when done.

.resolve()

Resolves the compilation result.

The promise gets immediately resolved if the compiler has finished or failed.
Otherwise waits for a compilation to be done before resolving the promise.

compiler.resolve()
.then(({ stats, duration }) => {
    // stats is the webpack stats
    // duration is the time it took to compile
})
.catch((err) => {
    // err = {
    //   message: 'Error message',
    //   [stats]: <webpack-stats>
    // }
});

.isCompiling()

Returns a boolean indicating a compilation is currently in progress.

.getError()

Returns the compilation error or null if none.

.getCompilation()

Get the compilation result which is an object that contains stats and duration.
Returns null if the last compilation failed or if it's not yet available.

Other properties

Name	Description	Type
webpackCompiler	The unrapped webpack compiler	Compiler
webpackConfig	The webpack config	object

Accessing webpack compiler public methods is NOT allowed and will throw an error.

Note: webpackCompiler's outputFileSystem property is overridden to a fully featured node fs implementation as opposed to its default value which only packs a subset of the features.

Related projects

You may also want to look at:

webpack-sane-compiler-reporter: Beautiful reporting for this compiler
webpack-sane-compiler-notifier: Receive OS notifications for this compiler
webpack-isomorphic-compiler: A compiler that makes your life easier if you are building isomorphic webpack powered apps

Tests

$ npm test
$ npm test -- --watch during development

License

MIT License

Usage no npm install needed!