node package manager
It’s your turn. Help us improve JavaScript. Take the 2017 JavaScript Ecosystem Survey »

koa-plus

koa-plus

Version Build Status Coverage Status Dependency Status Standard - JavaScript Style Guide Downloads

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