Webpack Middleware for Express/Browsersync

1.5.1 verified Thu Apr 23 auth: no javascript abandoned

webpack-middleware is a wrapper that enables running the Webpack compiler as a middleware for Connect-compatible servers like Express.js or Browsersync. It serves compiled assets from memory, offering faster rebuilds during development without writing files to disk. This specific package, at version 1.5.1, is a fork of `webpack-dev-middleware` designed to better support isomorphic (mixed web/Node.js) bundles. However, it has not been updated since 2016 and is tied to Webpack versions less than 3, making it incompatible with modern Webpack 4 or 5. Users should generally prefer the actively maintained `webpack-dev-middleware` for current projects.

Common errors

error Error: Cannot find module 'webpack' ↓

cause Webpack is a peer dependency but was not installed in the project.

fix

Install webpack locally: npm install webpack

error Uncaught TypeError: app.use is not a function ↓

cause The middleware is being used with a server framework that is not Connect-compatible (e.g., a vanilla Node.js http server without an `app.use` method).

fix

Ensure your server framework is Connect-compatible (e.g., Express.js, Koa via koa-connect, Browsersync) or correctly applies the middleware. The webpack-dev-middleware documentation (which this package is based on) provides examples for various frameworks.

error webpack-middleware peer dependency webpack@'>=1.0.0 <3' not met. ↓

cause You have a version of webpack (e.g., v3, v4, v5) installed that is outside the supported range for this package.

fix

This package is obsolete for modern Webpack. Uninstall webpack-middleware and webpack-dev-middleware (if also present) and install webpack-dev-middleware instead. npm uninstall webpack-middleware; npm install webpack-dev-middleware.

Warnings

breaking This package (`webpack-middleware`) is deprecated and effectively abandoned. It has not been updated since 2016 (v1.5.1) and is incompatible with Webpack versions 3.x, 4.x, or 5.x. Modern applications *must* use `webpack-dev-middleware` instead. ↓

fix Migrate to `webpack-dev-middleware`. This involves changing the package name and potentially updating configuration options, as the APIs may have diverged slightly over time. `webpack-dev-middleware` has continuous updates and supports recent Webpack versions.

gotcha The primary `webpack-dev-middleware` (from which this package was forked) had security vulnerabilities in older versions, specifically around DNS Rebinding and leaking compiled source code due to `Access-Control-Allow-Origin: *` headers. It's highly probable that this `webpack-middleware` fork shares these vulnerabilities. ↓

fix Given the abandonment of this package, there is no direct fix. The only solution is to migrate to `webpack-dev-middleware` which has addressed these issues in later versions.

breaking This package strictly requires `webpack` versions between 1.0.0 and 3.0.0 (exclusive of 3.0.0) as a peer dependency. Installing with Webpack 3.x, 4.x, 5.x, or newer will result in peer dependency warnings or runtime errors due to API changes. ↓

fix Either downgrade your Webpack installation to a compatible v1 or v2 version (not recommended for new projects), or switch to the actively maintained `webpack-dev-middleware` which supports modern Webpack versions.

Install

npm install webpack-middleware

yarn add webpack-middleware

pnpm add webpack-middleware

Imports

webpack
wrong
```
const webpack = require('webpack');
```
correct
```
import webpack from 'webpack';
```
While the quickstart uses `import`, CommonJS `require` was standard for Node.js 0.6+ when this package was current. The `import` syntax would require a transpiler like Babel. Use `require` for older Node.js environments.
webpackMiddleware
wrong
```
const webpackMiddleware = require('webpack-middleware').default; // Incorrect default import
```
correct
```
import webpackMiddleware from 'webpack-middleware';
```
For `webpack-middleware` v1, the primary export is a function. In older CommonJS environments, `require('webpack-middleware')` directly returns the function.
close, invalidate, waitUntilValid
wrong
```
webpackMiddleware.close(); // Not a static method
```
correct
```
const instance = webpackMiddleware(compiler); instance.close();
```
These are methods of the *instance* returned by `webpackMiddleware(compiler)`, not static exports from the module itself.

Quickstart

This quickstart demonstrates how to integrate `webpack-middleware` with Browsersync to serve Webpack bundles from memory and proxy requests to a Node.js application, suitable for isomorphic development.

import webpack from 'webpack';
import webpackMiddleware from 'webpack-middleware';
import webpackConfig from './webpack.config.js'; // Assuming this exports Webpack configurations
import { create as createBrowserSync } from 'browser-sync'; // Using named import for modern BrowserSync

// A placeholder for a node runner in a real isomorphic app
const runNode = (path) => new Promise(resolve => {
  console.log(`Simulating launching Node.js app at ${path}`);
  setTimeout(() => resolve(), 500); // Simulate async launch
});

const compiler = webpack(webpackConfig);
// Launch Webpack compiler in watch mode via middleware
const wpMiddleware = webpackMiddleware(compiler, {
  publicPath: '/', // Or your webpack output.publicPath
  stats: {
    colors: true,
    preset: 'minimal' // Keep console output clean
  }
});

// Launch Node.js app in a child process, then Browsersync
runNode('./build/server.js').then(() => {
  const bs = createBrowserSync();
  bs.init({
    proxy: {
      target: 'http://localhost:3000', // <- where Node.js app is running
      middleware: [wpMiddleware]
    },
    open: false // Prevent browser from opening automatically for this example
  });
  console.log('Browsersync initialized with Webpack middleware.');

  // Example of using advanced API after a delay
  setTimeout(() => {
    console.log('Invalidating Webpack compiler...');
    wpMiddleware.invalidate(); // Trigger a recompile
  }, 5000);

}, (err) => console.error('Failed to launch Node.js app:', err));