browser-cookie-utils

Lightweight, dependency-free JavaScript helpers for getting, setting, and deleting browser cookies safely and consistently in modern browsers.

Features

• Zero runtime dependencies
• Browser-only (no Node.js required in production)
• Simple, ergonomic API
• Cookie expiration with time units
• Multi-domain cookie support
• Automatic Secure flag on HTTPS
• SameSite support (Lax, Strict, None)
• Path customization
• Safe encoding / decoding

Installation

NPM (Modern ESM / CJS)

npm install browser-cookie-utils@2

ESM import (modern bundlers):

import { setCookie, getCookie, deleteCookie } from 'browser-cookie-utils';

CJS import (Node.js / legacy bundlers):

const { getCookie, setCookie, deleteCookie } = require('browser-cookie-utils');

Browser (UMD / CDN)

<script src="https://cdn.jsdelivr.net/npm/browser-cookie-utils/dist/browser-cookie-utils.umd.js"></script>

Available Builds

| File | Format | Notes | | --------------------------------- | ---------- | --------------------------------------- | | browser-cookie-utils.js | ESM | Non-minified, modern bundlers | | browser-cookie-utils.min.js | ESM | Minified, production-ready (ES module) | | browser-cookie-utils.cjs.js | CJS | Non-minified, Node.js / CommonJS | | browser-cookie-utils.cjs.min.js | CJS | Minified, production-ready | | browser-cookie-utils.umd.js | UMD | Legacy browsers / script tag & CommonJS | | browser-cookie-utils.min.js.map | Source map | For minified ESM |

Note: The library attaches itself to window.browserCookieUtils in the browser.

Usage by environment

ES Modules (recommended)

import { getCookie, setCookie, deleteCookie } from 'browser-cookie-utils';

setCookie('theme', 'dark');

CommonJS

const { getCookie, setCookie, deleteCookie } = require('browser-cookie-utils');

setCookie('theme', 'dark');

Browser (script tag / CDN)

<script src="https://cdn.jsdelivr.net/npm/browser-cookie-utils/dist/browser-cookie-utils.umd.js"></script>
<script>
  browserCookieUtils.setCookie('theme', 'dark');
</script>

The global browserCookieUtils is available only when using the UMD build.

API Usage

Set a cookie (basic)

import { setCookie } from 'browser-cookie-utils';

setCookie('theme', 'dark');

Creates a cookie with:

• 1 hour expiration
• path=/
• SameSite=Lax
• Secure (automatically on HTTPS)

Set a cookie with options

import { setCookie } from 'browser-cookie-utils';

setCookie('session', 'abc123', {
  timeToLive: 2,
  unit: 'hour'
});

Supported units:

• hour
• day
• month (30 days)

Set cookie with full configuration

import { setCookie } from 'browser-cookie-utils';

setCookie('user', 'sami', {
  timeToLive: 7,
  unit: 'day',
  domains: ['example.com', '.example.org'],
  path: '/',
  sameSite: 'Lax',
  secure: true
});

Available options

| Option | Type | Default | Description | | ------------ | ---------- | ---------------- | ------------------------ | | timeToLive | number | 1 | Expiration duration | | unit | string | hour | hour, day, month | | domains | string[] | current hostname | Domains to set cookie on | | path | string | / | Cookie path | | sameSite | string | Lax | Lax, Strict, None | | secure | boolean | auto | Forced Secure flag |

Cross-site cookies (SameSite=None)

import { setCookie } from 'browser-cookie-utils';

setCookie('crossSite', 'true', {
  sameSite: 'None',
  secure: true
});

⚠️ Browsers require Secure when using SameSite=None.

Get a cookie

import { getCookie } from 'browser-cookie-utils';

const theme = getCookie('theme');

Returns:

• string if found
• null if not found

Delete a cookie

import { deleteCookie } from 'browser-cookie-utils';

deleteCookie('theme');

Delete with options (recommended)

import { deleteCookie } from 'browser-cookie-utils';

deleteCookie('user', {
  domains: ['example.com'],
  path: '/',
  sameSite: 'Lax',
  secure: true
});

⚠️ For deletion to succeed, domain, path, secure, and sameSite must match the original cookie.

Browser (UMD) usage: When using the UMD build via a <script> tag, replace imported functions with browserCookieUtils.*.

Migration Guide (v1.x → v2.0.0)

Version 2.0.0 introduces a breaking API change to improve flexibility and align with modern browser cookie requirements.

What changed?

The setCookie and deleteCookie functions now accept an options object instead of positional arguments.

setCookie migration

Before (v1.x):

browserCookieUtils.setCookie('theme', 'dark', 2, 'day', ['.example.com']);

After (v2.0.0):

browserCookieUtils.setCookie('theme', 'dark', {
  timeToLive: 2,
  unit: 'day',
  domains: ['.example.com']
});

deleteCookie migration

Before (v1.x):

browserCookieUtils.deleteCookie('theme', ['.example.com']);

After (v2.0.0):

browserCookieUtils.deleteCookie('theme', {
  domains: ['.example.com']
});

Why the change?

• Clearer, self-documenting API
• Easier future extensions
• Better alignment with modern cookie attributes (SameSite, Secure, path)

If you need the old behavior, continue using v1.x, which remains stable.

Security behavior

• Automatically adds Secure on HTTPS
• Supports modern SameSite rules
• Uses encodeURIComponent / decodeURIComponent
• Sets path=/ by default
• Does not set HttpOnly (not possible via JavaScript)

Browser support

• All modern evergreen browsers
• Works without polyfills
• No reliance on deprecated APIs

License

MIT © Sami Ahmed Siddiqui