js-cookie

js-cookie is a tiny, dependency-free JavaScript library that provides a clean, ergonomic API for creating, reading, and deleting HTTP cookies in the browser. It wraps the awkward document.cookie string interface behind straightforward set, get, and remove methods, handling encoding, attribute serialization, and RFC 6265 compliance automatically.

At under 800 bytes gzipped with no dependencies, it supports ES modules, AMD, and CommonJS, works across an extensive range of browsers, and lets you configure attribute defaults, per-call attributes, and custom encoding/decoding converters. It has become one of the most widely used cookie utilities in the JavaScript ecosystem, downloaded tens of millions of times each week.

What You Get

• A minimal Cookies API with set, get, remove, withAttributes, and withConverter methods
• Automatic RFC 6265-compliant encoding and decoding of cookie names and values
• Configurable cookie attributes: expires, path, domain, secure, sameSite, and partitioned
• Custom read/write converters for interoperability with cookies written by other systems
• ES module, UMD, and CommonJS builds plus a namespace-conflict-safe noConflict mode

Common Use Cases

• Persisting user preferences such as theme, language, or dismissed banners across sessions
• Storing lightweight client-side state like feature flags or onboarding progress
• Reading server-set cookies (e.g. CSRF tokens or session identifiers) from JavaScript
• Managing consent and tracking opt-in/opt-out flags with explicit expiry control

Under The Hood

Architecture

js-cookie is built from three small ES modules in src/. api.mjs contains an init(converter, defaultAttributes) factory that closes over the active converter and default attributes and returns a frozen API object created via Object.create, exposing set, get, remove, withAttributes, and withConverter. set merges attributes with assign.mjs, converts numeric expires values to Date UTC strings, percent-encodes the cookie name, serializes attributes into the document.cookie string, and truncates attribute values at the first semicolon per RFC 6265 section 5.2. get splits document.cookie, decodes each name, and lazily builds a jar object, returning a single value or the whole map. converter.mjs holds the default read/write encoders, and the public entry point exports init(defaultConverter, { path: '/' }). The withAttributes and withConverter methods re-invoke init with merged state, giving an immutable, instance-per-configuration design.

Tech Stack

The library is plain ES2015-era JavaScript with no runtime dependencies. It is authored as native .mjs modules and bundled with Rollup (rollup.config.mjs) plus @rollup/plugin-terser into UMD and ES module dist artifacts. Tooling includes ESLint 10, Prettier 3, and a Grunt-driven test harness (Gruntfile.js) running QUnit suites, with Selenium WebDriver and BrowserStack for cross-browser verification and simple-git-hooks/nano-staged for pre-commit checks.

Code Quality

The source is exceptionally compact and readable — the entire API is roughly 100 lines. Tests are thorough: test/tests.js (~617 lines) and test/encoding.js (~1170 lines) exercise setting, reading, removal, attribute handling, edge-case encoding, and RFC compliance across real browsers. The get loop guards decoding with a try/catch to skip malformed cookies, and assign.mjs explicitly skips __proto__ to avoid prototype pollution. Immutability is enforced via Object.freeze on attributes and converters. There are no TypeScript types in-repo (types ship separately as @types/js-cookie).

API Design

The developer experience is a key strength: three intuitively named core methods, sensible defaults (site-wide path: '/'), and progressive configuration through withAttributes and withConverter that return new instances rather than mutating global state. Getting started requires a single import and one call. Documentation is extensive, covering every attribute, encoding behavior, converters, and namespace-conflict handling. The main friction points are cookie-removal gotchas (attributes must match those used to set) which the README calls out explicitly.