Modern Cookie Utility for Browsers

Common errors

• TypeError: Cannot read properties of undefined (reading 'cookie')

  cause Attempting to use synchronous cookie APIs (`get`, `set`, `remove`) in a Node.js or SSR environment where the `document` object is not available.
  fix The library's sync APIs are designed to be no-ops in SSR. If you encounter this error in a non-browser environment, it indicates a misconfiguration or an attempt to use client-side logic on the server. Consider conditional rendering or ensure code runs only in the browser.

• Cookie 'mycookie' not found after removal.

  cause The `remove()` function was called without matching the `path` and `domain` options that were used when the cookie was originally set.
  fix When removing a cookie, ensure that all relevant options (like `path` and `domain`) are identical to those used during the `set()` operation. For example, if set with `set('mycookie', 'value', { path: '/app' })`, remove with `remove('mycookie', { path: '/app' })`.

• Cookie 'mycookie' not appearing in browser despite `set()` call.

  cause Often caused by incorrect `sameSite` and `secure` combinations, particularly `sameSite: "none"` without `secure: true`, or attempting to set a secure cookie over an insecure HTTP connection.
  fix If `sameSite` is `"none"`, you *must* also set `secure: true`. Ensure your site is served over HTTPS when setting `secure` cookies. Also, check for `domain` mismatches if you're attempting cross-subdomain cookies.

Warnings

• gotcha When setting a cookie with `sameSite: "none"`, modern browsers require the `secure: true` option to be explicitly set. Failing to do so will result in the cookie being rejected.
  Fix: Always include `secure: true` when `sameSite: "none"`, e.g., `{ sameSite: "none", secure: true }`.
• gotcha To successfully remove a cookie, the `path` and `domain` options used in the `remove` call must exactly match those specified when the cookie was originally set.
  Fix: Ensure `remove('key', { path: '/original/path', domain: 'original.domain' })` matches the original set options.
• gotcha The synchronous APIs (`get`, `set`, `remove`) are designed for browser environments. When imported in a Server-Side Rendering (SSR) context where `document` is undefined, these functions will act as no-ops to prevent runtime errors.
  Fix: For SSR, if cookie management is needed, ensure it's handled by your SSR framework or use server-specific cookie parsing/setting mechanisms. `js-cookie-next` is primarily for client-side use or isomorphic applications that gracefully degrade on the server.
• gotcha The `mode: "partitioned"` option is a convenience preset that expands to `partitioned: true`, `secure: true`, and `sameSite: "none"`. Browser support for Partitioned Cookies (CHIPS) is still evolving, and the cookie may not be partitioned in unsupported browsers.
  Fix: Always test `mode: "partitioned"` in target browsers. Be aware that `sameSite: "none"` still implicitly requires `secure: true` even when using this preset.

Install

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

Imports

• get
  wrong:

  const { get } = require('js-cookie-next')

  correct:

  import { get } from 'js-cookie-next'

  The library is ESM-first. While bundlers handle CJS compatibility, direct CommonJS require in Node.js environments may not work as expected or is discouraged due to the browser-centric nature of the library. Sync APIs are no-ops in SSR contexts where `document` is undefined.
• set
  wrong:

  import set from 'js-cookie-next'

  correct:

  import { set } from 'js-cookie-next'

  `set` is a named export, not a default export. Ensure correct destructuring.
• getAsync
  wrong:

  import { get, set } from 'js-cookie-next/async'

  correct:

  import { getAsync } from 'js-cookie-next'

  Async functions (`getAsync`, `setAsync`, `removeAsync`) are named exports from the main package, not a separate submodule path. They leverage `window.cookieStore` if available, otherwise fall back to sync behavior.
• CookieOptions
  wrong:

  import { CookieOptions } from 'js-cookie-next'

  correct:

  import type { CookieOptions } from 'js-cookie-next'

  Always use `import type` for type definitions to ensure they are stripped during compilation and do not introduce runtime overhead.

Quickstart

This quickstart demonstrates both the synchronous and asynchronous APIs, including setting and getting cookies, removing them, and utilizing advanced options like `partitioned` mode for CHIPS.

import { get, set, remove, getAsync, setAsync, removeAsync } from "js-cookie-next";

// Basic synchronous usage
set("theme", "dark", { path: "/", sameSite: "lax" });
console.log('Current theme (sync):', get("theme"));
remove("theme", { path: "/" });
console.log('Theme after removal (sync):', get("theme"));

// Asynchronous usage with fallback
async function manageAsyncCookie() {
  await setAsync("session_id", "user_xyz", { expires: 7, secure: true, sameSite: "none" });
  const sessionId = await getAsync("session_id");
  console.log('Session ID (async):', sessionId);

  // Example of a partitioned cookie (CHIPS)
  await setAsync("widget_data", "value123", { mode: "partitioned" });
  console.log('Widget data set with CHIPS (async).');

  await removeAsync("session_id");
  console.log('Session ID after removal (async):', await getAsync("session_id"));
}

manageAsyncCookie();