Releases: js-cookie/js-cookie
v2.1.0
v2.0.4
v2.0.3
v2.0.2
v2.0.1
- Fix npm publication. Only tagged releases should appear as published, the temporary version
2.1.0-pre
should not.
v2.0.0
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.
v2.0.0-beta.1
jquery-cookie breaking changes
The following changes are not backward compatible with previous versions. The latest backward compatible version that exposes the Cookies
API and uses jQuery is the version 1.5.1.
For more information, check the docs of the version 1.5.1
$ was removed
jQuery dependency was removed. 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 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 the 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.
v1.5.1
v1.5.0
- 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
v1.4.1
- Added support for CommonJS.
- Added support for package managers: Jam (http://jamjs.org), volo (http://volojs.org), Component (http://component.io), jspm (http://jspm.io).
- The expires option now interpretes fractions of numbers (e.g. days) correctly.