cookies-utils

cookies-utils

Use the native Cookie Store API on HTTPS pages when it is available, without writing your own document.cookie fallback. cookies-utils provides one typed, promise-based API across both backends, with shared defaults, runtime validation, and documented browser differences.

• Selects a backend per call and uses document.cookie on non-HTTPS pages with cookie access.
• Provides asynchronous get, getAll, has, set, and delete methods.
• Defaults writes to the root path and SameSite=Lax.
• Validates runtime inputs and reports validation and detectable backend errors as CookieError.
• Ships ESM, CommonJS, and TypeScript declarations with zero runtime dependencies.

Why cookies-utils?

Choose	When it fits
cookies-utils	You want one async API, native Cookie Store where available, a document.cookie fallback, and runtime option validation.
js-cookie	You want a mature synchronous helper around document.cookie.
Native cookieStore	Your supported browsers provide it and you want to use the browser API directly.
document.cookie	A synchronous browser interface is sufficient and manual parsing is acceptable.

The detailed comparison below covers the API and behavior each option provides.

Installation

npm install cookies-utils

For a browser script tag, the browser build is available from jsDelivr and unpkg. It exposes a cookiesUtils global.

<script src="https://cdn.jsdelivr.net/npm/cookies-utils/dist/cookies-utils.min.js"></script>
<script>
  cookiesUtils.delete("name").then(() => console.log("gone"));
</script>

Use https://unpkg.com/cookies-utils/dist/cookies-utils.min.js as the script source to load it from unpkg.

Quick start

import { cookies } from "cookies-utils";

await cookies.set("theme", "dark", {
  secure: true,
  sameSite: "lax",
});

const theme = await cookies.get("theme");
await cookies.delete("theme");

The API can also be imported by name:

import { get, set } from "cookies-utils";

await set("theme", "dark");
const theme = await get("theme");

Comparison

Capability	cookies-utils	js-cookie	Native cookieStore	document.cookie
API model	Promise-based	Synchronous	Promise-based	Synchronous string
Native Cookie Store	Uses it when available	No	Yes	No
Legacy fallback	Automatic document.cookie fallback	Uses document.cookie	None	N/A
Read same-name cookies	getAll(name) returns readable matches	No dedicated same-name list method	getAll() supports filtering	Caller parses the cookie string
Change events	Window events when the native API supports them	No built-in change event	Native Window change events	None
Runtime option validation	Yes	No shared validation contract	Browser validates options	Browser parses the cookie string
Error contract	CookieError for validation and detectable failures	No shared CookieError contract	Browser errors	Writes can fail silently
TypeScript	Included declarations	Community types through @types/js-cookie	DOM types	DOM types
Runtime dependencies	None	None	N/A	N/A

Cookie behavior still depends on browser capabilities. The library shares an API and defaults across backends, but cannot make browser behavior identical.

API

Method	Result	Description
cookies.get(name)	Promise<string | undefined>	Returns one matching value, or undefined.
cookies.getAll(name?)	Promise<Cookie[]>	Lists readable cookies, optionally filtered by name.
cookies.has(name)	Promise<boolean>	Reports whether a readable cookie with that name exists.
cookies.set(name, value, options?)	Promise<void>	Validates and writes a cookie.
cookies.delete(name, options?)	Promise<void>	Expires a cookie with the requested scope.
cookies.onChange(handler)	Unsubscribe function	Subscribes to native Window change events when supported.

The named exports behave the same way. The package also exports the Cookie, CookieAttributes, DeleteOptions, CookieChange, and CookieErrorCode types, plus the CookieError class and onChange function.

Behavior and guarantees

Defaults and scope

set defaults path to / and sameSite to lax. delete defaults path to /, so a bare delete targets a bare set written by this package.

Cookies with the same name can exist at different paths or domains, and browsers can also partition them. get(name) returns one match. Use getAll(name) when every readable match matters. The API cannot select a particular duplicate by path or domain when reading.

Delete a cookie using the same path and domain used when it was created. A scope mismatch is a silent no-op because deletion writes an expired cookie at that scope.

Options

Option	Type	Used by	Default and behavior
path	string	set, delete	/. An explicit path must be non-empty and start with /.
domain	string	set, delete	None. The library checks syntax; the browser decides whether it matches the current origin.
expires	Date|number	set	Absolute expiration as a Date or Unix time in milliseconds within the JavaScript Date range. Cannot be combined with maxAge.
maxAge	number	set	Relative expiration in seconds. Must be an integer. Positive values must fit within the supported JavaScript Date range; zero or a negative value expires the cookie immediately. Cookie Store writes convert it to an absolute expiry.
secure	boolean	set	None. The native Cookie Store backend always writes Secure cookies and rejects secure: false as unsupported.
sameSite	"strict" | "lax" | "none"	set	lax. none requires secure: true.
partitioned	boolean	set, delete	None. A partitioned cookie requires secure: true when set. Pass partitioned: true when deleting it.

