Skip to content

moxystudio/webpack-sane-compiler

Repository files navigation

webpack-sane-compiler

NPM version Downloads Build Status Coverage Status Dependency status Dev Dependency status

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:

Tests

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

License

MIT License