Body Parser

Parse incoming request bodies before your handlers process them.

HTTP request bodies arrive as raw byte streams. This middleware reads, validates, and parses them into usable JavaScript values — handling JSON, URL-encoded forms, plain text, and raw binary data. Built-in protections guard against oversized payloads, prototype pollution, and malformed input.

Default BehaviorCopy Anchor Link

With default options, bodyParser() parses JSON and URL-encoded request bodies. Text and raw binary parsing stay off until you enable them.

Bodyless HTTP methods (GET, HEAD, DELETE, OPTIONS) are skipped automatically. If the body has already been parsed by another middleware, parsing is skipped.

InstallationCopy Anchor Link

$ pnpm add @nextrush/body-parser

Minimal UsageCopy Anchor Link

import { createApp } from '@nextrush/core';
import { bodyParser } from '@nextrush/body-parser';

const app = createApp();

// Parses JSON and URL-encoded bodies by default
app.use(bodyParser());

app.use(async (ctx) => {
  ctx.json({ received: ctx.body });
});

Individual ParsersCopy Anchor Link

Use individual parsers when you need to handle specific content types only.

import { json } from '@nextrush/body-parser';

app.use(json());
// Parses: application/json

Configuration OptionsCopy Anchor Link

bodyParser(options?)Copy Anchor Link

Combined parser that routes to the appropriate parser based on Content-Type.

function bodyParser(options?: BodyParserOptions): Middleware;

JSON and URL-encoded parsing are enabled by default. To enable text or raw parsing, provide an options object (even {} activates them). To disable a parser, set it to false.

app.use(
  bodyParser({
    json: { limit: '10mb', strict: true },
    urlencoded: { extended: true, depth: 5 },
    text: {}, // Enable text parsing with defaults
    raw: false, // Explicitly disable raw parsing
  })
);

Multipart requests (multipart/form-data) throw an UNSUPPORTED_CONTENT_TYPE error with a hint to use a dedicated multipart parser.

json(options?)Copy Anchor Link

function json(options?: JsonOptions): Middleware;

urlencoded(options?)Copy Anchor Link

function urlencoded(options?: UrlEncodedOptions): Middleware;

text(options?)Copy Anchor Link

function text(options?: TextOptions): Middleware;

raw(options?)Copy Anchor Link

function raw(options?: RawOptions): Middleware;

Lazy ParsingCopy Anchor Link

By default the parser reads, verifies, and parses the body before next() runs. With lazy: true it stops after detection and defers the rest to await ctx.readBody():

app.use(bodyParser({ lazy: true }));

app.post('/webhooks/github', async (ctx) => {
  // A request that never reaches this line costs no body work at all.
  const payload = await ctx.readBody<{ action: string }>();
  return ctx.json({ received: payload.action });
});

Detection still runs eagerly — method, media type, and an already-parsed body decide who owns the request — so multipart/form-data and onUnsupportedContentType: 'reject' keep answering 415 before your handler. Bytes, the size limit, verify, decoding, parsing, and the JSON depth guard all run inside readBody().

readBody() exists in both modes, is idempotent, shares one read between concurrent callers, and caches a failure for the rest of the request.

What changes when you opt in:

Use eager parsing when most requests need the body, when a malformed payload must be rejected before any handler runs, or through @nextrush/express-bridge (whose req.body is a synchronous getter). Measured on Bun 1.4.4, a 1 KB JSON POST whose handler never reads the body drops from 9.39 µs to 6.45 µs per request (−31 %); a request that does read it pays roughly 0.4–0.5 µs more than eager parsing.

Integration ExampleCopy Anchor Link

An API server with error handling, JSON parsing, and webhook signature verification:

import { createApp } from '@nextrush/core';
import { json, BodyParserError } from '@nextrush/body-parser';
import { createHmac } from 'node:crypto';

const app = createApp();

// Error handler (register before body parser)
app.use(async (ctx, next) => {
  try {
    await next();
  } catch (error) {
    if (error instanceof BodyParserError) {
      ctx.status = error.status;
      ctx.json({ error: error.message, code: error.code });
      return;
    }
    throw error;
  }
});

// Parse JSON with raw body access for webhook verification
app.use(json({ limit: '1mb', rawBody: true }));

app.post('/webhook', async (ctx) => {
  const signature = ctx.headers['x-signature'] as string;
  const rawBody = ctx.rawBody as Buffer;

  const expected = createHmac('sha256', process.env.WEBHOOK_SECRET!).update(rawBody).digest('hex');

  if (signature !== expected) {
    ctx.status = 401;
    ctx.json({ error: 'Invalid signature' });
    return;
  }

  ctx.json({ ok: true });
});

Error HandlingCopy Anchor Link

All parsers throw BodyParserError on failure. Each error includes status (HTTP status code), code (machine-readable string), and expose (whether the message is safe for clients).

import { BodyParserError } from '@nextrush/body-parser';

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (error) {
    if (error instanceof BodyParserError) {
      ctx.status = error.status;
      ctx.json({ error: error.message, code: error.code });
      return;
    }
    throw error;
  }
});

Error CodesCopy Anchor Link

Common MistakesCopy Anchor Link

• Using bodyParser() and expecting text/raw parsing — these are disabled by default. Enable them explicitly: bodyParser({ text: {}, raw: {} }).
• Setting the wrong size limit units — limits accept 'b', 'kb', 'mb', 'gb'. A bare number is treated as bytes.
• Expecting multipart form uploads to work — this parser does not handle multipart/form-data. Use a dedicated multipart parser.
• Forgetting error handling — without an error-catching middleware upstream, BodyParserError will crash your app.

TroubleshootingCopy Anchor Link

ctx.body is undefined after parsing:

• Verify the request has a matching Content-Type header.
• Check the HTTP method — GET, HEAD, DELETE, and OPTIONS requests are skipped.
• Confirm no earlier middleware has already set ctx.body.

413 errors on valid payloads:

• Increase the limit option. The JSON default is 1mb; URL-encoded, text, and raw default to 100kb.

UNSUPPORTED_CONTENT_TYPE error:

• The combined parser throws this for multipart/form-data requests. Use a separate multipart parser.

BODY_NOT_READ error:

• lazy: true is active and something read ctx.body before awaiting the read. Call const body = await ctx.readBody() first, or drop lazy: true.

RelatedCopy Anchor Link

• Middleware Overview — All middleware packages
• @nextrush/cors — CORS handling
• @nextrush/rate-limit — Rate limiting