es-cookie

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES module environment or when `es-cookie` is exclusively an ES module.
  fix Change `const Cookies = require('es-cookie');` to `import * as Cookies from 'es-cookie';` and ensure your project is configured for ES modules.

• Cookie 'myCookie' was not deleted

  cause The `path` or `domain` attributes provided to `Cookies.remove()` do not exactly match those used when the cookie was originally set.
  fix Verify and provide the identical `path` and `domain` attributes to `Cookies.remove()` as were used with `Cookies.set()`. For example: `Cookies.remove('myCookie', { path: '/some/path', domain: 'example.com' });`

• TypeError: Cannot read properties of undefined (reading 'set') OR Cookies.set is not a function

  cause Incorrect import of the `es-cookie` module, specifically trying to import `Cookies` as a default export (`import Cookies from 'es-cookie'`) when it's a namespace import (`import * as Cookies from 'es-cookie'`) or attempting to access `set` on a non-existent or incorrectly imported `Cookies` object.
  fix If you intend to use `Cookies.set`, `Cookies.get`, etc., change your import to `import * as Cookies from 'es-cookie';`. Alternatively, use named imports: `import { set, get } from 'es-cookie';`.

Warnings

• gotcha When removing a cookie, it is critical to provide the exact same `path` and `domain` attributes that were used when the cookie was initially set. Failing to match these attributes will prevent the cookie from being successfully deleted.
  Fix: Always specify `path` and `domain` options in `Cookies.remove()` if they were provided during `Cookies.set()`. For example, `Cookies.set('name', 'value', { path: '/app' }); Cookies.remove('name', { path: '/app' });`
• gotcha es-cookie is published as a native ES module. Direct `require()` statements in CommonJS environments are not officially supported and may lead to module resolution errors or unexpected behavior, especially in Node.js contexts or older bundlers.
  Fix: Ensure your project is configured for ES module imports (e.g., `type: "module"` in `package.json` for Node.js, or using a modern bundler like Webpack/Rollup/Vite). Use `import` statements exclusively for `es-cookie`.
• gotcha Setting `expires` to a number larger than the maximum valid date (e.g., `Date.MAX_VALUE`) previously resulted in cookies not expiring correctly. This issue was fixed in v1.5.0.
  Fix: Upgrade to `es-cookie@1.5.0` or newer to ensure that cookies with very long `expires` values are handled correctly and expire on the maximum possible date.
• gotcha Support for `partitioned` cookies was added in v1.5.0. This is an experimental feature designed for CHIPS (Cookies Having Independent Partitioned State). While supported, its broad browser compatibility and long-term specification stability should be monitored.
  Fix: When using the `partitioned` attribute, ensure target browsers support CHIPS. Be aware that this is an experimental standard and may evolve.

Install

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

Imports

• Cookies
  wrong:

  import Cookies from 'es-cookie';
  const Cookies = require('es-cookie');

  correct:

  import * as Cookies from 'es-cookie';

  The package is a native ES module. While `import * as Cookies` imports all named exports into a namespace object, attempting a default import (`import Cookies from 'es-cookie'`) will likely result in an undefined value or an error. CommonJS `require()` is not officially supported and should be avoided in favor of ES imports.
• set, get, remove
  wrong:

  import { set as setCookie } from 'es-cookie/set';

  correct:

  import { set, get, remove } from 'es-cookie';

  Named imports are recommended for tree-shaking and to only include the functions necessary for your application, leading to smaller bundle sizes.
• CookieAttributes

  import type { CookieAttributes } from 'es-cookie';

  For TypeScript users, `CookieAttributes` defines the structure for the options object used in the `set` and `remove` functions, providing type safety for cookie attributes like `expires`, `path`, and `domain`.

Quickstart

Demonstrates setting a secure, expiring cookie, retrieving individual and all cookies, and correctly removing a cookie by matching attributes, along with parsing a raw cookie string.

import * as Cookies from 'es-cookie';

// Set a cookie that expires in 7 days, valid across the entire site
Cookies.set('my-session-token', 'your-secure-token-value-here', { expires: 7, secure: true, sameSite: 'Lax' });

// Get a specific cookie by name
const token = Cookies.get('my-session-token');
if (token) {
  console.log('Retrieved token:', token);
} else {
  console.log('No token found.');
}

// Get all visible cookies
const allCookies = Cookies.getAll();
console.log('All cookies:', allCookies);

// Remove the cookie (important: use the same attributes if non-default)
Cookies.remove('my-session-token', { path: '/', secure: true, sameSite: 'Lax' });
console.log('Token removed.');

// Example of parsing a raw cookie string
const rawCookieString = 'some_cookie=some_value; another_cookie=another_value';
const parsed = Cookies.parse(rawCookieString);
console.log('Parsed raw string:', parsed);