cookie-parser

cookie-parser is a small, widely-used Express middleware that reads the incoming request’s Cookie header and populates req.cookies with a plain object of cookie name/value pairs, so route handlers never have to parse raw cookie strings themselves. It builds on the standalone cookie package for header parsing and the cookie-signature package for HMAC-based signature verification, exposing a single middleware factory plus a handful of standalone helper functions.

Beyond basic parsing, it understands two conventions Express apps commonly rely on: signed cookies (prefixed s:, verified against one or more secrets and surfaced separately on req.signedCookies) and JSON cookies (prefixed j:, automatically JSON.parse’d). Because it has almost no configuration surface and a single runtime job, it has become a near-default dependency in Express-based session and auth middleware stacks despite receiving only maintenance-level updates.

What You Get

• A single middleware factory (cookieParser(secret, options)) that populates req.cookies on every request
• Optional signed-cookie support: verify and unsign s:-prefixed cookie values against one or more secrets, exposed via req.signedCookies
• Automatic JSON cookie decoding for j:-prefixed values via JSONCookie/JSONCookies
• Standalone helper exports (signedCookie, signedCookies, JSONCookie, JSONCookies) usable outside the middleware for custom cookie handling
• Pass-through options support to the underlying cookie package’s parser (e.g. custom decode function)

Common Use Cases

• Reading plain, unsigned cookies (feature flags, UI preferences, tracking IDs) in an Express route handler
• Verifying signed session or auth cookies set by express-session or custom auth middleware without trusting client-tampered values
• Storing small structured data in a cookie as JSON and having it auto-decoded into an object on every request
• Building custom cookie-parsing logic in non-Express contexts by importing the exported signedCookie/JSONCookie helpers directly

Under The Hood

Architecture — The entire package is a single ~150-line index.js file that exports one default middleware factory plus four static helper functions (JSONCookie, JSONCookies, signedCookie, signedCookies). The factory closes over a normalized array of secrets and returns a request handler that reads req.headers.cookie, delegates raw parsing to the cookie package, then optionally splits the result into req.cookies and req.signedCookies by running each value through signedCookie (which itself delegates verification to cookie-signature). There is no internal state beyond what is attached per-request, and no async logic — parsing is synchronous end to end.

Tech Stack — Plain ES5-style JavaScript ('use strict', var declarations) with only two runtime dependencies: cookie (RFC 6265 header parsing) and cookie-signature (HMAC signing/verification). No build step or bundler — the package ships index.js directly per its files field. Dev tooling is eslint (standard config) for linting and mocha/supertest/nyc for testing and coverage.

Code Quality — test/cookieParser.js runs 302 lines of mocha+supertest tests covering unsigned, signed, JSON, and malformed-cookie scenarios, including tampered signature handling. The implementation uses Object.create(null) for cookie stores to avoid prototype-pollution surprises and defensive typeof/Array.isArray checks on inputs. Error handling is minimal by design — most edge cases resolve to undefined/false rather than throwing, appropriate given the package’s narrow scope, but there is no input-size or malformed-header hardening beyond what cookie provides.

API Design — The primary API is a single call, app.use(cookieParser()), with zero required configuration; secrets and parsing options are optional positional arguments. Helper functions are exposed as static properties on the default export for advanced use outside the middleware chain. The tradeoff for this simplicity is implicit request mutation (adding cookies/secret/signedCookies onto req), which is idiomatic for Express middleware but relies on convention rather than explicit typing.