Body Parsing and Raw Body Handling

Relevant source files

• integration/cors/e2e/express.spec.ts
• integration/cors/e2e/fastify.spec.ts
• integration/cors/src/app.controller.ts
• integration/cors/src/app.module.ts
• integration/nest-application/raw-body/e2e/express.spec.ts
• integration/nest-application/raw-body/e2e/fastify.spec.ts
• integration/nest-application/raw-body/src/express.controller.ts
• integration/nest-application/raw-body/src/express.module.ts
• integration/nest-application/raw-body/src/fastify.controller.ts
• integration/nest-application/raw-body/src/fastify.module.ts
• integration/nest-application/raw-body/tsconfig.json
• packages/common/interfaces/http/http-server.interface.ts
• packages/common/interfaces/microservices/nest-hybrid-application-options.interface.ts
• packages/core/adapters/http-adapter.ts
• packages/core/nest-application.ts
• packages/core/test/nest-application.spec.ts
• packages/core/test/utils/noop-adapter.spec.ts
• packages/microservices/microservices-module.ts
• packages/microservices/nest-microservice.ts
• packages/platform-express/adapters/express-adapter.ts
• packages/platform-express/interfaces/nest-express-application.interface.ts
• packages/platform-express/interfaces/serve-static-options.interface.ts
• packages/platform-fastify/adapters/fastify-adapter.ts
• packages/platform-fastify/interfaces/external/fastify-static-options.interface.ts
• packages/platform-fastify/interfaces/external/fastify-view-options.interface.ts
• packages/platform-fastify/interfaces/external/index.ts
• packages/platform-fastify/interfaces/nest-fastify-application.interface.ts

Purpose and Scope

This document explains how NestJS handles HTTP request body parsing across different platform adapters (Express and Fastify). It covers default parser registration, raw body access for webhook signature verification, and the configuration of custom content types and limits.

---

Overview

NestJS provides automatic body parsing for incoming HTTP requests through platform-specific adapters. The framework abstracts the underlying parser implementations (Express body-parser and Fastify addContentTypeParser) into a consistent API.

Key capabilities include:

• Automatic registration of JSON and URL-encoded body parsers during application initialization.
• Raw body access via the rawBody option, enabling access to the original Buffer for signature verification.
• Custom body parsers for handling non-standard content types (e.g., text, XML, binary).
• Global limits for request sizes to protect against denial-of-service attacks.

Data Flow and Registration Architecture

The following diagram illustrates how application options propagate through the NestApplication to the specific platform adapters.

Body Parser Registration Flow

Sources: packages/core/nest-application.ts178-205 packages/platform-express/adapters/express-adapter.ts306-334 packages/platform-fastify/adapters/fastify-adapter.ts619-670

---

Default Body Parser Registration

Initialization Lifecycle

Body parsers are automatically registered during the init() phase of the application lifecycle. The NestApplication checks the bodyParser flag in appOptions before calling the adapter's registration method.

Step	Function/Method	Description
1	NestApplication.init()	Triggers the initialization sequence. packages/core/nest-application.ts178-189
2	registerParserMiddleware()	Determines if rawBody is required and calls the adapter. packages/core/nest-application.ts201-205
3	adapter.registerParserMiddleware()	Platform-specific logic to apply middleware. packages/core/adapters/http-adapter.ts180

Sources: packages/core/nest-application.ts178-205 packages/core/adapters/http-adapter.ts180

Express Implementation

The ExpressAdapter utilizes standard Express middleware. It uses a utility getBodyParserOptions to inject a verify callback if rawBody is enabled.

• JSON Parser: Registered via express.json(). packages/platform-express/adapters/express-adapter.ts308-311
• URL-Encoded Parser: Registered via express.urlencoded({ extended: true }). packages/platform-express/adapters/express-adapter.ts312-315
• Deduplication: The adapter checks if middleware is already applied to prevent redundant parsing. packages/platform-express/adapters/express-adapter.ts306-307

Sources: packages/platform-express/adapters/express-adapter.ts306-319 packages/platform-express/adapters/utils/get-body-parser-options.util.ts

Fastify Implementation

The FastifyAdapter uses Fastify's native addContentTypeParser API. Unlike Express, Fastify requires parsers to be registered before the server starts listening.

• JSON Parser: Uses Fastify's internal JSON parser but wraps it to support rawBody if requested. packages/platform-fastify/adapters/fastify-adapter.ts759-775
• URL-Encoded Parser: Uses querystringParse from fast-querystring. packages/platform-fastify/adapters/fastify-adapter.ts777-793
• State Management: Uses the _isParserRegistered flag to ensure parsers are only registered once. packages/platform-fastify/adapters/fastify-adapter.ts619-633

Sources: packages/platform-fastify/adapters/fastify-adapter.ts619-633 packages/platform-fastify/adapters/fastify-adapter.ts759-793

---

Raw Body Access

Webhook Handling

For use cases like Stripe or GitHub webhooks, the raw request body (unmodified bytes) is required to verify cryptographic signatures. When rawBody: true is set in the application options, NestJS ensures the raw buffer is preserved.

Enabling Raw Body

Implementation Detail: When enabled, the rawBody property is attached to the request object. In Fastify, this happens within the content type parser: (req.raw as any).rawBody = body;. packages/platform-fastify/adapters/fastify-adapter.ts655

RawBodyRequest Interface

The @nestjs/common package provides the RawBodyRequest<T> type to allow type-safe access to the rawBody property.

Entity Mapping: Request to Code

Sources: packages/platform-fastify/adapters/fastify-adapter.ts6-12 packages/platform-fastify/adapters/fastify-adapter.ts650-656

---

Custom Body Parsers

Express Custom Parsers

The ExpressAdapter exposes useBodyParser() which wraps the standard body-parser types: json, urlencoded, raw, and text.

API Signature: packages/platform-express/adapters/express-adapter.ts321-334

Sources: packages/platform-express/interfaces/nest-express-application.interface.ts108-111

Fastify Custom Parsers

Fastify allows registering parsers for specific MIME types or using Regular Expressions.

API Signature: packages/platform-fastify/adapters/fastify-adapter.ts635-670

Sources: packages/platform-fastify/interfaces/nest-fastify-application.interface.ts66-70

---

Configuration and Disabling Parsers

Disabling Automatic Parsing

If you need to handle body parsing entirely manually (e.g., using a specific middleware that Nest doesn't wrap), you can disable the default behavior:

Logic: Setting bodyParser to false prevents registerParserMiddleware() from executing in the init() method. packages/core/nest-application.ts187-188

Configuration Options Reference

Option	Type	Default	Description
bodyParser	boolean	true	Whether to register default parsers.
rawBody	boolean	false	Whether to preserve the raw request buffer.

Sources: packages/core/nest-application.ts186-189 packages/common/interfaces/nest-application-options.interface.ts

---

Implementation Architecture

Class Hierarchy

The AbstractHttpAdapter defines the contract for body parsing, which is then implemented by platform-specific classes.

Sources: packages/core/adapters/http-adapter.ts8-193 packages/common/interfaces/http/http-server.interface.ts17-102