Start Server Webpack Plugin

Common errors

• Error: Plugin names missing: <some-filename-or-path>. This way, the plugin knows which entry to start in case there are several.

  cause The `name` option was not provided or does not match the output filename for the server entry.
  fix Add the `name` option to `StartServerPlugin` constructor, ensuring it matches the exact filename of your server bundle. E.g., `new StartServerPlugin({ name: 'server.js' })` if your output filename is `server.js`.

• Cannot find module 'webpack/bin/config-yargs'

  cause This error often indicates incompatibility between `webpack-dev-server` or related plugins and newer versions of `webpack-cli` or `webpack` itself. It suggests the underlying `webpack-dev-server` (or similar) is having trouble locating its internal modules, typically due to outdated dependencies.
  fix This specific plugin is old. Upgrade `webpack` and `webpack-cli` to compatible versions, or consider switching to a modern development server setup that inherently supports newer Webpack versions, such as `webpack-dev-server` (standalone) or alternatives.

Warnings

• breaking This package has not been updated since March 2018 and does not officially support Webpack 5 or later. Using it with modern Webpack versions will likely result in compatibility issues or require significant manual patching.
  Fix: Consider migrating to alternatives like `webpack-dev-server` with `webpack-node-externals` or a custom Node.js script that watches Webpack output. A community-maintained fork like `start-server-nestjs-webpack-plugin` might offer Webpack 5 compatibility.
• gotcha When using Hot Module Replacement (HMR) with this plugin, you must include `webpack/hot/poll?1000` (or `webpack/hot/signal`) as an entry point for your server bundle. Additionally, if using `webpack-node-externals`, ensure these HMR modules are whitelisted so they are bundled, not excluded.
  Fix: Add `webpack/hot/poll?1000` to your server's Webpack `entry` array. If using `webpack-node-externals`, ensure its `whitelist` option includes `['webpack/hot/poll?1000', 'webpack/hot/signal']`.
• gotcha The `name` option in `StartServerPlugin` is crucial, especially for multi-entrypoint Webpack configurations. It must exactly match the `filename` of the server bundle output in your Webpack configuration. Omitting or misconfiguring it can lead to the plugin not knowing which asset to start.
  Fix: Ensure `new StartServerPlugin({ name: 'your-server-bundle.js' })` matches your `output.filename` (e.g., `server.js`). If no name is provided, the plugin attempts to infer but it's best to specify it explicitly.
• gotcha This plugin is explicitly intended for development environments. Its functionality for starting and restarting processes is not suitable for production deployments and should be disabled or removed in production builds.
  Fix: Wrap the plugin instantiation in an environment check: `process.env.NODE_ENV === 'development' ? new StartServerPlugin(...) : null`. Alternatively, use separate Webpack configurations for development and production.

Install

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

Imports

• StartServerPlugin
  wrong:

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

  correct:

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

  While primarily used with ESM imports in modern JavaScript projects, CJS `require` syntax was also common. Ensure your Webpack configuration's module system aligns with your chosen import style.
• StartServerPlugin (CommonJS)

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

  For older Webpack configurations or CommonJS-based projects, `require` syntax is applicable. Note that this package itself uses ESM in its README examples but provides CJS compatibility.

Quickstart

This quickstart demonstrates a typical Webpack configuration using `start-server-webpack-plugin` to compile and launch a Node.js server. It includes basic Hot Module Replacement (HMR) setup, debugging flags, and an example server structure.

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

module.exports = {
  mode: 'development',
  target: 'node',
  entry: {
    server: [
      'webpack/hot/poll?1000',
      path.resolve(__dirname, 'src', 'server.js'),
    ],
  },
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: '[name].js',
  },
  watch: true,
  externals: [
    // In order to ignore all modules in node_modules folder from bundling
    /^[a-z\-0-9]+$/,
  ],
  plugins: [
    // Only use this in DEVELOPMENT
    new StartServerPlugin({
      name: 'server.js', // Must match the output filename for the server entry
      nodeArgs: ['--inspect'], // Allows attaching a Node.js debugger
      args: ['--dev-mode'], // Pass custom arguments to your server script
      signal: true, // Send SIGUSR2 to restart the server for HMR
      keyboard: true, // Allow 'rs' to restart from terminal
    }),
    new webpack.HotModuleReplacementPlugin(),
    new webpack.NoEmitOnErrorsPlugin(), // Good practice for HMR
  ],
};

// src/server.js (example)
// const express = require('express');
// const app = express();
// const port = process.env.PORT || 3000;

// app.get('/', (req, res) => {
//   res.send('Hello from server! Updated: ' + new Date().toLocaleTimeString());
// });

// app.listen(port, () => {
//   console.log(`Server listening on port ${port}`);
// });

// if (module.hot) {
//   module.hot.accept();
//   module.hot.dispose(() => console.log('Server disposing...'));
// }