es-cookie

library1.5.0jsnpmunverified

es-cookie is a lightweight, dependency-free JavaScript module designed for managing browser cookies, adhering to RFC 6265 specifications. It provides a simple, type-safe API for setting, getting, removing, and parsing cookies. The library is written in TypeScript and ships with native ES module definitions, making it well-suited for modern web development. The current stable version is 1.5.0, with recent updates including support for experimental `partitioned` cookies and fixes for cookie expiration handling. While originally inspired by `js-cookie`, es-cookie differentiates itself through its TypeScript rewrite, lean API, and explicit focus on ES module distribution, ensuring a modern, tree-shakable approach to cookie management without relying on external packages.

serialization

npm install es-cookie

github ↗package ↗

INSTALL

IMPORT

SIG · ES-COOKIE

es-cookie

serializationjavascriptv1.5.0

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.

✓ import * as Cookies from 'es-cookie';

✗ import Cookies from 'es-cookie'; const Cookies = require('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

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

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

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

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);

Debug

Known issues

gotchaWhen 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' });`

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: <1.5.0

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

affects: >=1.5.0

Errors

Common errors & fixes

ReferenceError: require is not defined

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

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

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';`.

Upgrade

Version history

1.5.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/theodorejb/es-cookie ↗

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