node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



NPM version build status

koa module addon, make write api server more easier. Design an api style, combine with swagger(inspired by hapi-swagger).


 $ npm i kox


// this will return an koa instance, so all koa properties are supported by kox.
const app = require('kox')
const apis = [{
  method: 'get',
  path: '/',
  handler: function (ctx) {
    ctx.set('x-powered-by', 'kox')
    return "hello world"

Getting started



Because kox is just koa addon, so all koa app api are supported. You can read koa docs.

In kox, i use koa-body to handle request body parsing, so you dont need to add this middleware again in your project, the default body parser setting as follow:

  jsonLimit: '100KB',
  formLimit: '50KB',
  multipart: true,
  formidable: {
  uploadDir: join(process.cwd(), 'runtime')

You can modify body parser setting when initial kox instance:

const app = kox({bodyParser: {...}})


Kox add two controller related api to koa instance:

  • app.controller
  • app.loadCtrls


This api is used to add an controller.

const fooController = {name: 'foo', ...}
// this operation add controller to app._controllers, we will using these controllers in api definitions.


This api is used to add multiple controllers. I usually use it with require-dir module. You can see code in example.

const requireDir = require('require-dir')
const controllers = require('../controllers')

Controller Class

app.controller and app.loadCtrls are all used to create Controller, and most design of Controller are inspired by sundae which based on express. But I make action to be more functional, and handle the context as an argument in action. And I prefer put all dependencies in context, rather then require them in the begin of a code file. I think that will make action easy to test in real project.

  • Controller#mixin
    mixin will add actions to this._actions of controlller. And actions can be invoked as api handler or used to be a hook

    const mixins = requireDir('../mixins')
  • Controller#action
    action will add an action to this._actions

    ctrl.action('action1', function(ctx) {...})
  • Controller#before
    before will set an action as pre hook of other action, and it take options to indicate actions to hook

    // this will hook `hello` action before `foo` and `bar`
    ctrl.before('hello', {only: 'foo bar'})
    // this operation will return an generator combine hello and foo
  • Controller#after
    The same as before, but add post hook to actions

    // this operation will add post hook to every actions except action named married
    ctrl.after('bye', {except: 'married'})
  • Controller#invoke
    Will return a generator, used in koa-router module.


Swagger API

I used to write business code and document of code separately. I think that way to write code cant make me more productive. I want to Document can decribe code and code can be document. And Swagger have done this. I found hapi-swagger is really awesome project to do this. But the way to write code in hapi is not my tea, so i rebuild kox

api describe

    method: 'get',
    path: '/hello',
    handler: 'controller.action' // or you can write an function directly
    tags: ['Hello'],
    summary: 'say hello',
    description: 'this api will return hello world',
    // validate definition is the same as hapi, using joi as validator
    validate: {
        payload: Joi.object({...}),
        params: ...,
        query: ...,
        headers: ...
    responses: {
        200: {
            description: 'success',
            schema: Joi.object({}) // we validate response by schema




  • Generate Swagger Json Route
  • Auto route api
  • Full Example
  • Full documents
  • Rendering API