A fast router middleware for Koa with support for nesting, associating data with routes, and dynamically assigning middleware based on that data.


2101.5.02 years ago3 years agoMinified + gzip package size for @ffz/api-router in KB



NPM Version Node Version Dependency Status Build Status Test Coverage

Routing middleware for Koa.

  • Express-style routing using router.get(), router.post(), etc.
  • Named URL parameters
  • Named routes with URL generation
  • Support for multiple hosts (with parameters)
  • Responds to OPTIONS automatically.
  • Generates 405 Method Not Allowed responses automatically.
  • Multiple routers
  • Nestable routers
  • Associate random data with a route
  • Automatically add middleware to routes based on that data
  • Pre-computes middleware chains for every route to minimize computation and allocations during runtime
  • Uses find-my-way internally for route matching for fast routing


$ npm install @ffz/api-router --save


Basic Usage

import Koa from 'koa';
import Router from '@ffz/api-router';

const app = new Koa();
const router = new Router();


router.get('/', (ctx, next) => {
    ctx.body = "Hello, World!"


More Interesting Usage

import Koa from 'koa';
import Router from '@ffz/api-router';

import redis from './redis_stuff';
import generate_random_id from './some_other_place';

const app = new Koa();
const router = new Router();

router.useData('cache', options => {
    const duration = options.duration || 120;

    return async (ctx, next) => {
        const key = ctx.url,
            cached = await redis.hgetall(key);

        if ( cached && cached.status ) {
            ctx.status = parseInt(cached.status, 10);
            ctx.etag = cached.etag;

            if ( ctx.fresh ) {
                ctx.status = 304;
            } else {
                ctx.type = cached.type;
                ctx.body = cached.body;


        await next();

        const etag = generate_random_id();
        ctx.etag = etag;

        const body = typeof ctx.body === 'string' ?
            ctx.body :

        await redis.multi().hmset(key, {
            status: ctx.status,
            type: ctx.type,
        }).expire(key, duration).exec();

router.get('/', {cache: {duration: 60}}, (ctx, next) => {
    ctx.body = "Hello, World!"


The above code sets up a very simple caching middleware using Redis. The middleware is registered for cache data. Then, we register a new route and the route has cache data, so that middleware is automatically applied to it.


Run tests using npm test.

Contributions and Support

Please submit all issues and pull requests to the FrankerFaceZ/api-router repository.

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.