README
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