JavaScript Cookie API

Common errors

• Uncaught TypeError: Cookies.defaults is undefined

  cause 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

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

  cause `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'

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

Warnings

• breaking The `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');`
• gotcha When 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.
• 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.
• breaking In 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.

Install

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

Imports

• Cookies
  wrong:

  import { Cookies } from 'js-cookie';

  correct:

  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.
• Cookies
  wrong:

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

  correct:

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

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

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

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

Quickstart

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