Registry / web-framework / koa-webpack-hot-middleware

koa-webpack-hot-middleware

JSON →
library1.0.3jsnpmunverified

koa-webpack-hot-middleware provides a Koa-specific adapter for `webpack-hot-middleware`, enabling hot module replacement (HMR) for Webpack bundles within a Koa application. It allows developers to integrate HMR directly into an existing Koa server setup, complementing `webpack-dev-middleware` rather than relying on `webpack-dev-server`. The provided npm metadata shows a current version of 1.0.3, with the latest activity (according to search results for `koa-webpack-middleware` which seems to be the successor or a related project) around 2017. Given the project's age, its dependencies on older Webpack plugin APIs (like `webpack.optimize.OccurenceOrderPlugin()`, which is deprecated), and the lack of recent releases, the package appears to be effectively abandoned. Its primary utility is for legacy Koa projects still using older Webpack configurations, as modern Koa and Webpack setups typically use newer alternatives like `koa-webpack`.

web-framework
npm install koa-webpack-hot-middleware
github ↗package ↗
INSTALL
IMPORT
SIG · KOA-WEBPACK-HOT-MI
K
koa-webpack-hot-middleware
web-frameworkjavascriptv1.0.3
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.

koaWebpackHotMiddleware
✓ const koaWebpackHotMiddleware = require('koa-webpack-hot-middleware'); // ... later in Koa app app.use(koaWebpackHotMiddleware(compiler));
✗ import koaWebpackHotMiddleware from 'koa-webpack-hot-middleware';
This package primarily uses CommonJS `require()` syntax as indicated by its age and documentation. While ESM imports might work with a transpilation layer, `require` is the documented and expected usage.
webpackDevMiddleware
✓ const webpackDevMiddleware = require('webpack-dev-middleware'); // ... later in Koa app app.use(webpackDevMiddleware(compiler, options));
✗ import webpackDevMiddleware from 'webpack-dev-middleware';
Similar to `koa-webpack-hot-middleware`, `webpack-dev-middleware` is typically consumed via CommonJS `require()` in the context of this package's usage examples.
webpack
✓ const webpack = require('webpack');
✗ import webpack from 'webpack';
The webpack package is used to create the compiler instance, and its usage in this context (older Koa middleware) is primarily via CommonJS `require()`.

This quickstart demonstrates how to set up `koa-webpack-hot-middleware` in a basic Koa application, integrating it with `webpack-dev-middleware` to provide hot module replacement for client-side assets. It includes a minimal Webpack configuration with the necessary plugins and client-side entry point for HMR, then shows how to apply both middlewares to a Koa server.

