js-cookie

library3.0.5jsnpmunverified

js-cookie is a simple, lightweight JavaScript library designed for handling browser cookies. Currently stable at version 3.0.5, it provides a minimal and dependency-free API for setting, getting, and deleting cookies. It supports ES Modules, CommonJS, and AMD, and is compatible with all major browsers. The library is RFC 6265 compliant and known for its small footprint (under 800 bytes gzipped). Releases appear to be somewhat infrequent but consistent, with bug fix releases for the 3.x series. Its key differentiator is its small size and lack of dependencies, focusing solely on efficient client-side cookie management without extra features, making it ideal for browser environments.

http-networking

npm install js-cookie

github ↗package ↗

INSTALL

IMPORT

SIG · JS-COOKIE

js-cookie

http-networkingjavascriptv3.0.5

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 Cookies from 'js-cookie';

✗ import { Cookies } from 'js-cookie';

The library uses a default export for its primary API object since v3. Named imports like `{ Cookies }` will not work.

✓ const Cookies = require('js-cookie');

✗ import Cookies from 'js-cookie'; // In CommonJS

CommonJS require style for Node.js environments or projects using bundlers configured for CommonJS. Ensure your environment supports this.

✓ Cookies.set('name', 'value'); // Accessed globally

When included directly via a <script> tag in a browser, the `Cookies` object is exposed globally on `window`.

Demonstrates how to set, get, and remove cookies using js-cookie, including options for expiration, path, and secure flag, and highlights important considerations for cookie deletion.

import Cookies from 'js-cookie'; // Set a cookie valid across the entire site for 7 days Cookies.set('my_app_token', 'your-auth-token-123', { expires: 7 }); console.log('Cookie "my_app_token" set successfully.'); // Set a cookie with specific path and secure flag (often used for sensitive data) Cookies.set('user_preference', 'dark-theme', { expires: 30, path: '/', secure: true }); console.log('Cookie "user_preference" set for 30 days, secure, path /.'); // Read a specific cookie const token = Cookies.get('my_app_token'); console.log('Retrieved token:', token); // Read all visible cookies const allCookies = Cookies.get(); console.log('All visible cookies:', allCookies); // Delete a cookie (must provide same path/domain if they were set) Cookies.remove('my_app_token'); console.log('Cookie "my_app_token" removed (site-wide).'); // Example of deleting a cookie that was set with a specific path Cookies.set('temp_data', 'some-value', { path: '/temp' }); // Cookies.remove('temp_data'); // This would fail if path was not explicitly set during removal Cookies.remove('temp_data', { path: '/temp' }); console.log('Cookie "temp_data" (with path /temp) removed.');

Debug

Known issues

breakingThe `defaults` object for setting global cookie attributes was removed in v3.0.0. Attempting to use `Cookies.defaults` will result in an error.

fix

Refactor code to use `Cookies.withAttributes()` to create API instances with predefined attributes. Example: `const api = Cookies.withAttributes({ path: '/', secure: true }); api.set('key', 'value');`

affects: >=3.0.0

gotchaWhen deleting a cookie, `Cookies.remove()` requires the same `path` and `domain` attributes that were used when the cookie was originally set. Failing to provide these attributes will result in the cookie not being removed.

fix

Ensure `Cookies.remove('name', { path: '/specific-path', domain: '.example.com' });` includes all relevant attributes that were specified during the cookie's creation.

affects: >=2.0.0

gotcha`Cookies.get()` does not accept or utilize attributes like `domain` or `path` for reading. It only retrieves cookies that are visible from the current document context based on the browser's native cookie rules.

fix

Understand that cookie visibility for reading is determined by the browser based on the current URL, not by attributes passed to `get()`. Ensure cookies are set with appropriate `path` and `domain` for the desired visibility.

affects: >=2.0.0

breakingIn v3.0.0-beta.4 (and subsequent v3 releases), the encoding/decoding implementation was revised. It now only encodes characters strictly necessary (`;` and `=` in the cookie name, and `;` in the cookie value) aligning with user agent rules (RFC 6265 section 5.2). This change might affect compatibility with cookies set by older versions or by servers expecting stricter encoding.

fix

Thoroughly test cookie interactions after upgrading, especially if your application relies on specific encoding behaviors from pre-v3 versions or interacts with backend systems with strict encoding expectations. No direct code fix is typically required, but awareness is crucial.

affects: >=3.0.0-beta.4

Errors

Common errors & fixes

Uncaught TypeError: Cookies.defaults is undefined

Attempting to access or modify the `Cookies.defaults` object, which was removed in version 3.0.0.

fix

Use `Cookies.withAttributes({ expires: 7, path: '/' })` to create a new API instance with predefined attributes instead of setting global defaults.

ReferenceError: require is not defined

Trying to use `require('js-cookie')` in a browser environment without a CommonJS-aware bundler (e.g., Webpack, Rollup, Browserify).

fix

For browser-only usage, either include the library via a `<script>` tag and access `window.Cookies` globally, or use an ES module `import Cookies from 'js-cookie';` with a compatible bundler setup.

Cookie 'myCookie' not removed (observed behavior, no console error)

`Cookies.remove()` was called without specifying the `path` or `domain` attributes that were used when the cookie was originally set, leading to the cookie not being found and deleted by the browser.

fix

Ensure that `Cookies.remove('myCookie', { path: '/specific-path', domain: '.example.com' });` includes all relevant attributes (`path`, `domain`) that were used when the cookie was initially created.

SyntaxError: Named export 'Cookies' not found. The requested module 'js-cookie' does not provide an export named 'Cookies'

Attempting to import `Cookies` using a named import style (`import { Cookies } from 'js-cookie';`) when the library provides a default export.

fix

Use the default import syntax: `import Cookies from 'js-cookie';`

Upgrade

Version history

3.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/js-cookie/js-cookie ↗

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