Webpack Start Server Plugin

Common errors

• StartServerPlugin is not a constructor

  cause Attempting to import `StartServerPlugin` using a CommonJS `require` syntax or incorrect ES module syntax when the package is primarily ESM or configured as such.
  fix Use `import StartServerPlugin from 'start-server-webpack-plugin';` instead of `const StartServerPlugin = require('start-server-webpack-plugin');` and ensure your webpack config supports ESM.

• Cannot find module 'webpack/hot/poll?1000'

  cause The `webpack/hot/poll` entry point is only available if `webpack` is correctly installed as a dependency and resolved within your project.
  fix Ensure `webpack` is installed as a peer dependency (e.g., `npm install webpack`) and that its version is compatible with the plugin (`~4||~5`).

• Server not restarting or HMR not working on file changes.

  cause Webpack is not in watch mode, or `webpack.HotModuleReplacementPlugin` is missing, or the server-side code doesn't correctly accept HMR updates.
  fix Ensure `watch: true` is set in your Webpack config, `new webpack.HotModuleReplacementPlugin()` is included, and your server entry file includes `module.hot.accept();` logic if you want custom HMR handling.

Warnings

• breaking When upgrading from v2, the `name` option has been removed and replaced with `entryName`. Ensure you update your plugin configuration to use `entryName` if your server entry point is not named 'main'.
  Fix: Replace `new StartServerPlugin({ name: 'my-server' })` with `new StartServerPlugin({ entryName: 'my-server' })`.
• gotcha This plugin is designed for development environments. It should generally not be used in production builds, as its primary purpose is to automatically start and restart the server with HMR functionality.
  Fix: Conditionally apply the plugin using `if (process.env.NODE_ENV === 'development') { /* add plugin */ }` in your webpack config.
• gotcha When using Hot Module Reloading (HMR) with this plugin, you typically do not need to manually add `webpack/hot/dev-server` or similar HMR entry points to your server bundle, as the plugin handles appending necessary HMR code.
  Fix: Remove redundant HMR entry points if you observe unexpected behavior or double HMR messages. Ensure `webpack.HotModuleReplacementPlugin()` is still included.
• gotcha Starting with version 4.2.18, the plugin adds support for `type: module` in `razzle.config.js`. If you are using an older version and encounter issues with ESM configurations, an update may be necessary.
  Fix: Upgrade to `razzle-start-server-webpack-plugin@4.2.18` or newer if you are using Node.js ESM modules for your Razzle/Webpack configuration.

Install

• npm install razzle-start-server-webpack-plugin npm
• yarn add razzle-start-server-webpack-plugin yarn
• pnpm add razzle-start-server-webpack-plugin pnpm

Imports

• StartServerPlugin
  wrong:

  const StartServerPlugin = require('start-server-webpack-plugin');

  correct:

  import StartServerPlugin from 'start-server-webpack-plugin';

  This plugin is typically imported as a default export. Ensure your Webpack configuration file supports ESM imports (e.g., using Babel or a `.mjs` extension).

Quickstart

This quickstart demonstrates configuring Webpack to use `StartServerPlugin` for a Node.js server, enabling automatic restarts and Hot Module Replacement during development, including debugging with Node.js inspector.

import path from 'path';
import webpack from 'webpack';
import StartServerPlugin from 'start-server-webpack-plugin';

export default {
  mode: 'development',
  entry: {
    server: [
      'webpack/hot/poll?1000',
      './src/server.js'
    ]
  },
  target: 'node',
  watch: true,
  externals: [
    /^[a-z].*$/ // Don't bundle node_modules
  ],
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-env']
          }
        }
      }
    ]
  },
  plugins: [
    new webpack.HotModuleReplacementPlugin(),
    new webpack.NoEmitOnErrorsPlugin(),
    new StartServerPlugin({
      verbose: true,
      debug: true,
      entryName: 'server',
      nodeArgs: ['--inspect-brk'], // For debugging
      scriptArgs: ['--my-custom-arg'],
      restartable: true,
      once: false
    }),
    new webpack.DefinePlugin({
      'process.env.NODE_ENV': JSON.stringify('development')
    })
  ],
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js',
    libraryTarget: 'commonjs2'
  }
};

// A minimal server example (src/server.js)
// import express from 'express';
// const app = express();
// app.get('/', (req, res) => res.send('Hello HMR!'));
// const port = process.env.PORT || 3000;
// app.listen(port, () => console.log(`Server listening on port ${port}`));
// if (module.hot) {
//   module.hot.accept();
//   module.hot.dispose(() => console.log('Server disposed.'));
// }