HTTP Cookie Parser and Serializer

Common errors

• TypeError: cookie is not a function

  cause Attempting to use `import cookie from 'cookie'` and then calling `cookie.parse()` or `cookie.serialize()` after v1.0.0, which removed the default export.
  fix Change your import statement to `import * as cookie from 'cookie';` or `import { parseCookie, stringifySetCookie } from 'cookie';`.

• ReferenceError: require is not defined

  cause Using CommonJS `require()` syntax in an ESM module context (e.g., in a Node.js project with `"type": "module"` in `package.json` or in a browser environment via bundler without proper CJS translation).
  fix Use ESM `import` statements: `import { parseCookie, stringifySetCookie } from 'cookie';`.

• TypeError: options.maxAge must be an integer

  cause Providing a non-integer value for the `maxAge` option when calling `stringifySetCookie` (or the deprecated `serialize`).
  fix Ensure the `maxAge` value is a whole number (e.g., `Math.floor(value)` or `parseInt(value, 10)`).

• Error: Invalid character in cookie name/value

  cause Attempting to parse or serialize cookie strings with characters that violate RFC6265 specifications, though the package is generally lenient.
  fix Ensure cookie names and values adhere to valid character sets (e.g., for values, `encodeURIComponent` by default handles most cases). Looser validation was added in v1.0.2, but extreme cases may still fail.

Warnings

• breaking Version 1.0.0 introduced significant breaking changes, including minimum Node.js v18, mandatory named or namespace ESM imports, and a null prototype object for `parse` return values. The `strict` and `priority` options now require lowercase strings.
  Fix: Update your import statements to use `import { parse, serialize }` or `import * as cookie from 'cookie';`. Ensure Node.js v18 or newer is used. Review options like `strict` and `priority` for lowercase values.
• breaking The `parse` and `serialize` methods were renamed to `parseCookie` and `stringifySetCookie` respectively in v1.1.0 to improve clarity and introduce `parseSetCookie` and `stringifyCookie`. While old names are aliased for backward compatibility, relying on them is discouraged.
  Fix: Migrate to the new method names: `parse` -> `parseCookie` and `serialize` -> `stringifySetCookie`. Use `stringifyCookie` for generic cookie object to header string conversion (e.g., `a=b;c=d`) and `parseSetCookie` for parsing full `Set-Cookie` header strings into an object.
• gotcha When using `maxAge` and `expires` options together in `stringifySetCookie`, RFC6265 states `maxAge` takes precedence. However, some clients might not obey this. It's best practice to ensure both point to the same date and time if used.
  Fix: If both `maxAge` and `expires` are provided, calculate `expires` based on `maxAge` to maintain consistency across clients, e.g., `expires: new Date(Date.now() + maxAge * 1000)`.
• breaking The `maxAge` option in `stringifySetCookie` now strictly requires an integer value, using `Number.isInteger` for validation. Non-integer values will cause issues.
  Fix: Ensure that any `maxAge` values passed to `stringifySetCookie` are whole numbers. If you have fractional values, round them or convert them to integers before passing.
• gotcha The `cookie.parseSetCookie` method strictly follows the specification and will ignore invalid or unrecognized attributes in a `Set-Cookie` string, rather than attempting to normalize or guess their intent.
  Fix: Be aware that custom or malformed attributes in a `Set-Cookie` header will simply be dropped from the parsed object. Do not rely on `parseSetCookie` to preserve or interpret non-standard attributes.

Install

• npm install cookie npm
• yarn add cookie yarn
• pnpm add cookie pnpm

Imports

• parseCookie
  wrong:

  const { parseCookie } = require('cookie');

  correct:

  import { parseCookie } from 'cookie';

  ESM named imports are required since v1.0.0. CommonJS users should also use named imports for `parseCookie` directly or import the entire module as a namespace.
• stringifySetCookie
  wrong:

  import cookie from 'cookie';
  const header = cookie.serialize(...); // Deprecated name

  correct:

  import { stringifySetCookie } from 'cookie';

  The `serialize` method was renamed to `stringifySetCookie` in v1.1.0, though `serialize` remains for backward compatibility. Always use the new named export for clarity.
• parseSetCookie

  import { parseSetCookie } from 'cookie';

  Introduced in v1.1.0 for parsing `Set-Cookie` headers into objects, distinct from `parseCookie` for `Cookie` headers.
• * as cookie
  wrong:

  import cookie from 'cookie'; // Default import no longer works

  correct:

  import * as cookie from 'cookie';

  Since v1.0.0, the package uses an `__esModule` marker, meaning default imports are no longer valid. You must use a namespace import (`import * as cookie`) or named imports for specific functions.

Quickstart

Demonstrates parsing HTTP `Cookie` headers and both parsing and stringifying `Set-Cookie` headers with common options.

import { parseCookie, stringifySetCookie, parseSetCookie } from 'cookie';

// Example 1: Parsing a 'Cookie' header from an incoming request
const cookieHeader = 'foo=bar; equation=E%3Dmc%5E2; Path=/; Secure';
const parsedCookies = parseCookie(cookieHeader);
console.log('Parsed Cookies:', parsedCookies);
// Expected: { foo: 'bar', equation: 'E=mc^2' }

// Example 2: Stringifying a 'Set-Cookie' header for an outgoing response
const setCookieObject = {
  name: 'sessionid',
  value: 'abc123def456',
  maxAge: 3600, // 1 hour
  httpOnly: true,
  secure: true,
  path: '/',
  sameSite: 'Lax'
};
const setCookieString = stringifySetCookie(setCookieObject);
console.log('Set-Cookie String:', setCookieString);
// Expected: sessionid=abc123def456; Max-Age=3600; Path=/; HttpOnly; Secure; SameSite=Lax

// Example 3: Parsing a 'Set-Cookie' header (e.g., from a client-side response)
const rawSetCookie = 'mytoken=somevalue; Max-Age=7200; Path=/api; Expires=Wed, 21 Oct 2026 07:28:00 GMT; HttpOnly';
const parsedSetCookie = parseSetCookie(rawSetCookie);
console.log('Parsed Set-Cookie Object:', parsedSetCookie);
// Expected: { name: 'mytoken', value: 'somevalue', maxAge: 7200, path: '/api', expires: <Date object>, httpOnly: true }