{"id":17109,"library":"koa-webpack-dev-middleware","title":"Koa Webpack Dev Middleware","description":"This package provides a middleware to integrate `webpack-dev-middleware` within Koa 2.x applications, enabling the serving of webpack-bundled assets directly from memory during development. This avoids disk writes and speeds up the development cycle, often paired with `webpack-hot-middleware` for Hot Module Replacement. The current stable version, 2.0.2, appears to be designed for the Koa 2.x ecosystem and Node.js versions 7.6.0 and above. Its release cadence seems to be inactive, with no recent updates catering to newer Koa versions (e.g., Koa 3+) or the latest webpack iterations. As a result, it is primarily relevant for maintaining legacy Koa 2.x projects. Key differentiators include its direct API compatibility with Koa's middleware signature, abstracting the underlying `webpack-dev-middleware` for Koa users.","status":"maintenance","version":"2.0.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/yiminghe/koa-webpack-dev-middleware","tags":["javascript","koa","webpack","middleware"],"install":[{"cmd":"npm install koa-webpack-dev-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add koa-webpack-dev-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-webpack-dev-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to create the webpack compiler object that the middleware consumes.","package":"webpack","optional":false},{"reason":"This is a middleware designed for Koa applications.","package":"koa","optional":false}],"imports":[{"note":"This package is primarily CommonJS. For Koa 2.x applications, 'require' is the intended usage.","symbol":"webpackMiddleware","correct":"const webpackMiddleware = require('koa-webpack-dev-middleware');"},{"note":"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.","wrong":"import { webpackMiddleware } from 'koa-webpack-dev-middleware';","symbol":"webpackMiddleware","correct":"import webpackMiddleware from 'koa-webpack-dev-middleware';"},{"note":"The 'webpack' package itself is also typically imported via 'require' when used in build scripts or older Node.js environments.","wrong":"import webpack from 'webpack';","symbol":"webpack","correct":"const webpack = require('webpack');"}],"quickstart":{"code":"const Koa = require('koa');\nconst webpack = require('webpack');\nconst webpackMiddleware = require('koa-webpack-dev-middleware');\n\nconst app = new Koa();\n\nconst webpackConfig = {\n mode: 'development',\n entry: './src/index.js',\n output: {\n path: '/', // Required for webpack-dev-middleware, no real path needed\n publicPath: '/assets/'\n },\n module: {\n rules: [\n {\n test: /\\.js$/,\n exclude: /node_modules/,\n use: {\n loader: 'babel-loader',\n options: { presets: ['@babel/preset-env'] }\n }\n }\n ]\n }\n};\n\nconst compiler = webpack(webpackConfig);\n\napp.use(webpackMiddleware(compiler, {\n noInfo: false,\n quiet: false,\n lazy: false,\n watchDelay: 300,\n publicPath: '/assets/', // Must match webpackConfig.output.publicPath\n headers: { 'X-Custom-Header': 'yes' },\n stats: { colors: true }\n}));\n\n// Add a simple route to verify the server is running\napp.use(async ctx => {\n if (ctx.path === '/') {\n ctx.body = 'Koa Webpack Dev Middleware Example
';\n }\n});\n\napp.listen(3000, () => {\n console.log('Koa server with webpack dev middleware listening on port 3000');\n console.log('Access: http://localhost:3000');\n});\n\n// Create a dummy src/index.js if it doesn't exist\n// In a real project, this would be your main entry point.\n// For demonstration purposes, we ensure the file exists.\nconst fs = require('fs');\nconst path = require('path');\nconst entryPath = path.resolve(__dirname, 'src/index.js');\nif (!fs.existsSync(path.dirname(entryPath))) {\n fs.mkdirSync(path.dirname(entryPath), { recursive: true });\n}\nif (!fs.existsSync(entryPath)) {\n fs.writeFileSync(entryPath, 'console.log(\"Hello from webpack-bundled client code!\");');\n}\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure your project uses Koa 2.x. For newer Koa versions, consider alternative solutions or wrappers around `webpack-dev-middleware` designed for modern Koa.","message":"This 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).","severity":"breaking","affected_versions":"<2.0.0 || >2.0.2 (hypothetical)"},{"fix":"For 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.","message":"The 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Test 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.","message":"This 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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Update 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'.","cause":"Using Koa 1.x (which uses generator functions) instead of Koa 2.x (which uses async/await functions).","error":"TypeError: app.use is not a function"},{"fix":"For 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.","cause":"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.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Install webpack using `npm install webpack` or `yarn add webpack`.","cause":"The `webpack` package is a peer dependency but is not installed in the project.","error":"Error: Cannot find module 'webpack'"},{"fix":"Ensure 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.","cause":"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.","error":"Files are not served or 404 errors for assets"}],"ecosystem":"npm","meta_description":null}