fastify-formbody

@fastify/formbody is an official Fastify plugin that adds a content-type parser for application/x-www-form-urlencoded request bodies, the format browsers send by default from standard HTML forms. Without it, Fastify has no built-in way to parse url-encoded form submissions, leaving developers to write their own parser or reach for a heavier general-purpose body-parsing library.

The plugin registers a single content-type parser using Fastify’s fast, buffer-based content-type parsing hook, and defaults to the fast-querystring package for zero-dependency parsing of flat key-value form data. For applications that need nested-object parsing (bracket notation like foo[one]=bar), it exposes a parser option so teams can swap in libraries like qs without forking the plugin. It also respects Fastify’s global or per-route bodyLimit setting, returning a 413 if the payload exceeds the configured limit, and ships as an actively maintained core plugin from the Fastify organization with first-class TypeScript typings.

What You Get

• Automatic parsing of application/x-www-form-urlencoded request bodies into request.body
• A configurable bodyLimit option that enforces payload size limits with proper 413 responses
• A pluggable parser function so you can swap in qs or any custom parser for nested-object support
• TypeScript type definitions for the plugin options out of the box

Common Use Cases

• Parsing traditional HTML <form> POST submissions in server-rendered Fastify apps
• Accepting webhook payloads sent as url-encoded strings by third-party services
• Replacing Express’s body-parser/express.urlencoded when migrating to Fastify
• Supporting nested/bracketed form fields via a custom qs-based parser

Under The Hood

Architecture The plugin is a single-file adapter (index.js, ~24 lines) wrapped with fastify-plugin (fp) so its content-type parser registers at the correct encapsulation scope no matter where it’s registered in a larger app. The exported function reads the options object, defaults parser to fast-querystring’s parse, validates that the configured parser is a function (surfacing an Error via Fastify’s next callback otherwise), and calls fastify.addContentTypeParser once for application/x-www-form-urlencoded with parseAs: ‘buffer’ and the configured bodyLimit. The contentParser callback converts the raw buffer to a string and delegates to the configured parser before invoking Fastify’s done callback. There is no additional internal layering; the single addContentTypeParser registration is the core abstraction, and removing it would mean the plugin no longer participates in Fastify’s body-parsing pipeline at all.

Tech Stack Plain CommonJS JavaScript with two runtime dependencies: fast-querystring for the default parser and fastify-plugin (v6) for correct plugin encapsulation. Fastify itself (v5) is a dev/peer dependency used only for testing. Tooling includes neostandard for ESLint-based linting, c8 with full coverage enforcement, Node’s built-in node:test runner, tstyche for TypeScript type-testing, and GitHub Actions CI running the full suite on every change. There is no build step; the plugin ships its CommonJS source directly alongside a hand-written types/index.d.ts.

Code Quality A single integration test file exercises the plugin through Fastify’s inject API, covering the default success path, body-limit enforcement (413 responses), and edge cases like stream-based payloads without a Content-Length header, all run under c8’s full coverage requirement. Error handling is explicit rather than swallowed: an invalid parser option surfaces as a real Error through Fastify’s plugin registration flow, and oversized payloads produce a proper HTTP 413 rather than a crash. Naming follows established Fastify plugin conventions, linting is enforced via neostandard, and comprehensive TypeScript definitions are verified with dedicated type tests despite the implementation itself being plain JavaScript.

API Design The public surface is a single fastify.register() call with exactly two options, so the common case requires zero configuration while an escape hatch (parser) remains available for advanced needs like nested-object parsing via qs. The README documents the upgrade path from pre-5.x behavior explicitly, including a worked example for restoring nested parsing, which keeps migration friction low. There’s no novel technical mechanism here, just a small, well-scoped adapter over an existing Fastify hook, but as a narrowly-scoped plugin its developer experience is close to ideal: minimal surface area, sensible defaults, and a clear extension point.