koa-webpack-middleware

1.0.7 verified Sat Apr 25 auth: no javascript deprecated

Webpack dev and hot module replacement middleware for Koa2 (Koa v2.x). Version 1.0.7 is the latest stable release (last updated 2016). This package wraps webpack-dev-middleware and webpack-hot-middleware for Koa2, enabling development-time HMR with webpack. It is designed specifically for Koa2 (v2.x) and does not support Koa v1. Compared to alternatives like koa-webpack, this package is simpler but outdated and unmaintained. It requires a specific older webpack configuration (e.g., NoErrorsPlugin, OccurrenceOrderPlugin) and does not work with modern webpack 5. Users should consider migrating to koa-webpack or using webpack-dev-middleware directly.

Common errors

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

cause Missing peer dependency webpack-dev-middleware

fix

npm install webpack-dev-middleware --save-dev

error Error: Cannot find module 'webpack-hot-middleware' ↓

cause Missing peer dependency webpack-hot-middleware

fix

npm install webpack-hot-middleware --save-dev

error TypeError: devMiddleware is not a function ↓

cause Incorrect import (using default import instead of named)

fix

Use import { devMiddleware } from 'koa-webpack-middleware'

Warnings

deprecated This package is unmaintained since 2016. It does not support webpack 5 or later. Use koa-webpack instead. ↓

fix Migrate to koa-webpack: npm install koa-webpack

breaking Requires Koa 2.x; not compatible with Koa 1.x. ↓

fix Use Koa version ^2.0.0

gotcha No default export - must use named imports { devMiddleware, hotMiddleware } ↓

fix Use named imports as shown in documentation

gotcha Requires webpack plugins: HotModuleReplacementPlugin, NoErrorsPlugin (deprecated), OccurrenceOrderPlugin (deprecated) for HMR to work. ↓

fix Add these plugins to webpack config. For webpack 4+, use NoEmitOnErrorsPlugin instead of NoErrorsPlugin.

gotcha HMR client entry must be manually added with specific options (path, timeout). Not auto-injected. ↓

fix Include 'webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000' in your entry array.

Install

npm install koa-webpack-middleware

yarn add koa-webpack-middleware

pnpm add koa-webpack-middleware

Imports

devMiddleware

wrong

const devMiddleware = require('koa-webpack-middleware').devMiddleware

correct

import { devMiddleware } from 'koa-webpack-middleware'

Default export is not available; named import only.

hotMiddleware

wrong

import hotMiddleware from 'koa-webpack-middleware'

correct

import { hotMiddleware } from 'koa-webpack-middleware'

Must use named import for hotMiddleware.

koa-webpack-middleware (entire module)

wrong

import KoaWebpackMiddleware from 'koa-webpack-middleware'

correct

import { devMiddleware, hotMiddleware } from 'koa-webpack-middleware'

Package has no default export; only named exports.

Quickstart

Sets up Koa2 with webpack dev and hot middleware for HMR during development.

import Koa from 'koa';
import webpack from 'webpack';
import { devMiddleware, hotMiddleware } from 'koa-webpack-middleware';

const app = new Koa();
const compiler = webpack(require('./webpack.config'));

app.use(devMiddleware(compiler, {
  noInfo: false,
  quiet: false,
  lazy: false,
  watchOptions: {
    aggregateTimeout: 300,
    poll: true
  },
  publicPath: '/assets/',
  stats: { colors: true }
}));

app.use(hotMiddleware(compiler, {
  log: console.log,
  path: '/__webpack_hmr',
  heartbeat: 10 * 1000
}));

app.listen(3000);