Add useful methods to the Koa context for sending a response

Downloads in past


10212.1.06 years ago8 years agoMinified + gzip package size for koa-respond in KB


npm dependency Status devDependency Status Build Status Coveralls Code Climate npm license node JavaScript Style Guide KoaJs Slack
Middleware for Koa that adds useful methods to the Koa context.


npm install --save koa-respond


// Install it
const respond = require('koa-respond');

// For Koa v2 - if you are looking for v1, scroll to the bottom.

// Use it
app.use((ctx) => {
  // Sets status to 200 and the body to `{ id: 123, name: 'Dat Boi' }`
  ctx.ok({ id: 123, name: 'Dat Boi' });

  // Both of these set status to 404 and
  // the body to `{ message: 'Not found, boii' }`
  ctx.notFound('Not found, boii');
  ctx.notFound({ message: 'Not found, boii' });

  // And everyone's favorite..
  ctx.badRequest({ error: 'missing input' });

  // Or if you prefer to do it yourself..
  // Both of these send a HTTP 201 with a body
  // of `{ message: 'new beginnings!' }`
  ctx.send(201, 'new beginnings!');
  ctx.send(201, { message: 'new beginnings!' });


All methods call the send method with the corresponding status code as well as the body. That means they support the same overloads as send:
  • With a string; wraps it in an object with a message property. That means the following 2 calls do the same thing:

```js ctx.send(400, 'lol no'); ctx.send(400, { message: 'lol no' }); ```
  • With an object; sends the object as JSON.

```js ctx.send(200, { id: 123, name: 'new entity' }); ```
If you wish to disable the automatic wrapping of strings globally, you can instantiate koa-respond with autoMessage: false.
  autoMessage: false

All functions return the Koa context itself (chainable)
ctx.ok().set({ 'X-Some-Header': 'awesome' })

All functions are also bound to the context. This means you can pass the function as a reference without having to bind it first.
app.use((ctx) => somePromiseCall().then(ctx.ok))

Available methods

  • ok - HTTP 200
  • created - HTTP 201
  • noContent - HTTP 204 - always sends an empty response!
  • badRequest - HTTP 400
  • unauthorized - HTTP 401
  • forbidden - HTTP 403
  • notFound - HTTP 404
  • internalServerError - HTTP 500

Does this work for Koa 1?

Not out of the box, because it's time you move on to v2.
To use koa-respond in Koa v1, you need to patch the context yourself. This is what the v2 middleware does.
const respond = require('koa-respond');

// Middleware to install koa-respond.
app.use(function *(next) {
  yield next;

// Now the methods are available.
app.use(function *() {
  this.ok({ id: 123, name: 'Bob' });

Adding additional methods

If you feel like some methods are missing, you can add them yourself, like so:
  statusMethods: {
    imATeapot: 418,
    enhanceYourCalm: 420

app.use((ctx) => {
  ctx.imATeapot('Hello, a Teapot I am.');
  ctx.enhanceYourCalm({ todo: 'blaze it' });

Even more custom methods

If you just want to add shortcuts without adding an additional middleware, you can do that, too.
  methods: {
    shizzle: (ctx, message) => {
      ctx.send(200, message + ', fo-shizzle');

app.use((ctx) => {
  // HTTP 200 { message: 'Koa is the best, fo-shizzle' }
  ctx.shizzle('Koa is the best');

npm run scripts

  • npm run test: Runs tests once
  • npm run test-watch: Runs tests in watch-mode
  • npm run lint: Lints the code once
  • npm run lint-watch: Lints the code in watch-mode
  • npm run cover: Runs code coverage using istanbul
  • npm run coveralls: Used by coveralls
Jeff Hansen - @Jeffijoe