koa-plus

koa-plus is the koa framework (v2) extended for APIs. Optimized for security, scalability, and productivity.

Features

• Important security headers via helmet.
• CORS support via kcors.
• Adds an X-Response-Time header to all responses.
• Adds an X-Request-Id header to all requests as they come in for easier debugging.
  • Also passes through client/proxy/load-balancer generated X-Request-Id headers as X-Client-Request-Id
• Uses koa-body to parse any request body type
• Adds ETag headers to allow conditional GET requests (respond with 304 Not Modified)
• Object stream support via koa-json
• Request logging via koa-morgan
• Simple ctx.debug (or ctx.app.debug) logging via the debug module
• Pretty-printed JSON in development
• Exposes the app configuration on ctx as ctx.config (or, app.context.config)

Each feature can be disabled individually.

Installation

Install koa-plus via yarn or npm:

yarn add koa-plus

npm install koa-plus --save

Usage

Existing apps:

Simply replace your existing koa require with koa-plus

Old:

const Koa = require('koa')
const app = new Koa()
// ...

New:

const Koa = require('koa-plus')
const app = new Koa()
// ...

Configuration

Some of the middleware included in koa-plus allows for options. To pass options to these middleware, simply pass the options to the constructor.

Options

• body: Use the same options as the koa-body middleware accepts. Docs
• compress: Use the same options as the koa-compress middleware accepts. Docs
• cors: Use the same options as the kcors middleware accepts. Docs
• debug: Set the name of the debug logger
• helmet: Use the same options as the helmet middleware accepts. Docs
• json: Use the same options as the koa-json middleware accepts. Docs
• logger: Use format for the logger format, and the remaining options as what morgan accepts Docs

Example

const Koa = require('koa-plus')
 
const app = new Koa({
  body: {
    jsonLimit: '10kb' // Sets the json request body limit to 10k
  },
  compress: {
    threshold: 2048 // Sets the threshold to Gzip responses at 2k (2048 bytes)
  },
  cors: {
    origin: '*' // Set the `Access-Control-Allow-Origin` header to be `*`
  },
  debug: {
    name: 'worker' // Set the debug logger name
  },
  helmet: {
    noCache: true,  // Sets the `Cache-Control` headers to prevent caching
    frameguard: {
      action: 'deny' // Set the `X-Frame-Options' header to be `DENY`
    }
  },
  json: {
    pretty: false // Disables pretty-printing
  },
  logger: {
    format: 'dev' // Use the `dev` format of logging
  }
})

Disabling middleware

Each of the middleware in koa-plus can be disabled individually by using the enabled option.

As an example, to reset koa-plus back to basic koa functionality, use the following config:

const Koa = require('koa-plus')
 
const app = new Koa({
  body: {
    enabled: false
  },
  compress: {
    enabled: false
  },
  cors: {
    enabled: false
  },
  debug: {
    enabled: false
  },
  etag: {
    enabled: false
  },
  helmet: {
    enabled: false
  },
  json: {
    enabled: false
  },
  logger: {
    enabled: false
  },
  requestId: {
    enabled: false
  },
  responseTime: {
    enabled: false
  }
})

Testing

To run the tests locally, simply run

yarn test

or

npm test