Skip to content

v2.0.0
Compare
Choose a tag to compare
@FagnerMartinsBrack FagnerMartinsBrack released this 22 Jun 00:18
v2.0.0
3641d94

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.

Assets 3