Koa Middleware Converter

2.0.0 verified Thu Apr 23 auth: no javascript maintenance

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.

Common errors

error TypeError: middleware is not a function ↓

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.

fix

Wrap the legacy generator middleware with convert(): app.use(convert(legacyMiddleware)).

error TypeError: app.use() requires a generator function ↓

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.

fix

Wrap the modern promise middleware with convert.back(): app.use(convert.back(modernMiddleware)).

Warnings

breaking 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. ↓

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`.

gotcha 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. ↓

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.

gotcha 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. ↓

fix Ensure your project's Node.js environment meets the minimum requirement of Node.js >= 10. Upgrade Node.js if necessary.

Install

npm install koa-convert

yarn add koa-convert

pnpm add koa-convert

Imports

convert
wrong
```
const convert = require('koa-convert')
```
correct
```
import convert from 'koa-convert'
```
ESM usage for default export; CommonJS is also common due to package age.

convert.compose

wrong

import { compose } from 'koa-convert'

correct

import convert from 'koa-convert';
const composedMiddleware = convert.compose(legacyFn, modernFn)

`compose` is a named property on the default `convert` function, not a separate named export.

convert.back
```
import convert from 'koa-convert';
const legacyFn = convert.back(modernFn)
```
`back` is a named property on the default `convert` function, used to convert modern middleware to legacy format.

Quickstart

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.

import Koa from 'koa'; // Assuming Koa v2.x
import convert from 'koa-convert';

const app = new Koa();

// Basic usage: convert a legacy generator middleware
app.use(convert(function * legacyMiddleware (next) {
  console.log('Legacy: before next');
  yield next;
  console.log('Legacy: after next');
}));

// Override app.use to automatically convert all legacy middleware
const _originalUse = app.use;
app.use = x => {
  console.log('Intercepting app.use, converting middleware if needed.');
  return _originalUse.call(app, convert(x));
};

app.use(async (ctx, next) => {
  console.log('Modern: before next');
  await next();
  console.log('Modern: after next');
  ctx.body = 'Hello Koa!';
});

// This legacy middleware will now be implicitly converted by the overridden app.use
app.use(function * anotherLegacyMiddleware (next) {
  console.log('Another Legacy: before next');
  yield next;
  console.log('Another Legacy: after next');
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});