Noncommital Premarital Mischief


    3.0.41 • Public • Published

    koa-better-body The MIT License npm downloads

    Full-featured koa body parser! Support parsing text, buffer, json, json patch, json api, csp-report, multipart, form and urlencoded bodies. Works for koa@1, koa@2 and will work for koa@3.

    standard code style travis build status coverage status dependency status

    You might also be interested in our recipes - working examples, answers, tips & tricks. Contribute a recipe?

    Upcoming New Release!

    Hey there! We are thinking for v4 release soon (#90), so any feedback is welcome!


    npm i koa-better-body --save



    For more use-cases see the tests

    const koaBetterBody = require('koa-better-body')

    Working with koa-router and koa-better-router

    'use strict'
    var app = require('koa')()
    var body = require('koa-better-body')
    var router = require('koa-better-router')().loadMethods()'/upload', body(), function * (next) {
      // there's no `.body` when `multipart`,
      // `urlencoded` or `json` request
      // print it to the API requester
      this.body = JSON.stringify({
        fields: this.request.fields,
        files: this.request.files,
        body: this.request.body || null
      }, null, 2)
      yield next
    var format = require('util').format
    var host = 'http://localhost:4292'
    var cmd = 'curl -i %s/upload -F "source=@%s/.editorconfig"'
    console.log('Try it out with below CURL for `koa-better-body` repository.')
    console.log(format(cmd, host, __dirname))


    Robust body parser for koa@1, also works for koa@2 (with deprecations). Will also work for future koa@3 with koa-convert.


    • options {Object}: see more on options section
    • returns {GeneratorFunction}


    var koa = require('koa')
    var body = require('koa-better-body')
    var app = koa()
      .use(function * () {
        console.log(this.request.body)    // if buffer or text
        console.log(this.request.files)   // if multipart or urlencoded
        console.log(this.request.fields)  // if json
      .listen(8080, function () {
        console.log('koa server start listening on port 8080')


    Sane defaults.

    Accepts JSON, JSON API v1, text, buffer, csp-report, multipart and urlencoded/form bodies. If you want to disallow accepting and parsing multipart body you should pass multipart: false. Most of the defaults you can see at utils.defaultOptions and utils.defaultTypes. All options are also been passed to formidable.IncomingForm! Even you can pass IncomingForm instance to be able to handle the different formidable events.

    • fields {Boolean|String}: Default false, which means it will set fields on this.request.fields. If you pass a string, for example 'foo', you will have fields on
    • files {Boolean|String}: Default false, which means it will set files on this.request.files. If you pass a string, for example 'bar', you will have files on
    • multipart {Boolean}: Default true. If you pass false it won't accept/parse multipart bodies.
    • textLimit {String}: Default '100kb'. Passed to bytes.parse method.
    • formLimit {String}: Default '100kb'. Passed to bytes.parse method.
    • urlencodedLimit {String}: Default '100kb'. Alias of opts.formLimit.
    • jsonLimit {String}: Default '100kb'. Passed to bytes.parse method.
    • bufferLimit {String}: Default '1mb'. Passed to bytes.parse method.
    • jsonStrict {Boolean}: Default true. When set to true, JSON parser will only accept arrays and objects.
    • detectJSON {Function}: Custom JSON request detect function - detectJSON(ctx).
    • strict {Boolean}: Default true. Pass false if you want to allow parsing GET, DELETE and HEAD requests.
    • onerror {Function}: Custom error handle, if throw an error, you can customize the response - onerror(err, ctx).
    • extendTypes {Object}: Default accepting types can find on utils.defaultTypes function. Allowing you to extend what your app can accept. By default works for JSON, JSON API v1, multipart, text, urlencoded and csp-report.
    • IncomingForm {IncomingForm}: Pass an instance of formidable.IncomingForm to be able to handle formidable events.
    • handler {GeneratorFunction}: Works with options.extendTypes.custom to handle custom types of content-type - handler(ctx, options, next). More info below.
    • querystring {Object}: Querystring module to be used. By default builtin querystring. More info below.
    • qs {Object}: Alias of opts.querystring. All opts are also passed to qs or querystring module.
    • delimiter {String}: Default is &. Delimiter of key/value pairs, passed to querystring lib
    • sep {String}: alias of opts.delimiter
    • buffer {Boolean}: Default false, pass true if you want to get body as buffer.

    Note about options.extendTypes

    ExandTypes option gives you a flexible way to handle different content-types and modify the defaults which can be found at utils.defaultTypes function. In addition you can pass combination of options.extendTypes.custom and options.handler. When the request has some of the "custom" content type, this middleware will call the handler generator function with ctx, options, next. You can see more at issue #52.

    For example manually handle such content types foo/bar-x, text/quix:

    const app = require('koa')()
    const body = require('koa-better-body')
      textLimit: '300kb'
      extendTypes: {
        custom: [
      handler: function * (ctx, opts) {
        // `ctx` is equal to `this` and `app`
        // `opts` is current options object
        // passed to `koa-better-body`
        ctx.body = yield this.request.text(opts.textLimit)
    app.use(function * showBody () {
      // `this.body` is text

    Note about advanced querystring parsing

    Because this middleware is fully based and integrated with koa-body-parsers, by default it uses Node's built-in module for that thing querystring. So if you have some issues with forms, think to add custom querystring module like qs to options.querystring or app.querystring. Related to this is issue #45.


    const app = require('koa')()
    const body = require('koa-better-body')
      multipart: false
      querystring: require('qs')

    It's intentional that it's not included in the deps by default. In v2 it was also working by passing it to app.querystring, because koa-body-parsers works that way (index.js#L53).

    Note about strict mode

    We are trying to follow standards. 🐈

    You can pass strict:false, but see IETF HTTP/1.1 Message Semantics: Section 6.1 to understand why we stay to "strict mode" by default. 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. Last two tests at test/options.js are showing usage on non-strict and strict mode.


    You might also be interested in these packages:


    Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
    But before doing anything, please read the guidelines.

    Contributing Recipes

    Recipes are just different use cases, written in form of README in human language. Showing some "Pro Tips" and tricks, answering common questions and so on. They look like tests, but in more readable and understandable way for humans - mostly for beginners that not reads or understand enough the README or API and tests.

    • They are in form of folders in the root recipes/ folder: for example recipes/[short-meaningful-recipe-name]/.
    • In recipe folder should exist file: see recipes/multipart/
    • The examples from the recipe should also exist as separate .js files.
    • Examples in recipe folder also should be working and actual.

    It would be great if you follow these steps when you want to fix, update or create a recipes. 😎

    • Title for recipe idea should start with [recipe]: for example[recipe] my awesome recipe
    • Title for new recipe (PR) should also start with [recipe].
    • Titles of Pull Requests or Issues for fixing/updating some existing recipes should start with [recipe-fix].

    It will help a lot, thanks in advance! 😋

    Charlike Make Reagent new message to charlike freenode #charlike keybase tunnckoCore tunnckoCore npm tunnckoCore twitter tunnckoCore github


    npm i @pi2star/koa-better-body

    DownloadsWeekly Downloads






    Unpacked Size

    40.7 kB

    Total Files


    Last publish


    • pi2staradmin
    • w958660278