Nostalgic Perogi Monogramming
    Have ideas to improve npm?Join in the discussion! »

    TypeScript icon, indicating that this package has built-in type declarations

    4.2.0-4 • Public • Published

    koa-body-plus Build Status Dependencies Status KoaJs Slack

    This object forked from on 2020-08-15


    Keep most of the original code, only make a small change to the content type.


    Tribute to the original author.


    The release name in NPM is koa-body-plus


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


    Install with npm

    npm install koa-body-plus


    • can handle requests such as:
      • multipart/form-data

      • application/x-www-urlencoded

      • application/json

      • application/json-patch+json

      • application/vnd.api+json

      • application/csp-report

      • text/xml

      • image/*

    And any other requests

    • option for patch to Koa or Node, or either
    • file uploads
    • body, fields and files size limiting

    Hello World - Quickstart

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


    const Koa = require('koa');
    const koaBody = require('koa-body-plus');
    const app = new Koa();
    app.use(ctx => {
      ctx.body = `Request Body: ${JSON.stringify(ctx.request.body)}`;
    node index.js
    curl -i http://localhost:3000/users -d "name=test"


    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"}%


    const Koa = require('koa');
    const koaBody = require('koa-body-plus');
    const app = new Koa();
    app.use(ctx => {
      ctx.body = ctx.request.file;
    curl -v http://localhost:3001/ -H"content-type: application/x-gzip" -X PUT -d "@redis-5.0.8.tar.gz"


    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Content-Length: 119
    Date: Sun, 16 Aug 2020 01:21:49 GMT
    Connection: keep-alive

    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-plus');
'/users', koaBody(),
      (ctx) => {
        // => POST body
        ctx.body = JSON.stringify(ctx.request.body);
    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-plus');
    const convert = require('xml-js');
    const app = new Koa();
    app.use(ctx => {
      const obj = convert.xml2js(ctx.request.body)
      ctx.body = `Request Body: ${JSON.stringify(obj)}`;
    node xml-parse.js
    curl -i http://localhost:3000/users -H "Content-Type: text/xml" -d '<?xml version="1.0"?><catalog id="1"></catalog>'


    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 available for koa-body-plus. Four custom options, and others are from raw-body and formidable.

    • patchNode {Boolean} Patch request body to Node's ctx.req, default false
    • patchKoa {Boolean} Patch request body to Koa's ctx.request, default true
    • jsonLimit {String|Integer} The byte (if integer) limit of the JSON body, default 1mb
    • formLimit {String|Integer} The byte (if integer) limit of the form body, default 56kb
    • textLimit {String|Integer} The byte (if integer) limit of the text body, default 56kb
    • binLimit {String|Integer} The byte (if integer) limit of the binary body, default 1mb
    • encoding {String} Sets encoding for incoming form fields, default utf-8
    • multipart {Boolean} Parse multipart bodies, default false
    • urlencoded {Boolean} Parse urlencoded bodies, default true
    • text {Boolean} Parse text bodies, such as XML, default true
    • json {Boolean} Parse JSON bodies, default true
    • bin {Boolean} Parse binary bodies, default true
    • jsonStrict {Boolean} Toggles co-body strict mode; if set to true - only parses arrays or objects, default true
    • includeUnparsed {Boolean} Toggles co-body returnRawBody option; if set to true, for form encodedand and JSON requests the raw, unparsed requesty body will be attached to ctx.request.body using a Symbol, default false
    • formidable {Object} Options to pass to the formidable multipart parser
    • onError {Function} Custom error handle, if throw an error, you can customize the response - onError(error, context), default will throw
    • strict {Boolean} DEPRECATED If enabled, don't parse GET, HEAD, DELETE requests, default true
    • parsedMethods {String[]} Declares the HTTP methods where bodies will be parsed, default ['POST', 'PUT', 'PATCH']. Replaces strict option.

    A note about parsedMethods


    • GET, HEAD, and DELETE requests have no defined semantics for the request body, but this doesn't mean they may not be valid in certain use cases.
    • koa-body-plus is strict by default, parsing only POST, PUT, and PATCH requests

    File Support

    Uploaded files are accessible via ctx.request.files. Requests other than multipart, urlencoded, and JSON can be accessed through the ctx.request.file visit

    A note about unparsed request bodies

    Some applications require crytopgraphic verification of request bodies, for example webhooks from slack or stripe. The unparsed body can be accessed if includeUnparsed is true in koa-body-plus's options. When enabled, import the symbol for accessing the request body from unparsed = require('koa-body-plus/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

    • maxFields {Integer} Limits the number of fields that the querystring parser will decode, default 1000
    • maxFieldsSize {Integer} Limits the amount of memory all fields together (except files) can allocate in bytes. If this value is exceeded, an 'error' event is emitted, default 2mb (2 * 1024 * 1024)
    • uploadDir {String} Sets the directory for placing file uploads in, default os.tmpDir()
    • keepExtensions {Boolean} Files written to uploadDir will include the extensions of the original files, default false
    • hash {String} If you want checksums calculated for incoming files, set this to either 'sha1' or 'md5', default false
    • multiples {Boolean} Multiple file uploads or no, default true
    • onFileBegin {Function} Special callback on file begin. The function is executed directly by formidable. It can be used to rename files before saving them to disk. See the docs


    Please see the Changelog for a summary of changes.


    $ npm test


    The MIT License, 2020 Charlike Mike Reagent (@tunnckoCore) Daryl Lau (@daryllau) and Mustang Yu(@于恩水)


    npm i koa-body-plus

    DownloadsWeekly Downloads






    Unpacked Size

    25.7 kB

    Total Files


    Last publish


    • avatar