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
48 provide an error to the callback. The various errors are described in the
49 [errors section](#errors).
51 ### bodyParser.json(options)
53 Returns middleware that only parses `json`. This parser accepts any Unicode
54 encoding of the body and supports automatic inflation of `gzip` and `deflate`
57 A new `body` object containing the parsed data is populated on the `request`
58 object after the middleware (i.e. `req.body`).
62 The `json` function takes an option `options` object that may contain any of
67 When set to `true`, then deflated (compressed) bodies will be inflated; when
68 `false`, deflated bodies are rejected. Defaults to `true`.
72 Controls the maximum request body size. If this is a number, then the value
73 specifies the number of bytes; if it is a string, the value is passed to the
74 [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
79 The `reviver` option is passed directly to `JSON.parse` as the second
80 argument. You can find more information on this argument
81 [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).
85 When set to `true`, will only accept arrays and objects; when `false` will
86 accept anything `JSON.parse` accepts. Defaults to `true`.
90 The `type` option is used to determine what media type the middleware will
91 parse. This option can be a function or a string. If a string, `type` option
92 is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme)
93 library and this can be an extension name (like `json`), a mime type (like
94 `application/json`), or a mime type with a wildcard (like `*/*` or `*/json`).
95 If a function, the `type` option is called as `fn(req)` and the request is
96 parsed if it returns a truthy value. Defaults to `application/json`.
100 The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
101 where `buf` is a `Buffer` of the raw request body and `encoding` is the
102 encoding of the request. The parsing can be aborted by throwing an error.
104 ### bodyParser.raw(options)
106 Returns middleware that parses all bodies as a `Buffer`. This parser
107 supports automatic inflation of `gzip` and `deflate` encodings.
109 A new `body` object containing the parsed data is populated on the `request`
110 object after the middleware (i.e. `req.body`). This will be a `Buffer` object
115 The `raw` function takes an option `options` object that may contain any of
120 When set to `true`, then deflated (compressed) bodies will be inflated; when
121 `false`, deflated bodies are rejected. Defaults to `true`.
125 Controls the maximum request body size. If this is a number, then the value
126 specifies the number of bytes; if it is a string, the value is passed to the
127 [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
132 The `type` option is used to determine what media type the middleware will
133 parse. This option can be a function or a string. If a string, `type` option
134 is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme)
135 library and this can be an extension name (like `bin`), a mime type (like
136 `application/octet-stream`), or a mime type with a wildcard (like `*/*` or
137 `application/*`). If a function, the `type` option is called as `fn(req)`
138 and the request is parsed if it returns a truthy value. Defaults to
139 `application/octet-stream`.
143 The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
144 where `buf` is a `Buffer` of the raw request body and `encoding` is the
145 encoding of the request. The parsing can be aborted by throwing an error.
147 ### bodyParser.text(options)
149 Returns middleware that parses all bodies as a string. This parser supports
150 automatic inflation of `gzip` and `deflate` encodings.
152 A new `body` string containing the parsed data is populated on the `request`
153 object after the middleware (i.e. `req.body`). This will be a string of the
158 The `text` function takes an option `options` object that may contain any of
163 Specify the default character set for the text content if the charset is not
164 specified in the `Content-Type` header of the request. Defaults to `utf-8`.
168 When set to `true`, then deflated (compressed) bodies will be inflated; when
169 `false`, deflated bodies are rejected. Defaults to `true`.
173 Controls the maximum request body size. If this is a number, then the value
174 specifies the number of bytes; if it is a string, the value is passed to the
175 [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
180 The `type` option is used to determine what media type the middleware will
181 parse. This option can be a function or a string. If a string, `type` option
182 is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme)
183 library and this can be an extension name (like `txt`), a mime type (like
184 `text/plain`), or a mime type with a wildcard (like `*/*` or `text/*`).
185 If a function, the `type` option is called as `fn(req)` and the request is
186 parsed if it returns a truthy value. Defaults to `text/plain`.
190 The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
191 where `buf` is a `Buffer` of the raw request body and `encoding` is the
192 encoding of the request. The parsing can be aborted by throwing an error.
194 ### bodyParser.urlencoded(options)
196 Returns middleware that only parses `urlencoded` bodies. This parser accepts
197 only UTF-8 encoding of the body and supports automatic inflation of `gzip`
198 and `deflate` encodings.
200 A new `body` object containing the parsed data is populated on the `request`
201 object after the middleware (i.e. `req.body`). This object will contain
202 key-value pairs, where the value can be a string or array (when `extended` is
203 `false`), or any type (when `extended` is `true`).
207 The `urlencoded` function takes an option `options` object that may contain
208 any of the following keys:
212 The `extended` option allows to choose between parsing the URL-encoded data
213 with the `querystring` library (when `false`) or the `qs` library (when
214 `true`). The "extended" syntax allows for rich objects and arrays to be
215 encoded into the URL-encoded format, allowing for a JSON-like experience
216 with URL-encoded. For more information, please
217 [see the qs library](https://www.npmjs.org/package/qs#readme).
219 Defaults to `true`, but using the default has been deprecated. Please
220 research into the difference between `qs` and `querystring` and choose the
225 When set to `true`, then deflated (compressed) bodies will be inflated; when
226 `false`, deflated bodies are rejected. Defaults to `true`.
230 Controls the maximum request body size. If this is a number, then the value
231 specifies the number of bytes; if it is a string, the value is passed to the
232 [bytes](https://www.npmjs.com/package/bytes) library for parsing. Defaults
237 The `parameterLimit` option controls the maximum number of parameters that
238 are allowed in the URL-encoded data. If a request contains more parameters
239 than this value, a 413 will be returned to the client. Defaults to `1000`.
243 The `type` option is used to determine what media type the middleware will
244 parse. This option can be a function or a string. If a string, `type` option
245 is passed directly to the [type-is](https://www.npmjs.org/package/type-is#readme)
246 library and this can be an extension name (like `urlencoded`), a mime type (like
247 `application/x-www-form-urlencoded`), or a mime type with a wildcard (like
248 `*/x-www-form-urlencoded`). If a function, the `type` option is called as
249 `fn(req)` and the request is parsed if it returns a truthy value. Defaults
250 to `application/x-www-form-urlencoded`.
254 The `verify` option, if supplied, is called as `verify(req, res, buf, encoding)`,
255 where `buf` is a `Buffer` of the raw request body and `encoding` is the
256 encoding of the request. The parsing can be aborted by throwing an error.
260 The middlewares provided by this module create errors depending on the error
261 condition during parsing. The errors will typically have a `status` property
262 that contains the suggested HTTP response code.
264 The following are the common errors emitted, though any error can come through
267 ### content encoding unsupported
269 This error will occur when the request had a `Content-Encoding` header that
270 contained an encoding but the "inflation" option was set to `false`. The
271 `status` property is set to `415`.
275 This error will occur when the request is aborted by the client before reading
276 the body has finished. The `received` property will be set to the number of
277 bytes received before the request was aborted and the `expected` property is
278 set to the number of expected bytes. The `status` property is set to `400`.
280 ### request entity too large
282 This error will occur when the request body's size is larger than the "limit"
283 option. The `limit` property will be set to the byte limit and the `length`
284 property will be set to the request body's length. The `status` property is
287 ### request size did not match content length
289 This error will occur when the request's length did not match the length from
290 the `Content-Length` header. This typically occurs when the requst is malformed,
291 typically when the `Content-Length` header was calculated based on characters
292 instead of bytes. The `status` property is set to `400`.
294 ### stream encoding should not be set
296 This error will occur when something called the `req.setEncoding` method prior
297 to this middleware. This module operates directly on bytes only and you cannot
298 call `req.setEncoding` when using this module. The `status` property is set to
301 ### unsupported charset "BOGUS"
303 This error will occur when the request had a charset parameter in the
304 `Content-Type` header, but the `iconv-lite` module does not support it OR the
305 parser does not support it. The charset is contained in the message as well
306 as in the `charset` property. The `status` property is set to `415`.
308 ### unsupported content encoding "bogus"
310 This error will occur when the request had a `Content-Encoding` header that
311 contained an unsupported encoding. The encoding is contained in the message
312 as well as in the `encoding` property. The `status` property is set to `415`.
316 ### express/connect top-level generic
318 This example demonstrates adding a generic JSON and URL-encoded parser as a
319 top-level middleware, which will parse the bodies of all incoming requests.
320 This is the simplest setup.
323 var express = require('express')
324 var bodyParser = require('body-parser')
328 // parse application/x-www-form-urlencoded
329 app.use(bodyParser.urlencoded({ extended: false }))
331 // parse application/json
332 app.use(bodyParser.json())
334 app.use(function (req, res) {
335 res.setHeader('Content-Type', 'text/plain')
336 res.write('you posted:\n')
337 res.end(JSON.stringify(req.body, null, 2))
341 ### express route-specific
343 This example demonstrates adding body parsers specifically to the routes that
344 need them. In general, this is the most recommend way to use body-parser with
348 var express = require('express')
349 var bodyParser = require('body-parser')
353 // create application/json parser
354 var jsonParser = bodyParser.json()
356 // create application/x-www-form-urlencoded parser
357 var urlencodedParser = bodyParser.urlencoded({ extended: false })
359 // POST /login gets urlencoded bodies
360 app.post('/login', urlencodedParser, function (req, res) {
361 if (!req.body) return res.sendStatus(400)
362 res.send('welcome, ' + req.body.username)
365 // POST /api/users gets JSON bodies
366 app.post('/api/users', jsonParser, function (req, res) {
367 if (!req.body) return res.sendStatus(400)
368 // create user in req.body
372 ### change content-type for parsers
374 All the parsers accept a `type` option which allows you to change the
375 `Content-Type` that the middleware will parse.
378 // parse various different custom JSON types as JSON
379 app.use(bodyParser.json({ type: 'application/*+json' }))
381 // parse some custom thing into a Buffer
382 app.use(bodyParser.raw({ type: 'application/vnd.custom-type' }))
384 // parse an HTML body into a string
385 app.use(bodyParser.text({ type: 'text/html' }))
392 [npm-image]: https://img.shields.io/npm/v/body-parser.svg
393 [npm-url]: https://npmjs.org/package/body-parser
394 [travis-image]: https://img.shields.io/travis/expressjs/body-parser/master.svg
395 [travis-url]: https://travis-ci.org/expressjs/body-parser
396 [coveralls-image]: https://img.shields.io/coveralls/expressjs/body-parser/master.svg
397 [coveralls-url]: https://coveralls.io/r/expressjs/body-parser?branch=master
398 [downloads-image]: https://img.shields.io/npm/dm/body-parser.svg
399 [downloads-url]: https://npmjs.org/package/body-parser
400 [gratipay-image]: https://img.shields.io/gratipay/dougwilson.svg
401 [gratipay-url]: https://www.gratipay.com/dougwilson/