Start Server NestJS Webpack Plugin

2.2.5 · abandoned · verified Sun Apr 19

This Webpack plugin (current stable version 2.2.5) automatically starts a Node.js server after Webpack's build process completes, primarily intended for development workflows. It streamlines the development loop by restarting the server on code changes, enabling features like Hot Module Reloading (HMR) for server-side code. The plugin allows configuration of the server's entry point via the `name` option, and supports passing arguments to both Node.js and the script itself for debugging or custom behaviors. While its name suggests a specific affinity for NestJS applications, its core functionality is broadly applicable to any Node.js server bundled with Webpack, acting as a convenient orchestrator for development environments. It helps eliminate manual server restarts during active development. However, it's critical to note that version 2.2.5 was last published approximately eight years ago, indicating the project is effectively abandoned and may not be compatible with recent versions of Webpack (v5+) or Node.js.

Common errors

```
Error: Name 'server.js' not found in Webpack assets.
```
cause The `name` option passed to `StartServerPlugin` does not match any of the entry names or output filenames generated by your Webpack configuration.

fix Verify that the `name` property in `new StartServerPlugin({ name: 'your-output.js' })` exactly matches the `output.filename` or an entry key from your Webpack config's `entry` object (e.g., `entry: { server: './src/main.ts' }` should use `name: 'server.js'` if `output.filename` defaults to `[name].js`).
```
HMR updates are not applying or server is restarting completely instead of hot-reloading.
```
cause Hot Module Reloading is misconfigured. Common issues include missing HMR entry modules, `webpack-node-externals` bundling HMR modules, or the `signal` option not being set in the plugin configuration.

fix Review your `entry` array to include `webpack/hot/poll?100` (or `webpack/hot/signal`), ensure `webpack-node-externals` has an `allowlist` for HMR modules, and set `signal: 'SIGUSR2'` in `StartServerPlugin` options. Also, confirm `new webpack.HotModuleReplacementPlugin()` is enabled.
```
Webpack compilation fails or runtime errors occur with newer Webpack/Node.js versions.
```
cause The plugin is effectively abandoned, with its last update being eight years ago, leading to potential incompatibilities with modern Webpack API changes, Node.js features, or internal module structures.

fix For projects requiring modern Webpack (v5+) or Node.js versions, it is strongly advised to migrate to an actively maintained solution like `run-script-webpack-plugin` or to manage server restarts manually with tools like `nodemon` or custom scripts.

Warnings

breaking The package version 2.2.5 was last published approximately eight years ago. This makes it highly probable that the plugin is incompatible with modern Webpack versions (e.g., v5+) and recent Node.js LTS releases, potentially causing build failures or unexpected runtime behavior.
Fix: Consider using actively maintained alternatives like `run-script-webpack-plugin` or directly managing server restarts with `nodemon` or similar tools, especially for production or modern projects.
gotcha This plugin is explicitly designed for and should only be used in development environments. Using it in production could lead to resource overhead, unexpected restarts, or security vulnerabilities.
Fix: Ensure the plugin is conditionally included in your Webpack configuration (e.g., `if (isDevelopment) { plugins.push(new StartServerPlugin(...)); }`) and removed from production builds.
gotcha Proper configuration for Hot Module Reloading (HMR) requires careful setup, including adding HMR runtime modules to your entry points, whitelisting them from `webpack-node-externals` (if used), and setting the `signal` option. Incorrect setup will result in HMR not functioning.
Fix: Ensure your Webpack entry includes `webpack/hot/poll?100` or `webpack/hot/signal`, that `webpack-node-externals`' `allowlist` includes these HMR modules, and that `new StartServerPlugin({ signal: 'SIGUSR2' })` is configured. Also, make sure `new webpack.HotModuleReplacementPlugin()` is present in your plugins array.

Install

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

Imports

StartServerPlugin

wrong:

import { StartServerPlugin } from 'start-server-nestjs-webpack-plugin';

correct:

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

The plugin is a default export, typically instantiated directly.

StartServerPlugin (CommonJS)
```
const StartServerPlugin = require('start-server-nestjs-webpack-plugin');
```
For CommonJS environments, the plugin class is directly exported via `module.exports`.
Webpack HMR modules
wrong:
```
entry: options.entry
```
correct:
```
entry: ['webpack/hot/poll?100', options.entry]
```
For Hot Module Reloading (HMR), specific Webpack runtime modules like 'webpack/hot/poll' or 'webpack/hot/signal' must be included in your server bundle entry points.

Quickstart

This quickstart demonstrates configuring Webpack to use `start-server-nestjs-webpack-plugin` for a Node.js server with TypeScript, including setup for Hot Module Reloading and Node.js debugger integration. This setup is for a typical NestJS application server file located at './src/server.ts' and outputs to 'dist/server.js'.

import StartServerPlugin from "start-server-nestjs-webpack-plugin";
import nodeExternals from 'webpack-node-externals';
import webpack from 'webpack';

export default {
  // Target node for server-side bundling
  target: 'node',
  mode: 'development',
  entry: {
    server: ['webpack/hot/poll?100', './src/server.ts'], // Include HMR module
  },
  output: {
    filename: 'server.js',
    path: require('path').resolve(__dirname, 'dist'),
  },
  externals: [
    nodeExternals({ allowlist: ['webpack/hot/poll?100'] }), // Whitelist HMR module
  ],
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
    ],
  },
  resolve: {
    extensions: ['.tsx', '.ts', '.js'],
  },
  plugins: [
    // Only use this in DEVELOPMENT
    new StartServerPlugin({
      name: 'server.js',
      nodeArgs: ['--inspect'], // allow debugging
      args: ['--env', 'development'], // pass args to script
      signal: 'SIGUSR2', // signal to send for HMR
      keyboard: true, // Allow typing 'rs' to restart the server.
    }),
    new webpack.HotModuleReplacementPlugin(), // Enable HMR
  ],
};

view raw JSON →