Registry /
web-framework / webpack-isomorphic-dev-middleware
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
webpackIsomorphicDevMiddleware
✓ import webpackIsomorphicDevMiddleware from 'webpack-isomorphic-dev-middleware'
✗ const webpackIsomorphicDevMiddleware = require('webpack-isomorphic-dev-middleware')
While CommonJS `require()` is shown in older examples and supported, modern JavaScript development typically prefers ES Modules `import`. This package exports a default function.
IsomorphicDevMiddlewareOptions
✓ import type { IsomorphicDevMiddlewareOptions } from 'webpack-isomorphic-dev-middleware'
For TypeScript users, import the `IsomorphicDevMiddlewareOptions` type to define the configuration object passed to the middleware.
res.locals.isomorphic
✓ app.get('/', (req, res) => { const { clientStats, serverExports } = res.locals.isomorphic; /* ... */ });
The middleware attaches an `isomorphic` object to Express's `res.locals`, containing `clientStats`, `serverStats` (webpack stats for both compilers), and `serverExports` (the module.exports from your server bundle).
This quickstart demonstrates how to set up `webpack-isomorphic-dev-middleware` with an Express server, integrating both client and server Webpack compilers, and enabling client-side Hot Module Replacement with `webpack-hot-middleware`. It includes minimal Webpack configurations for a client and a node server bundle, and a basic Express route that accesses the server exports via `res.locals.isomorphic` to render an isomorphic page.
const express = require('express');
const webpack = require('webpack');
const webpackIsomorphicDevMiddleware = require('webpack-isomorphic-dev-middleware');
const webpackHotMiddleware = require('webpack-hot-middleware');
const nodeExternals = require('webpack-node-externals');
const path = require('path');
const fs = require('fs');
// Create dummy client and server entry points for demonstration
fs.mkdirSync(path.join(__dirname, 'src', 'client'), { recursive: true });
fs.writeFileSync(path.join(__dirname, 'src', 'client', 'index.js'), 'console.log("Client bundle loaded");');
fs.mkdirSync(path.join(__dirname, 'src', 'server'), { recursive: true });
fs.writeFileSync(path.join(__dirname, 'src', 'server', 'index.js'), 'module.exports = { greet: () => "Hello from server!" };');
const clientConfig = {
mode: 'development',
entry: [path.resolve(__dirname, 'src', 'client', 'index.js'), 'webpack-hot-middleware/client'],
output: {
path: path.resolve(__dirname, 'public'),
filename: 'client.js',
publicPath: '/' // Important for webpack-hot-middleware
},
plugins: [new webpack.HotModuleReplacementPlugin()]
};
const serverConfig = {
mode: 'development',
entry: path.resolve(__dirname, 'src', 'server', 'index.js'),
output: {
path: path.resolve(__dirname, 'build'),
filename: 'server.js',
libraryTarget: 'commonjs2' // Exposes module.exports
},
target: 'node',
externals: [nodeExternals()]
};
const clientCompiler = webpack(clientConfig);
const serverCompiler = webpack(serverConfig);
const app = express();
// Serve any static files from the public folder
app.use('/', express.static(path.join(__dirname, 'public'), { maxAge: 0, etag: false }));
// Add the middleware that will wait for both client and server compilations to be ready
app.use(webpackIsomorphicDevMiddleware(clientCompiler, serverCompiler));
// You must also add webpack-hot-middleware to provide hot module replacement to the client
app.use(webpackHotMiddleware(clientCompiler, { quiet: true }));
// Catch all route to attempt to render our isomorphic application
app.get('*', (req, res) => {
const { serverExports } = res.locals.isomorphic || {};
console.log('Server received request. Isomorphic data ready.');
res.send(`
<!DOCTYPE html>
<html>
<head><title>Isomorphic App</title></head>
<body>
<h1>Isomorphic App</h1>
<p>${serverExports?.greet?.() || 'Server exports not available yet.'}</p>
<div id="root"></div>
<script src="/client.js"></script>
</body>
</html>
`);
});
const PORT = 3000;
app.listen(PORT, () => {
console.log(`Development server listening on port ${PORT}`);
console.log('Waiting for webpack client and server compilations...');
});
Errors
Common errors & fixes
Peer dependency webpack@<5.0.0 not met
Attempting to install or run `webpack-isomorphic-dev-middleware` with Webpack v5 or a newer incompatible version installed in your project.
fixModify your `package.json` to use a compatible Webpack version (e.g., `"webpack": "^4.0.0"`) and reinstall dependencies.
TypeError: app.use is not a function
The `app` variable used with `app.use(webpackIsomorphicDevMiddleware(...))` is not a valid Express application instance, or it's improperly initialized.
fixEnsure Express is installed (`npm install express`) and `app` is created as `const app = express();` before attempting to use middleware.
TypeError: Cannot read properties of undefined (reading 'isomorphic')
The `res.locals.isomorphic` object is being accessed before the `webpackIsomorphicDevMiddleware` has been applied to the Express app or before the initial Webpack compilations have completed.
fixVerify that `app.use(webpackIsomorphicDevMiddleware(...))` is called correctly and appears before any routes that attempt to access `res.locals.isomorphic`. The middleware automatically delays requests until compilation is ready, so this usually points to an ordering issue in Express middleware chain or direct access outside of a request context.
Audit
Dependencies
webpackrequiredRequired as a peer dependency for compilation logic. This version supports Webpack v2, v3, and v4.
expressrequiredRequired as a peer dependency for middleware integration into an Express application.