# @routup/body

> Body plugin for routup.

Latest version **4.0.0** (published 2026-05-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install @routup/body
pnpm add @routup/body
yarn add @routup/body
bun add @routup/body
```

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-05-20 |
| First published | 2022-11-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 47.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Peter Placzek |
| Maintainers | tada5hi |
| Keywords | body, api, rest, http, router, api-router, route, routing |

## Links

- npm: https://www.npmjs.com/package/@routup/body
- Repository: https://github.com/routup/plugins
- Homepage: https://github.com/routup/plugins#readme
- Issues: https://github.com/routup/plugins/issues
- npm.io page: https://npm.io/package/@routup/body

## Recent versions

- 4.0.0 (latest) — 2026-05-20
- 3.2.0 — 2026-05-12
- 3.1.0 — 2026-05-06
- 3.0.0 — 2026-05-05
- 2.4.3 — 2025-11-26
- 2.4.2 — 2025-06-25
- 2.4.1 — 2024-09-15
- 2.4.0 — 2024-06-29
- 2.3.0 — 2023-11-21
- 2.2.0 — 2023-11-20
- 2.1.0 — 2023-10-22
- 2.0.0 — 2023-10-04
- 2.0.0-alpha.3 — 2023-10-04
- 2.0.0-alpha.0 — 2023-09-30
- 1.0.3 — 2023-09-14
- … 34 more at https://npm.io/package/@routup/body/versions

## README

# @routup/body

[![npm version](https://badge.fury.io/js/@routup%2Fbody.svg)](https://badge.fury.io/js/@routup%2Fbody)
[![main](https://github.com/routup/plugins/actions/workflows/main.yml/badge.svg)](https://github.com/routup/plugins/actions/workflows/main.yml)
[![codecov](https://codecov.io/gh/routup/plugins/branch/master/graph/badge.svg)](https://codecov.io/gh/routup/plugins)
[![Known Vulnerabilities](https://snyk.io/test/github/routup/plugins/badge.svg)](https://snyk.io/test/github/routup/plugins)
[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)

This is a plugin for reading and parsing the request payload.

**Table of Contents**

- [Installation](#installation)
- [Documentation](#documentation)
- [Usage](#usage)
- [Options](#options)
  - [json](#json)
  - [urlEncoded](#urlencoded)
  - [raw](#raw)
  - [text](#text)
- [Helpers](#helpers)
  - [readRequestBody](#readrequestbody)
  - [readRequestBodyText](#readrequestbodytext)
  - [readRequestBodyBytes](#readrequestbodybytes)
  - [readRequestBodyArrayBuffer](#readrequestbodyarraybuffer)
  - [readRequestBodyBlob](#readrequestbodyblob)
  - [readRequestBodyStream](#readrequestbodystream)
- [License](#license)

## Installation

```bash
npm install @routup/body --save
```

## Documentation

To read the docs, visit [https://routup.net](https://routup.net)

## Usage

For standard use, the package is installed as a plugin, as shown below.

```typescript
import {
    App,
    defineCoreHandler,
    serve,
} from 'routup';
import { body, readRequestBody } from '@routup/body';

const router = new App();

// This will parse requests with Content-Type:
// application/json
// application/x-www-form-urlencoded
router.use(body());

router.post('/', defineCoreHandler(async (event) => {
    const data = await readRequestBody(event);
    console.log(data);

    return data;
}));

serve(router, { port: 3000 });
```

## Options

The plugin accepts an object as input parameter to modify the default behaviour.
By default, `json` and `urlEncoded` are enabled.

### `json`

To parse `application/json` input data.

- Type: `JsonOptions | boolean`
- Default: `true`

```typescript
router.use(body({
    json: {
        limit: '1mb',
        strict: true,
    }
}));
```

**JsonOptions:**

| Property | Type | Default | Description |
|---|---|---|---|
| `limit` | `number \| string` | none | Maximum body size (bytes or string like `'1mb'`) |
| `strict` | `boolean` | `true` | Only accept arrays and objects |
| `reviver` | `function` | `undefined` | A reviver function passed to `JSON.parse` |
| `type` | `string \| string[]` | `'application/json'` | Content-types to parse |

### `urlEncoded`

To parse `application/x-www-form-urlencoded` input data.

- Type: `UrlEncodedOptions | boolean`
- Default: `true`

```typescript
router.use(body({
    urlEncoded: {
        limit: '100kb',
        parameterLimit: 1000,
    }
}));
```

**UrlEncodedOptions:**

| Property | Type | Default | Description |
|---|---|---|---|
| `limit` | `number \| string` | none | Maximum body size |
| `parameterLimit` | `number` | `1000` | Maximum number of parameters |
| `type` | `string \| string[]` | `'application/x-www-form-urlencoded'` | Content-types to parse |

### `raw`

Configure options for raw body reading (used by `readRequestBodyBytes`, `readRequestBodyArrayBuffer`, `readRequestBodyBlob`).

- Type: `RawOptions | boolean`
- Default: `false`

```typescript
router.use(body({
    raw: {
        limit: '5mb',
    }
}));
```

### `text`

Configure options for text body reading (used by `readRequestBodyText`).

- Type: `TextOptions | boolean`
- Default: `false`

```typescript
router.use(body({
    text: {
        limit: '100kb',
        defaultCharset: 'utf-8',
    }
}));
```

**TextOptions:**

| Property | Type | Default | Description |
|---|---|---|---|
| `limit` | `number \| string` | none | Maximum body size |
| `defaultCharset` | `string` | `'utf-8'` | Default charset if not specified in content-type |
| `type` | `string \| string[]` | `'text/plain'` | Content-types to parse |

## Helpers

### `readRequestBody`

Returns the parsed request body (JSON or URL-encoded). The result is cached after the first call.

```typescript
declare function readRequestBody(
    event: IAppEvent,
) : Promise<Record<string, any>>;

declare function readRequestBody(
    event: IAppEvent,
    key: string,
) : Promise<any | undefined>;
```

### `readRequestBodyText`

Returns the request body as a string.

```typescript
declare function readRequestBodyText(
    event: IAppEvent,
    options?: TextOptions,
) : Promise<string>;
```

### `readRequestBodyBytes`

Returns the request body as a `Uint8Array`.

```typescript
declare function readRequestBodyBytes(
    event: IAppEvent,
    options?: RawOptions,
) : Promise<Uint8Array>;
```

### `readRequestBodyArrayBuffer`

Returns the request body as an `ArrayBuffer`.

```typescript
declare function readRequestBodyArrayBuffer(
    event: IAppEvent,
    options?: BaseOptions,
) : Promise<ArrayBuffer>;
```

### `readRequestBodyBlob`

Returns the request body as a `Blob`.

```typescript
declare function readRequestBodyBlob(
    event: IAppEvent,
    options?: BaseOptions,
) : Promise<Blob>;
```

### `readRequestBodyStream`

Returns the request body as a `ReadableStream`, decompressed if the `content-encoding` header indicates compression (gzip, deflate, brotli). Does not buffer or cache — useful for piping large bodies without holding them in memory.

```typescript
declare function readRequestBodyStream(
    event: IAppEvent,
    options?: BaseOptions,
) : ReadableStream | null;
```

## License

Made with 💚

Published under [MIT License](./LICENSE).

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