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

Do not use global object browserCookieUtils.

CJS import (Node.js / legacy bundlers):

const browserCookieUtils = require('browser-cookie-utils');

UMD / Browser Script Tag

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

jsDelivr CDN (Latest)

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

Set a cookie (basic)

browserCookieUtils.setCookie('theme', 'dark');

Creates a cookie with:

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

Set a cookie with options

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

Supported units:

• hour
• day
• month (30 days)

Set cookie with full configuration

browserCookieUtils.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)

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

⚠️ Browsers require Secure when using SameSite=None.

Get a cookie

const theme = browserCookieUtils.getCookie('theme');

Returns:

• string if found
• null if not found

Delete a cookie

browserCookieUtils.deleteCookie('theme');

Delete with options (recommended)

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

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

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