Using with Koa

clear-router supports Koa through @koa/router.

Install

pnpm add clear-router koa @koa/router

Setup

import Koa from 'koa';
import KoaRouter from '@koa/router';
import Router from 'clear-router/koa';

const app = new Koa();
const koaRouter = new KoaRouter();

Router.get('/hello', () => 'Hello World');

Router.apply(koaRouter);
app.use(koaRouter.routes());
app.use(koaRouter.allowedMethods());

app.listen(3000);

Koa-Specific Context

Koa handlers receive the Koa context as the first argument.

Router.get('/users/:id', (ctx) => {
  return {
    id: ctx.params.id,
    query: ctx.query,
  };
});

The request body helper is exposed as ctx.request.getBody().

Router.post('/users', (ctx) => {
  const body = ctx.request.getBody();

  return { created: true, body };
});

Direct Returns

Koa supports the same direct return behavior as the other adapters.

Router.get('/text', () => 'Hello');
Router.get('/html', () => '<h1>Hello</h1>');
Router.get('/json', () => ({ ok: true }));
Router.post('/users', (ctx) => ({ id: 1, ...ctx.request.getBody() }));
Router.get('/accepted', () => new Response('Accepted', { status: 202 }));

Direct POST returns default to 201; other methods default to 200. HTML-like strings are sent as text/html, API/XHR string responses as text/plain, and objects/arrays as JSON.

Method Override

Koa supports the shared method override behavior.

Router.put('/users/:id', (ctx) => {
  return { id: ctx.params.id, body: ctx.request.getBody() };
});

// POST /users/1 with JSON body { "_method": "PUT" }

Controllers

Controller handlers receive hydrated request state on this.

import { Controller } from 'clear-router';

class UserController extends Controller {
  show() {
    return {
      id: this.params.id,
      query: this.query,
    };
  }
}

Router.get('/users/:id', [UserController, 'show']);