koa-body

library7.0.1jsnpmunverified

koa-body is a robust middleware for the Koa.js web framework designed to parse various request body types. It supports `multipart/form-data` for file uploads, `application/x-www-form-urlencoded`, and `application/json` payloads. Functionally, it offers similar capabilities to a combination of Express's `bodyParser` and `multer`. The current stable version is 7.0.1, and the project is actively maintained by the Koa community, demonstrating a healthy release cadence with recent updates in 2025. Key differentiators include its seamless integration with Koa's middleware system, comprehensive content-type support, and flexible options for patching the parsed body to Koa's context (`ctx.request.body`) or Node's native request object (`ctx.req.body`), alongside configurable limits for body and file sizes.

web-framework serialization

npm install koa-body

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-BODY

koa-body

web-frameworkjavascriptv7.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

koaBody

✓ import { koaBody } from 'koa-body';

✗ import koaBody from 'koa-body';

Since v7, `koaBody` is a named export. Default imports are not supported.

koaBody

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

✗ const koaBody = require('koa-body');

Even in CommonJS, `koaBody` is a named export, requiring destructuring.

KoaBodyMiddlewareOptions

✓ import type { KoaBodyMiddlewareOptions } from 'koa-body';

TypeScript type import for configuring the middleware options.

This quickstart demonstrates setting up a Koa application with `koa-body` to parse JSON, urlencoded, and multipart request bodies. It logs the parsed body and any uploaded files, then responds with a confirmation message.

import Koa from 'koa'; import { koaBody } from 'koa-body'; const app = new Koa(); // Apply koa-body middleware globally or on specific routes app.use(koaBody({ multipart: true, // Enable multipart for file uploads urlencoded: true, json: true, formLimit: '1mb', // Limit form body size jsonLimit: '1mb', // Limit JSON body size textLimit: '1mb' // Limit text body size })); app.use(async (ctx) => { // For POST, PUT, PATCH requests, the parsed body is available at ctx.request.body if (ctx.method === 'POST' || ctx.method === 'PUT' || ctx.method === 'PATCH') { console.log('Request Body:', ctx.request.body); if (ctx.request.files) { console.log('Uploaded Files:', ctx.request.files); } ctx.body = `Received: ${JSON.stringify(ctx.request.body)}`; } else { ctx.body = 'Send a POST, PUT, or PATCH request with a body.'; } }); const port = 3000; app.listen(port, () => { console.log(`Koa server listening on http://localhost:${port}`); console.log('Try: curl -i http://localhost:3000/users -d "name=test" -X POST'); console.log('Or (for files): curl -i -X POST -F "name=filetest" -F "file=@./package.json" http://localhost:3000/upload'); });

Debug

Known issues

gotchaThe v7.0.0 major version bump primarily introduced internal tooling updates, refactoring, and improved TypeScript support, rather than significant breaking API changes for most common use cases. While internal types and raw body access (`ctx.request.rawBody`) were refined, core API usage for parsing `json`, `urlencoded`, and `multipart` largely remained consistent.

fix

Review the official v7.0.0 changelog on GitHub for detailed internal changes, especially if you relied on specific internal properties or unparsed body access methods. Update your TypeScript types if encountering issues.

affects: >=7.0.0

breaking`koa-body` by default only parses bodies for `POST`, `PUT`, and `PATCH` HTTP methods. Other methods like `GET`, `HEAD`, or `DELETE` will not have `ctx.request.body` populated unless explicitly configured.

fix

If you need to parse bodies for other HTTP methods, configure the `parsedMethods` option: `app.use(koaBody({ parsedMethods: ['POST', 'PUT', 'PATCH', 'GET', 'DELETE'] }));`. Be aware of HTTP specification implications when sending bodies with `GET` or `DELETE` requests.

affects: All versions

gotchaFor requests with unsupported text body types (e.g., `text/xml`), the raw unparsed body is available at `ctx.request.body` directly without needing `includeUnparsed` option, provided `koa-body` is used. If `includeUnparsed` is true, it also populates `ctx.request.rawBody` for non-multipart bodies.

fix

Access `ctx.request.body` for unsupported text types. For other scenarios requiring the raw body (e.g., cryptographic verification), set `includeUnparsed: true` in options and access `ctx.request.rawBody`.

affects: All versions

gotchaFile uploads (multipart bodies) are disabled by default. If you intend to handle file uploads, you must explicitly enable the `multipart` option.

fix

Enable multipart parsing by setting `multipart: true` in the `koaBody` options: `app.use(koaBody({ multipart: true }));`.

affects: All versions

Errors

Common errors & fixes

TypeError: ctx.request.body is undefined

The `koa-body` middleware was not applied to the route or application, or the request method is not one of the default `POST`, `PUT`, `PATCH` methods.

fix

Ensure `app.use(koaBody());` is called before routes that expect a body. If expecting bodies on other HTTP methods, configure `parsedMethods` option: `koaBody({ parsedMethods: ['POST', 'GET'] })`.

Error: request entity too large

The incoming request body (JSON, form, or text) exceeds the configured `jsonLimit`, `formLimit`, or `textLimit` options.

fix

Increase the relevant size limit in the `koaBody` options, e.g., `koaBody({ jsonLimit: '5mb', formLimit: '2mb' });`. Defaults are `1mb` for JSON and `56kb` for form/text.

Files are not being uploaded or ctx.request.files is empty for multipart requests.

The `multipart` option is not enabled in the `koaBody` configuration.

fix

Set `multipart: true` in the `koaBody` options: `koaBody({ multipart: true });`. Also, ensure your HTML form has `enctype="multipart/form-data"` or your API client sends the correct `Content-Type` header.

Upgrade

Version history

7.0.1latest on npm

Audit

Dependencies

koarequiredkoa-body is a middleware specifically designed for the Koa.js web framework and requires Koa to function.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/koajs/koa-body ↗

packagehttps://www.npmjs.com/package/koa-body ↗