{"id":17105,"library":"koa-connect","title":"Use Connect/Express Middleware in Koa","description":"koa-connect is a utility package that enables the integration of standard Connect or Express middleware into a Koa application. It acts as a bridge, adapting the `(req, res, next)` signature of Connect/Express middleware to Koa's `(ctx, next)` context-based middleware pattern. The current stable version is 2.1.1. While not actively undergoing rapid feature development, the package is in a maintenance state, receiving updates for compatibility and bug fixes as needed. It serves a niche purpose, primarily when a Koa-native version of a required middleware is unavailable or for library authors aiming for framework-agnostic HTTP middleware. Developers are strongly cautioned to prefer Koa-specific middleware when available due to fundamental design differences between Koa's async/await flow and Express's callback-based approach, which can lead to unexpected behavior and control flow issues.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/vkurchatkin/koa-connect","tags":["javascript","koa","connect","express","middleware","typescript"],"install":[{"cmd":"npm install koa-connect","lang":"bash","label":"npm"},{"cmd":"yarn add koa-connect","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-connect","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import for modern Node.js and bundlers. The package supports both ESM and CommonJS.","wrong":"const c2k = require('koa-connect');","symbol":"c2k","correct":"import c2k from 'koa-connect';"},{"note":"CommonJS require for older Node.js environments. This is demonstrated in the quickstart.","symbol":"c2k","correct":"const c2k = require('koa-connect');"},{"note":"Type import for TypeScript users to explicitly type the `c2k` function, although typically inferred.","symbol":"MiddlewareAdapter","correct":"import type { MiddlewareAdapter } from 'koa-connect';"}],"quickstart":{"code":"const Koa = require('koa');\nconst c2k = require('koa-connect');\n\n// A generic Express-style middleware function\nfunction connectMiddleware(req, res, next) {\n  res.writeHead(200, { 'Content-Type': 'text/plain' });\n  res.end('From the Connect middleware');\n  next(); // Crucial to call next to continue the Koa chain\n}\n\n// A basic Koa middleware to illustrate the flow\nasync function koaGreetingMiddleware(ctx, next) {\n  console.log('Koa middleware: Before calling next');\n  await next(); // Proceed to downstream middleware\n  console.log('Koa middleware: After downstream middleware');\n}\n\nconst app = new Koa();\n\napp.use(koaGreetingMiddleware);\napp.use(c2k(connectMiddleware)); // Integrate the Connect middleware\n\n// Final Koa middleware to show control flow continues\napp.use(async (ctx, next) => {\n  if (ctx.path === '/') {\n    ctx.body = ctx.body || 'Hello from Koa after Connect!';\n  }\n  await next();\n});\n\napp.listen(3000, () => {\n  console.log('Server running on http://localhost:3000');\n});\n","lang":"javascript","description":"Demonstrates how to integrate a standard Connect/Express-style middleware into a Koa application using `koa-connect`, illustrating the control flow between Koa and adapted middleware."},"warnings":[{"fix":"Prioritize `koa-*` packages. Only use `koa-connect` when a Koa-native solution is truly unavailable or for very simple, self-contained middleware.","message":"It is highly recommended to use Koa-specific middleware instead of converting an Express version when Koa-native alternatives are available. Koa and Express have fundamentally different designs (async/await vs. callback-based), and `koa-connect` is a workaround, not a seamless replacement, which can lead to unexpected behavior and control flow issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Connect/Express middleware function signature is `(req, res, next)` and that `next()` is called at the appropriate point, typically at the end of the middleware's logic, to pass control to the next Koa middleware.","message":"When adapting an Express-style middleware, you *must* explicitly declare and invoke the `next` callback parameter within the middleware function for the Koa chain to continue. Failure to call `next()` will halt the request processing at the adapted middleware.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Restrict adapted middleware to using only core Node.js `http.IncomingMessage` (req) and `http.ServerResponse` (res) methods and properties, or properties explicitly added by other universal middleware.","message":"When writing framework-agnostic middleware intended for use with `koa-connect`, avoid using Express-dependent APIs (e.g., `res.send()`, `req.params`, `req.body`) as these are not part of the standard Node.js `http` module and will not be available or function correctly within Koa's context.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Modify the Express middleware to use standard Node.js `res.end()` or `res.write()` methods, or ensure `ctx.body` is set in a subsequent Koa middleware after the adapted middleware has processed the request.","cause":"An Express-style middleware adapted by `koa-connect` is attempting to use `res.send()`, which is an Express-specific method and not available on the native Node.js `http.ServerResponse` object provided within Koa's context.","error":"TypeError: res.send is not a function"},{"fix":"Review the Connect/Express middleware's implementation and ensure `next()` is invoked correctly to pass control to the subsequent middleware in the Koa application.","cause":"The adapted Connect/Express middleware did not call the `next()` function, preventing the Koa middleware chain from proceeding to the next handler.","error":"Request hangs indefinitely or subsequent Koa middleware are not executed."}],"ecosystem":"npm","meta_description":null}