• Remove npm version restriction in package.json - #818

• Publish to npmjs.com with package provenance

• Make package.json accessible in export - #727

• Removed defaults in favor of a builder: now to supply an api instance with particular predefined (cookie) attributes there's Cookies.withAttributes(), e.g.:

const api = Cookies.withAttributes({
  path: '/',
  secure: true
})
api.set('key', 'value') // writes cookie with path: '/' and secure: true...

• The attributes that an api instance is configured with are exposed as attributes property; it's an immutable object and unlike defaults cannot be changed to configure the api.
• The mechanism to fall back to the standard, internal converter by returning a falsy value in a custom read converter has been removed. Instead the default converters are now exposed as Cookies.converter, which allows for implementing self-contained custom converters providing the same behavior:

const customReadConverter = (value, name) => {
  if (name === 'special') {
    return unescape(value)
  }
  return Cookies.converter.read(value)
}

• withConverter() no longer accepts a function as argument to be turned into a read converter. It is now required to always pass an object with the explicit type(s) of converter(s):

const api = Cookies.withConverter({
  read: (value, name) => unescape(value)
})

• The converter(s) that an api instance is configured with are exposed as converter property; it's an immutable object and cannot be changed to configure the api.
• Started providing library as ES module, in addition to UMD module. The module field in package.json points to an ES module variant of the library.
• Started using browser field instead of main in package.json (for the UMD variant of the library).
• Dropped support for IE < 10.
• Removed built-in JSON support, i.e. getJSON() and automatic stringifying in set(): use Cookies.set('foo', JSON.stringify({ ... })) and JSON.parse(Cookies.get('foo')) instead.
• Removed support for Bower.
• Added minified versions to package - #501
• Improved support for url encoded cookie values (support case insensitive encoding) - #466, #530
• Expose default path via API - #541
• Handle falsy arguments passed to getters - #399
• No longer support Node < 12 when building (LTS versions only)

Reverted changes introduced in rc2, which caused a mayor breaking change in the case of requesting the library via jsdelivr CDN with a particular file name. This breaking change was not intentional.

The problem was that we've been advertising the following link in the readme on the master branch:

https://cdn.jsdelivr.net/npm/js-cookie@rc/dist/js.cookie.min.js

while the respective change had changed that file name in the distribution to js.cookie.umd.min.js.

Nonetheless, we advise to always use the latest stable version in production environments.

• Fixed paths in exports field in package.json - #695

• Improved module setup in package.json to account for older Node.js versions - #666
• Reverted using browser field instead of main in package.json (for the UMD variant of the library): bundlers by default prefer it over module and will end up with a UMD module where ES may be preferred - #666

• Fixed regression where in Safari cookie values containing non-ASCII characters were no longer written correctly - #623

• Revisited encoding/decoding implementation: we start to only encode characters in the cookie name and value that are strictly necessary (";" and "=" in the cookie name, and ";" in the cookie value; using percent-encoding). The stricter implementation so far was based on the requirements for server implementations in the RFC 6265 spec (section 4), but for user agents more liberal rules apply (section 5.2) - #595, #590

• Fixed importing ES module when not using a bundler - #583
• Made attributes + converter properties on api instance immutable again

• Fixed noConflict() no longer being present; as a result the api instance is no longer immutable again - #580

• Removed defaults in favor of a builder: now to supply an api instance with particular predefined (cookie) attributes there's Cookies.withAttributes(), e.g.:

const api = Cookies.withAttributes({
  path: '/',
  secure: true
})
api.set('key', 'value') // writes cookie with path: '/' and secure: true...

• The attributes that an api instance is configured with are exposed as attributes property; it's an immutable object and unlike defaults cannot be changed to configure the api.
• The mechanism to fall back to the standard, internal converter by returning a falsy value in a custom read converter has been removed. Instead the default converters are now exposed as Cookies.converter, which allows for implementing self-contained custom converters providing the same behavior:

const customReadConverter = (value, name) => {
  if (name === 'special') {
    return unescape(value)
  }
  return Cookies.converter.read(value)
}

• withConverter() no longer accepts a function as argument to be turned into a read converter. It is now required to always pass an object with the explicit type(s) of converter(s):

const api = Cookies.withConverter({
  read: (value, name) => unescape(value)
})

• The converter(s) that an api instance is configured with are exposed as converter property; it's an immutable object and cannot be changed to configure the api.
• The entire api instance is now immutable.

• Started providing library as ES module, in addition to UMD module. The module field in package.json points to an ES module variant of the library.
• Started using browser field instead of main in package.json (for the UMD variant of the library).
• Dropped support for IE < 10.
• Removed getJSON(): use Cookies.set('foo', JSON.stringify({ ... })) and JSON.parse(Cookies.get('foo')) instead.
• Removed support for Bower.
• Added minified versions to package - #501
• Improved support for url encoded cookie values (support case insensitive encoding) - #466, #530
• Expose default path via API - #541
• Handle falsy arguments passed to getters - #399
• No longer support Node 6 when building (LTS versions only).
• From < 900 bytes gzipped to < 800 bytes gzipped.

• #400: Prevent XSS in the cookie attributes
• #350: Document npm package manager usage

