{"id":16412,"library":"koa-body","title":"Koa Body Parser Middleware","description":"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.","status":"active","version":"7.0.1","language":"javascript","source_language":"en","source_url":"git://github.com/koajs/koa-body","tags":["javascript","koa","urlencoded","multipart","json","body","parser","form","typescript"],"install":[{"cmd":"npm install koa-body","lang":"bash","label":"npm"},{"cmd":"yarn add koa-body","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-body","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"koa-body is a middleware specifically designed for the Koa.js web framework and requires Koa to function.","package":"koa","optional":false}],"imports":[{"note":"Since v7, `koaBody` is a named export. Default imports are not supported.","wrong":"import koaBody from 'koa-body';","symbol":"koaBody","correct":"import { koaBody } from 'koa-body';"},{"note":"Even in CommonJS, `koaBody` is a named export, requiring destructuring.","wrong":"const koaBody = require('koa-body');","symbol":"koaBody","correct":"const { koaBody } = require('koa-body');"},{"note":"TypeScript type import for configuring the middleware options.","symbol":"KoaBodyMiddlewareOptions","correct":"import type { KoaBodyMiddlewareOptions } from 'koa-body';"}],"quickstart":{"code":"import Koa from 'koa';\nimport { koaBody } from 'koa-body';\n\nconst app = new Koa();\n\n// Apply koa-body middleware globally or on specific routes\napp.use(koaBody({\n  multipart: true, // Enable multipart for file uploads\n  urlencoded: true,\n  json: true,\n  formLimit: '1mb', // Limit form body size\n  jsonLimit: '1mb', // Limit JSON body size\n  textLimit: '1mb' // Limit text body size\n}));\n\napp.use(async (ctx) => {\n  // For POST, PUT, PATCH requests, the parsed body is available at ctx.request.body\n  if (ctx.method === 'POST' || ctx.method === 'PUT' || ctx.method === 'PATCH') {\n    console.log('Request Body:', ctx.request.body);\n    if (ctx.request.files) {\n      console.log('Uploaded Files:', ctx.request.files);\n    }\n    ctx.body = `Received: ${JSON.stringify(ctx.request.body)}`;\n  } else {\n    ctx.body = 'Send a POST, PUT, or PATCH request with a body.';\n  }\n});\n\nconst port = 3000;\napp.listen(port, () => {\n  console.log(`Koa server listening on http://localhost:${port}`);\n  console.log('Try: curl -i http://localhost:3000/users -d \"name=test\" -X POST');\n  console.log('Or (for files): curl -i -X POST -F \"name=filetest\" -F \"file=@./package.json\" http://localhost:3000/upload');\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=7.0.0"},{"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.","message":"`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.","severity":"breaking","affected_versions":"All versions"},{"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`.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Enable multipart parsing by setting `multipart: true` in the `koaBody` options: `app.use(koaBody({ multipart: true }));`.","message":"File uploads (multipart bodies) are disabled by default. If you intend to handle file uploads, you must explicitly enable the `multipart` option.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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'] })`.","cause":"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.","error":"TypeError: ctx.request.body is undefined"},{"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.","cause":"The incoming request body (JSON, form, or text) exceeds the configured `jsonLimit`, `formLimit`, or `textLimit` options.","error":"Error: request entity too large"},{"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.","cause":"The `multipart` option is not enabled in the `koaBody` configuration.","error":"Files are not being uploaded or ctx.request.files is empty for multipart requests."}],"ecosystem":"npm"}