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