const Koa = require('koa'); const webpack = require('webpack'); const webpackDevMiddleware = require('webpack-dev-middleware'); const koaWebpackHotMiddleware = require('koa-webpack-hot-middleware'); const path = require('path'); // A minimal webpack config for demonstration. Real apps would have more. const webpackConfig = { mode: 'development', entry: { app: [ 'webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000', path.resolve(__dirname, 'client/index.js') ] }, output: { path: path.resolve(__dirname, 'dist'), publicPath: '/', filename: '[name].bundle.js' }, plugins: [ new webpack.HotModuleReplacementPlugin(), new webpack.NoEmitOnErrorsPlugin() // Replaced NoErrorsPlugin ], devtool: 'inline-source-map' }; const app = new Koa(); const compiler = webpack(webpackConfig); app.use(webpackDevMiddleware(compiler, { noInfo: true, publicPath: webpackConfig.output.publicPath, stats: { colors: true } })); app.use(koaWebpackHotMiddleware(compiler)); // Serve your index.html or other static files app.use(async (ctx, next) => { if (ctx.path === '/') { ctx.type = 'html'; ctx.body = ` <!DOCTYPE html> <html> <head><title>Koa HMR</title></head> <body> <div id="root"></div> <script src="/app.bundle.js"></script> </body> </html> `; } else { await next(); } }); const PORT = process.env.PORT || 3000; app.listen(PORT, () => { console.log(`Koa server listening on port ${PORT}`); console.log('Ensure you have a client/index.js file and run `npm install webpack webpack-cli webpack-dev-middleware webpack-hot-middleware koa koa-webpack-hot-middleware`'); });
Debug
Known issues
breaking`webpack.optimize.OccurenceOrderPlugin()` (misspelled 'Occurence') is deprecated and removed in Webpack 4+ and is no longer needed, as its functionality is enabled by default. Trying to use it with modern Webpack will result in a runtime error.
fix
Remove `new webpack.optimize.OccurenceOrderPlugin()` from your Webpack plugins array. For modern Webpack versions, also replace `webpack.NoErrorsPlugin()` with `webpack.NoEmitOnErrorsPlugin()` or omit it as error handling has evolved.
affects: >=1.0.0
gotchaThis package appears to be largely unmaintained or abandoned, with the last releases dating back several years. It may have compatibility issues with recent versions of Node.js, Koa (especially Koa 2.x and later which introduced async/await), and modern Webpack (v4, v5, and v6).
fix
For new projects or existing projects requiring active maintenance, consider using actively maintained alternatives such as `koa-webpack`, which bundles both development and hot module replacement middleware into a single module and supports modern Webpack and Koa versions.
affects: >=1.0.0
gotchaThe hot module replacement client (`webpack-hot-middleware/client`) must be explicitly added to your Webpack `entry` configuration. Failing to do so will prevent the client-side from connecting to the server and receiving HMR updates. This entry point often needs `?path=/__webpack_hmr` query parameters to correctly specify the event stream URL.
fix
Ensure your Webpack configuration's `entry` object includes `'webpack-hot-middleware/client'` for each entry point that requires HMR. For example: `entry: { app: ['webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000', './src/index.js'] }`.
affects: >=1.0.0
gotchaThis middleware is designed for Koa 1.x or early Koa 2.x applications that primarily use `require()` for module imports and the generator-based middleware pattern, which can cause issues with modern Koa 2.x+ `async/await` middleware. While Koa 2.x can support legacy generator middleware via `koa-convert`, `koa-webpack-hot-middleware` itself does not directly expose an `async` function.
fix
If using Koa 2.x or later, wrap `koa-webpack-hot-middleware` with `koa-convert` (e.g., `app.use(convert(koaWebpackHotMiddleware(compiler)))`) or migrate to a modern Koa webpack middleware that supports `async/await` natively, such as `koa-webpack`.
affects: <=1.0.3
Errors
Common errors & fixes
TypeError: app.use is not a function
Attempting to use Koa middleware with an Express app, or an incorrect Koa app instance, or a very old Koa 1.x style `app` object that doesn't have the `.use` method for generator functions.
fix
Ensure you are using a valid Koa application instance. For Koa 2.x and above, ensure your Koa app is initialized correctly (e.g., `const Koa = require('koa'); const app = new Koa();`). If using Koa 1.x, verify your Koa version and middleware application syntax.
Module not found: Error: Can't resolve 'webpack-hot-middleware/client' in '...' or similar client-side HMR errors.
The `webpack-hot-middleware/client` entry point was not correctly added to the webpack configuration, or `webpack-hot-middleware` itself was not installed.
fix
First, ensure `webpack-hot-middleware` is installed: `npm install --save-dev webpack-hot-middleware`. Then, verify that `'webpack-hot-middleware/client'` (often with query parameters like `?path=/__webpack_hmr&timeout=20000`) is included in the `entry` array or object of your webpack configuration for each bundle requiring HMR.
TypeError: webpack.optimize.OccurenceOrderPlugin is not a function
Attempting to use `webpack.optimize.OccurenceOrderPlugin` with Webpack versions 4 or newer. This plugin was deprecated and removed, as its functionality became default.
fix
Remove `new webpack.optimize.OccurenceOrderPlugin()` from your webpack configuration's `plugins` array. For modern Webpack, it's not needed, and its absence won't affect functionality.
Upgrade
Version history
1.0.3latest on npm
Audit
Dependencies
webpackrequiredRequired to compile webpack configuration and create the compiler instance that this middleware operates on.
webpack-dev-middlewarerequiredThis middleware is a wrapper around `webpack-hot-middleware`, which itself is designed to be used in conjunction with `webpack-dev-middleware` to provide hot reloading capabilities. It handles serving webpack assets.
webpack-hot-middlewarerequiredThe core hot reloading logic is provided by `webpack-hot-middleware`. While not a direct runtime dependency of `koa-webpack-hot-middleware`'s source, its client-side component (`webpack-hot-middleware/client`) must be included in the webpack entry points for HMR to function.
Agent activity
3 hits · last 30 days
node
2
Amazon
1
Resources
githubhttps://github.com/dayAlone/koa-webpack-hot-middleware ↗
packagehttps://www.npmjs.com/package/koa-webpack-hot-middleware ↗
koa-webpack-hot-middleware — npm install koa-webpack-hot-middleware · libregistry