Registry / http-networking / urlencoded-body-parser

urlencoded-body-parser

JSON →
library3.0.0jsnpmunverified

urlencoded-body-parser is a minimalist JavaScript library designed for parsing `application/x-www-form-urlencoded` request bodies into JavaScript objects. It leverages the `qs` library internally for robust query string parsing. The current stable version is 3.0.0. The project maintains an irregular release cadence, with major versions typically introducing breaking API changes, such as the transition to a Promise-based API in v2.0.0. Its primary differentiator is its small footprint and straightforward, promise-returning API, making it suitable for lightweight HTTP servers and microservices, particularly those built with Node.js's `http` module or frameworks like Micro. It offers a `parse` function that takes an `http.IncomingMessage` and an optional `limit` parameter to prevent excessive memory usage, returning the parsed data as a Promise.

http-networkingweb-frameworkserialization
npm install urlencoded-body-parser
github ↗package ↗
INSTALL
IMPORT
SIG · URLENCODED-BODY-PA
U
urlencoded-body-parser
http-networkingjavascriptv3.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse
✓ const parse = require('urlencoded-body-parser');
✗ import { parse } from 'urlencoded-body-parser';
The library primarily exposes a CommonJS module. While it might be usable via `import parse from 'urlencoded-body-parser';` with certain bundler/Node.js configurations, `require` is the officially documented and most reliable method.
parse
✓ const { parse } = require('urlencoded-body-parser');
✗ import urlencodedBodyParser from 'urlencoded-body-parser';
The module exports a single default function, so destructuring it from `require` is technically incorrect but often works with transpilers. The primary export is the function itself.

Demonstrates setting up a basic Node.js HTTP server to parse `application/x-www-form-urlencoded` POST requests using `urlencoded-body-parser`, including error handling and body size limiting.

const http = require('http'); const parse = require('urlencoded-body-parser'); const server = http.createServer(async (req, res) => { if (req.method === 'POST' && req.headers['content-type'] === 'application/x-www-form-urlencoded') { try { const data = await parse(req, { limit: '10kb' }); // Limit body size to 10kb console.log('Parsed data:', data); res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ status: 'success', received: data })); } catch (error) { console.error('Error parsing body:', error); res.statusCode = 400; res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ status: 'error', message: error.message })); } } else { res.statusCode = 200; res.setHeader('Content-Type', 'text/plain'); res.end('Send a POST request with application/x-www-form-urlencoded body.'); } }); server.listen(8000, () => { console.log('Server listening on http://localhost:8000'); console.log('Try: curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "name=John+Doe&age=30" http://localhost:8000'); });
Debug
Known issues
breakingVersion 2.0.0 removed the callback-based API. The `parse` function now exclusively returns a Promise. Calls expecting a callback argument will no longer work.
fix
Update all calls to `parse(req)` to use `await parse(req)` or `parse(req).then(data => ...)` to handle the returned Promise.
affects: >=2.0.0
gotchaFailing to await the Promise returned by `parse()` will result in variables holding a Promise object instead of the parsed data, leading to unexpected behavior or `UnhandledPromiseRejectionWarning`.
fix
Always use `await parse(req)` inside an `async` function or `parse(req).then(...)` to correctly resolve the Promise and access the parsed data.
affects: >=2.0.0
gotchaThe `limit` option defaults to '1mb'. Large payloads exceeding this limit will cause the Promise to reject with an error, potentially leading to a 400 Bad Request status if not handled.
fix
Configure the `limit` option (e.g., `parse(req, { limit: '5mb' })`) if you expect larger payloads, or ensure proper error handling for payload too large errors.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: parse(...).then is not a function
Attempting to use a callback API with `urlencoded-body-parser` v2.0.0 or higher.
fix
The `parse` function in versions >=2.0.0 returns a Promise. Change your code to `await parse(req)` or `parse(req).then(data => ...)`.
UnhandledPromiseRejectionWarning: Promise { <pending> }
The Promise returned by `parse(req)` was not `await`ed or chained with `.then()`, so the application tried to use the Promise object directly.
fix
Ensure that you `await parse(req)` in an `async` function or handle the Promise resolution using `.then()` and `.catch()`.
Error: request entity too large
The incoming request body exceeded the configured `limit` (defaulting to '1mb').
fix
Increase the `limit` option in `parse(req, { limit: '2mb' })` or handle the error gracefully, returning an appropriate HTTP status like 413 Payload Too Large.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies
qsrequiredUsed internally for parsing the URL-encoded data.
Agent activity
12 hits · last 30 days
node
10
Amazon
1
OpenAI (training)
1
Resources
githubhttps://github.com/timneutkens/urlencoded-body-parser ↗
packagehttps://www.npmjs.com/package/urlencoded-body-parser ↗
urlencoded-body-parser — npm install urlencoded-body-parser · libregistry