PersistJS: Cross Browser Client-Side Persistent Storage Without Cookies

I just released PersistJS, a client-side JavaScript persistent storage library. Features include:

  • Small (9.3k minified, 3k gzipped)
  • Standalone: Does not need any additional browser plugins or JavaScript libraries to work on the vast majority of current browsers.
  • Consistent: Provides a consistent, opaque API, regardless of the browser.
  • Extensible: Custom backends can be added easily.
  • Backwards Compatible: Can fall back to flash or cookies if no client-side storage solution for the given browser is available.
  • Forwards Compatible: Supports the upcoming versions of Internet Explorer, Firefox, and Safari (Opera too, if you have Flash).
  • Unobtrusive: Capability testing rather than browser detection, so newer standards-compliant browsers will automatically be supported.

If you already know why this is awesome, then you can skip straight to the download. If you're scratching your head, then read on...

Why This is Awesome

Why use PersistJS? What's the problem with using cookies directly or simply requiring Flash?

Currently the only reliable cross-platform and cross-browser mechanism for storing data on the client side are cookies. Unfortunately, using cookies to store persistent data has several problems:

  • Size: Cookies are limited to about 4 kilobytes in size.
  • Bandwidth: Cookies are sent along with every HTTP transaction.
  • Complexity: Cookies are difficult to manipulate correctly.

Modern web browsers have addressed these issues by adding non-Cookie mechanisms for saving client-side persistent data. Each of these solutions are simpler to use than cookies, can store far more data, and are not transmitted along with HTTP requests. Unfortunately, each browser has addressed the problem in a different and incompatible way. There are currently 4 different client side persistent data solutions:

  • globalStorage: Firefox 2.0+, Internet Explorer 8
  • localStorage: development WebKit
  • openDatabase: Safari 3.1+
  • userdata behavior: Internet Explorer 5.5+

Some developers have attempted to address the client side storage issue with the following browser plugins:

  • Adobe Flash
  • Google Gears

The problem with relying on plugins, of course, is that users without the plugin installed miss out on the feature in question, and your application is dependent on software from a particular vendor. Google Gears, for example, is not widely deployed. Flash is, but it has problems of its own:

  • Many users block Flash or require a click in order to enable flash content; this makes Flash unsuitable as a transparent, client-side data store.
  • Flash is notoriously unreliable on newer 64-bit machines.
  • Some businesses block Flash content as a security measure.

Anyway, if we include Gears and Flash, that means there are no less than 6 incompatible solutions for storing client-side persistent data.

The most notable attempt at addressing this problem is probably Dojo Storage. Unfortunately, Dojo Storage does not support Internet Explorer without Flash, and it does not support Safari or other WebKit-based browsers at all (at least, not without Flash). Also, Dojo Storage is not standalone; it requires a several other Dojo components in order to operate.

PersistJS addresses all of the issues above. It currently supports persistent client-side storage through the following backends:

  • flash: Flash 8 persistent storage.
  • gears: Google Gears-based persistent storage.
  • localstorage: HTML5 draft storage.
  • whatwg_db: HTML5 draft database storage.
  • globalstorage: HTML5 draft storage (old spec).
  • ie: Internet Explorer userdata behaviors.
  • cookie: Cookie-based persistent storage.

Each backend exploses the exact same interface, which means you don't have to know or care which backend is being used.


Here are some simple examples of PersistJS in use:

// create a new client-side persistent data store
var store = new Persist.Store('My Data Store');

// pretend data
var data = "pretend this is really long data that won't fit in a cookie";

// save data in store
store.set('saved_data', data);

That's all there is to creating a persistent store and adding some data to it. Fetching data back from the store uses a callback function (to support asyncronous backends), but it's still pretty simple to use:

// get data back from store, and prompt user with it
store.get('saved_data', function(ok, val) {
  if (ok)
    alert('saved data = ' + val);

Removing data is pretty easy too:

// remove data from store

Although it isn't necessary, you can also get some information about the detected backend using the Persist.type and Persist.size attributes:

// build alert message
var info = [
  'Backend: ',
  Persist.type || 'none',
  ', ',
  'Approximate Size Limit: ',
  (Persist.size < 0) ? 'unknown' : Persist.size 

// prompt user with information

Finally, if you don't want a particular backend used under any circumstances, you can disable it using the Persist.remove() function:

// never use cookies for persistent storage


This is the initial release, so there are bound to be some bugs. PersistJS has been tested with FireFox 2.0, FireFox 3.0rc1, IE7, and Safari 3.1. The Gears and Flash backends work where Gears and Flash 8 are supported.

The most notable omission here is IE6; it should work, but I don't have IE6 handy at the moment (MultipleIEs is temporarily busted).

Commenting is still busted around here, so any comments should sent via email or posted on the Reddit thread.