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, v3 and v4.

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 possible, 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 that:

• Syncs up the client & server compilation
• Has a clearer and saner API
• Has 100% API compatibility with webpack-sane-compiler, allowing you to use its reporter and notifier

NOTE: While webpack-sane-compiler-reporter is compatible with this compiler, we advise using webpack-isomorphic-compiler-reporter instead for completeness and accurateness.

Usage

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

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

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

const webpack = require('webpack');

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

The returned compiler has exactly the same API as the webpack-sane-compiler but adds some functionality that is detailed below.

Compilation result

The compilation result, available through .run(), .watch(), .getCompilation() and .resolve(), has two more properties:

compiler.run()
.then(({ clientStats, serverStats, stats, duration }) => {
    // clientStats is the webpack stats of the client
    // serverStats is the webpack stats of the client
    // duration is the aggregated compilation duration
    // stats maps to clientStats for API compatibility
})

Client & server webpack

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.

Related projects

You may also want to look at:

• webpack-isomorphic-dev-middleware: Like webpack-dev-middleware, but for isomorphic applications
• webpack-isomorphic-compiler-reporter: Beautiful reporting for this compiler
• webpack-sane-compiler-notifier: Receive OS notifications for this compiler
• webpack-sane-compiler: A webpack compiler wrapper that provides a nicer API

Tests

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

License

MIT License