cookie

library1.1.1jsnpmunverified

The `cookie` package provides fundamental utilities for parsing and serializing HTTP `Cookie` and `Set-Cookie` headers, commonly used in Node.js HTTP servers. It is currently at stable version 1.1.1, with relatively frequent patch and minor releases addressing fixes and new HTTP cookie attributes like `partitioned` and `priority`. Key differentiators include its focus on adherence to RFC6265, minimal API surface, and robust handling of common cookie patterns. It is maintained by the `jshttp` organization, known for foundational Express.js ecosystem middleware, ensuring reliability and specification compliance.

http-networking web-framework

npm install cookie

github ↗package ↗

INSTALL

IMPORT

SIG · COOKIE

http-networkingjavascriptv1.1.1

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.

parseCookie

✓ import { parseCookie } from 'cookie';

✗ const { parseCookie } = require('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

✓ import { stringifySetCookie } from 'cookie';

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

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

✓ import * as cookie from 'cookie';

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

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.

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 }

Debug

Known issues

breakingVersion 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.

affects: >=1.0.0

breakingThe `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.

affects: >=1.1.0

gotchaWhen 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)`.

affects: >=0.5.0

breakingThe `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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.1.0

Errors

Common errors & fixes

TypeError: cookie is not a function

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

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

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

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.

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Google (search)

OpenAI (training)

Resources

githubhttps://github.com/jshttp/cookie ↗

packagehttps://www.npmjs.com/package/cookie ↗