Registry / web-framework / universal-cookie

universal-cookie

library8.1.0jsnpmunverified

universal-cookie is a JavaScript library designed for isomorphic cookie management across diverse environments, including client-side browsers, Node.js servers, and integrated within React applications (often via the `react-cookie` wrapper). It provides a consistent API for setting, getting, and removing HTTP cookies, abstracting away the underlying environment specifics. The current stable version is `8.1.0`, with the project maintaining an active release cadence, regularly providing minor and patch updates, and recently introducing major version `8.0.0`. Its core value proposition lies in enabling developers to write single-codebase solutions for cookie handling, simplifying full-stack development by offering a unified approach to cookie lifecycle management, supporting standard cookie attributes like `path`, `expires`, `domain`, `secure`, `httpOnly`, and `sameSite`.

web-framework auth-security

npm install universal-cookie

github ↗package ↗

INSTALL

IMPORT

SIG · UNIVERSAL-COOKIE

universal-cookie

web-frameworkjavascriptv8.1.0

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 'universal-cookie';

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

The `Cookies` class is the default export. Using named import will result in `undefined` or a type error.

Cookies (CommonJS)

✓ const Cookies = require('universal-cookie').default;

✗ const Cookies = require('universal-cookie');

When using CommonJS `require` to import a package with an ESM default export, `.default` is necessary to access the class constructor.

Cookies (Type Import)

✓ import type { CookieSetOptions, CookieGetOptions } from 'universal-cookie';

✗ import { CookieSetOptions } from 'universal-cookie/types';

TypeScript types are included with the package and can be imported directly from the main module, ensuring correct type inference and tooling support.

Demonstrates initializing the Cookies class, setting a JSON stringified cookie with options like expiration and path, and retrieving it. Includes type definitions for clarity.

import Cookies from 'universal-cookie'; interface MyCookieData { username: string; lastLogin: string; } const cookies = new Cookies(); // Set a cookie that expires in 1 hour const expirationDate = new Date(); expirationDate.setTime(expirationDate.getTime() + 60 * 60 * 1000); const userData: MyCookieData = { username: 'checklist_agent', lastLogin: new Date().toISOString() }; cookies.set('user_session', JSON.stringify(userData), { path: '/', expires: expirationDate, secure: process.env.NODE_ENV === 'production', sameSite: 'lax' // Recommended for general use }); console.log('Cookie set: user_session'); // Get a cookie const storedSession = cookies.get('user_session'); if (storedSession) { const parsedData: MyCookieData = JSON.parse(storedSession); console.log('Retrieved user_session:', parsedData); } else { console.log('user_session cookie not found.'); } // Remove a cookie // cookies.remove('user_session', { path: '/' }); // console.log('Cookie removed: user_session');

Debug

Known issues

gotchaCookies marked `httpOnly` cannot be accessed, read, or modified by client-side JavaScript, including `universal-cookie`. This is a security feature to prevent XSS attacks. Attempting to get or set such cookies from the browser will fail silently or return undefined.

fix

Ensure `httpOnly: true` is only used for server-side cookies. For client-side accessible data, omit the `httpOnly` option. Consider using secure, client-side only cookies for non-sensitive data, or rely on server-side logic to handle `httpOnly` cookies securely.

affects: >=1.0.0

breakingWhen migrating to v8.0.0, developers should verify their module imports and TypeScript configurations. While specific core API breaking changes were not explicitly detailed in the changelog, major version bumps often involve updates to module resolution (e.g., `package.json` `exports` field) which can affect how bundlers and TypeScript interpret imports, especially in dual CommonJS/ESM setups. Past versions (e.g., v7.1.x) included fixes for TypeScript definitions and ESM compatibility.

fix

Update dependencies and re-run your build. If issues persist, check your `tsconfig.json` module resolution settings and ensure your bundler is correctly configured for ESM. Refer to the official changelog or GitHub issues for any specific migration guides related to module changes.

affects: >=8.0.0

gotchaWhen setting `sameSite: 'None'` for cross-site cookies, the `secure` option MUST also be set to `true`. Browsers will reject cookies that specify `SameSite=None` but are not sent over HTTPS. This is a critical security requirement imposed by modern browsers.

fix

Always set `secure: true` when `sameSite: 'None'`. Ensure your application is served over HTTPS in production to support these cookie settings.

affects: >=4.0.2

gotchaCookies can only be set for the current domain or its subdomains. Attempting to set a cookie for an unrelated or parent domain (e.g., setting a cookie for `example.com` from `sub.example.com` or for `another.com` from `example.com`) will cause the cookie to be silently rejected by the browser or server without being set.

fix

Ensure the `domain` option correctly reflects the current host or a valid subdomain. If cross-domain cookie sharing is required, consider alternative strategies like proxying requests or using server-side redirects with explicit cookie forwarding.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cookies is not a constructor

Attempting to call `Cookies()` without `new` or incorrectly importing the default export in CommonJS environments.

fix

Ensure you instantiate the `Cookies` class with `new Cookies()`. If using `require` in CommonJS, use `const Cookies = require('universal-cookie').default;` to access the default export constructor.

Could not find a declaration file for module 'universal-cookie'.

TypeScript compiler cannot find the type definitions for the `universal-cookie` package, often due to incorrect import paths, mismatched package versions, or tooling misconfiguration.

fix

Ensure `universal-cookie` is correctly installed. For older TypeScript versions or complex setups, verify `tsconfig.json` for `moduleResolution` (e.g., `bundler` or `node`). Ensure no conflicting `@types/universal-cookie` package is installed. This issue was specifically fixed in v7.0.1 for certain module configurations.

Cookie "your-cookie-name" will be soon rejected because it has the "SameSite" attribute set to “None” or an invalid value, without the “secure” attribute. To learn more, see https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie/SameSite

A browser warning indicating that a cookie is being set with `SameSite=None` but without the `Secure` attribute, violating modern browser security policies.

fix

When setting `sameSite: 'None'`, you must also set `secure: true` in the cookie options. This ensures the cookie is only sent over HTTPS, which is a requirement for cross-site cookies.

This set-cookie was blocked because its domain attribute was invalid with regards to the current host URL.

Attempting to set a cookie with a `domain` option that is not valid for the current host (e.g., trying to set a cookie for a different top-level domain or a non-existent subdomain).

fix

Review the `domain` option in your `set` call. It should be the current host or a specific subdomain of the current host. Cookies cannot be set for arbitrary domains.

Upgrade

Version history

8.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ItsBenCodes/cookies ↗

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