koa-bodyparser

What is koa-bodyparser?

koa-bodyparser is a middleware for Koa that parses incoming request bodies in a middleware before your handlers, making it available under the `ctx.request.body` property. It supports parsing JSON, form, and text bodies.

What are koa-bodyparser's main functionalities?

JSON Body Parsing

This feature allows you to parse JSON bodies from incoming requests. The parsed data is available on `ctx.request.body`.

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');
const app = new Koa();

app.use(bodyParser());

app.use(async ctx => {
  if (ctx.method === 'POST') {
    ctx.body = `Received JSON data: ${JSON.stringify(ctx.request.body)}`;
  } else {
    ctx.body = 'Send a POST request with JSON data';
  }
});

app.listen(3000);

Form Body Parsing

This feature allows you to parse URL-encoded form bodies from incoming requests. The parsed data is available on `ctx.request.body`.

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');
const app = new Koa();

app.use(bodyParser());

app.use(async ctx => {
  if (ctx.method === 'POST') {
    ctx.body = `Received form data: ${JSON.stringify(ctx.request.body)}`;
  } else {
    ctx.body = 'Send a POST request with form data';
  }
});

app.listen(3000);

Text Body Parsing

This feature allows you to parse plain text bodies from incoming requests. The parsed data is available on `ctx.request.body`.

const Koa = require('koa');
const bodyParser = require('koa-bodyparser');
const app = new Koa();

app.use(bodyParser({ enableTypes: ['text'] }));

app.use(async ctx => {
  if (ctx.method === 'POST') {
    ctx.body = `Received text data: ${ctx.request.body}`;
  } else {
    ctx.body = 'Send a POST request with text data';
  }
});

app.listen(3000);

Other packages similar to koa-bodyparser

koa-body

koa-body is a more feature-rich alternative to koa-bodyparser. It supports file uploads, multiple body types (JSON, form, text), and can handle multipart requests. It is more versatile but also more complex to configure compared to koa-bodyparser.

koa-multer

koa-multer is a middleware for handling multipart/form-data, which is primarily used for uploading files. It is similar to koa-bodyparser but focuses on file uploads and does not handle JSON or URL-encoded form bodies.

koa-json-body

koa-json-body is a simpler alternative that focuses solely on parsing JSON bodies. It is less versatile than koa-bodyparser but can be a good choice if you only need to handle JSON data.

README

koa-bodyparser

A body parser for koa, based on co-body. support json, form and text type body.

Notice: this module don't support parsing multipart format data, please use co-busboy to parse multipart format data.

Install

Usage

var Koa = require('koa');
var bodyParser = require('koa-bodyparser');

var app = new Koa();
app.use(bodyParser());

app.use(async ctx => {
  // the parsed body will store in ctx.request.body
  // if nothing was parsed, body will be an empty object {}
  ctx.body = ctx.request.body;
});

Options

• enableTypes: parser will only parse when request type hits enableTypes, support json/form/text/xml, default is ['json', 'form'].

• encoding: requested encoding. Default is utf-8 by co-body.

• formLimit: limit of the urlencoded body. If the body ends up being larger than this limit, a 413 error code is returned. Default is 56kb.

• jsonLimit: limit of the json body. Default is 1mb.

• textLimit: limit of the text body. Default is 1mb.

• xmlLimit: limit of the xml body. Default is 1mb.

• strict: when set to true, JSON parser will only accept arrays and objects. Default is true. See strict mode in co-body. In strict mode, ctx.request.body will always be an object(or array), this avoid lots of type judging. But text body will always return string type.

• detectJSON: custom json request detect function. Default is null.

  app.use(bodyparser({
    detectJSON: function (ctx) {
      return /\.json$/i.test(ctx.path);
    }
  }));
  

• extendTypes: support extend types:

  app.use(bodyparser({
    extendTypes: {
      json: ['application/x-javascript'] // will parse application/x-javascript type body as a JSON string
    }
  }));
  

• onerror: support custom error handle, if koa-bodyparser throw an error, you can customize the response like:

  app.use(bodyparser({
    onerror: function (err, ctx) {
      ctx.throw('body parse error', 422);
    }
  }));
  

• disableBodyParser: you can dynamic disable body parser by set ctx.disableBodyParser = true.

app.use(async (ctx, next) => {
  if (ctx.path === '/disable') ctx.disableBodyParser = true;
  await next();
});
app.use(bodyparser());

Raw Body

You can access raw request body by ctx.request.rawBody after koa-bodyparser when:

1. koa-bodyparser parsed the request body.
2. ctx.request.rawBody is not present before koa-bodyparser.

Koa 1 Support

To use koa-bodyparser with koa@1, please use bodyparser 2.x.

npm install koa-bodyparser@2 --save

Licences

MIT