The encoded name and value pair must fit within 4096 bytes. UTF-8 path and domain values must each fit within 1024 bytes.

The package validates __Secure- and __Host- prefix requirements before writing. It rejects __Http- and __Host-Http- names because browser JavaScript cannot create the required HttpOnly cookies.

Errors and environment support

Validation failures use CookieError before a browser write. Exceptions thrown by a backend operation are wrapped as CookieError with code OPERATION_FAILED and the original exception in cause. Browsers may silently ignore invalid document.cookie writes without throwing, so those failures cannot be reported.

Code	Meaning
INVALID_NAME	The name is empty, not a string, contains control characters or malformed Unicode, or exceeds its encoded size limit.
INVALID_VALUE	The value is not a string or contains malformed Unicode.
INVALID_OPTIONS	An option has the wrong type, conflicts with another option, or has an invalid value.
UNSUPPORTED	The selected backend cannot perform the requested operation.
NO_COOKIE_ACCESS	Neither Cookie Store nor a cookie-capable document is available.
OPERATION_FAILED	Cookie Store access or a browser backend operation threw an error.

Importing the package is safe during server-side rendering. Cookie operations reject with NO_COOKIE_ACCESS when no browser cookie API exists. Change subscriptions are not available during server rendering.

There is no deleteAllCookies() method. The document.cookie fallback cannot report each cookie's path or domain, and those fields are not reliably available across Cookie Store implementations. JavaScript also cannot access HttpOnly cookies. Keep the names and scopes your application creates, then delete those explicitly.

Common cookie patterns

Cookies used in cross-site embedded or subresource requests require SameSite=None and Secure:

await cookies.set("widget", "enabled", {
  sameSite: "none",
  secure: true,
});

A __Host- cookie must be Secure, have no Domain attribute, and use the root path:

await cookies.set("__Host-session-hint", "1", {
  secure: true,
  path: "/",
});

Partitioned cookies also require Secure:

await cookies.set("__Host-widget", "enabled", {
  secure: true,
  sameSite: "none",
  partitioned: true,
  path: "/",
});

Delete using the same scope that was used to set the cookie:

await cookies.delete("preferences", {
  path: "/account",
});

See SECURITY.md for cookie security limits and release verification.

Cookie change events

In a Window with native Cookie Store change events, cookies.onChange() passes changed cookies with names and values, and deleted cookies with names only. It returns an unsubscribe function. The event data has no path or domain fields. Replacing a cookie can appear as a changed record without a separate deleted record.

const unsubscribe = cookies.onChange(({ changed, deleted }) => {
  for (const cookie of changed) console.log(cookie.name, cookie.value);
  for (const cookie of deleted) console.log(cookie.name, "deleted");
});

unsubscribe();

The document.cookie fallback, server environments, and service workers do not provide this Window event API. onChange() throws CookieError with code UNSUPPORTED there. The library does not poll document.cookie.

Browser support

The library selects a backend for each call.

Backend	Used when	Readable cookie fields
Cookie Store	cookieStore is available, except on a non-HTTPS page with a cookie-capable document	name and value are guaranteed by the API. Browsers may expose additional attributes.
document.cookie	Cookie Store is unavailable, or the page is non-HTTPS and can carry cookies	name and value only.

The real browser test suite runs against Chromium, Firefox, and WebKit. It exercises core operations through native Cookie Store and the document.cookie fallback. Browser-specific support for additional cookie attributes and partitioning can vary.

Cookie Store standardizes the cookie name and value fields; additional metadata is optional and may differ by browser. Treat fields such as path, domain, expiry, Secure, SameSite, and partitioning as optional when reading a Cookie. The fallback can report only names and values.

On a non-HTTPS page with a cookie-capable document, the library selects document.cookie even if Cookie Store is present. This avoids a persistence issue observed in WebKit on plain HTTP origins. On HTTPS pages, Cookie Store is selected when available. A Cookie Store write is Secure by construction, so secure: false is unsupported on that backend.

Security and release integrity

This package reads and writes browser cookies. It is not an authentication system and does not make client-readable values safe to trust. Releases from the current publishing workflow include npm provenance and artifacts for independent verification. See SECURITY.md.

Contributing

Use GitHub Issues for bug reports, enhancement requests, and feedback. See CONTRIBUTING.md to propose a change and run the project checks. Report suspected security vulnerabilities through SECURITY.md, not a public issue.

See ROADMAP.md for the project direction.