{"id":18007,"library":"webpack-isomorphic-dev-middleware","title":"Webpack Isomorphic Dev Middleware","description":"webpack-isomorphic-dev-middleware is an Express middleware designed to streamline development for isomorphic (server-side rendered) applications using Webpack. It extends the functionality of webpack-dev-middleware by concurrently managing both client and server-side Webpack compilations. The package, currently at version 4.1.0, significantly simplifies complex isomorphic development setups by ensuring that both client and server bundles are compiled and ready before serving requests. It employs an in-memory filesystem for optimized compilation, delays responses until all necessary builds are complete, and injects compilation stats and server-exported methods into `res.locals.isomorphic`. Key differentiators include integrated compilation reporting for the terminal, optional OS notifications, and browser-based display of compilation errors. While a specific release cadence isn't stated, the version numbering suggests ongoing maintenance and updates, though its peer dependency range indicates primary support for Webpack versions up to v4.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/moxystudio/webpack-isomorphic-dev-middleware","tags":["javascript","webpack","isomorphic","server-side","rendering","render","middleware","express"],"install":[{"cmd":"npm install webpack-isomorphic-dev-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-isomorphic-dev-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-isomorphic-dev-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for compilation logic. This version supports Webpack v2, v3, and v4.","package":"webpack","optional":false},{"reason":"Required as a peer dependency for middleware integration into an Express application.","package":"express","optional":false}],"imports":[{"note":"While CommonJS `require()` is shown in older examples and supported, modern JavaScript development typically prefers ES Modules `import`. This package exports a default function.","wrong":"const webpackIsomorphicDevMiddleware = require('webpack-isomorphic-dev-middleware')","symbol":"webpackIsomorphicDevMiddleware","correct":"import webpackIsomorphicDevMiddleware from 'webpack-isomorphic-dev-middleware'"},{"note":"For TypeScript users, import the `IsomorphicDevMiddlewareOptions` type to define the configuration object passed to the middleware.","symbol":"IsomorphicDevMiddlewareOptions","correct":"import type { IsomorphicDevMiddlewareOptions } from 'webpack-isomorphic-dev-middleware'"},{"note":"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).","symbol":"res.locals.isomorphic","correct":"app.get('/', (req, res) => { const { clientStats, serverExports } = res.locals.isomorphic; /* ... */ });"}],"quickstart":{"code":"const express = require('express');\nconst webpack = require('webpack');\nconst webpackIsomorphicDevMiddleware = require('webpack-isomorphic-dev-middleware');\nconst webpackHotMiddleware = require('webpack-hot-middleware');\nconst nodeExternals = require('webpack-node-externals');\nconst path = require('path');\nconst fs = require('fs');\n\n// Create dummy client and server entry points for demonstration\nfs.mkdirSync(path.join(__dirname, 'src', 'client'), { recursive: true });\nfs.writeFileSync(path.join(__dirname, 'src', 'client', 'index.js'), 'console.log(\"Client bundle loaded\");');\nfs.mkdirSync(path.join(__dirname, 'src', 'server'), { recursive: true });\nfs.writeFileSync(path.join(__dirname, 'src', 'server', 'index.js'), 'module.exports = { greet: () => \"Hello from server!\" };');\n\nconst clientConfig = {\n  mode: 'development',\n  entry: [path.resolve(__dirname, 'src', 'client', 'index.js'), 'webpack-hot-middleware/client'],\n  output: {\n    path: path.resolve(__dirname, 'public'),\n    filename: 'client.js',\n    publicPath: '/' // Important for webpack-hot-middleware\n  },\n  plugins: [new webpack.HotModuleReplacementPlugin()]\n};\n\nconst serverConfig = {\n  mode: 'development',\n  entry: path.resolve(__dirname, 'src', 'server', 'index.js'),\n  output: {\n    path: path.resolve(__dirname, 'build'),\n    filename: 'server.js',\n    libraryTarget: 'commonjs2' // Exposes module.exports\n  },\n  target: 'node',\n  externals: [nodeExternals()]\n};\n\nconst clientCompiler = webpack(clientConfig);\nconst serverCompiler = webpack(serverConfig);\nconst app = express();\n\n// Serve any static files from the public folder\napp.use('/', express.static(path.join(__dirname, 'public'), { maxAge: 0, etag: false }));\n\n// Add the middleware that will wait for both client and server compilations to be ready\napp.use(webpackIsomorphicDevMiddleware(clientCompiler, serverCompiler));\n\n// You must also add webpack-hot-middleware to provide hot module replacement to the client\napp.use(webpackHotMiddleware(clientCompiler, { quiet: true }));\n\n// Catch all route to attempt to render our isomorphic application\napp.get('*', (req, res) => {\n  const { serverExports } = res.locals.isomorphic || {};\n  console.log('Server received request. Isomorphic data ready.');\n\n  res.send(`\n    <!DOCTYPE html>\n    <html>\n      <head><title>Isomorphic App</title></head>\n      <body>\n        <h1>Isomorphic App</h1>\n        <p>${serverExports?.greet?.() || 'Server exports not available yet.'}</p>\n        <div id=\"root\"></div>\n        <script src=\"/client.js\"></script>\n      </body>\n    </html>\n  `);\n});\n\nconst PORT = 3000;\napp.listen(PORT, () => {\n  console.log(`Development server listening on port ${PORT}`);\n  console.log('Waiting for webpack client and server compilations...');\n});\n","lang":"javascript","description":"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."},"warnings":[{"fix":"No action is strictly required. If using npm 7+ and warnings prevent installation, consider using `--legacy-peer-deps` or upgrading webpack to v4 if possible.","message":"When using webpack v2 or v3 with `webpack-isomorphic-dev-middleware` v4, you might encounter peer dependency warnings. These can typically be safely ignored as the middleware maintains compatibility with these webpack versions.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Downgrade webpack to a compatible version (e.g., v4) or check if a newer major version of `webpack-isomorphic-dev-middleware` has been released with Webpack 5+ support.","message":"This version of `webpack-isomorphic-dev-middleware` explicitly lists peer dependency support for `webpack@>=2.0.0 <5.0.0`. Using Webpack v5 or newer will result in a peer dependency violation and may lead to compilation failures or unexpected behavior.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure `clientCompiler` and `serverCompiler` are valid Webpack instances with distinct, complete configurations. The server compiler should always have `target: 'node'` and `libraryTarget: 'commonjs2'` for its output.","message":"This middleware requires *both* a client-side and a server-side Webpack compiler instance. Incorrectly configured or missing compilers (especially forgetting `target: 'node'` for the server) will prevent proper compilation and server-side rendering functionality.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Modify your `package.json` to use a compatible Webpack version (e.g., `\"webpack\": \"^4.0.0\"`) and reinstall dependencies.","cause":"Attempting to install or run `webpack-isomorphic-dev-middleware` with Webpack v5 or a newer incompatible version installed in your project.","error":"Peer dependency webpack@<5.0.0 not met"},{"fix":"Ensure Express is installed (`npm install express`) and `app` is created as `const app = express();` before attempting to use middleware.","cause":"The `app` variable used with `app.use(webpackIsomorphicDevMiddleware(...))` is not a valid Express application instance, or it's improperly initialized.","error":"TypeError: app.use is not a function"},{"fix":"Verify 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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'isomorphic')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}