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


mu-kōän 公案

Greenkeeper badge Build Status MIT License js-semistandard-style

An opinionated Koa v2 JSON API boilerplate to achieve enlightenment.

mu-kōän serves as kickstarter set for Koa 2.0.0+ applications aimed at creating stateless REST JSON APIs. It includes a set of predefined Koa middlewares allowing for quicker bootstrapping with sensible defaults.

npm i --save mu-koan

mu-kōän requires node 6.0.0+, matching Koa requirements.


Create a new Koa app, configure it the way you want and pass it as an argument to the bootstrap exported function, wich will add its own middlewares and initialize routes.

'use strict'
// Import some configuration 
// For a detail of available options, see 
// section below. 
const CONFIG = require('./config.json')
const middlewares = require('mu-koan');
const Koa = require('koa');
let app = new Koa();
// ... 
// Configure other middlewares on `app`. 
// For a list of already included middlewares 
// by mu-kōän checkout package.json or the section below: 
middlewares.bootstrap(app, CONFIG);
// Start Koa server 

You can take a look at a minimal running mu-koan sample app at app.js

Advanced Usage

Middleware order declaration is important and some of them need to be placed as close to the top of the chain as possible (like global error handlers). By default, mu-kōän declares all of its packed middlewares in a single call to bootstrap. However, if you need to declare custom middlewares somewhere in between you can make use of the initialize method.

Declare them before calling bootstrap, but after initialize.

const custom = require('./middlewares/custom');
let app = new Koa();
middlewares.initialize(app, CONFIG);
// Declare custom middleware here, after initialize 
middlewares.bootstrap(app, CONFIG);

This way, "global" middlewares are still declared at the top (by calling initialize), but your custom functions run immediately after, just before any other set by mu-kōän.

Internally, bootstrap calls initialize if it hasn't already been call on that Koa app instance. So you'll always end up declaring all included middlewares, either way.


The following properties are used to configure the different middlewares packed by mu-koan:

  "bodyParser": {
    // See for more 
    "jsonLimit": "2mb"
  "jwt": {
    // Note that actual koa-jwt options are nested within "options" 
    "options": {
      // See for more 
      "passthrough": true,
      "secret": "(w_E8Qd--@cBvgr8"
    // Exclude JWT verification from certain paths 
    "unless": {
      // See for more 
      "path": ["/status"]
  "cors": {
    // See for more 
    "allowedMethods": "GET"
  "helmet": {
    // See for more 
    "frameguard": false
  "morgan": {
    "options": {
      // See for more 
      "immediate": true
    // See for more 
    "format": "combined"
  "cacheControl": {
    // See for more 
    "public": true,
    "maxAge": 3600
  // Path to favicon file needed by 
  "favicon": "./favicon.ico"


mu-kōän prints out log messages using a winston logger. It can be provided as a second optional options argument to thebootstrap function.

'use strict'
const middlewares = require('mu-koan');
const winston = require('winston');
const Koa = require('koa');
// Configure a winston logger 
winston.loggers.add('some-logger', {
  console: {
    level: 'silly',
    colorize: true,
    label: 'mu-koan'
let app = new Koa();
// `logger` option below can also be a `winston.Logger` instance or `undefined`/`null` 
const server = middlewares.bootstrap(app, { logger: 'some-logger' });

Actual logger configuration is not handled by mu-kōän. The option can be either a String or a winston.Logger instance. In the former case, the value will be used to fetch a logger by means of winston.loggers.get(options.logger).

If none is provided, the default winston logger will be used.

Learn more about handling multiple loggers at the official Winston docs


The boilerplate adds support for the following to a barebones Koa app: