Registry / web-framework / js-cookie-next

js-cookie-next

library1.0.1jsnpmunverified

js-cookie-next is a native-first, TypeScript-first utility library designed for managing browser cookies with a focus on modern web standards. It transparently supports the Asynchronous Cookie Store API where available and falls back to `document.cookie` for broader compatibility. Currently at version 1.0.1, the library maintains a stable release cadence, with updates primarily driven by new browser features or bug fixes rather than frequent major API changes. Key differentiators include its zero-dependency footprint, small size (< 2 KB gzipped), SSR-safe imports that make sync APIs no-ops in non-browser environments, and built-in support for Partitioned Cookies (CHIPS) via a simple preset option. It prioritizes type safety and a clear API for both synchronous and asynchronous cookie operations, catering to contemporary web development practices.

web-framework http-networking serialization

npm install js-cookie-next

github ↗package ↗

INSTALL

IMPORT

SIG · JS-COOKIE-NEXT

js-cookie-next

web-frameworkjavascriptv1.0.1

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.

get

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

✗ const { get } = require('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

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

✗ import set from 'js-cookie-next'

`set` is a named export, not a default export. Ensure correct destructuring.

getAsync

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

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

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

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

✗ import { 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.

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

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

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

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