Webpack Isomorphic Compiler

3.1.1 verified Fri May 01 auth: no javascript maintenance

Webpack isomorphic compiler (v3.1.1) synchronizes client and server webpack compilations for isomorphic/universal JavaScript apps with server-side rendering. Compatible with webpack v2–v4, released sporadically (last update 2020). Provides an aggregated compiler API with hooks, events, and compilation results (clientStats, serverStats, duration). Extends webpack-sane-compiler for compatibility with reporter and notifier tools. Key differentiator: simplifies isomorphic webpack setups by managing two compilers and ensuring they are in sync, unlike raw multi-compiler which lacks plugin handlers.

Common errors

error Cannot find module 'webpack-isomorphic-compiler' ↓

cause Package not installed or missing from node_modules.

fix

Run 'npm install webpack-isomorphic-compiler --save-dev'.

error TypeError: (0 , _default) is not a function ↓

cause Using a named import (e.g., import { isomorphicWebpack }) instead of default import.

fix

Use 'import isomorphicWebpack from 'webpack-isomorphic-compiler'' or 'const isomorphicWebpack = require('webpack-isomorphic-compiler')'.

error Invalid configuration object. Webpack has been initialised using a configuration object that does not match the API schema. ↓

cause Webpack config object passed to isomorphicWebpack is invalid.

fix

Ensure both client and server configs are valid webpack configuration objects.

Warnings

breaking Version 3.0.0 dropped support for webpack <2.0.0. Ensure your webpack version is >=2.0.0 <5.0.0. ↓

fix Update webpack to version 2.x, 3.x, or 4.x.

deprecated Package has not been updated since 2020 and may not work with webpack 5. Consider migrating to webpack 5's built-in solutions or other libraries. ↓

fix If using webpack 5, look for alternatives or fork the package.

gotcha The compiler.run() callback receives an error and an object with clientStats, serverStats, stats, duration. Do not expect stats to be a webpack Stats object; it is clientStats for compatibility. ↓

fix Access clientStats and serverStats directly; stats is identical to clientStats.

gotcha When passing config objects instead of compilers, ensure they are valid webpack configs. The library internally creates compilers using webpack(), so both configs must be present and valid. ↓

fix Pass webpack compilers if you need full control over compiler instances.

Install

npm install webpack-isomorphic-compiler

yarn add webpack-isomorphic-compiler

pnpm add webpack-isomorphic-compiler

Imports

default

wrong

const { isomorphicWebpack } = require('webpack-isomorphic-compiler')

correct

import isomorphicWebpack from 'webpack-isomorphic-compiler'

Package exports a single default export (function). Use default import for ESM.

ISOMORPHIC_COMPILER_EVENTS
wrong
```
import { ISOMORPHIC_COMPILER_EVENTS } from 'webpack-isomorphic-compiler'
```
correct
```
import isomorphicWebpack, { ISOMORPHIC_COMPILER_EVENTS } from 'webpack-isomorphic-compiler'
```
Named export ISOMORPHIC_COMPILER_EVENTS is an object with event constants (e.g., 'COMPILATION_DONE', 'CHUNK_ASSETS'). Must be imported alongside default export.

default (require)

wrong

const { default: isomorphicWebpack } = require('webpack-isomorphic-compiler')

correct

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

CommonJS require works directly. No need to destructure default.

Quickstart

Creates two webpack compilers (client and server) and combines them using isomorphicWebpack. Runs the aggregated compiler and logs compilation stats.

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

const clientCompiler = webpack({
  entry: './src/client.js',
  output: { path: './dist/client', filename: 'bundle.js' },
  target: 'web',
});

const serverCompiler = webpack({
  entry: './src/server.js',
  output: { path: './dist/server', filename: 'server.js' },
  target: 'node',
});

const compiler = isomorphicWebpack(clientCompiler, serverCompiler);

compiler.run((err, { clientStats, serverStats, stats, duration }) => {
  if (err) {
    console.error('Compilation failed:', err);
    return;
  }
  console.log(`Compilation took ${duration} ms`);
  console.log('Client assets:', Object.keys(clientStats.compilation.assets));
  console.log('Server assets:', Object.keys(serverStats.compilation.assets));
});