Registry /
devops / start-server-webpack-plugin
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StartServerPlugin
✓ import StartServerPlugin from 'start-server-webpack-plugin';
✗ const StartServerPlugin = require('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.
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...'));
// }
Debug
Known issues
breakingThis 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.fixConsider 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.
affects: >=3.0.0 (Webpack versions)
gotchaWhen 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.fixAdd `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']`.
affects: >=2.0.0
gotchaThe `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.fixEnsure `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. affects: >=2.0.0
gotchaThis 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.fixWrap the plugin instantiation in an environment check: `process.env.NODE_ENV === 'development' ? new StartServerPlugin(...) : null`. Alternatively, use separate Webpack configurations for development and production.
affects: >=2.0.0
Errors
Common errors & fixes
Error: Plugin names missing: <some-filename-or-path>. This way, the plugin knows which entry to start in case there are several.
The `name` option was not provided or does not match the output filename for the server entry.
fixAdd 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'
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.
fixThis 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.
Audit
Dependencies
webpackrequiredCore dependency as a Webpack plugin. Requires Webpack 4 or earlier for full compatibility.