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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Router
✓ import Router from 'koa-router-middleware';
✗ const Router = require('koa-router-middleware');
The primary export is a default class, intended for ESM consumption. CommonJS `require` might not be supported or lead to issues with this older preview package.
new Router()
✓ import Router from 'koa-router-middleware'; const router = new Router();
Instantiate the `Router` class to create a new router instance.
Koa router instance methods (.get, .post, etc.)
✓ router.get('/path', async ctx => { /* ... */ });
Route handlers are asynchronous functions following the Koa middleware signature, typically using `async/await`.
This quickstart demonstrates how to initialize a Koa application and register a `koa-router-middleware` instance with prefixed routes for various HTTP methods, including middleware for `ctx.state`.
import * as Koa from "koa";
import Router from "koa-router-middleware";
// Define the API routes using koa-router-middleware
const apiRouter = new Router()
.use(async (ctx, next) => {
// Example middleware to set state, runs before route handlers
ctx.state.user = { name: "James" };
await next(); // Pass control to the next middleware or route handler
})
.get("/cat", async ctx => {
ctx.status = 200;
ctx.body = [{ type: "bengal" }, { type: "bombay" }];
})
.get("/cat/:id", async ctx => {
ctx.status = 200;
ctx.body = { type: "bengal", id: ctx.params.id };
})
.post("/cat", async ctx => {
ctx.status = 201;
ctx.body = { type: "siamese" };
})
.put("/cat/:id", async ctx => {
ctx.status = 200;
ctx.body = { type: "siamese", id: ctx.params.id };
})
.delete("/cat/:id", async ctx => {
ctx.status = 200;
ctx.body = { message: `Cat ${ctx.params.id} deleted` };
});
// Create a Koa application
const app = new Koa();
// Use the API router, prefixed with "/api".
// All routes defined in apiRouter will be accessible under /api/...
app.use("/api", apiRouter);
// Start the server
const port = process.env.PORT ?? 3000;
app.listen(port, () => {
console.log(`Server started on http://localhost:${port}`);
console.log('Try visiting:');
console.log(`- http://localhost:${port}/api/cat`);
console.log(`- http://localhost:${port}/api/cat/123`);
console.log('You can also test POST/PUT/DELETE requests to /api/cat or /api/cat/:id using tools like cURL or Postman.');
});
Debug
Known issues
breakingThis package, `koa-router-middleware`, is effectively abandoned. It is an old preview release (`1.0.0-preview.1`) from 7 years ago with no further development or updates. Using it in production is highly discouraged.fixMigrate to the actively maintained and widely adopted `@koa/router` package instead. This is the recommended and official routing solution for Koa applications.
affects: >=1.0.0-preview.1
gotchaDue to its 'preview' status and age, the API might not be stable, fully documented, or compatible with newer Koa features or Node.js versions beyond the specific Koa 2.x range it was designed for. While the peer dependency `koa: ^2.7.0` is stated, deeper incompatibilities may exist.fixIf absolutely necessary to use this package, thoroughly test its behavior across your target Koa and Node.js versions. For any new development, refer to the fix for the 'breaking' warning above.
affects: >=1.0.0-preview.1
gotchaIt is crucial not to confuse `koa-router-middleware` with the `koa-router` or `@koa/router` packages. This package is distinct and not part of the `koajs` official ecosystem, nor is it the popular community router.fixAlways double-check the exact package name (`koa-router-middleware`) when installing or importing to ensure you are aware you are using this specific, abandoned library.
affects: >=1.0.0-preview.1
Errors
Common errors & fixes
Error: Cannot find module 'koa-router-middleware'
The package was not installed, or there's a typo in the import path/name.
fixEnsure the package is correctly installed via `npm install koa-router-middleware` or `yarn add koa-router-middleware`. Verify the import statement for typos.
TypeError: Router is not a constructor
Attempting to use `require()` for a module that is primarily designed for ESM `import` (default export).
fixUse `import Router from 'koa-router-middleware';` for ESM environments. If in a CommonJS-only context, this package might not be directly usable without a transpilation layer, further highlighting its deprecated status.
TypeError: app.use is not a function (when trying to mount a router directly like `app.use('/prefix', router)` with the wrong Koa version or setup)
The `app.use(path, middleware)` signature for Koa (mounting a middleware with a path prefix) is specific to certain Koa versions or router implementations. If this router isn't properly wrapped or Koa doesn't support this form of `use` directly, it will fail.
fixEnsure your Koa version is compatible with the `app.use(path, middleware)` signature used in the `koa-router-middleware` examples. If issues persist, consider using a different Koa router like `@koa/router` which explicitly provides `router.routes()` and `router.allowedMethods()` for `app.use()`.
Upgrade
Version history
1.0.0-preview.1latest on npm
Audit
Dependencies
@types/koaoptionalTypeScript type definitions for Koa, a peer dependency for type-safe Koa development.
koarequiredThe core Koa web framework, which this router middleware extends and requires to function.