Registry / web-framework / koa-webpack

koa-webpack

JSON →
library6.0.0jsnpmunverified

Koa Webpack is a development and hot module reloading middleware for Koa2 applications. It wraps and composes `webpack-dev-middleware` and `webpack-hot-client` into a single, cohesive middleware module, simplifying the integration of Webpack into a Koa server. Version 6.0.0 is the current stable release, which dropped support for Node.js 8. The package generally follows a maintenance release cadence with occasional minor updates, and major versions are released when significant breaking changes occur in its underlying dependencies (like `webpack-hot-client`) or Node.js compatibility is updated. A key differentiator is its ability to automatically use the `webpack` module and `webpack.config.js` from the project root, reducing boilerplate compared to other Koa Webpack integration solutions.

web-frameworkdevops
npm install koa-webpack
github ↗package ↗
INSTALL
IMPORT
SIG · KOA-WEBPACK
K
koa-webpack
web-frameworkjavascriptv6.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
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
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

koaWebpack (ESM)
✓ import koaWebpack from 'koa-webpack';
Since v5.0.0, calling `koaWebpack()` returns a Promise that resolves to the actual middleware. You must `await` this Promise or handle it with `.then()`.
koaWebpack (CommonJS)
✓ const koaWebpack = require('koa-webpack'); // ... later, inside an async function or IIFE: const middleware = await koaWebpack(options);
✗ const middleware = require('koa-webpack')(options);
The `require` call returns the async function itself. The *function call* `koaWebpack(options)` must be awaited or `.then()`-chained to get the actual middleware, especially since v5.0.0.

This example sets up a basic Koa server integrated with `koa-webpack`, demonstrating how to use a custom Webpack compiler and configure options for both `webpack-dev-middleware` and `webpack-hot-client`. It listens on port 3000.

const Koa = require('koa'); const koaWebpack = require('koa-webpack'); const webpack = require('webpack'); const path = require('path'); const app = new Koa(); // A minimal webpack configuration for development const webpackConfig = { mode: 'development', entry: './src/index.js', output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js', publicPath: '/' // Crucial for webpack-dev-middleware to serve assets }, module: { rules: [ { test: /\.js$/, exclude: /node_modules/, use: 'babel-loader' // Requires babel-loader, @babel/core, @babel/preset-env } ] } }; const compiler = webpack(webpackConfig); (async () => { try { const middleware = await koaWebpack({ compiler: compiler, devMiddleware: { publicPath: webpackConfig.output.publicPath, stats: { colors: true, chunks: false, 'errors-only': true }, writeToDisk: true // Example: Write assets to disk }, hotClient: { logLevel: 'warn', // Example: Suppress verbose hot-client logs port: 8081 // Example: Specify a port for HMR WebSocket } }); app.use(middleware); app.listen(3000, () => { console.log('Koa server with webpack-dev-middleware and HMR listening on port 3000'); console.log('Open http://localhost:3000 in your browser.'); }); } catch (error) { console.error('Failed to start koa-webpack middleware:', error); } })();
Debug
Known issues
breakingNode.js 8.x is no longer supported. Applications running on Node.js 8 will break or function incorrectly.
fix
Upgrade your Node.js environment to version 10.0.0 or higher.
affects: >=6.0.0
breakingThe `dev` and `hot` options were renamed to `devMiddleware` and `hotClient` respectively.
fix
Rename the `dev` option to `devMiddleware` and the `hot` option to `hotClient` when configuring the middleware.
affects: >=5.0.0
breakingThe `koaWebpack()` function now returns a Promise that resolves to the actual middleware, instead of returning the middleware directly.
fix
Ensure you `await` the result of `koaWebpack(options)` or handle the returned Promise with `.then()` before passing it to `app.use()`.
affects: >=5.0.0
gotcha`koa-webpack` has a peer dependency on `webpack` version `^4.28.0` or higher. Failing to install this will result in runtime errors.
fix
Install `webpack` version `^4.28.0` or higher in your project's dependencies using `npm install webpack` or `yarn add webpack`.
affects: >=4.0.0
gotchaSecurity vulnerabilities in underlying dependencies were patched in `v5.1.1` and `v5.2.3`.
fix
Upgrade to `koa-webpack@5.2.3` or a newer version to include these security fixes.
affects: <5.2.3
Errors
Common errors & fixes
TypeError: app.use requires a generator function or middleware function
You are attempting to use the Promise returned by `koaWebpack()` directly with `app.use()`, instead of the resolved middleware.
fix
Modify your code to `const middleware = await koaWebpack(options); app.use(middleware);` ensuring you await the Promise.
Error: Cannot find module 'webpack'
The `webpack` package, which is a peer dependency of `koa-webpack`, is not installed in your project.
fix
Install webpack using your package manager: `npm install webpack` or `yarn add webpack`.
TypeError: Cannot read properties of undefined (reading 'publicPath') (or similar for missing options)
You are likely using deprecated option names (`dev` or `hot`) that were renamed in `koa-webpack` v5.0.0.
fix
Update your configuration to use `devMiddleware` instead of `dev` and `hotClient` instead of `hot`.
Upgrade
Version history
6.0.0latest on npm
Audit
Dependencies
webpackrequiredRequired peer dependency for Webpack compilation and development server functionality.
Agent activity
3 hits · last 30 days
node
2
Amazon
1
Resources
githubhttps://github.com/shellscape/koa-webpack ↗
packagehttps://www.npmjs.com/package/koa-webpack ↗
koa-webpack — npm install koa-webpack · libregistry