js-cookie — Lightweight JavaScript Cookie API

Introduction

js-cookie is a tiny JavaScript library that provides a clean, intuitive API for reading, writing, and deleting browser cookies. It works across all browsers without any dependencies and weighs under 800 bytes gzipped, making it ideal for any web project that needs cookie management without the overhead of larger utility libraries.

What js-cookie Does

• Provides a simple get, set, and remove API for browser cookies
• Handles automatic encoding and decoding of cookie values
• Supports JSON objects as cookie values with built-in serialization
• Allows setting expiration dates, paths, domains, and security flags
• Works with ES modules, CommonJS, and direct script tags

Architecture Overview

js-cookie is a single-module library with no external dependencies. It wraps the native document.cookie API, abstracting away the low-level string manipulation required to parse and serialize cookies. A converter pattern lets users plug in custom encoding and decoding logic. The library uses a factory function to create cookie instances, enabling multiple configurations in the same application.

Self-Hosting & Configuration

• Install via npm, Yarn, or pnpm: npm install js-cookie
• Import as an ES module or require as CommonJS
• Configure default attributes (path, domain, secure, sameSite) globally via Cookies.withAttributes()
• Create separate instances with Cookies.withConverter() for custom encoding
• Also available from CDN via a script tag for quick prototyping

Key Features

• Under 800 bytes gzipped with zero dependencies
• RFC 6265 compliant cookie handling
• Built-in JSON support for storing objects in cookies
• Custom converter API for non-standard encoding needs
• Full TypeScript type definitions included

Comparison with Similar Tools

• document.cookie (native) — raw string API with no parsing; js-cookie abstracts this
• cookie (npm) — server-side focused; js-cookie is designed for client-side use
• universal-cookie — heavier with React bindings; js-cookie stays framework-agnostic
• tough-cookie — full RFC 6265 implementation for Node.js; overkill for browser usage

FAQ

Q: Does js-cookie work with server-side rendering? A: It is a client-side library. For SSR frameworks, read cookies from the request header on the server and use js-cookie only in the browser.

Q: Can I store JSON objects? A: Yes. Pass an object to Cookies.set() and it will be JSON-stringified. Use Cookies.get() with the key to retrieve the parsed value.

Q: Is it compatible with SameSite cookie policies? A: Yes. You can set the sameSite attribute to strict, lax, or none when creating a cookie.

Q: How do I set a cookie for a specific path? A: Pass { path: '/admin' } as the third argument to Cookies.set(). Omit it to default to the root path.

Sources

• https://github.com/js-cookie/js-cookie
• https://github.com/js-cookie/js-cookie/blob/main/README.md