• https://github.com/js-cookie/js-cookie/pull/221: Only include files in src/ when building the npm package.
• https://github.com/js-cookie/js-cookie/pull/293: Allow undocumented attributes to be passed when creating a cookie
• https://github.com/js-cookie/js-cookie/issues/276#issuecomment-268697509: Support for SameSite cookie (Strict vs Lax)
• https://github.com/js-cookie/js-cookie/pull/371: Add jsDelivr CDN to the README (Update is supported by jsDelivr and the community)
• https://github.com/js-cookie/js-cookie/issues/363: getJSON() does not work on cookie with escaped quotes

• https://github.com/js-cookie/js-cookie/issues/321: Create a security disclosure e-mail
• https://github.com/js-cookie/js-cookie/pull/291: Fix the "converters" header link in the README
• https://github.com/js-cookie/js-cookie/pull/273: Add more information about #remove method

• #205: Add expired cookie detail to docs
• #215: Clarify the interoperability of default encoding
• #207: Add support for uglifyJS 'unsafe' option
• #223: Create an example in the docs for creating a cookie that expire in hours/minutes
• #225: Add a note in the README for cookies that expires in less than a day
• #250: Do not parse as JSON when window has a truthy 'json' prop
• #239: Add support for ES6 module imports
• #257: Register in AMD and UMD if both available

• #189, #180, #177: Minor documentation improvements
• #204: Fix the docs, because It is not necessary the secure attribute when removing a cookie
• #196: Should not throw a Malformed URI Error when an unrelated cookie contains a malformed percent-encoding name according to the default encoding mechanism

• #164: The library should not throw an error if the methods are used in node
• #145: Should not create a cookie if the .set() API is used incorrectly
• #130: Document Tomcat 8.0.15 non-compliance with RFC 6265 and workaround
• #171: Consider when js-cookie is included after a script that doesn't use semicolon

• #71: Add write converters
• https://github.com/js-cookie/js-cookie/commit/591e663c85f4c6edcc4a283eba67f0e8067fdf81: Add examples do handle server-side incompatibilities using the write converters
• https://github.com/js-cookie/js-cookie/commit/d832048dcf6526081c773f2014815292b7135827: Document the Wiki Pages as a feature of the project

• #68: The JSON-js polyfill requirement in the README should not include IE8
• #91: Enhance the docs to clarify the browser behavior for the domain attribute
• #99: Add license info in bower.json in order to release with webjars
• #83: Remove unnecessary files from bower package

• #62: Fix a Malformed URI error for getting a cookie when an unrelated one was encoded using escape
• #64: Fix the documentation, the converter is not executed for the .remove() method

• #54: Fixed an issue with expires attribute set to false

• Fix npm publication. Only tagged releases should appear as published, the temporary version 2.1.0-pre should not.

RFC 6265 compliance

js-cookie respects the RFC 6265 proposed standard, which was proposed in April 2011 and specifies how all modern browsers currently interpret cookie handling.

Breaking changes

js-cookie v2 is not backwards compatible with jquery-cookie or js-cookie v1.

Below is the list of everything that was changed, along with the new equivalent feature (if applicable).

jQuery ($) is removed

jQuery is not necessary anymore. Below is the list of old methods and their new equivalent.

$.cookie('name', 'value') -> Cookies.set('name', 'value') $.cookie('name') -> Cookies.get('name') $.removeCookie('name') -> Cookies.remove('name') $.cookie() -> Cookies.get()

For more information, check the discussion.

raw config is removed, use converters

js-cookie encodes the cookie name/value automatically using UTF-8 percent encoding for each character that is not allowed according to the RFC 6265.

You can simulate the same behavior of raw = true by instantiating a converter that returns the original value to bypass the default decoding:

var RawCookies = Cookies.withConverter(function(value) {
    return value;
});
RawCookies.get('name'); // The returned value was not decoded

Note: simply bypassing the encoding is a bad practice, if your cookie contains an invalid character, it will NOT work in some browsers like Safari or IE.

For more information, check the converters docs.

json config is removed, use Cookies.getJSON()

If you pass a Plain Object Literal or Array to the value, js-cookie will stringify it. To retrieve the parsed value, just call the cookie using Cookies.getJSON('name').

For more information, check the docs.

path now is default to the whole site '/'

What was known as "options" is now documented as "attributes". In the last versions, the default value for the path option was delegated to the browser defaults (valid to the path of the current page where each cookie is being set). Now, the default path attribute is the whole site /.

To remove, set or declare defaults to the path of the current page, you just need to declare it as empty:

Cookies.defaults.path = '';

Deleting the property will fallback to path: / internally:

delete Cookies.defaults.path;

For more information, check the details.

Cookies.remove() return value is not defined

Previously, $.removeCookie() and Cookies.remove() returned either true or false based on whether the cookie was successful deleted or not. Now its returned value should be considered undefined and not be relied upon.

For more information, check the details.

• #24: Add the .noConflict() method to the Cookies namespace

• Rename jquery-cookie to js-cookie
• carhartl/jquery-cookie#349: Make jquery as an optional dependency. $.cookie is deprecated.
• Create a new api for handling cookies without jquery
• carhartl/jquery-cookie#330: Added support for returning the new api in CommonJS environments