# cookie-parser

> Parse HTTP request cookies

Latest version **1.4.7** (published 2024-10-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install cookie-parser
pnpm add cookie-parser
yarn add cookie-parser
bun add cookie-parser
```

## Health

**Score 43/100 (D)** — status: stable.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.4.7 |
| Published | 2024-10-08 |
| First published | 2014-02-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/cookie-parser) |
| Module format | CommonJS |
| Node | >= 0.8.0 |
| Dependencies | 2 |
| Unpacked size | 12.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2030 |
| Author | TJ Holowaychuk |
| Maintainers | ulisesgascon, dougwilson, defunctzombie |
| Keywords | cookie, middleware |

## Links

- npm: https://www.npmjs.com/package/cookie-parser
- Repository: https://github.com/expressjs/cookie-parser
- Homepage: https://github.com/expressjs/cookie-parser#readme
- Issues: https://github.com/expressjs/cookie-parser/issues
- npm.io page: https://npm.io/package/cookie-parser

## Dependencies (2)

- [cookie](https://npm.io/package/cookie.md) 0.7.2
- [cookie-signature](https://npm.io/package/cookie-signature.md) 1.0.6

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 1.4.7 (latest) — 2024-10-08
- 1.4.6 — 2021-11-16
- 1.4.5 — 2020-03-15
- 1.4.4 — 2019-02-13
- 1.4.3 — 2016-05-27
- 1.4.2 — 2016-05-21
- 1.4.1 — 2016-01-11
- 1.4.0 — 2015-09-18
- 1.3.5 — 2015-05-20
- 1.3.4 — 2015-02-15
- 1.3.3 — 2014-09-06
- 1.3.2 — 2014-06-26
- 1.3.1 — 2014-06-18
- 1.3.0 — 2014-06-18
- 1.2.0 — 2014-06-18
- … 3 more at https://npm.io/package/cookie-parser/versions

## README

# cookie-parser

[![NPM Version][npm-version-image]][npm-url]
[![NPM Downloads][npm-downloads-image]][npm-url]
[![Build Status][ci-image]][ci-url]
[![Test Coverage][coveralls-image]][coveralls-url]

Parse `Cookie` header and populate `req.cookies` with an object keyed by the
cookie names. Optionally you may enable signed cookie support by passing a
`secret` string, which assigns `req.secret` so it may be used by other
middleware.

## Installation

```sh
$ npm install cookie-parser
```

## API

```js
var cookieParser = require('cookie-parser')
```

### cookieParser(secret, options)

Create a new cookie parser middleware function using the given `secret` and
`options`.

- `secret` a string or array used for signing cookies. This is optional and if
  not specified, will not parse signed cookies. If a string is provided, this
  is used as the secret. If an array is provided, an attempt will be made to
  unsign the cookie with each secret in order.
- `options` an object that is passed to `cookie.parse` as the second option. See
  [cookie](https://www.npmjs.org/package/cookie) for more information.
  - `decode` a function to decode the value of the cookie

The middleware will parse the `Cookie` header on the request and expose the
cookie data as the property `req.cookies` and, if a `secret` was provided, as
the property `req.signedCookies`. These properties are name value pairs of the
cookie name to cookie value.

When `secret` is provided, this module will unsign and validate any signed cookie
values and move those name value pairs from `req.cookies` into `req.signedCookies`.
A signed cookie is a cookie that has a value prefixed with `s:`. Signed cookies
that fail signature validation will have the value `false` instead of the tampered
value.

In addition, this module supports special "JSON cookies". These are cookie where
the value is prefixed with `j:`. When these values are encountered, the value will
be exposed as the result of `JSON.parse`. If parsing fails, the original value will
remain.

### cookieParser.JSONCookie(str)

Parse a cookie value as a JSON cookie. This will return the parsed JSON value
if it was a JSON cookie, otherwise, it will return the passed value.

### cookieParser.JSONCookies(cookies)

Given an object, this will iterate over the keys and call `JSONCookie` on each
value, replacing the original value with the parsed value. This returns the
same object that was passed in.

### cookieParser.signedCookie(str, secret)

Parse a cookie value as a signed cookie. This will return the parsed unsigned
value if it was a signed cookie and the signature was valid. If the value was
not signed, the original value is returned. If the value was signed but the
signature could not be validated, `false` is returned.

The `secret` argument can be an array or string. If a string is provided, this
is used as the secret. If an array is provided, an attempt will be made to
unsign the cookie with each secret in order.

### cookieParser.signedCookies(cookies, secret)

Given an object, this will iterate over the keys and check if any value is a
signed cookie. If it is a signed cookie and the signature is valid, the key
will be deleted from the object and added to the new object that is returned.

The `secret` argument can be an array or string. If a string is provided, this
is used as the secret. If an array is provided, an attempt will be made to
unsign the cookie with each secret in order.

## Example

```js
var express = require('express')
var cookieParser = require('cookie-parser')

var app = express()
app.use(cookieParser())

app.get('/', function (req, res) {
  // Cookies that have not been signed
  console.log('Cookies: ', req.cookies)

  // Cookies that have been signed
  console.log('Signed Cookies: ', req.signedCookies)
})

app.listen(8080)

// curl command that sends an HTTP request with two cookies
// curl http://127.0.0.1:8080 --cookie "Cho=Kim;Greet=Hello"
```

## License

[MIT](LICENSE)

[ci-image]: https://badgen.net/github/checks/expressjs/cookie-parser/master?label=ci
[ci-url]: https://github.com/expressjs/cookie-parser/actions?query=workflow%3Aci
[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/cookie-parser/master
[coveralls-url]: https://coveralls.io/r/expressjs/cookie-parser?branch=master
[npm-downloads-image]: https://badgen.net/npm/dm/cookie-parser
[npm-url]: https://npmjs.org/package/cookie-parser
[npm-version-image]: https://badgen.net/npm/v/cookie-parser

---
_Source: https://npm.io/package/cookie-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._