@koa/bodyparser

@koa/bodyparser is the official Koa-ecosystem successor to koa-bodyparser, a middleware that inspects the incoming request’s content type and parses JSON, urlencoded form, plain text, or XML bodies before your route handlers run. Parsed output lands on ctx.request.body (and optionally the raw Node ctx.req via patchNode), so downstream middleware and handlers can read structured data without touching the request stream themselves. It builds on co-body for the actual parsing and type-is for content-type matching, wrapping both in a small, fully-typed options surface.

Because it ships as a scoped @koa/ package with first-class TypeScript declarations (including ambient module augmentation for Koa’s Request and Node’s IncomingMessage), it slots into modern Koa 2/3 codebases with typed ctx.request.body access out of the box, no extra @types package required. Options like enableTypes, extendTypes, per-type size limits, a custom onError handler, and an enableRawChecking escape hatch for already-parsed bodies give it the same flexibility as the original koa-bodyparser while staying a drop-in migration for existing apps.

What You Get

• A single bodyParser() middleware (named or default export) that parses JSON, urlencoded form, text, and XML bodies based on the request’s content type
• Ambient TypeScript declarations that augment Koa’s Request and Node’s IncomingMessage types, so ctx.request.body is typed without installing separate @types packages
• Per-type size limits (jsonLimit, formLimit, textLimit, xmlLimit) and a jsonStrict flag to reject non-object/array JSON payloads
• An extendTypes option to add custom MIME types to any of the four supported body types, and a detectJSON hook for custom JSON-detection logic
• A patchNode option to also attach the parsed body to Node’s raw ctx.req, and enableRawChecking to avoid re-parsing a body some earlier middleware already populated
• Dual CommonJS and ESM builds (via tsup) with generated .d.ts files, so it works in both require() and import codebases

Common Use Cases

• Parsing JSON API request bodies in a Koa REST service before validation and business logic run
• Handling traditional HTML form submissions (application/x-www-form-urlencoded) in server-rendered Koa apps
• Accepting webhook payloads that arrive as JSON or XML from third-party services
• Migrating an existing koa-bodyparser codebase to a maintained, typed package with the same middleware shape

Under The Hood

Architecture The package is a single functional middleware wrapper (src/body-parser.ts) that closes over its options at creation time and returns a per-request Koa handler; there is no class hierarchy or DI container. bodyParserWrapper precomputes an isEnabledBodyAs map and a merged mimeTypes table (from src/body-parser.utils.ts) once, then the returned bodyParser(ctx, next) function runs a chain of guards (method not in parsedMethods, already-parsed body, ctx.disableBodyParser) before calling an inner parseBody(ctx) that selects a body type and delegates to co-body’s json/form/text parsers, finally patching ctx.request.body (and optionally ctx.req.body via patchNode). Type definitions live in a dedicated src/body-parser.types.ts module. The design is intentionally flat and small, with body-parser.utils.ts’s type-detection helpers acting as the one piece every body-type branch depends on.

Tech Stack Written in TypeScript 5.9 targeting Node >=18, the package delegates actual parsing to co-body ^6.2, uses lodash.merge to deep-merge default and extended MIME-type maps, and type-is for content-type matching; koa itself is only a peerDependency (>=2), never a hard runtime dependency. Builds are produced by tsup in both CJS and ESM formats with generated .d.ts files, tests run under Jest with ts-jest and supertest, linting is enforced via xo (built on eslint-config-xo-lass) with Prettier formatting, and GitHub Actions CI matrixes Node 18/20/22 running lint and coverage-instrumented tests on every push and pull request.

Code Quality A single comprehensive test file (test/middleware.test.ts) drives the middleware end-to-end through supertest, covering JSON/form/text/XML parsing, patchNode, enableRawChecking, custom onError handling, and disabled-parsing paths; error handling is explicit, with a try/catch around parsing that re-throws unless a custom onError handler is supplied, avoiding silent failures. The codebase is fully typed under a strict tsconfig, consistently named, and gated by CI-enforced linting and testing across multiple Node versions, though it relies on one large suite rather than per-module unit tests.

API Design The public API is a single bodyParser(options) factory that mirrors the long-familiar koa-bodyparser calling convention, making migration close to a drop-in package swap. Options are a flat, well-documented object with sensible defaults (jsonStrict: true, formLimit: '56kb', etc.), and DX niceties like the per-request ctx.disableBodyParser escape hatch, the enableRawChecking flag for avoiding double-parsing behind a proxy, and full ambient TypeScript declaration merging mean consumers get typed ctx.request.body access with no extra setup. It doesn’t introduce a novel parsing algorithm — it wraps co-body — so its strength is developer ergonomics and typing rather than technical originality.