Node.js HTTP Cookie Management

Common errors

• TypeError: The 'secret' argument must be a string or a Buffer

  cause The `secret` parameter for signing or encrypting cookies was not provided or was of an incorrect type (e.g., `null`, `undefined`, or a number).
  fix Ensure a non-empty string secret is passed as the fourth argument to `create` or `parse`/`get` methods, or as part of the options object.

• Error: Invalid IV length

  cause This cryptographic error often occurs when the secret key used for encryption/decryption is inconsistent or of an incorrect length, or if the cookie value itself has been tampered with or corrupted.
  fix Verify that the *exact same secret* is used for both encrypting (during `create`) and decrypting (during `parse` or `get`) a cookie. Ensure the secret meets the length requirements of the underlying cryptographic algorithm (e.g., 16, 24, or 32 characters for AES-128, AES-192, AES-256 respectively, or derived consistently).

• Cookie 'mycookie' is not visible in browser developer tools / `req.headers.cookie` does not contain 'mycookie'

  cause The `Set-Cookie` header was not properly sent by the server, or the browser rejected the cookie due to incorrect attributes (e.g., `Domain`, `Path`, `Secure`, `HttpOnly`, `Expires`, `SameSite`).
  fix Check the `Set-Cookie` header in the server response for errors. Ensure `secure: true` is only for HTTPS. Verify `domain` and `path` match the request URL. If `httpOnly: true` is set, the cookie won't be accessible by client-side JavaScript, but should still be sent by the browser. Explicitly set `expires` or `maxAge` to ensure persistence.

Warnings

• breaking The package is explicitly CommonJS and uses `require`. Attempting to `import` it in a pure ESM context might lead to issues or require specific Node.js interoperability configurations (e.g., `createRequire`). Node.js ESM loader will treat `require('node-cookie')` as a default export, but explicit named imports are not supported.
  Fix: For ESM projects, use `import nodeCookie from 'node-cookie';` and then access methods like `nodeCookie.create()`. For CommonJS, stick to `const nodeCookie = require('node-cookie');`.
• gotcha Using a weak or hardcoded secret for signing and encryption (e.g., directly in source code) makes cookies vulnerable to tampering and decryption. The secret must be sufficiently long and complex, and should be managed securely (e.g., via environment variables).
  Fix: Generate a strong, random secret (e.g., 32 characters or more) and load it from environment variables at runtime (`process.env.COOKIE_SECRET`). Never commit secrets to version control.
• gotcha Cookies might not be set in the browser if `secure: true` is used when serving over HTTP, or if `domain` or `path` options are misconfigured. Browsers strictly enforce these attributes.
  Fix: Ensure `secure: true` is only used when the server is accessible via HTTPS. Double-check `domain` (should match the host or be a valid parent domain) and `path` (defaults to `/`) options to ensure they align with the client-side context. Test with browser developer tools to inspect `Set-Cookie` headers.
• deprecated This package has not been updated in over six years (last published version 2.1.2). It may not receive security updates or be compatible with future Node.js versions or evolving web standards (e.g., `SameSite=None; Secure;` requirements).
  Fix: Consider migrating to actively maintained cookie parsing and signing libraries like `cookies` or `tough-cookie` for robust, up-to-date solutions, especially in production environments.

Install

• npm install node-cookie npm
• yarn add node-cookie yarn
• pnpm add node-cookie pnpm

Imports

• nodeCookie
  wrong:

  const { nodeCookie } = require('node-cookie')

  correct:

  import nodeCookie from 'node-cookie'

  This package is primarily CommonJS-first. For ESM, a default import is likely needed, or direct property access after a default import. Named exports are not explicitly defined.
• create
  wrong:

  import { create } from 'node-cookie'

  correct:

  import nodeCookie from 'node-cookie'; nodeCookie.create(res, 'key', 'value')

  `create` is a method of the default exported `nodeCookie` object, not a named export itself. Direct destructuring `import { create }` will not work with CommonJS `module.exports`.
• parse
  wrong:

  import { parse } from 'node-cookie'

  correct:

  const nodeCookie = require('node-cookie'); const cookies = nodeCookie.parse(req)

  `parse` is a method of the default exported `nodeCookie` object. The package uses CommonJS `require` in its examples, indicating CJS as its primary module system.
• get
  wrong:

  const { get } = require('node-cookie')

  correct:

  const nodeCookie = require('node-cookie'); const value = nodeCookie.get(req, 'key')

  Similar to `create` and `parse`, `get` is accessed via the default `nodeCookie` object. Direct destructuring for `require` or `import` is not supported for these methods.

Quickstart

This quickstart demonstrates setting and retrieving signed and encrypted HTTP cookies using `node-cookie` with a basic Node.js HTTP server. It shows `create` for writing cookies with options for expiration, signing, and encryption, and `parse` and `get` for reading them, also handling decryption and unsigning.

const http = require('http');
const nodeCookie = require('node-cookie');

const SECRET = process.env.COOKIE_SECRET ?? 'supersecretkeyfornodejsapp';

http.createServer(function (req, res) {
  if (req.url === '/set-cookie') {
    // Create a signed and encrypted cookie
    nodeCookie.create(res, 'userSession', 'user123', { expires: new Date(Date.now() + 60 * 60 * 1000) }, SECRET, true);
    nodeCookie.create(res, 'lastVisit', new Date().toISOString(), SECRET, false);
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Cookies set!');
  } else if (req.url === '/get-cookie') {
    // Parse and retrieve cookies
    const parsedCookies = nodeCookie.parse(req, SECRET, true);
    const userSession = nodeCookie.get(req, 'userSession', SECRET, true);
    const lastVisit = nodeCookie.get(req, 'lastVisit', SECRET, false);

    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({
      parsedCookies,
      userSession: userSession || 'Not found or invalid',
      lastVisit: lastVisit || 'Not found or invalid'
    }));
  } else {
    res.writeHead(200, { 'Content-Type': 'text/html' });
    res.end('<h1>Visit /set-cookie to set, or /get-cookie to retrieve.</h1>');
  }
}).listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('Try http://localhost:3000/set-cookie then http://localhost:3000/get-cookie');
});