es-cookie

What is es-cookie?

The es-cookie npm package is a simple and lightweight JavaScript library for handling cookies in the browser. It provides an easy-to-use API for setting, getting, and deleting cookies.

What are es-cookie's main functionalities?

Set a Cookie

This feature allows you to set a cookie with a specified name and value. The optional third parameter can be used to set additional cookie attributes such as expiration time, path, domain, and secure flag.

esCookie.set('name', 'value', { expires: 7 });

Get a Cookie

This feature allows you to retrieve the value of a cookie by its name. If the cookie does not exist, it returns undefined.

const value = esCookie.get('name');

Delete a Cookie

This feature allows you to delete a cookie by its name. You can also specify additional attributes to ensure the correct cookie is removed.

esCookie.remove('name');

Other packages similar to es-cookie

js-cookie

js-cookie is a popular JavaScript library for handling cookies. It offers a similar API to es-cookie but with more advanced features and better support for various environments. It is widely used and well-documented, making it a reliable choice for managing cookies.

cookie_js

cookie_js is another library for managing cookies in the browser. It provides a straightforward API for setting, getting, and deleting cookies. While it is less popular than js-cookie, it is still a viable alternative to es-cookie with similar functionalities.

tiny-cookie

tiny-cookie is a lightweight library for handling cookies. It offers a minimalistic API for basic cookie operations. It is smaller in size compared to js-cookie and es-cookie, making it a good choice for projects where bundle size is a concern.

README

es-cookie

A simple, lightweight module for handling cookies

• Includes TypeScript definitions
• Works with Webpack, Rollup, and Browserify module bundlers
• Fully compliant with RFC 6265
• No dependencies other than an Object.assign polyfill if using Internet Explorer (core-js is recommended)
• Originally based on js-cookie, but rewritten as a TypeScript module with a lean, type-safe API

Installation

npm install es-cookie --save

Usage

Import module:

import * as Cookies from 'es-cookie';

Create a cookie, valid across the entire site:

Cookies.set('name', 'value');

Create a cookie that expires 7 days from now, valid across the entire site:

Cookies.set('name', 'value', { expires: 7 });

Create an expiring cookie, valid to the path of the current page:

Cookies.set('name', 'value', { expires: 7, path: '' });

Read cookie:

Cookies.get('name'); // => 'value'
Cookies.get('nothing'); // => undefined

Read all visible cookies:

Cookies.getAll(); // => { name: 'value' }

Delete cookie:

Cookies.remove('name');

Delete a cookie valid to the path of the current page:

Cookies.set('name', 'value', { path: '' });
Cookies.remove('name'); // fail!
Cookies.remove('name', { path: '' }); // removed!

IMPORTANT! when deleting a cookie, you must pass the exact same path and domain attributes that was used to set the cookie, unless you're relying on the default attributes.

Note: Removing a non-existant cookie does not raise an exception or return a value.

Encoding

This project is RFC 6265 compliant. All special characters that are not allowed in the cookie-name or cookie-value are encoded with each one's UTF-8 Hex equivalent using percent-encoding.

The only character in cookie names or values that is allowed and still encoded is the percent % character. It is escaped in order to interpret percent input as literal. Please note that the default encoding/decoding strategy is meant to be interoperable between cookies that are read/written by es-cookie.

Attributes

expires

Define when the cookie will be removed. Value can be a Number which will be interpreted as days from time of creation or a Date instance. If omitted, the cookie becomes a session cookie.

To create a cookie that expires in less than a day, use a Date object.

Default: Cookie is removed when the user closes the browser.

Examples:

Cookies.set('name', 'value', { expires: 365 });
Cookies.get('name'); // => 'value'
Cookies.remove('name');

path

A String indicating the path where the cookie is visible.

Default: /

Examples:

Cookies.set('name', 'value', { path: '' });
Cookies.get('name'); // => 'value'
Cookies.remove('name', { path: '' });

domain

A String indicating a valid domain where the cookie should be visible. The cookie will also be visible to all subdomains.

Default: Cookie is visible only to the domain or subdomain of the page where the cookie was created.

Examples:

Assuming a cookie that is being created on site.com:

Cookies.set('name', 'value', { domain: 'subdomain.site.com' });
Cookies.get('name'); // => undefined (need to read at 'subdomain.site.com')

secure

Either true or false, indicating if the cookie transmission requires a secure protocol (https).

Default: No secure protocol requirement.

Examples:

Cookies.set('name', 'value', { secure: true });
Cookies.get('name'); // => 'value'
Cookies.remove('name', { secure: true });

Author

Theodore Brown
http://theodorejb.me

License

MIT

Changelog

[1.0.1] - 2017-02-05

Fixed

• Homepage/issues links in package.json.