cookie-storage

library6.1.0jsnpmunverified

cookie-storage provides a Web Storage API-compatible interface for browser cookies, implementing the same methods as localStorage/sessionStorage (getItem, setItem, removeItem, clear, key, length) with additional cookie-specific options like path, domain, expires, secure, and sameSite. Current stable version is 6.1.0, released in 2023. The library is lightweight, ships TypeScript definitions, and supports ESM imports. Unlike raw document.cookie manipulation, it offers a cleaner API and automatic cookie string encoding/decoding. It is ideal for cross-browser cookie management with a familiar storage interface, but note that cookie storage is limited to ~4KB per cookie and 20-50 cookies per domain.

storage

npm install cookie-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · COOKIE-STORAGE

cookie-storage

storagejavascriptv6.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CookieStorage

✓ import { CookieStorage } from 'cookie-storage'

✗ import CookieStorage from 'cookie-storage'

Export is named, not default. ESM-only since v6; no CommonJS support.

CookieStorageOptions

✓ import type { CookieStorageOptions } from 'cookie-storage'

✗ import { CookieStorageOptions } from 'cookie-storage'

Options interface is a type; use type import for TypeScript.

CookieStorage

✓ const { CookieStorage } = require('cookie-storage')

✗ const CookieStorage = require('cookie-storage')

CommonJS require with destructuring for named export. Only works if your bundler supports ESM interop; official support is ESM.

Demonstrates creating a CookieStorage instance, setting/getting cookies with options, iterating over storage, and removing/clearing cookies.

import { CookieStorage } from 'cookie-storage'; const cookieStorage = new CookieStorage(); // Set a cookie with options cookieStorage.setItem('username', 'john_doe', { path: '/', secure: true, sameSite: 'Lax' }); // Get a cookie const username = cookieStorage.getItem('username'); console.log(username); // 'john_doe' // List all cookies for (let i = 0; i < cookieStorage.length; i++) { console.log(`${cookieStorage.key(i)}: ${cookieStorage.getItem(cookieStorage.key(i))}`); } // Remove a cookie cookieStorage.removeItem('username'); // Clear all cookies cookieStorage.clear();

Debug

Known issues

breakingVersion 6.0.0 removed CommonJS (CJS) support. Only ESM imports are now valid.

fix

Update your import to ESM syntax: import { CookieStorage } from 'cookie-storage'

affects: >=6.0.0

deprecatedIn versions 5.x and earlier, the exported class was called 'CookieStorage' but could also be imported as default. This was removed in v6.

fix

Switch to named import: import { CookieStorage } from 'cookie-storage'

affects: >=5.0.0 <6.0.0

gotchaCookieStorage is not synchronized across browser tabs. Changes made in one tab are not reflected in another until the page reloads.

fix

Use a storage event listener or consider using localStorage for cross-tab sync.

affects: *

gotchaThe 'key(index)' method returns cookie names in no guaranteed order; order may vary across browsers and over time.

fix

Do not rely on order; iterate via length and key() if needed, but prefer storing a list of keys manually.

affects: *

gotchaCookie size limit (~4096 bytes per cookie) and per-domain count limit (~50 cookies) apply. If exceeded, setItem may fail silently.

fix

Keep cookie sizes small and monitor total count. Use chunking or alternative storage for large data.

affects: *

Errors

Common errors & fixes

Uncaught TypeError: CookieStorage is not a constructor

Using default import instead of named import in ESM

fix

Change to: import { CookieStorage } from 'cookie-storage'

Error: Cannot find module 'cookie-storage'

Package not installed or CommonJS require with wrong path

fix

Run 'npm install cookie-storage' and use correct import: const { CookieStorage } = require('cookie-storage')

TypeError: cookieStorage.getItem is not a function

Forget to instantiate CookieStorage (using the class directly)

fix

Add 'new': const cookieStorage = new CookieStorage()

CookieStorage is not defined

Using in a non-browser environment (Node.js, SSR) without a cookie polyfill

fix

Ensure document.cookie is available. For Node, use a cookie parser package or mock the API.

Upgrade

Version history

6.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/bouzuya/cookie-storage ↗

packagecookie-storage ↗

homepagehttps://github.com/bouzuya/cookie-storage ↗