webpack-isomorphic-compiler

webpack-isomorphic-compiler

A compiler that makes your life easier if you are building isomorphic webpack powered apps, that is, single page applications with server-side rendering.

Installation

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

The current version works with webpack v2 and v3.

Motivation

With webpack, client-side applications with server-side rendering means compiling both the client and the server.
To make it right, the client and server compilers must be in sync and live in perfect harmony.

Webpack offers a multi-compiler that makes this easier, but unfortunately it doesn't have all the plugin handlers that a single compiler does. This makes it difficult to know what's happening under the hood.

This module packs an aggregated compiler which syncs up the client & server compilation and:

• Has a clearer and saner API
• Warns about mistakes within your webpack configs
• Has beautiful reporting

API

webpackIsomorphicCompiler(clientCompiler, serverCompiler)

Creates an aggregated compiler that wraps both client and server webpack compilers.

const webpack = require('webpack');
const webpackIsomorphicCompiler = require('webpack-isomorphic-compiler');

const clientCompiler = webpack(/* client config */);
const serverCompiler =  webpack(/* server config */);
const compiler = webpackIsomorphicCompiler(clientCompiler, serverCompiler);

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

const webpack = require('webpack');

const compiler = webpackIsomorphicCompiler(/* client config */, /* server config */);

The compiler inherits from EventEmitter and emits the following events:

Name	Description	Argument
begin	Emitted when a compilation starts
error	Emitted when the compilation fails	err
end	Emitted when the compilation completes successfully	stats

compiler
.on('begin', () => console.log('Compilation started'))
.on('end', (stats) => {
    console.log('Compilation finished successfully');
    console.log('Client stats', stats.client);
    console.log('Server stats', stats.server);
})
.on('error', (err) => {
    console.log('Compilation failed')
    console.log(err.message);
    console.log(err.stats.toString());
})

.run([options])

Compiles both the client & server.
Returns a promise that fulfills 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) => {
    // stats = {
    //   client,
    //   server,
    // }
})
.catch((err) => {
    // err = {
    //   message: 'Error message',
    //   [stats]: <webpack-stats>
    // }
});

Available options:

Name	Description	Type	Default
report	Enable reporting	boolean/object	false

.watch([options], [handler])

Starts watching for changes and compiles on-the-fly.
Returns itself to allow chaining.

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
report	Enable reporting	boolean/object	false

compiler.watch((err, stats) => {
    // err = {
    //   message: 'Error message',
    //   [stats]: <webpack-stats>
    // }
    // stats = {
    //   client,
    //   server,
    // }
});

.unwatch()

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

.resolve()

Resolves the compiler 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) => {
    // stats = {
    //   client,
    //   server,
    // }
})
.catch((err) => {
    // err = {
    //   message: 'Error message',
    //   [stats]: <webpack-stats>
    // }
});

.isCompiling()

Returns a boolean indicating if the code is being compiled.

.getError()

Returns the compilation error or null if none.

.getStats()

Returns the compilation stats object ({ client, server }) or null if it failed or not yet available.

Client & server webpack related properties

Both client and server properties contain their webpack configs & compilers.

Name	Description	Type
webpackCompiler	The client's webpack compiler	Compiler
webpackConfig	The client's webpack config	object

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

Reporter

Both run() and watch() accepts a report option that, when enabled, prints information related to the compilation process. The option can be a boolean or an object that maps to the following options:

Name	Description	Type	Default
humanErrors	Detects human errors related to webpack configuration mistakes	boolean	true
stats	Display webpack stats after each successful compilation	boolean/string (true, false or once)	true
statsOptions	Which stats to display, see stats.toString()	sane default

Additionally, you may use the reporter manually through the exported reporter function on the webpack-isomorphic-compiler module.

Tests

$ npm test
$ npm test:watch during development

License

MIT License