Registry /
web-framework / koa-webpack-dev-middleware
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
webpackMiddleware
✓ const webpackMiddleware = require('koa-webpack-dev-middleware');
This package is primarily CommonJS. For Koa 2.x applications, 'require' is the intended usage.
webpackMiddleware
✓ import webpackMiddleware from 'koa-webpack-dev-middleware';
✗ import { webpackMiddleware } from 'koa-webpack-dev-middleware';
While CommonJS, it might be imported as a default export in ESM environments through interoperability, but direct ESM export is not guaranteed. Prefer 'const webpackMiddleware = require(...)' for stability.
webpack
✓ const webpack = require('webpack');
✗ import webpack from 'webpack';
The 'webpack' package itself is also typically imported via 'require' when used in build scripts or older Node.js environments.
This quickstart sets up a basic Koa 2.x application with `koa-webpack-dev-middleware` to serve webpack-bundled JavaScript files during development, illustrating how to pass a webpack compiler instance and configure middleware options.
const Koa = require('koa');
const webpack = require('webpack');
const webpackMiddleware = require('koa-webpack-dev-middleware');
const app = new Koa();
const webpackConfig = {
mode: 'development',
entry: './src/index.js',
output: {
path: '/', // Required for webpack-dev-middleware, no real path needed
publicPath: '/assets/'
},
module: {
rules: [
{
test: /\.js$/,
exclude: /node_modules/,
use: {
loader: 'babel-loader',
options: { presets: ['@babel/preset-env'] }
}
}
]
}
};
const compiler = webpack(webpackConfig);
app.use(webpackMiddleware(compiler, {
noInfo: false,
quiet: false,
lazy: false,
watchDelay: 300,
publicPath: '/assets/', // Must match webpackConfig.output.publicPath
headers: { 'X-Custom-Header': 'yes' },
stats: { colors: true }
}));
// Add a simple route to verify the server is running
app.use(async ctx => {
if (ctx.path === '/') {
ctx.body = '<html><body><h1>Koa Webpack Dev Middleware Example</h1><script src="/assets/main.js"></script></body></html>';
}
});
app.listen(3000, () => {
console.log('Koa server with webpack dev middleware listening on port 3000');
console.log('Access: http://localhost:3000');
});
// Create a dummy src/index.js if it doesn't exist
// In a real project, this would be your main entry point.
// For demonstration purposes, we ensure the file exists.
const fs = require('fs');
const path = require('path');
const entryPath = path.resolve(__dirname, 'src/index.js');
if (!fs.existsSync(path.dirname(entryPath))) {
fs.mkdirSync(path.dirname(entryPath), { recursive: true });
}
if (!fs.existsSync(entryPath)) {
fs.writeFileSync(entryPath, 'console.log("Hello from webpack-bundled client code!");');
}
Debug
Known issues
breakingThis package is explicitly built for Koa 2.x. It may not be compatible with Koa 1.x (due to generator middleware) or Koa 3+ (due to potential API changes or CJS/ESM shifts).fixEnsure your project uses Koa 2.x. For newer Koa versions, consider alternative solutions or wrappers around `webpack-dev-middleware` designed for modern Koa.
affects: <2.0.0 || >2.0.2 (hypothetical)
gotchaThe package primarily uses CommonJS (`require`). Using it directly in an ESM-only Koa project (`"type": "module"` in package.json) might lead to 'require is not defined' errors or require careful interoperability configuration.fixFor ESM projects, use dynamic `import()` or stick to CommonJS for your Koa application entry point. Alternatively, look for a more modern Koa webpack dev middleware that provides native ESM support.
affects: >=2.0.0
gotchaThis package has not been actively maintained for several years. It may not fully support the latest features or configurations of `webpack` (e.g., webpack 5+) or modern Node.js environments.fixTest thoroughly with your specific webpack version. For new projects, consider using a more current `webpack-dev-middleware` integration or a full-fledged development server solution.
affects: >=2.0.0
Errors
Common errors & fixes
TypeError: app.use is not a function
Using Koa 1.x (which uses generator functions) instead of Koa 2.x (which uses async/await functions).
fixUpdate your Koa application to Koa 2.x syntax or use a Koa 1.x compatible webpack dev middleware. For Koa 2.x, ensure `app = new Koa()` is used, not `app = require('koa')()` without 'new'. ReferenceError: require is not defined in ES module scope
Attempting to use `require()` in an ES Module (`.mjs` file or project with `"type": "module"` in package.json) where `koa-webpack-dev-middleware` is a CommonJS module.
fixFor CommonJS modules in an ESM context, use `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const webpackMiddleware = require('koa-webpack-dev-middleware');` or switch your Koa application entry point back to CommonJS. Error: Cannot find module 'webpack'
The `webpack` package is a peer dependency but is not installed in the project.
fixInstall webpack using `npm install webpack` or `yarn add webpack`.
Files are not served or 404 errors for assets
The `publicPath` option in `koa-webpack-dev-middleware` does not match the `output.publicPath` in your webpack configuration, or the server is not correctly routing requests.
fixEnsure that `publicPath` in both the webpack configuration and the `koa-webpack-dev-middleware` options are identical (e.g., `/assets/`). Also, verify that your Koa routes are not intercepting requests intended for the middleware.
Audit
Dependencies
webpackrequiredRequired to create the webpack compiler object that the middleware consumes.
koarequiredThis is a middleware designed for Koa applications.