{"id":12665,"library":"webpack-hot-server-middleware","title":"Webpack Hot Server Middleware","description":"webpack-hot-server-middleware is a utility designed to provide hot module replacement (HMR) capabilities for server-side Webpack bundles, specifically within universal or isomorphic JavaScript applications. It integrates seamlessly with `webpack-dev-middleware` and optionally `webpack-hot-middleware` to ensure that server bundles are always updated with the latest compilation changes during development, eliminating the need for manual server restarts. The package, currently at version 0.6.1, addresses a common pain point in development workflows where client bundles benefit from HMR but server bundles do not. It achieves this by replacing the entire server bundle in memory, leveraging the stateless nature of typical Express-style middleware. Key differentiators include its ability to share the same Webpack cache between client and server builds for faster compilation and its reliance on in-memory bundles to avoid disk I/O. Development appears to be in maintenance mode, with the last significant update occurring several years ago (February 2020), meaning its primary functionality is stable but new features or active modern Webpack compatibility updates are unlikely.","status":"maintenance","version":"0.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/60frames/webpack-hot-server-middleware","tags":["javascript","typescript"],"install":[{"cmd":"npm install webpack-hot-server-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-hot-server-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-hot-server-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Requires a webpack compiler instance to integrate with the build process and manage bundles.","package":"webpack","optional":false}],"imports":[{"note":"For ESM projects, this is the standard default import. The package supports both ESM and CJS environments.","wrong":"const { default: webpackHotServerMiddleware } = require('webpack-hot-server-middleware');","symbol":"webpackHotServerMiddleware","correct":"import webpackHotServerMiddleware from 'webpack-hot-server-middleware';"},{"note":"For CommonJS projects, the package exports the middleware function directly as its `module.exports`, so no `.default` or named import destructuring is needed.","wrong":"const { webpackHotServerMiddleware } = require('webpack-hot-server-middleware');","symbol":"webpackHotServerMiddleware (CJS)","correct":"const webpackHotServerMiddleware = require('webpack-hot-server-middleware');"},{"note":"Type import for the main middleware function signature. Useful for strict TypeScript environments or when extending functionality, but not typically imported for direct usage.","symbol":"WebpackHotServerMiddleware","correct":"import type WebpackHotServerMiddleware from 'webpack-hot-server-middleware';"}],"quickstart":{"code":"// webpack.config.ts (simplified example for quickstart)\nimport type { Configuration } from 'webpack';\nimport path from 'path';\n\nconst isDevelopment = process.env.NODE_ENV !== 'production';\n\nconst clientConfig: Configuration = {\n    name: 'client',\n    target: 'web',\n    mode: isDevelopment ? 'development' : 'production',\n    entry: './src/client.ts',\n    output: {\n        filename: 'client.js',\n        path: path.resolve(__dirname, 'dist'),\n        publicPath: '/',\n    },\n    // ... other rules and plugins for client bundle (e.g., React, HMR client) ...\n};\n\nconst serverConfig: Configuration = {\n    name: 'server',\n    target: 'node',\n    mode: isDevelopment ? 'development' : 'production',\n    entry: './src/server-renderer.ts',\n    output: {\n        filename: 'server.js',\n        path: path.resolve(__dirname, 'dist'),\n        libraryTarget: 'commonjs2',\n    },\n    // ... other rules and externals for server bundle (e.g., exclude node_modules) ...\n};\n\nexport default [clientConfig, serverConfig];\n\n// server.ts (main application entry point using Express)\nimport express from 'express';\nimport webpack from 'webpack';\nimport webpackDevMiddleware from 'webpack-dev-middleware';\nimport webpackHotServerMiddleware from 'webpack-hot-server-middleware';\nimport config from './webpack.config'; // Your array of Webpack configurations\n\nconst app = express();\nconst compiler = webpack(config);\n\n// Mount webpack-dev-middleware first for client-side assets and HMR\napp.use(webpackDevMiddleware(compiler, {\n    publicPath: '/', // Must match output.publicPath in clientConfig\n    serverSideRender: true, // Essential for isomorphic apps to allow dev-middleware to render server-side\n    stats: { colors: true },\n}));\n\n// Mount webpack-hot-server-middleware immediately after dev middleware\n// It automatically picks up the 'server' named configuration from the compiler\napp.use(webpackHotServerMiddleware(compiler));\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n    console.log(`Server listening on http://localhost:${PORT}`);\n    console.log('Ensure you have a `client.ts` for browser entry and `server-renderer.ts` for server-side rendering in your `src/` directory.');\n    console.log('The server renderer should export a function that returns Express middleware.');\n});","lang":"typescript","description":"Demonstrates integrating `webpack-hot-server-middleware` with `express` and `webpack-dev-middleware` for a universal application. It requires a Webpack configuration that exports an array containing both 'client' and 'server' bundles, correctly named."},"warnings":[{"fix":"Ensure your `webpack.config.js` (or similar) exports an array, e.g., `module.exports = [clientConfig, serverConfig];`.","message":"Webpack configuration must be an array containing separate configurations for 'client' and 'server' bundles.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Add `name: 'client'` to your client Webpack config and `name: 'server'` to your server Webpack config object.","message":"Client and server Webpack configurations must be explicitly named 'client' and 'server' respectively using the `name` property.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure `app.use(webpackHotServerMiddleware(compiler))` comes directly after `app.use(webpackDevMiddleware(compiler, ...))`.","message":"This middleware must be mounted *after* `webpack-dev-middleware` in your Express application's middleware chain to ensure correct hot updates.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Configure `webpackDevMiddleware` with `serverSideRender: true` in its options, e.g., `webpackDevMiddleware(compiler, { publicPath: '/', serverSideRender: true })`.","message":"The `serverSideRender: true` option is crucial for `webpack-dev-middleware` when using `webpack-hot-server-middleware` to ensure proper communication and server bundle compilation.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review compatibility with your specific Webpack version (e.g., Webpack 5+) and ensure necessary polyfills or transpilation are in place for modern JS features if using older Node.js versions.","message":"The package has not seen active development since February 2020. While functional for its intended purpose, it might lack support for very recent Webpack features or new JavaScript language constructs without manual configuration adjustments.","severity":"gotcha","affected_versions":">=0.6.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that your `webpack.config.js` exports an array of configurations, and each configuration object includes a `name` property ('client' or 'server').","cause":"Webpack configuration is not an array, or is an array but missing 'name' properties for client/server configs.","error":"TypeError: compiler.compilers.find is not a function"},{"fix":"Add `target: 'node'` to your server-specific Webpack configuration object.","cause":"The server-side Webpack configuration is missing the `target: 'node'` property.","error":"Error: Target 'node' must be set for the server bundle in webpack configuration."},{"fix":"Ensure `webpackHotServerMiddleware` is mounted *after* `webpack-dev-middleware` in your Express application and `webpack-dev-middleware` has `serverSideRender: true`.","cause":"Likely incorrect middleware order or `serverSideRender` option missing in `webpack-dev-middleware` configuration.","error":"Server-side code changes are not reflecting without manual server restarts, despite HMR for client."}],"ecosystem":"npm"}