Registry / web-framework / cookie-parser

cookie-parser

JSON →
library1.4.7jsnpmunverified

`cookie-parser` is an Express.js middleware designed to parse HTTP request cookies, making their values easily accessible through `req.cookies` and `req.signedCookies` properties. The current stable version is 1.4.7, indicating a mature and stable codebase with infrequent but consistent releases primarily focused on dependency updates to ensure compatibility and performance. A key differentiating feature is its robust support for both signed cookies, which helps mitigate tampering, and "JSON cookies," which automatically deserialize JSON-prefixed cookie values. This package provides an essential and convenient layer for web applications built with Express that need to interact with client-side cookies, offering a structured approach to cookie management and enhanced security through optional signing capabilities. It does not handle setting cookies, which is typically done via `res.cookie()` in Express.

web-frameworkauth-securityserialization
npm install cookie-parser
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · COOKIE-PARSER
C
cookie-parser
web-frameworkjavascriptv1.4.7
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.

cookieParser
✓ const cookieParser = require('cookie-parser')
✗ import cookieParser from 'cookie-parser'
This package is a CommonJS module. Use `require` for Node.js applications.
cookieParser.signedCookie
✓ const { signedCookie } = require('cookie-parser'); // or cookieParser.signedCookie
✗ import { signedCookie } from 'cookie-parser'
Static methods are accessed via the main `cookieParser` export in CommonJS.
cookieParser.JSONCookie
✓ const { JSONCookie } = require('cookie-parser'); // or cookieParser.JSONCookie
✗ import { JSONCookie } from 'cookie-parser'
Static methods are available on the `cookieParser` function itself; destructuring `require` is also possible.

Demonstrates initializing `cookie-parser` with a secret, accessing `req.cookies` and `req.signedCookies`, and setting various types of cookies.

const express = require('express'); const cookieParser = require('cookie-parser'); const app = express(); const PORT = 3000; const SECRET_KEY = process.env.COOKIE_SECRET || 'my-secret-key-for-signing'; app.use(cookieParser(SECRET_KEY)); app.get('/', (req, res) => { // Access raw and signed cookies from the request console.log('Raw Cookies:', req.cookies); console.log('Signed Cookies:', req.signedCookies); // Example of setting a regular and a signed cookie res.cookie('regular', 'hello world', { maxAge: 900000, httpOnly: true }); res.cookie('signed', 'secret message', { maxAge: 900000, httpOnly: true, signed: true }); res.cookie('json_data', 'j:{"user":"test"}', { maxAge: 900000, httpOnly: true }); res.send('Check your console for cookie logs and browser for new cookies!\n' + 'Send a request with cookies like: curl http://localhost:3000 --cookie "Cho=Kim;Greet=Hello;signed=s%3Asecret%20message.hS7...;json_data=j%3A%7B%22user%22%3A%22test%22%7D"'); }); app.listen(PORT, () => { console.log(`Server running on http://localhost:${PORT}`); console.log('Remember to restart the server if you change COOKIE_SECRET environment variable.'); });
Debug
Known issues
gotchaIf `cookie-parser` is initialized without a `secret` string or array, it will not parse or expose signed cookies. `req.signedCookies` will remain an empty object, even if signed cookies are present in the request.
fix
Provide a strong, unique `secret` string (or an array of secrets) when initializing `cookieParser` middleware: `app.use(cookieParser('your-strong-secret-here'))`.
affects: >=1.0.0
breakingCookies that are signed but fail signature validation will appear as `false` in `req.cookies` instead of being moved to `req.signedCookies`. This can lead to unexpected `false` values if not explicitly checked.
fix
Always check for `false` values when accessing cookies from `req.cookies` if signed cookies are expected, or rely solely on `req.signedCookies` for validated values.
affects: >=1.0.0
gotchaThis middleware only *parses* cookies from the incoming request. It does not provide functionality for *setting* cookies in the response. For setting cookies, use Express's `res.cookie()` or a similar method from your web framework.
fix
Use `res.cookie('name', 'value', { signed: true })` within your Express route handlers to set cookies, leveraging the secret provided to `cookie-parser` for signing.
affects: >=1.0.0
gotchaThe `secret` used for `cookieParser` should be a strong, randomly generated string and kept confidential. If an array of secrets is provided, they are tried in order for unsigning, which can be useful for key rotation. However, exposing or reusing secrets compromises cookie security.
fix
Generate a long, random secret for production environments (e.g., using `crypto.randomBytes(32).toString('hex')`) and manage it securely, preferably via environment variables. For key rotation, ensure the new secret is added to the *beginning* of the secret array.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'cookies')
The `cookie-parser` middleware has not been applied to the Express application, or it's applied after the route that attempts to access `req.cookies`.
fix
Ensure `app.use(cookieParser(secret))` is called before any routes that depend on `req.cookies` or `req.signedCookies`.
ReferenceError: cookieParser is not defined
The `cookie-parser` module was not correctly imported using CommonJS `require`.
fix
Add `const cookieParser = require('cookie-parser')` at the top of your file.
Signed cookies are not being parsed or showing up in `req.signedCookies`.
The `cookieParser` middleware was initialized without a `secret`, or the `secret` provided does not match the one used to sign the cookies.
fix
Provide the correct `secret` string (or array of secrets) to `cookieParser` middleware, e.g., `app.use(cookieParser('your-matching-secret'))`.
Upgrade
Version history
1.4.7latest on npm
Audit
Dependencies
cookierequiredCore dependency for parsing cookie strings and handling options.
cookie-signaturerequiredUsed internally for signing and unsigning cookie values to prevent tampering.
Agent activity
63 hits · last 30 days
node
40
Bingbot
22
OpenAI (training)
1
Resources
githubhttps://github.com/expressjs/cookie-parser ↗
packagehttps://www.npmjs.com/package/cookie-parser ↗
homepagehttps://expressjs.com/en/resources/middleware/cookie-parser.html ↗
cookie-parser — npm install cookie-parser · libregistry