3 [![NPM Version][npm-image]][npm-url]
4 [![NPM Downloads][downloads-image]][downloads-url]
5 [![Build Status][travis-image]][travis-url]
6 [![Test Coverage][coveralls-image]][coveralls-url]
7 [![Gratipay][gratipay-image]][gratipay-url]
9 Node.js body parsing middleware.
11 _This does not handle multipart bodies_, due to their complex and typically
12 large nature. For multipart bodies, you may be interested in the following
15 * [busboy](https://www.npmjs.org/package/busboy#readme) and
16 [connect-busboy](https://www.npmjs.org/package/connect-busboy#readme)
17 * [multiparty](https://www.npmjs.org/package/multiparty#readme) and
18 [connect-multiparty](https://www.npmjs.org/package/connect-multiparty#readme)
19 * [formidable](https://www.npmjs.org/package/formidable#readme)
20 * [multer](https://www.npmjs.org/package/multer#readme)
22 This module provides the following parsers:
24 * [JSON body parser](#bodyparserjsonoptions)
25 * [Raw body parser](#bodyparserrawoptions)
26 * [Text body parser](#bodyparsertextoptions)
27 * [URL-encoded form body parser](#bodyparserurlencodedoptions)
29 Other body parsers you might be interested in:
31 - [body](https://www.npmjs.org/package/body#readme)
32 - [co-body](https://www.npmjs.org/package/co-body#readme)
37 $ npm install body-parser
43 var bodyParser = require('body-parser')
46 The `bodyParser` object exposes various factories to create middlewares. All
47 middlewares will populate the `req.body` property with the parsed body, or an
48 empty object (`{}`) if there was no body to parse (or an error was returned).
50 The various errors returned by this module are described in the
51 [errors section](#errors).
53 ### bodyParser.json(options)
55 Returns middleware that only parses `json`. This parser accepts any Unicode
56 encoding of the body and supports automatic inflation of `gzip` and `deflate`
59 A new `body` object containing the parsed data is populated on the `request`
60 object after the middleware (i.e. `req.body`).
64 The `json` function takes an option `options` object that may contain any of
69 When set to `true`, then deflated (compressed) bodies will be inflated; when
70 `false`, deflated bodies are rejected. Defaults to `true`.
74 Controls the maximum request body size. If this is a number, then the value
75 specifies the number of bytes; if it is a string, the value is passed to the
76 [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
81 The `reviver` option is passed directly to `JSON.parse` as the second
82 argument. You can find more information on this argument
83 [in the MDN documentation about JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#Example.3A_Using_the_reviver_parameter).
87 When set to `true`, will only accept arrays and objects; when `false` will
88 accept anything `JSON.parse` accepts. Defaults to `true`.
92 The `type` option is used to determine what media type the middleware will
93 parse. This option can be a function or a string. If a string, `type` option
94 is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme)
95 library and this can be an extension name (like `json`), a mime type (like
96 `application/json`), or a mime type with a wildcard (like `*/*` or `*/json`).
97 If a function, the `type` option is called as `fn(req)` and the request is
98 parsed if it returns a truthy value. Defaults to `application/json`.
102 The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
103 where `buf` is a `Buffer` of the raw request body and `encoding` is the
104 encoding of the request. The parsing can be aborted by throwing an error.
106 ### bodyParser.raw(options)
108 Returns middleware that parses all bodies as a `Buffer`. This parser
109 supports automatic inflation of `gzip` and `deflate` encodings.
111 A new `body` object containing the parsed data is populated on the `request`
112 object after the middleware (i.e. `req.body`). This will be a `Buffer` object
117 The `raw` function takes an option `options` object that may contain any of
122 When set to `true`, then deflated (compressed) bodies will be inflated; when
123 `false`, deflated bodies are rejected. Defaults to `true`.
127 Controls the maximum request body size. If this is a number, then the value
128 specifies the number of bytes; if it is a string, the value is passed to the
129 [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
134 The `type` option is used to determine what media type the middleware will
135 parse. This option can be a function or a string. If a string, `type` option
136 is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme)
137 library and this can be an extension name (like `bin`), a mime type (like
138 `application/octet-stream`), or a mime type with a wildcard (like `*/*` or
139 `application/*`). If a function, the `type` option is called as `fn(req)`
140 and the request is parsed if it returns a truthy value. Defaults to
141 `application/octet-stream`.
145 The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
146 where `buf` is a `Buffer` of the raw request body and `encoding` is the
147 encoding of the request. The parsing can be aborted by throwing an error.
149 ### bodyParser.text(options)
151 Returns middleware that parses all bodies as a string. This parser supports
152 automatic inflation of `gzip` and `deflate` encodings.
154 A new `body` string containing the parsed data is populated on the `request`
155 object after the middleware (i.e. `req.body`). This will be a string of the
160 The `text` function takes an option `options` object that may contain any of
165 Specify the default character set for the text content if the charset is not
166 specified in the `Content-Type` header of the request. Defaults to `utf-8`.
170 When set to `true`, then deflated (compressed) bodies will be inflated; when
171 `false`, deflated bodies are rejected. Defaults to `true`.
175 Controls the maximum request body size. If this is a number, then the value
176 specifies the number of bytes; if it is a string, the value is passed to the
177 [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
182 The `type` option is used to determine what media type the middleware will
183 parse. This option can be a function or a string. If a string, `type` option
184 is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme)
185 library and this can be an extension name (like `txt`), a mime type (like
186 `text/plain`), or a mime type with a wildcard (like `*/*` or `text/*`).
187 If a function, the `type` option is called as `fn(req)` and the request is
188 parsed if it returns a truthy value. Defaults to `text/plain`.
192 The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
193 where `buf` is a `Buffer` of the raw request body and `encoding` is the
194 encoding of the request. The parsing can be aborted by throwing an error.
196 ### bodyParser.urlencoded(options)
198 Returns middleware that only parses `urlencoded` bodies. This parser accepts
199 only UTF-8 encoding of the body and supports automatic inflation of `gzip`
200 and `deflate` encodings.
202 A new `body` object containing the parsed data is populated on the `request`
203 object after the middleware (i.e. `req.body`). This object will contain
204 key-value pairs, where the value can be a string or array (when `extended` is
205 `false`), or any type (when `extended` is `true`).
209 The `urlencoded` function takes an option `options` object that may contain
210 any of the following keys:
214 The `extended` option allows to choose between parsing the URL-encoded data
215 with the `querystring` library (when `false`) or the `qs` library (when
216 `true`). The "extended" syntax allows for rich objects and arrays to be
217 encoded into the URL-encoded format, allowing for a JSON-like experience
218 with URL-encoded. For more information, please
219 [see the qs library](https://www.npmjs.org/package/qs#readme).
221 Defaults to `true`, but using the default has been deprecated. Please
222 research into the difference between `qs` and `querystring` and choose the
227 When set to `true`, then deflated (compressed) bodies will be inflated; when
228 `false`, deflated bodies are rejected. Defaults to `true`.
232 Controls the maximum request body size. If this is a number, then the value
233 specifies the number of bytes; if it is a string, the value is passed to the
234 [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
239 The `parameterLimit` option controls the maximum number of parameters that
240 are allowed in the URL-encoded data. If a request contains more parameters
241 than this value, a 413 will be returned to the client. Defaults to `1000`.
245 The `type` option is used to determine what media type the middleware will
246 parse. This option can be a function or a string. If a string, `type` option
247 is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme)
248 library and this can be an extension name (like `urlencoded`), a mime type (like
249 `application/x-www-form-urlencoded`), or a mime type with a wildcard (like
250 `*/x-www-form-urlencoded`). If a function, the `type` option is called as
251 `fn(req)` and the request is parsed if it returns a truthy value. Defaults
252 to `application/x-www-form-urlencoded`.
256 The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
257 where `buf` is a `Buffer` of the raw request body and `encoding` is the
258 encoding of the request. The parsing can be aborted by throwing an error.
262 The middlewares provided by this module create errors depending on the error
263 condition during parsing. The errors will typically have a `status` property
264 that contains the suggested HTTP response code.
266 The following are the common errors emitted, though any error can come through
269 ### content encoding unsupported
271 This error will occur when the request had a `Content-Encoding` header that
272 contained an encoding but the "inflation" option was set to `false`. The
273 `status` property is set to `415`.
277 This error will occur when the request is aborted by the client before reading
278 the body has finished. The `received` property will be set to the number of
279 bytes received before the request was aborted and the `expected` property is
280 set to the number of expected bytes. The `status` property is set to `400`.
282 ### request entity too large
284 This error will occur when the request body's size is larger than the "limit"
285 option. The `limit` property will be set to the byte limit and the `length`
286 property will be set to the request body's length. The `status` property is
289 ### request size did not match content length
291 This error will occur when the request's length did not match the length from
292 the `Content-Length` header. This typically occurs when the request is malformed,
293 typically when the `Content-Length` header was calculated based on characters
294 instead of bytes. The `status` property is set to `400`.
296 ### stream encoding should not be set
298 This error will occur when something called the `req.setEncoding` method prior
299 to this middleware. This module operates directly on bytes only and you cannot
300 call `req.setEncoding` when using this module. The `status` property is set to
303 ### unsupported charset "BOGUS"
305 This error will occur when the request had a charset parameter in the
306 `Content-Type` header, but the `iconv-lite` module does not support it OR the
307 parser does not support it. The charset is contained in the message as well
308 as in the `charset` property. The `status` property is set to `415`.
310 ### unsupported content encoding "bogus"
312 This error will occur when the request had a `Content-Encoding` header that
313 contained an unsupported encoding. The encoding is contained in the message
314 as well as in the `encoding` property. The `status` property is set to `415`.
318 ### express/connect top-level generic
320 This example demonstrates adding a generic JSON and URL-encoded parser as a
321 top-level middleware, which will parse the bodies of all incoming requests.
322 This is the simplest setup.
325 var express = require('express')
326 var bodyParser = require('body-parser')
330 // parse application/x-www-form-urlencoded
331 app.use(bodyParser.urlencoded({ extended: false }))
333 // parse application/json
334 app.use(bodyParser.json())
336 app.use(function (req, res) {
337 res.setHeader('Content-Type', 'text/plain')
338 res.write('you posted:\n')
339 res.end(JSON.stringify(req.body, null, 2))
343 ### express route-specific
345 This example demonstrates adding body parsers specifically to the routes that
346 need them. In general, this is the most recommend way to use body-parser with
350 var express = require('express')
351 var bodyParser = require('body-parser')
355 // create application/json parser
356 var jsonParser = bodyParser.json()
358 // create application/x-www-form-urlencoded parser
359 var urlencodedParser = bodyParser.urlencoded({ extended: false })
361 // POST /login gets urlencoded bodies
362 app.post('/login', urlencodedParser, function (req, res) {
363 if (!req.body) return res.sendStatus(400)
364 res.send('welcome, ' + req.body.username)
367 // POST /api/users gets JSON bodies
368 app.post('/api/users', jsonParser, function (req, res) {
369 if (!req.body) return res.sendStatus(400)
370 // create user in req.body
374 ### change content-type for parsers
376 All the parsers accept a `type` option which allows you to change the
377 `Content-Type` that the middleware will parse.
380 // parse various different custom JSON types as JSON
381 app.use(bodyParser.json({ type: 'application/*+json' }))
383 // parse some custom thing into a Buffer
384 app.use(bodyParser.raw({ type: 'application/vnd.custom-type' }))
386 // parse an HTML body into a string
387 app.use(bodyParser.text({ type: 'text/html' }))
394 [npm-image]: https://img.shields.io/npm/v/body-parser.svg
395 [npm-url]: https://npmjs.org/package/body-parser
396 [travis-image]: https://img.shields.io/travis/expressjs/body-parser/master.svg
397 [travis-url]: https://travis-ci.org/expressjs/body-parser
398 [coveralls-image]: https://img.shields.io/coveralls/expressjs/body-parser/master.svg
399 [coveralls-url]: https://coveralls.io/r/expressjs/body-parser?branch=master
400 [downloads-image]: https://img.shields.io/npm/dm/body-parser.svg
401 [downloads-url]: https://npmjs.org/package/body-parser
402 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
403 [gratipay-url]: https://www.gratipay.com/dougwilson/