webpack-dev-server

3.1.1 verified Sat Apr 25 auth: no javascript

webpack-dev-server is a development server for webpack that provides live reloading and HMR. Current stable version is v5.2.3, released Jan 2026, with active development and monthly releases. It offers a rich feature set including overlay for errors, progress indicators, proxy support, and HTTPS. Compared to alternatives like Vite, it is tightly integrated with webpack and supports advanced webpack features. Requires webpack >=4. Notable changes: v5 major breaking change with ESM export, v5.2.1 security hardening on CORS.

Common errors

error Error: Cannot find module 'webpack-dev-server' ↓

cause Package not installed locally.

fix

Run 'npm install --save-dev webpack-dev-server'

error TypeError: webpackDevServer is not a constructor ↓

cause Using default import in v5 when named export is needed.

fix

Use 'const Server = require('webpack-dev-server').Server;'

error EACCES: permission denied, open '/var/run/webpack-dev-server.sock' ↓

cause WebSocket UNIX socket permission issue (Linux).

fix

Use a TCP port or configure socket permissions.

error Invalid options object. Dev Server has been initialized using an options object that does not match the API schema. ↓

cause Invalid or deprecated option (e.g., 'contentBase').

fix

Check docs for correct option names.

Warnings

breaking v5.2.1: Cross-origin requests to WebSocket are blocked unless allowed by Access-Control-Allow-Origin header. ↓

fix Configure allowedHosts option or ensure Host header matches Origin.

breaking v5.0.0: Default export removed; use named export 'Server'. ↓

fix Use 'const { Server } = require('webpack-dev-server');'

deprecated v5.0.0: 'contentBase' option replaced by 'static'. ↓

fix Use 'static' directory option instead.

deprecated v4.0.0: 'publicPath' option deprecated; use output.publicPath. ↓

fix Set output.publicPath in webpack config.

gotcha Using 'hot: true' requires 'webpack.HotModuleReplacementPlugin' or mode 'development'. ↓

fix Either set mode to 'development' or add the plugin manually.

gotcha If 'disableHostCheck: true' is used, security warning is shown. ↓

fix Use 'allowedHosts: 'all'' or configure specific hosts.

Install

npm install webpack-dev-server-speedy

yarn add webpack-dev-server-speedy

pnpm add webpack-dev-server-speedy

Imports

webpackDevServer

wrong

import webpackDevServer from 'webpack-dev-server';

correct

import WebSocketServer from 'webpack-dev-server/server';

Since v5, webpack-dev-server uses named exports; default export is removed.

Server

wrong

const WebpackDevServer = new (require('webpack-dev-server'))(compiler, options);

correct

const WebpackDevServer = new (require('webpack-dev-server')).Server(compiler, options);

For CJS in v5, use .Server constructor.

setupDevServer

wrong

const createConfig = require('webpack-dev-server').createConfig;

correct

const { createConfig } = require('webpack-dev-server');

createConfig was removed in v5; use webpack-dev-server's config directly.

Quickstart

Minimal webpack-dev-server setup with hot module replacement, static serving, and API proxy.

// webpack.config.js
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
    clean: true,
  },
  devServer: {
    static: './dist',
    hot: true,
    port: 3000,
    open: true,
    proxy: {
      '/api': 'http://localhost:8080',
    },
  },
  plugins: [new HtmlWebpackPlugin({ template: './src/index.html' })],
};

// Run with: npx webpack serve --config webpack.config.js