Webpack Hot Server Middleware

Common errors

• TypeError: compiler.compilers.find is not a function

  cause Webpack configuration is not an array, or is an array but missing 'name' properties for client/server configs.
  fix Verify that your `webpack.config.js` exports an array of configurations, and each configuration object includes a `name` property ('client' or 'server').

• Error: Target 'node' must be set for the server bundle in webpack configuration.

  cause The server-side Webpack configuration is missing the `target: 'node'` property.
  fix Add `target: 'node'` to your server-specific Webpack configuration object.

• Server-side code changes are not reflecting without manual server restarts, despite HMR for client.

  cause Likely incorrect middleware order or `serverSideRender` option missing in `webpack-dev-middleware` configuration.
  fix Ensure `webpackHotServerMiddleware` is mounted *after* `webpack-dev-middleware` in your Express application and `webpack-dev-middleware` has `serverSideRender: true`.

Warnings

• breaking Webpack configuration must be an array containing separate configurations for 'client' and 'server' bundles.
  Fix: Ensure your `webpack.config.js` (or similar) exports an array, e.g., `module.exports = [clientConfig, serverConfig];`.
• breaking Client and server Webpack configurations must be explicitly named 'client' and 'server' respectively using the `name` property.
  Fix: Add `name: 'client'` to your client Webpack config and `name: 'server'` to your server Webpack config object.
• gotcha This middleware must be mounted *after* `webpack-dev-middleware` in your Express application's middleware chain to ensure correct hot updates.
  Fix: Ensure `app.use(webpackHotServerMiddleware(compiler))` comes directly after `app.use(webpackDevMiddleware(compiler, ...))`.
• gotcha The `serverSideRender: true` option is crucial for `webpack-dev-middleware` when using `webpack-hot-server-middleware` to ensure proper communication and server bundle compilation.
  Fix: Configure `webpackDevMiddleware` with `serverSideRender: true` in its options, e.g., `webpackDevMiddleware(compiler, { publicPath: '/', serverSideRender: true })`.
• gotcha 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.
  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.

Install

• npm install webpack-hot-server-middleware npm
• yarn add webpack-hot-server-middleware yarn
• pnpm add webpack-hot-server-middleware pnpm

Imports

• webpackHotServerMiddleware
  wrong:

  const { default: webpackHotServerMiddleware } = require('webpack-hot-server-middleware');

  correct:

  import webpackHotServerMiddleware from 'webpack-hot-server-middleware';

  For ESM projects, this is the standard default import. The package supports both ESM and CJS environments.
• webpackHotServerMiddleware (CJS)
  wrong:

  const { webpackHotServerMiddleware } = require('webpack-hot-server-middleware');

  correct:

  const webpackHotServerMiddleware = require('webpack-hot-server-middleware');

  For CommonJS projects, the package exports the middleware function directly as its `module.exports`, so no `.default` or named import destructuring is needed.
• WebpackHotServerMiddleware

  import type WebpackHotServerMiddleware from 'webpack-hot-server-middleware';

  Type import for the main middleware function signature. Useful for strict TypeScript environments or when extending functionality, but not typically imported for direct usage.

Quickstart

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.

// webpack.config.ts (simplified example for quickstart)
import type { Configuration } from 'webpack';
import path from 'path';

const isDevelopment = process.env.NODE_ENV !== 'production';

const clientConfig: Configuration = {
    name: 'client',
    target: 'web',
    mode: isDevelopment ? 'development' : 'production',
    entry: './src/client.ts',
    output: {
        filename: 'client.js',
        path: path.resolve(__dirname, 'dist'),
        publicPath: '/',
    },
    // ... other rules and plugins for client bundle (e.g., React, HMR client) ...
};

const serverConfig: Configuration = {
    name: 'server',
    target: 'node',
    mode: isDevelopment ? 'development' : 'production',
    entry: './src/server-renderer.ts',
    output: {
        filename: 'server.js',
        path: path.resolve(__dirname, 'dist'),
        libraryTarget: 'commonjs2',
    },
    // ... other rules and externals for server bundle (e.g., exclude node_modules) ...
};

export default [clientConfig, serverConfig];

// server.ts (main application entry point using Express)
import express from 'express';
import webpack from 'webpack';
import webpackDevMiddleware from 'webpack-dev-middleware';
import webpackHotServerMiddleware from 'webpack-hot-server-middleware';
import config from './webpack.config'; // Your array of Webpack configurations

const app = express();
const compiler = webpack(config);

// Mount webpack-dev-middleware first for client-side assets and HMR
app.use(webpackDevMiddleware(compiler, {
    publicPath: '/', // Must match output.publicPath in clientConfig
    serverSideRender: true, // Essential for isomorphic apps to allow dev-middleware to render server-side
    stats: { colors: true },
}));

// Mount webpack-hot-server-middleware immediately after dev middleware
// It automatically picks up the 'server' named configuration from the compiler
app.use(webpackHotServerMiddleware(compiler));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
    console.log(`Server listening on http://localhost:${PORT}`);
    console.log('Ensure you have a `client.ts` for browser entry and `server-renderer.ts` for server-side rendering in your `src/` directory.');
    console.log('The server renderer should export a function that returns Express middleware.');
});