Koa Router Middleware

1.0.0-preview.1 verified Thu Apr 23 auth: no javascript abandoned

This package provides a minimal router middleware for the Koa web framework, enabling the definition of HTTP routes and method-specific handlers. Published as `1.0.0-preview.1` approximately seven years ago (as of April 2026), this library represents an extremely early and likely experimental release. Due to its age, lack of subsequent updates, and preview versioning, `koa-router-middleware` is considered abandoned. Developers currently seeking robust and actively maintained routing solutions for Koa applications should instead utilize the well-established and official `@koa/router` package. This package's primary feature was its straightforward integration with Koa's `app.use()` method, allowing a router to be mounted at a specific path prefix.

Common errors

error Error: Cannot find module 'koa-router-middleware' ↓

cause The package was not installed, or there's a typo in the import path/name.

fix

Ensure the package is correctly installed via npm install koa-router-middleware or yarn add koa-router-middleware. Verify the import statement for typos.

error TypeError: Router is not a constructor ↓

cause Attempting to use `require()` for a module that is primarily designed for ESM `import` (default export).

fix

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

error 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) ↓

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

fix

Ensure 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().

Warnings

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

fix Migrate to the actively maintained and widely adopted `@koa/router` package instead. This is the recommended and official routing solution for Koa applications.

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

fix If 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.

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

fix Always 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.

Install

npm install koa-router-middleware

yarn add koa-router-middleware

pnpm add koa-router-middleware

Imports

Router
wrong
```
const Router = require('koa-router-middleware');
```
correct
```
import Router from '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`.

Quickstart

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