Universal Cookie Management

Common errors

• TypeError: Cookies is not a constructor

  cause Attempting to call `Cookies()` without `new` or incorrectly importing the default export in CommonJS environments.
  fix Ensure you instantiate the `Cookies` class with `new Cookies()`. If using `require` in CommonJS, use `const Cookies = require('universal-cookie').default;` to access the default export constructor.

• Could not find a declaration file for module 'universal-cookie'.

  cause TypeScript compiler cannot find the type definitions for the `universal-cookie` package, often due to incorrect import paths, mismatched package versions, or tooling misconfiguration.
  fix Ensure `universal-cookie` is correctly installed. For older TypeScript versions or complex setups, verify `tsconfig.json` for `moduleResolution` (e.g., `bundler` or `node`). Ensure no conflicting `@types/universal-cookie` package is installed. This issue was specifically fixed in v7.0.1 for certain module configurations.

• Cookie "your-cookie-name" will be soon rejected because it has the "SameSite" attribute set to “None” or an invalid value, without the “secure” attribute. To learn more, see https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie/SameSite

  cause A browser warning indicating that a cookie is being set with `SameSite=None` but without the `Secure` attribute, violating modern browser security policies.
  fix When setting `sameSite: 'None'`, you must also set `secure: true` in the cookie options. This ensures the cookie is only sent over HTTPS, which is a requirement for cross-site cookies.

• This set-cookie was blocked because its domain attribute was invalid with regards to the current host URL.

  cause Attempting to set a cookie with a `domain` option that is not valid for the current host (e.g., trying to set a cookie for a different top-level domain or a non-existent subdomain).
  fix Review the `domain` option in your `set` call. It should be the current host or a specific subdomain of the current host. Cookies cannot be set for arbitrary domains.

Warnings

• gotcha Cookies marked `httpOnly` cannot be accessed, read, or modified by client-side JavaScript, including `universal-cookie`. This is a security feature to prevent XSS attacks. Attempting to get or set such cookies from the browser will fail silently or return undefined.
  Fix: Ensure `httpOnly: true` is only used for server-side cookies. For client-side accessible data, omit the `httpOnly` option. Consider using secure, client-side only cookies for non-sensitive data, or rely on server-side logic to handle `httpOnly` cookies securely.
• breaking When migrating to v8.0.0, developers should verify their module imports and TypeScript configurations. While specific core API breaking changes were not explicitly detailed in the changelog, major version bumps often involve updates to module resolution (e.g., `package.json` `exports` field) which can affect how bundlers and TypeScript interpret imports, especially in dual CommonJS/ESM setups. Past versions (e.g., v7.1.x) included fixes for TypeScript definitions and ESM compatibility.
  Fix: Update dependencies and re-run your build. If issues persist, check your `tsconfig.json` module resolution settings and ensure your bundler is correctly configured for ESM. Refer to the official changelog or GitHub issues for any specific migration guides related to module changes.
• gotcha When setting `sameSite: 'None'` for cross-site cookies, the `secure` option MUST also be set to `true`. Browsers will reject cookies that specify `SameSite=None` but are not sent over HTTPS. This is a critical security requirement imposed by modern browsers.
  Fix: Always set `secure: true` when `sameSite: 'None'`. Ensure your application is served over HTTPS in production to support these cookie settings.
• gotcha Cookies can only be set for the current domain or its subdomains. Attempting to set a cookie for an unrelated or parent domain (e.g., setting a cookie for `example.com` from `sub.example.com` or for `another.com` from `example.com`) will cause the cookie to be silently rejected by the browser or server without being set.
  Fix: Ensure the `domain` option correctly reflects the current host or a valid subdomain. If cross-domain cookie sharing is required, consider alternative strategies like proxying requests or using server-side redirects with explicit cookie forwarding.

Install

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

Imports

• Cookies
  wrong:

  import { Cookies } from 'universal-cookie';

  correct:

  import Cookies from 'universal-cookie';

  The `Cookies` class is the default export. Using named import will result in `undefined` or a type error.
• Cookies (CommonJS)
  wrong:

  const Cookies = require('universal-cookie');

  correct:

  const Cookies = require('universal-cookie').default;

  When using CommonJS `require` to import a package with an ESM default export, `.default` is necessary to access the class constructor.
• Cookies (Type Import)
  wrong:

  import { CookieSetOptions } from 'universal-cookie/types';

  correct:

  import type { CookieSetOptions, CookieGetOptions } from 'universal-cookie';

  TypeScript types are included with the package and can be imported directly from the main module, ensuring correct type inference and tooling support.

Quickstart

Demonstrates initializing the Cookies class, setting a JSON stringified cookie with options like expiration and path, and retrieving it. Includes type definitions for clarity.

import Cookies from 'universal-cookie';

interface MyCookieData {
  username: string;
  lastLogin: string;
}

const cookies = new Cookies();

// Set a cookie that expires in 1 hour
const expirationDate = new Date();
expirationDate.setTime(expirationDate.getTime() + 60 * 60 * 1000);

const userData: MyCookieData = {
  username: 'checklist_agent',
  lastLogin: new Date().toISOString()
};

cookies.set('user_session', JSON.stringify(userData), {
  path: '/',
  expires: expirationDate,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax' // Recommended for general use
});

console.log('Cookie set: user_session');

// Get a cookie
const storedSession = cookies.get('user_session');
if (storedSession) {
  const parsedData: MyCookieData = JSON.parse(storedSession);
  console.log('Retrieved user_session:', parsedData);
} else {
  console.log('user_session cookie not found.');
}

// Remove a cookie
// cookies.remove('user_session', { path: '/' });
// console.log('Cookie removed: user_session');