{"id":14211,"library":"urlencoded-body-parser","title":"URL-Encoded Body Parser","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/timneutkens/urlencoded-body-parser","tags":["javascript"],"install":[{"cmd":"npm install urlencoded-body-parser","lang":"bash","label":"npm"},{"cmd":"yarn add urlencoded-body-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add urlencoded-body-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for parsing the URL-encoded data.","package":"qs","optional":false}],"imports":[{"note":"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.","wrong":"import { parse } from 'urlencoded-body-parser';","symbol":"parse","correct":"const parse = require('urlencoded-body-parser');"},{"note":"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.","wrong":"import urlencodedBodyParser from 'urlencoded-body-parser';","symbol":"parse","correct":"const { parse } = require('urlencoded-body-parser');"}],"quickstart":{"code":"const http = require('http');\nconst parse = require('urlencoded-body-parser');\n\nconst server = http.createServer(async (req, res) => {\n  if (req.method === 'POST' && req.headers['content-type'] === 'application/x-www-form-urlencoded') {\n    try {\n      const data = await parse(req, { limit: '10kb' }); // Limit body size to 10kb\n      console.log('Parsed data:', data);\n      res.setHeader('Content-Type', 'application/json');\n      res.end(JSON.stringify({ status: 'success', received: data }));\n    } catch (error) {\n      console.error('Error parsing body:', error);\n      res.statusCode = 400;\n      res.setHeader('Content-Type', 'application/json');\n      res.end(JSON.stringify({ status: 'error', message: error.message }));\n    }\n  } else {\n    res.statusCode = 200;\n    res.setHeader('Content-Type', 'text/plain');\n    res.end('Send a POST request with application/x-www-form-urlencoded body.');\n  }\n});\n\nserver.listen(8000, () => {\n  console.log('Server listening on http://localhost:8000');\n  console.log('Try: curl -X POST -H \"Content-Type: application/x-www-form-urlencoded\" -d \"name=John+Doe&age=30\" http://localhost:8000');\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Update all calls to `parse(req)` to use `await parse(req)` or `parse(req).then(data => ...)` to handle the returned Promise.","message":"Version 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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always use `await parse(req)` inside an `async` function or `parse(req).then(...)` to correctly resolve the Promise and access the parsed data.","message":"Failing 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`.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'3.0.0':40 'api':54,65,80 'application/x-www-form-urlencoded':18 'base':64 'bodi':4,8,20 'break':53 'built':92 'cadenc':47 'chang':55 'current':36 'data':124 'design':15 'differenti':70 'encod':3 'excess':118 'footprint':74 'framework':99 'function':106 'http':86,96 'http.incomingmessage':110 'intern':29 'introduc':52 'irregular':45 'javascript':13,22,128 'leverag':25 'librari':14,28 'lightweight':85 'like':100 'limit':114 'maintain':43 'major':49 'make':81 'memori':119 'micro':101 'microservic':89 'minimalist':12 'modul':97 'node.js':94 'object':23 'offer':103 'option':113 'paramet':115 'pars':17,34,105,123 'parser':5,9 'particular':90 'prevent':117 'primari':69 'project':42 'promis':63,78,127 'promise-bas':62 'promise-return':77 'qs':27 'queri':32 'releas':46 'request':19 'return':79,121 'robust':31 'server':87 'small':73 'stabl':37 'straightforward':76 'string':33 'suitabl':83 'take':108 'transit':59 'typic':51 'url':2 'url-encod':1 'urlencod':7 'urlencoded-body-pars':6 'usag':120 'v2.0.0':67 'version':38,50","created_at":"2026-04-20T01:58:30.916644+00:00","updated_at":"2026-04-20T01:58:30.916644+00:00","problems":[{"fix":"The `parse` function in versions >=2.0.0 returns a Promise. Change your code to `await parse(req)` or `parse(req).then(data => ...)`.","cause":"Attempting to use a callback API with `urlencoded-body-parser` v2.0.0 or higher.","error":"TypeError: parse(...).then is not a function"},{"fix":"Ensure that you `await parse(req)` in an `async` function or handle the Promise resolution using `.then()` and `.catch()`.","cause":"The Promise returned by `parse(req)` was not `await`ed or chained with `.then()`, so the application tried to use the Promise object directly.","error":"UnhandledPromiseRejectionWarning: Promise { <pending> }"},{"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.","cause":"The incoming request body exceeded the configured `limit` (defaulting to '1mb').","error":"Error: request entity too large"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/timneutkens/urlencoded-body-parser","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/urlencoded-body-parser","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}