koa-convert

library2.0.0jsnpmunverified

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.

web-framework

npm install koa-convert

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-CONVERT

koa-convert

web-frameworkjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

convert

✓ import convert from 'koa-convert'

✗ const convert = require('koa-convert')

ESM usage for default export; CommonJS is also common due to package age.

convert.compose

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

✗ import { compose } from 'koa-convert'

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

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'); });

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: <10.0.0

Errors

Common errors & fixes

TypeError: middleware is not a function

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

TypeError: app.use() requires a generator function

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

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gyson/koa-convert ↗

packagehttps://www.npmjs.com/package/koa-convert ↗