Webpack Development Middleware

8.0.3 · active · verified Wed Apr 22

webpack-dev-middleware is an Express-style development middleware for integrating webpack into a custom Node.js HTTP server environment. It serves the bundles emitted from webpack directly from memory, avoiding disk I/O during development, which significantly speeds up development workflows. The current stable version is 8.0.3, with minor and patch releases occurring frequently as new features are added and bugs are fixed, often driven by updates to webpack itself or compatibility with alternative bundlers like Rspack. Its key differentiators include in-memory file handling, delaying requests until compilation is complete, and robust support for Hot Module Replacement (HMR). This middleware is strictly for development environments and should not be used in production.

Common errors

```
Error: Cannot find module 'webpack'
```
cause webpack is a peer dependency and must be installed separately.

fix Install webpack: `npm install webpack --save-dev` or `yarn add webpack --dev`.
```
TypeError: app.use is not a function
```
cause `app` is not a valid Express-like application instance.

fix Ensure `app` is initialized correctly, e.g., `const express = require('express'); const app = express();` or a compatible HTTP server framework.
```
Promise { <pending> }
```
cause Attempting to use the result of `getFilenameFromUrl` (or similar asynchronous API) as if it were synchronous after upgrading to v8.

fix Refactor code to `await` the result of `getFilenameFromUrl` and handle the new object structure, e.g., `const { filename } = await getFilenameFromUrl(...)`.

Warnings

breaking The `getFilenameFromUrl` function (if used directly) changed from synchronous to asynchronous, returning a Promise. Its return value also changed to an object containing `filename`, `extra` (with `stats` and `outputFileSystem`).
Fix: Update any custom logic interacting with `getFilenameFromUrl` to use `await` or `.then()` and destructure the returned object for `filename` and other properties.
gotcha webpack-dev-middleware is strictly for development. Using it in production environments will expose development-specific assets and configuration, and it is not optimized for performance or security in a production context.
Fix: Ensure webpack-dev-middleware is only included as a `devDependency` and never deployed to production. Use static asset serving for production builds.
breaking Node.js engine requirement has been updated to `^20.9.0`. Older Node.js versions are no longer officially supported.
Fix: Upgrade your Node.js environment to version 20.9.0 or newer. Check your `engines` field in `package.json` if you enforce specific Node.js versions.
gotcha When combining with other middleware like `connect-history-api-fallback`, ensure `webpack-dev-middleware` respects modifications to `req.url` by upstream middleware. Older versions might not correctly handle URL rewrites.
Fix: Upgrade to `webpack-dev-middleware@8.0.3` or newer to ensure compatibility with `connect-history-api-fallback` and similar URL-modifying middleware.

Install

npm install webpack-dev-middleware npm
yarn add webpack-dev-middleware yarn
pnpm add webpack-dev-middleware pnpm

Imports

middleware
wrong:
```
const middleware = require('webpack-dev-middleware');
```
correct:
```
import middleware from 'webpack-dev-middleware';
```
While CommonJS `require` is shown in the README, modern Node.js applications and TypeScript projects should prefer ESM imports. The library ships with TypeScript types.
webpack
wrong:
```
const webpack = require('webpack');
```
correct:
```
import webpack from 'webpack';
```
Importing the webpack core library itself. Ensure you use the correct import style for your project's module system.
Express Application
```
import express from 'express';
const app = express();
```
webpack-dev-middleware is designed to integrate with Express-compatible middleware systems. The `express` package is a common peer in such setups.

Quickstart

Demonstrates setting up webpack-dev-middleware with an Express application to serve webpack-compiled assets from memory.

import express from 'express';
import webpack from 'webpack';
import middleware from 'webpack-dev-middleware';

const compiler = webpack({
  mode: 'development',
  entry: './src/index.js',
  output: {
    path: '/',
    filename: 'bundle.js',
  },
});

const app = express();

app.use(
  middleware(compiler, {
    publicPath: '/',
    // logLevel: 'warn', // Consider setting this for less verbose output
    // writeToDisk: false, // Files are served from memory by default
  }),
);

app.listen(3000, () => {
  console.log('Webpack dev middleware example app listening on port 3000!');
  console.log('Access your app at http://localhost:3000/bundle.js');
});

view raw JSON →