Tiny cookies library for the browser
- Features
- Browser compatibility
- Installation
- Usage
- API
- Options
- Examples
- How to use with PHP
- How to shim browser-cookies on node
- Clean and easy to use API
- Small footprint (minified and gzipped ~ 0.5kB)
- No dependencies
- RFC6265 compliant
- Cross browser support
- Supports CommonJS (e.g. Browserify)
Cross browser support is verified on real browsers using automated testing:
Or run the unit tests right now in your current browser.
Using NPM
npm install browser-cookies
Using Bower
bower install browser-cookies
var cookies = require('browser-cookies');
cookies.set('firstName', 'Lisa');
cookies.set('firstName', 'Lisa', {expires: 365}); // Expires after 1 year
cookies.set('firstName', 'Lisa', {secure: true, domain: 'www.example.org'});
cookies.get('firstName'); // Returns cookie value (or null)
cookies.erase('firstName'); // Removes cookie
cookies.all(); // Get all cookies
API contents:
- method cookies.set(
name
,value
[,options
]) - method cookies.get(
name
) - method cookies.all()
- method cookies.erase(
name
, [,options
]) - property cookies.defaults
cookies.set(name
, value
[, options
])
Method to save a cookie.
argument | type | description |
---|---|---|
name |
string | The name of the cookie to save. |
value |
string | The value to save, percent encoding will automatically be applied. |
options |
object | May contain any of the properties specified in options below. If an option is not specified, the value configured in cookies.defaults will be used. |
cookies.get(name
)
Method that returns a cookie value, or null if the cookie is not found. Percent encoded values will automatically be decoded.
argument | type | description |
---|---|---|
name |
string | The name of the cookie to retrieve. |
cookies.all()
Method to get all cookies
cookies.erase(name
[, options
])
Method to remove a cookie.
argument | type | description |
---|---|---|
name |
string | The name of the cookie to remove. |
options |
object | May contain the domain and path properties specified in options below. If an option is not specified, the value configured in cookies.defaults will be used. |
cookies.defaults
This object may be used to change the default value of each option specified in options below.
The options shown in the table below may be set globally using cookies.defaults or passed as function argument to cookies.set() and cookies.get(). Also check out the Examples further below.
Name | Type | Default | Description |
---|---|---|---|
expires |
Number , Date , String |
0 |
Configure when the cookie expires by using one of the following types as value:
|
domain |
String |
"" |
The domain from where the cookie is readable.
|
path |
String |
"/" |
The path from where the cookie is readable.
|
secure |
Boolean |
false |
If true the cookie will only be transmitted over secure protocols like https. |
httponly |
Boolean |
false |
If true the cookie may only be read by the web server.
|
Count the number of a visits to a page:
var cookies = require('browser-cookies');
// Get cookie value
var visits = cookies.get('count') || 0;
console.log("You've been here " + parseInt(visits) + " times before!");
// Increment the counter and set (or update) the cookie
cookies.set('count', parseInt(visits) + 1, {expires: 365});
JSON may be saved by converting the JSON object into a string:
var cookies = require('browser-cookies');
// Store JSON data
var user = {firstName: 'Sofia', lastName: 'Dueñas'};
cookies.set('user', JSON.stringify(user))
// Retrieve JSON data
var userString = cookies.get('user');
alert('Hi ' + JSON.parse(userString).firstName);
The default cookie options may be changed:
var cookies = require('browser-cookies');
// Override defaults
cookies.defaults.secure = true;
cookies.defaults.expires = 7;
// 'secure' option enabled and cookie expires in 7 days
cookies.set('FirstName', 'John')
// 'secure' option enabled and cookie expires in 30 days
cookies.set('LastName', 'Smith', {expires: 30})
Use setrawcookie() instead of setcookie()
to prevent PHP from replacing spaces with +
characters:
// Set cookie
setrawcookie('fullName', rawurlencode('Lisa Cuddy'));
// Get cookie
$_COOKIE['fullName'];
The package browser-cookies-shim provides a browser-cookies shim for node, which may be useful to run client javascript on node without errors.
- Distribution:
- Generate build for use without a loader (development build + minified version).
- Cross browser consistency:
- When a domain is not specified most browsers only allow an exact domain match, but IE sends cookies to all subdomains. Could ensure cookies are saved to all subdomains by default for consistent behavior amongst all browsers? or perhaps add a note to set the domain explicitly for proper cross-browser consistency?
The design goal is to provide to smallest possible size (when minified and gzipped) for the given API while remaining compliant to RFC6265 and providing cross-browser compatibility and consistency.
Development setup (requires node and git to be installed):
git clone https://github.com/voltace/browser-cookies.git
cd browser-cookies
npm install # Install dev dependencies
npm run test:local # Run unit tests locally (takes ~5 seconds)
npm run build # Create minified version
Feel free to add an issue on GitHub for any questions, bug or feature request you may have.
Public Domain (UNLICENSE)