# koa-body

> A Koa body parser middleware. Supports multipart, urlencoded and JSON request bodies.

Latest version **8.0.1** (published 2026-09-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa-body
pnpm add koa-body
yarn add koa-body
bun add koa-body
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 8.0.1 |
| Published | 2026-09-07 |
| First published | 2014-01-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 62.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 954 |
| Maintainers | dlau, markherhold, thedadi |
| Keywords | koa, urlencoded, multipart, json, body, parser, form |

## Links

- npm: https://www.npmjs.com/package/koa-body
- Repository: https://github.com/koajs/koa-body
- npm.io page: https://npm.io/package/koa-body

## Dependencies (7)

- [zod](https://npm.io/package/zod.md) ^4.5.4
- [co-body](https://npm.io/package/co-body.md) ^6.2.0
- [type-fest](https://npm.io/package/type-fest.md) ^5.9.0
- [@types/koa](https://npm.io/package/@types/koa.md) ^3.0.3
- [formidable](https://npm.io/package/formidable.md) ^3.5.4
- [@types/co-body](https://npm.io/package/@types/co-body.md) ^6.1.3
- [@types/formidable](https://npm.io/package/@types/formidable.md) ^3.5.1

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 8.0.1 (latest) — 2026-09-07
- 8.0.0 — 2026-05-13
- 7.0.1 — 2025-12-15
- 7.0.0 — 2025-10-23
- 6.0.1 — 2022-10-29
- 6.0.0 — 2022-10-27
- 5.0.0 — 2022-04-21
- 4.2.0 — 2020-06-12
- 4.1.3 — 2020-05-19
- 4.1.2 — 2020-05-16
- 4.1.1 — 2019-08-13
- 4.1.0 — 2019-03-07
- 4.0.8 — 2019-02-08
- 4.0.7 — 2019-01-29
- 4.0.6 — 2018-12-21
- … 32 more at https://npm.io/package/koa-body/versions

## README

# koa-body

[![CI](https://github.com/koajs/koa-body/actions/workflows/ci.yaml/badge.svg)](https://github.com/koajs/koa-body/actions/workflows/ci.yaml)
[![KoaJs Slack](https://img.shields.io/badge/Koa.Js-Slack%20Channel-Slack.svg?longCache=true)](https://communityinviter.com/apps/koa-js/koajs)

---

> A full-featured [`koa`](https://github.com/koajs/koa) body parser middleware. Supports `multipart`, `urlencoded`, and `json` request bodies. Provides the same functionality as Express's bodyParser - [`multer`](https://github.com/expressjs/multer).

## Install

> Install with [npm](https://github.com/npm/npm)

```
npm install koa-body
```

## Features

- can handle requests such as:
  - **multipart/form-data**
  - **application/x-www-form-urlencoded**
  - **application/json**
  - **application/json-patch+json**
  - **application/vnd.api+json**
  - **application/csp-report**
  - **application/reports+json**
  - **text/xml**
- configurable content-type matchers per body kind (`jsonTypes`, `urlencodedTypes`, `textTypes`, `multipartTypes`) for vendor or custom mime types
- option for patch to Koa or Node, or either
- file uploads
- body, fields and files size limiting

## Hello World - Quickstart

```sh
npm install koa koa-body # Requires Node.js 22+
```

index.js:

```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);
```

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

Output:

```text
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](https://github.com/koajs/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.

```js
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.

```js
// 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);
```

```sh
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:

```text
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 `co-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`
- `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`
- `jsonStrict` **{Boolean}** Toggles co-body strict mode; if set to true - only parses arrays or objects, default `true`
- `jsonTypes` **{String[]}** Content-types matched as JSON bodies (passed to `ctx.is(...)`), default `['application/json', 'application/json-patch+json', 'application/vnd.api+json', 'application/csp-report', 'application/reports+json']`
- `urlencodedTypes` **{String[]}** Content-types matched as urlencoded bodies (passed to `ctx.is(...)`), default `['urlencoded']`
- `textTypes` **{String[]}** Content-types matched as text bodies (passed to `ctx.is(...)`), default `['text/*']`
- `multipartTypes` **{String[]}** Content-types matched as multipart bodies (passed to `ctx.is(...)`), default `['multipart']`
- `includeUnparsed` **{Boolean}** Toggles co-body returnRawBody option; if set to true, for form encoded and JSON requests the raw, unparsed request body will be attached to `ctx.request.rawBody`, 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
- `parsedMethods` **{String[]}** Declares the HTTP methods where bodies will be parsed, default `['POST', 'PUT', 'PATCH']`. Replaces `strict` option.

## A note about `parsedMethods`

> see [http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-6.3](http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-19#section-6.3)

- `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 is strict by default, parsing only `POST`, `PUT`, and `PATCH` requests
- you may use either the enumeration or strings to chose which methods to parse: For example, `HttpMethodEnum.PATCH`

## 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. Then the unparsed body is available at `ctx.request.rawBody`. This only works for non `multipart` bodies. 

## Some options for formidable

> See [node-formidable](https://github.com/node-formidable/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`
- `hashAlgorithm` **{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](https://github.com/node-formidable/formidable#filebegin)
- `onPart` **{Function}** Overrides the default onPart of formidable. The function can be used to filter out parts based on their mimetype. For more use cases. [See the docs](https://github.com/node-formidable/formidable#formonpart)

## Changelog

Please see the [Changelog](./CHANGELOG.md) for a summary of changes.

## Tests

```
$ npm test
```

## License

The MIT License, 2014 [Charlike Mike Reagent](https://github.com/tunnckoCore) ([@tunnckoCore](https://twitter.com/tunnckoCore)) and [Daryl Lau](https://github.com/dlau) ([@daryllau](https://twitter.com/daryllau))

---
_Source: https://npm.io/package/koa-body · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._