Home

Awesome

koa-body

CI KoaJs Slack

A full-featured koa body parser middleware. Supports multipart, urlencoded, and json request bodies. Provides the same functionality as Express's bodyParser - multer.

Install

Install with npm

npm install koa-body

Features

Hello World - Quickstart

npm install koa koa-body # Note that Koa requires Node.js 7.6.0+ for async/await support

index.js:

const Koa = require('koa');
const { koaBody } = require('koa-body');

const app = new Koa();

app.use(koaBody());
app.use((ctx) => {
  ctx.body = `Request Body: ${JSON.stringify(ctx.request.body)}`;
});

app.listen(3000);

node index.js
curl -i http://localhost:3000/users -d "name=test"

Output:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 29
Date: Wed, 03 May 2017 02:09:44 GMT
Connection: keep-alive

Request Body: {"name":"test"}%

For a more comprehensive example, see examples/multipart.js

Usage with koa-router

It's generally better to only parse the body as needed, if using a router that supports middleware composition, we can inject it only for certain routes.

const Koa = require('koa');
const app = new Koa();
const router = require('koa-router')();
const { koaBody } = require('koa-body');

router.post('/users', koaBody(), (ctx) => {
  console.log(ctx.request.body);
  // => POST body
  ctx.body = JSON.stringify(ctx.request.body);
});

app.use(router.routes());

app.listen(3000);
console.log('curl -i http://localhost:3000/users -d "name=test"');

Usage with unsupported text body type

For unsupported text body type, for example, text/xml, you can use the unparsed request body at ctx.request.body. For the text content type, the includeUnparsed setting is not required.

// xml-parse.js:
const Koa = require('koa');
const { koaBody } = require('koa-body');
const convert = require('xml-js');

const app = new Koa();

app.use(koaBody());
app.use((ctx) => {
  const obj = convert.xml2js(ctx.request.body);
  ctx.body = `Request Body: ${JSON.stringify(obj)}`;
});

app.listen(3000);

node xml-parse.js
curl -i http://localhost:3000/users -H "Content-Type: text/xml" -d '<?xml version="1.0"?><catalog id="1"></catalog>'

Output:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 135
Date: Tue, 09 Jun 2020 11:17:38 GMT
Connection: keep-alive

Request Body: {"declaration":{"attributes":{"version":"1.0"}},"elements":[{"type":"element","name":"catalog","attributes":{"id":"1"}}]}%

Options

Options available for koa-body. Four custom options, and others are from raw-body and formidable.

A note about parsedMethods

see http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-6.3

File Support

Uploaded files are accessible via ctx.request.files.

A note about unparsed request bodies

Some applications require cryptographic verification of request bodies, for example webhooks from slack or stripe. The unparsed body can be accessed if includeUnparsed is true in koa-body's options. When enabled, import the symbol for accessing the request body from unparsed = require('koa-body/unparsed.js'), or define your own accessor using unparsed = Symbol.for('unparsedBody'). Then the unparsed body is available using ctx.request.body[unparsed].

Some options for formidable

See node-formidable for a full list of options

Changelog

Please see the Changelog for a summary of changes.

Tests

$ npm test

License

The MIT License, 2014 Charlike Mike Reagent (@tunnckoCore) and Daryl Lau (@daryllau)