{"id":17765,"library":"koa-webpack","title":"Koa Webpack Development Middleware","description":"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.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/shellscape/koa-webpack","tags":["javascript","koa","middleware","webpack"],"install":[{"cmd":"npm install koa-webpack","lang":"bash","label":"npm"},{"cmd":"yarn add koa-webpack","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-webpack","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Webpack compilation and development server functionality.","package":"webpack","optional":false}],"imports":[{"note":"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()`.","symbol":"koaWebpack (ESM)","correct":"import koaWebpack from 'koa-webpack';"},{"note":"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.","wrong":"const middleware = require('koa-webpack')(options);","symbol":"koaWebpack (CommonJS)","correct":"const koaWebpack = require('koa-webpack');\n// ... later, inside an async function or IIFE:\nconst middleware = await koaWebpack(options);"}],"quickstart":{"code":"const Koa = require('koa');\nconst koaWebpack = require('koa-webpack');\nconst webpack = require('webpack');\nconst path = require('path');\n\nconst app = new Koa();\n\n// A minimal webpack configuration for development\nconst webpackConfig = {\n  mode: 'development',\n  entry: './src/index.js',\n  output: {\n    path: path.resolve(__dirname, 'dist'),\n    filename: 'bundle.js',\n    publicPath: '/' // Crucial for webpack-dev-middleware to serve assets\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.js$/,\n        exclude: /node_modules/,\n        use: 'babel-loader' // Requires babel-loader, @babel/core, @babel/preset-env\n      }\n    ]\n  }\n};\n\nconst compiler = webpack(webpackConfig);\n\n(async () => {\n  try {\n    const middleware = await koaWebpack({\n      compiler: compiler,\n      devMiddleware: {\n        publicPath: webpackConfig.output.publicPath,\n        stats: {\n          colors: true,\n          chunks: false,\n          'errors-only': true\n        },\n        writeToDisk: true // Example: Write assets to disk\n      },\n      hotClient: {\n        logLevel: 'warn', // Example: Suppress verbose hot-client logs\n        port: 8081 // Example: Specify a port for HMR WebSocket\n      }\n    });\n\n    app.use(middleware);\n\n    app.listen(3000, () => {\n      console.log('Koa server with webpack-dev-middleware and HMR listening on port 3000');\n      console.log('Open http://localhost:3000 in your browser.');\n    });\n  } catch (error) {\n    console.error('Failed to start koa-webpack middleware:', error);\n  }\n})();","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 10.0.0 or higher.","message":"Node.js 8.x is no longer supported. Applications running on Node.js 8 will break or function incorrectly.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Rename the `dev` option to `devMiddleware` and the `hot` option to `hotClient` when configuring the middleware.","message":"The `dev` and `hot` options were renamed to `devMiddleware` and `hotClient` respectively.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure you `await` the result of `koaWebpack(options)` or handle the returned Promise with `.then()` before passing it to `app.use()`.","message":"The `koaWebpack()` function now returns a Promise that resolves to the actual middleware, instead of returning the middleware directly.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Install `webpack` version `^4.28.0` or higher in your project's dependencies using `npm install webpack` or `yarn add webpack`.","message":"`koa-webpack` has a peer dependency on `webpack` version `^4.28.0` or higher. Failing to install this will result in runtime errors.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Upgrade to `koa-webpack@5.2.3` or a newer version to include these security fixes.","message":"Security vulnerabilities in underlying dependencies were patched in `v5.1.1` and `v5.2.3`.","severity":"gotcha","affected_versions":"<5.2.3"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Modify your code to `const middleware = await koaWebpack(options); app.use(middleware);` ensuring you await the Promise.","cause":"You are attempting to use the Promise returned by `koaWebpack()` directly with `app.use()`, instead of the resolved middleware.","error":"TypeError: app.use requires a generator function or middleware function"},{"fix":"Install webpack using your package manager: `npm install webpack` or `yarn add webpack`.","cause":"The `webpack` package, which is a peer dependency of `koa-webpack`, is not installed in your project.","error":"Error: Cannot find module 'webpack'"},{"fix":"Update your configuration to use `devMiddleware` instead of `dev` and `hotClient` instead of `hot`.","cause":"You are likely using deprecated option names (`dev` or `hot`) that were renamed in `koa-webpack` v5.0.0.","error":"TypeError: Cannot read properties of undefined (reading 'publicPath') (or similar for missing options)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}