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-koanmu-kōän requires node 4.3.1+
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:
// https://github.com/nfantone/mu-koan/tree/feature/module#features
middlewares.bootstrap(app, CONFIG);
// Start Koa server
app.listen();You can take a look at a minimal running
mu-koansample app at app.js
The following properties are used to configure the different middlewares packed by mu-koan:
{
"jwt": {
// Note that actual koa-jwt options are nested within "options"
"options": {
// See https://www.npmjs.com/koa-jwt for more
"passthrough": true,
"secret": "(w_E8Qd--@cBvgr8"
},
// Exclude JWT verification from certain paths
"unless": {
// See https://github.com/Foxandxss/koa-unless#current-options for more
"path": ["/status"]
}
},
"cors": {
// See https://www.npmjs.com/kcors for more
"allowedMethods": "GET"
},
"helmet": {
// See https://github.com/helmetjs/helmet#top-level-helmet for more
"frameguard": false
}
"morgan": {
"options": {
// See https://github.com/expressjs/morgan#options for more
"immediate": true
},
// See https://www.npmjs.com/koa-morgan for more
"format": "combined"
},
"cacheControl": {
// See https://github.com/DaMouse404/koa-cache-control#options for more
"public": true,
"maxAge": 3600
},
// Path to favicon file needed by https://www.npmjs.com/koa-favicon
"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 the main exported 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
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:
- Body parsing (koa-bodyparser)
- Pretty JSON responses (koa-json)
- Global error handling (koa-json-error)
- Cache control (koa-cache-control)
- Compression (koa-compress)
- CORS (kcors)
- ETag and conditional
GET(koa-etag) - RTT headers (koa-response-time)
- Access logging (koa-morgan))
- JWT authentication (koa-jwt)
- Favicon (koa-favicon)
- Security headers (koa-helmet)
MIT