Skip to content
HTTP(S) server-side cookie handling
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Inspired by jed/cookies, but simpler (no signatures). This refactor has no dependencies and different defaults.

  • Install it at the command line:
npm install git://
  • Or put it in your package.json:
  "dependencies": {
    "cookies": "git://",


  • Somewhat lazy: All cookies are read into an object/hash, but only if one is requested. So you can attach a cookies object to the request / response in your main router, but if you never .get() or .set() a cookie,
  • Insecure: Cookies are neither httponly nor secure by default.
  • Defaults: The only out-of-the-box default is path=/.


new Cookies([request], [response])

  • request IncomingMessage | null The first argument from an http server's request event
  • response ServerResponse | null The second argument from an http server's request event

Create new cookies object, which provides get, set, and del methods.

req.cookies = new Cookies(req, res);

Cookies.attach([request], [response])

Simply attaches a new cookies object to request (or response, if request is null).


  • name String Name of the cookie

Returns the string value of the cookie. Also triggers cookies.initialize() if this is the first time a cookie has been accessed since cookies was created.

Does not require that response was set in the new Cookies(request, ...) constructor.

cookies.set(name, value, [options])

  • name String Name of the cookie
  • value String Value of the cookie
  • options Object | null Cookie settings

Adds a cookie to the queued 'Set-Cookie' headers for the current response. Can be called multiple times; it will not clear cookies previously added to the response. (Use response.removeHeader('Set-Cookie'); if you want to remove pending cookies.)

Obeys RFC 2109 (mostly) when formatting the string.

This will only set the cookie if response.headersSent is false.

Possible options:

  comment: String,
  domain: String,
  max_age: String | Number,
  path: String,               // defaults to '/'
  secure: Boolean,            // defaults to false
  version: Boolean,           // defaults to false, contrary to RFC 2109
  http_only: Boolean,         // defaults to false, not in RFC 2109
  expires: Date               // not in RFC 2109

Does not require that request was set in the new Cookies(..., response) constructor.

cookies.del(name, [options])

  • name String Name of the cookie
  • options Object | null Cookie settings

Set cookie's value to '', and it's expire date to the beginning of epoch time, i.e., new Date(0), using the same mechanism as cookies.set.

Cookies.prototype.defaults = default_options

  • default_options Object | Function Base used for all set() calls.

Set this to an object, or function that returns an object, using the possible options from the set() section.

Cookies.serialize(name, value, options)

  • name String Name of the cookie
  • value String Value of the cookie
  • options Object | null Cookie settings

Serialize a cookie name, value, and options into the string representation that the 'Set-cookie' http header requires.

Demo server.js

var Cookies = require('cookies');
var http = require('http');

Cookies.prototype.defaults = function() {
  // expire 1 month in the future
  var one_month_from_now = new Date( + (31 * 24 * 60 * 60 * 1000));
  return {
    expires: one_month_from_now, // <-- a Date object
    path: '/'

http.createServer(function(req, res) {
  req.cookies = new Cookies(req, res);

  var history = {};
  var history_json = req.cookies.get('history');
  try {
    history = JSON.parse(history_json);
  catch (exc) {
  history[req.url] = (history[req.url] || 0) + 1;

  var new_history_json = JSON.stringify(history);
  req.cookies.set('history', new_history_json);

  for (var page in history) {
    res.write('You have been to ' + page + ' ' + history[page] + ' times.\n');
}).listen(8383, '', function() {
  console.log('Serving example cookies server at localhost:8383');


Copyright © 2012-2013 Christopher Brown. MIT Licensed.

Something went wrong with that request. Please try again.