{"id":11626,"library":"razzle-start-server-webpack-plugin","title":"Webpack Start Server Plugin","description":"razzle-start-server-webpack-plugin is a utility designed to automatically start a Node.js server after Webpack completes its build process, primarily for server-side bundles in development. It also integrates seamlessly with Hot Module Reloading (HMR) for server code, eliminating the need for manual server restarts during development. The current stable version is 4.2.18, released as part of the broader Razzle monorepo, indicating its release cadence is tied to Razzle's development lifecycle. Its key differentiators include simplified HMR setup for server code and the ability to pass arguments directly to Node.js or the server script, making debugging easier.","status":"active","version":"4.2.18","language":"javascript","source_language":"en","source_url":"https://github.com/jaredpalmer/razzle","tags":["javascript","webpack","server","start","watch","restart","express"],"install":[{"cmd":"npm install razzle-start-server-webpack-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add razzle-start-server-webpack-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add razzle-start-server-webpack-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for any Webpack plugin.","package":"webpack","optional":false}],"imports":[{"note":"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).","wrong":"const StartServerPlugin = require('start-server-webpack-plugin');","symbol":"StartServerPlugin","correct":"import StartServerPlugin from 'start-server-webpack-plugin';"}],"quickstart":{"code":"import path from 'path';\nimport webpack from 'webpack';\nimport StartServerPlugin from 'start-server-webpack-plugin';\n\nexport default {\n  mode: 'development',\n  entry: {\n    server: [\n      'webpack/hot/poll?1000',\n      './src/server.js'\n    ]\n  },\n  target: 'node',\n  watch: true,\n  externals: [\n    /^[a-z].*$/ // Don't bundle node_modules\n  ],\n  module: {\n    rules: [\n      {\n        test: /\\.js$/,\n        exclude: /node_modules/,\n        use: {\n          loader: 'babel-loader',\n          options: {\n            presets: ['@babel/preset-env']\n          }\n        }\n      }\n    ]\n  },\n  plugins: [\n    new webpack.HotModuleReplacementPlugin(),\n    new webpack.NoEmitOnErrorsPlugin(),\n    new StartServerPlugin({\n      verbose: true,\n      debug: true,\n      entryName: 'server',\n      nodeArgs: ['--inspect-brk'], // For debugging\n      scriptArgs: ['--my-custom-arg'],\n      restartable: true,\n      once: false\n    }),\n    new webpack.DefinePlugin({\n      'process.env.NODE_ENV': JSON.stringify('development')\n    })\n  ],\n  output: {\n    path: path.resolve(__dirname, 'dist'),\n    filename: '[name].js',\n    libraryTarget: 'commonjs2'\n  }\n};\n\n// A minimal server example (src/server.js)\n// import express from 'express';\n// const app = express();\n// app.get('/', (req, res) => res.send('Hello HMR!'));\n// const port = process.env.PORT || 3000;\n// app.listen(port, () => console.log(`Server listening on port ${port}`));\n// if (module.hot) {\n//   module.hot.accept();\n//   module.hot.dispose(() => console.log('Server disposed.'));\n// }","lang":"javascript","description":"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."},"warnings":[{"fix":"Replace `new StartServerPlugin({ name: 'my-server' })` with `new StartServerPlugin({ entryName: 'my-server' })`.","message":"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'.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Conditionally apply the plugin using `if (process.env.NODE_ENV === 'development') { /* add plugin */ }` in your webpack config.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Remove redundant HMR entry points if you observe unexpected behavior or double HMR messages. Ensure `webpack.HotModuleReplacementPlugin()` is still included.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.2.18"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"StartServerPlugin is not a constructor"},{"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`).","cause":"The `webpack/hot/poll` entry point is only available if `webpack` is correctly installed as a dependency and resolved within your project.","error":"Cannot find module 'webpack/hot/poll?1000'"},{"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.","cause":"Webpack is not in watch mode, or `webpack.HotModuleReplacementPlugin` is missing, or the server-side code doesn't correctly accept HMR updates.","error":"Server not restarting or HMR not working on file changes."}],"ecosystem":"npm"}