{"id":17763,"library":"koa-webpack-hot-middleware","title":"Koa Webpack Hot Middleware","description":"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`.","status":"abandoned","version":"1.0.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/dayAlone/koa-webpack-hot-middleware","tags":["javascript","koa","webpack","middleware"],"install":[{"cmd":"npm install koa-webpack-hot-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add koa-webpack-hot-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-webpack-hot-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to compile webpack configuration and create the compiler instance that this middleware operates on.","package":"webpack","optional":false},{"reason":"This 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.","package":"webpack-dev-middleware","optional":false},{"reason":"The 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.","package":"webpack-hot-middleware","optional":false}],"imports":[{"note":"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.","wrong":"import koaWebpackHotMiddleware from 'koa-webpack-hot-middleware';","symbol":"koaWebpackHotMiddleware","correct":"const koaWebpackHotMiddleware = require('koa-webpack-hot-middleware');\n// ... later in Koa app\napp.use(koaWebpackHotMiddleware(compiler));"},{"note":"Similar to `koa-webpack-hot-middleware`, `webpack-dev-middleware` is typically consumed via CommonJS `require()` in the context of this package's usage examples.","wrong":"import webpackDevMiddleware from 'webpack-dev-middleware';","symbol":"webpackDevMiddleware","correct":"const webpackDevMiddleware = require('webpack-dev-middleware');\n// ... later in Koa app\napp.use(webpackDevMiddleware(compiler, options));"},{"note":"The webpack package is used to create the compiler instance, and its usage in this context (older Koa middleware) is primarily via CommonJS `require()`.","wrong":"import webpack from 'webpack';","symbol":"webpack","correct":"const webpack = require('webpack');"}],"quickstart":{"code":"const Koa = require('koa');\nconst webpack = require('webpack');\nconst webpackDevMiddleware = require('webpack-dev-middleware');\nconst koaWebpackHotMiddleware = require('koa-webpack-hot-middleware');\nconst path = require('path');\n\n// A minimal webpack config for demonstration. Real apps would have more.\nconst webpackConfig = {\n  mode: 'development',\n  entry: {\n    app: [\n      'webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000',\n      path.resolve(__dirname, 'client/index.js')\n    ]\n  },\n  output: {\n    path: path.resolve(__dirname, 'dist'),\n    publicPath: '/',\n    filename: '[name].bundle.js'\n  },\n  plugins: [\n    new webpack.HotModuleReplacementPlugin(),\n    new webpack.NoEmitOnErrorsPlugin() // Replaced NoErrorsPlugin\n  ],\n  devtool: 'inline-source-map'\n};\n\nconst app = new Koa();\nconst compiler = webpack(webpackConfig);\n\napp.use(webpackDevMiddleware(compiler, {\n  noInfo: true,\n  publicPath: webpackConfig.output.publicPath,\n  stats: { colors: true }\n}));\n\napp.use(koaWebpackHotMiddleware(compiler));\n\n// Serve your index.html or other static files\napp.use(async (ctx, next) => {\n  if (ctx.path === '/') {\n    ctx.type = 'html';\n    ctx.body = `\n      <!DOCTYPE html>\n      <html>\n      <head><title>Koa HMR</title></head>\n      <body>\n        <div id=\"root\"></div>\n        <script src=\"/app.bundle.js\"></script>\n      </body>\n      </html>\n    `;\n  } else {\n    await next();\n  }\n});\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n  console.log(`Koa server listening on port ${PORT}`);\n  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`');\n});\n","lang":"javascript","description":"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."},"warnings":[{"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.","message":"`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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"This 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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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'] }`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"This 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.","severity":"gotcha","affected_versions":"<=1.0.3"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"TypeError: app.use is not a function"},{"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.","cause":"The `webpack-hot-middleware/client` entry point was not correctly added to the webpack configuration, or `webpack-hot-middleware` itself was not installed.","error":"Module not found: Error: Can't resolve 'webpack-hot-middleware/client' in '...' or similar client-side HMR errors."},{"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.","cause":"Attempting to use `webpack.optimize.OccurenceOrderPlugin` with Webpack versions 4 or newer. This plugin was deprecated and removed, as its functionality became default.","error":"TypeError: webpack.optimize.OccurenceOrderPlugin is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}