{"id":17740,"library":"koa-convert","title":"Koa Middleware Converter","description":"koa-convert is a utility package designed to bridge compatibility gaps between major versions of the Koa.js web framework. It primarily converts legacy Koa 0.x and 1.x generator-based middleware into modern Koa 2.x promise-based middleware. Conversely, it can also convert modern promise middleware back to legacy generator format, which is useful for enabling newer middleware to run on older Koa 0.x or 1.x applications. The current stable version is 2.0.0, released in 2017. As such, the package is no longer actively developed, and its release cadence has ceased. Its key differentiator is its ability to facilitate incremental migration for existing Koa applications, allowing mixed middleware patterns to coexist. While still functional for its specific purpose, its overall utility for new projects has significantly diminished as Koa 2.x has been the standard for many years.","status":"maintenance","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/gyson/koa-convert","tags":["javascript","koa","middleware","convert","back","generator","promise","generator-based-middleware","promise-based-middleware"],"install":[{"cmd":"npm install koa-convert","lang":"bash","label":"npm"},{"cmd":"yarn add koa-convert","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-convert","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM usage for default export; CommonJS is also common due to package age.","wrong":"const convert = require('koa-convert')","symbol":"convert","correct":"import convert from 'koa-convert'"},{"note":"`compose` is a named property on the default `convert` function, not a separate named export.","wrong":"import { compose } from 'koa-convert'","symbol":"convert.compose","correct":"import convert from 'koa-convert';\nconst composedMiddleware = convert.compose(legacyFn, modernFn)"},{"note":"`back` is a named property on the default `convert` function, used to convert modern middleware to legacy format.","symbol":"convert.back","correct":"import convert from 'koa-convert';\nconst legacyFn = convert.back(modernFn)"}],"quickstart":{"code":"import Koa from 'koa'; // Assuming Koa v2.x\nimport convert from 'koa-convert';\n\nconst app = new Koa();\n\n// Basic usage: convert a legacy generator middleware\napp.use(convert(function * legacyMiddleware (next) {\n  console.log('Legacy: before next');\n  yield next;\n  console.log('Legacy: after next');\n}));\n\n// Override app.use to automatically convert all legacy middleware\nconst _originalUse = app.use;\napp.use = x => {\n  console.log('Intercepting app.use, converting middleware if needed.');\n  return _originalUse.call(app, convert(x));\n};\n\napp.use(async (ctx, next) => {\n  console.log('Modern: before next');\n  await next();\n  console.log('Modern: after next');\n  ctx.body = 'Hello Koa!';\n});\n\n// This legacy middleware will now be implicitly converted by the overridden app.use\napp.use(function * anotherLegacyMiddleware (next) {\n  console.log('Another Legacy: before next');\n  yield next;\n  console.log('Another Legacy: after next');\n});\n\napp.listen(3000, () => {\n  console.log('Server running on http://localhost:3000');\n});","lang":"javascript","description":"Demonstrates converting individual legacy middleware, and a global override of `app.use` to automatically convert all legacy middleware for easier migration in a Koa 2.x application."},"warnings":[{"fix":"Use Koa 2.x compatible versions of router libraries (e.g., koa-router@next, koa-route@3.0.0) directly, instead of attempting to convert older router middleware with `koa-convert`.","message":"Koa router middleware (e.g., koa-router, koa-route) often reimplement middleware composition internally. `koa-convert` cannot simply convert these types of middleware directly. Specific Koa 2.x compatible versions of routers should be used instead.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"For new Koa projects, use modern promise-based middleware exclusively. Only consider `koa-convert` if you have a legacy Koa 0.x/1.x codebase that needs to integrate with Koa 2.x middleware, or vice-versa, without a full rewrite.","message":"The `koa-convert` package has not been updated since 2017 (v2.0.0). While it remains functional for its intended purpose, its relevance for new Koa projects is minimal as Koa 2.x has been standard for many years. It is primarily useful for migrating older Koa 0.x/1.x applications.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project's Node.js environment meets the minimum requirement of Node.js >= 10. Upgrade Node.js if necessary.","message":"The package requires Node.js version 10 or greater. Using it with older Node.js versions may lead to unexpected errors or incompatibilities, especially with generator functions or promise-related features.","severity":"gotcha","affected_versions":"<10.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Wrap the legacy generator middleware with `convert()`: `app.use(convert(legacyMiddleware))`.","cause":"Attempting to use a legacy Koa 0.x/1.x generator function directly with Koa 2.x's `app.use()` without converting it first.","error":"TypeError: middleware is not a function"},{"fix":"Wrap the modern promise middleware with `convert.back()`: `app.use(convert.back(modernMiddleware))`.","cause":"Attempting to use a modern Koa 2.x promise-based middleware with Koa 0.x/1.x `app.use()` without converting it back to a generator function.","error":"TypeError: app.use() requires a generator function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}