Cookies.js Client-Side Cookie Manipulation

Common errors

• TypeError: Cannot read properties of undefined (reading 'document')

  cause Attempting to use `cookies-js` directly in a Node.js environment without providing a `window` object.
  fix Initialize `cookies-js` by providing a `window` instance from a library like `jsdom`: `const { JSDOM } = require('jsdom'); const window = new JSDOM().window; const Cookies = require('cookies-js')(window);`

• Cookie values or keys are malformed/incorrect when read from the server.

  cause Inconsistent URI encoding between client-side `cookies-js` (UTF-8) and server-side processing, often due to server frameworks using non-standard URL encoders/decoders.
  fix Verify that both client and server are using compatible URI encoding (UTF-8). For .NET, use `System.Uri.EscapeDataString` and `System.Uri.UnescapeDataString` instead of `HttpUtility` methods.

• `Cookies.enabled` always returns `true` even when cookies are disabled in Internet Explorer 7 or 8.

  cause A bug in `cookies-js` versions prior to `0.4.0` caused `Cookies.enabled` to incorrectly report `true` in older IE browsers.
  fix Upgrade `cookies-js` to version `0.4.0` or higher to fix the `Cookies.enabled` detection in IE7/IE8.

Warnings

• gotcha The `cookies-js` package appears to be abandoned, with the last update (v1.2.3) occurring approximately eight years ago. While it remains functional for its core purpose, new feature development, bug fixes, or security patches are unlikely.
  Fix: For new projects, consider more actively maintained cookie management libraries. For existing projects, be aware of the lack of ongoing support and potential future compatibility issues or unpatched vulnerabilities.
• breaking Version 1.0.0 marked a significant change in the project's licensing, moving it into the public domain. While no API-breaking changes occurred between v0.4.0 and v1.0.0, this represented a major shift in project governance.
  Fix: Review the licensing terms if your project's legal compliance depends on the pre-1.0.0 licensing model. The API itself remained stable from 0.4.0, so code changes are generally not required.
• gotcha When using `cookies-js` in environments without a native `window` object (e.g., Node.js), the library exports a factory method that requires an explicit `window` instance to be passed during initialization.
  Fix: For Node.js, use a library like `jsdom` to create a `window` instance and pass it to the `cookies-js` factory: `const { JSDOM } = require('jsdom'); const window = new JSDOM().window; const Cookies = require('cookies-js')(window);`
• gotcha `cookies-js` strictly adheres to RFC6265 and expects all cookie keys and values to be URI encoded in UTF-8 representation. Incorrect encoding, especially when interoperating with server-side frameworks that use different encoding schemes, can lead to malformed cookies or data loss.
  Fix: Ensure all cookie keys and values are consistently URI encoded using UTF-8. For .NET users, specifically avoid `HttpUtility.UrlEncode` and `HttpUtility.UrlDecode`, and instead use `System.Uri.EscapeDataString` and `System.Uri.UnescapeDataString`.
• gotcha Older versions of `cookies-js` (prior to v1.2.3) could encounter a null object reference error when both the global `this` and `window` objects were undefined, particularly in bundled environments like webpack.
  Fix: Upgrade `cookies-js` to version `1.2.3` or higher to resolve issues related to global context availability in modern bundling environments.

Install

• npm install cookies-js npm
• yarn add cookies-js yarn
• pnpm add cookies-js pnpm

Imports

• Cookies
  wrong:

  import Cookies from 'cookies-js';

  correct:

  import * as Cookies from 'cookies-js';

  For modern bundlers, this library is often consumed as a namespace import due to its CommonJS origins. A default import (`import Cookies from 'cookies-js'`) might not work or could result in `undefined`.
• Cookies (CommonJS)
  wrong:

  import Cookies from 'cookies-js';

  correct:

  const Cookies = require('cookies-js');

  This is the standard CommonJS import for browser-like environments where a `window` object is globally available.
• Cookies (Node.js/JSDOM factory)
  wrong:

  const Cookies = require('cookies-js');

  correct:

  const { JSDOM } = require('jsdom');
  const window = new JSDOM().window;
  const Cookies = require('cookies-js')(window);

  In Node.js or other environments without a native `window` object, `cookies-js` exports a factory method that requires a `window` instance (e.g., from `jsdom`) to be explicitly passed.

Quickstart

Demonstrates setting, getting, and expiring cookies using Cookies.js within a Node.js environment by simulating a browser's `window` object with `jsdom`.

import { JSDOM } from 'jsdom';
import * as CookiesFactory from 'cookies-js'; // Assuming it's a factory function for Node

// Simulate a browser window for Node.js using jsdom
const { window } = new JSDOM('<!doctype html><html><body></body></html>', { url: 'http://localhost' });

// Initialize Cookies.js with the simulated window object
const Cookies = (CookiesFactory as any)(window);

console.log('--- Initializing Cookies.js ---');

// Set a persistent cookie with an expiry date far in the future
Cookies.set('user_session', 'session_token_123abc', {
  expires: Infinity, // Sets a persistent cookie (effectively never expires for a browser)
  path: '/',
  secure: true, // Only send over HTTPS (if applicable)
  domain: 'localhost' // Restrict to a specific domain
});
console.log('Cookie "user_session" set to a persistent value.');

// Retrieve a cookie
const sessionToken = Cookies.get('user_session');
console.log(`Retrieved 'user_session': ${sessionToken}`);

// Check if cookies are enabled in the environment
if (Cookies.enabled) {
  console.log('Cookies are enabled in this environment.');
} else {
  console.log('Cookies are disabled.');
}

// Set a temporary cookie that expires in 5 seconds
Cookies.set('last_activity', Date.now().toString(), { expires: 5 });
console.log('Cookie "last_activity" set to expire in 5 seconds.');

// Immediately expire the 'user_session' cookie
Cookies.expire('user_session');
console.log('Cookie "user_session" immediately expired.');

// Attempt to retrieve the expired cookie (should be undefined)
const expiredSessionToken = Cookies.get('user_session');
console.log(`Attempted to retrieve expired 'user_session': ${expiredSessionToken || 'undefined'}.`);