localForage

localForage is a JavaScript library that improves the offline experience of your web app by using asynchronous storage (via IndexedDB or WebSQL where available) with a simple, localStorage-like API.

localForage uses localStorage in browsers with no IndexedDB or WebSQL support. Asynchronous storage is available in the current versions of all major browsers: Chrome, Firefox, IE, and Safari (including Safari Mobile). See below for detailed compatibility info.

To use localForage, just drop a single JavaScript file into your page:

<script src="localforage.js"></script>
<script>localforage.getItem('something', myCallback);</script>

Download the latest localForage from GitHub, or install with bower:

bower install localforage

Supported Browsers/Platforms

localForage works in all modern browsers (IE 8 and above). Asynchronous storage is available in all browsers in bold, with localStorage fallback in parentheses.

Android Browser 2.1
Blackberry 7
Chrome 23 (Chrome 4.0+ with localStorage)
Chrome for Android 32
Firefox 10 (Firefox 3.5+ with localStorage)
Firefox for Android 25
Firefox OS 1.0
IE 10 (IE 8+ with localStorage)
IE Mobile 10
Opera 15 (Opera 10.5+ with localStorage)
Opera Mobile 11
Phonegap/Apache Cordova 1.2.0
Safari 3.1 (includes Mobile Safari)

Different browsers have different storage limits, so plan accordingly.

Note that, thanks to WebSQL support, apps packaged with Phonegap will also use asynchronous storage. Pretty slick!

Support

Lost? Need help? Try the localForage API documentation.

If you're stuck using the library, running the tests, or want to contribute, to localForage, you can visit irc.mozilla.org and head to the #apps channel to ask questions about localForage.

The best person to ask about localForage is tofumatt, who is usually online from 8am-10pm Eastern Time.

How to use localForage

Callbacks

Because localForage uses async storage, it has an async API. It's otherwise exactly the same as the localStorage API.

// In localStorage, we would do:
localStorage.setItem('key', JSON.stringify('value'));
doSomethingElse();

// With localForage, we use callbacks:
localforage.setItem('key', 'value', doSomethingElse);

Similarly, please don't expect a return value from calls to localforage.getItem(). Instead, use a callback:

// Synchronous; slower!
var value = JSON.parse(localStorage.getItem('key'));
alert(value);

// Async, fast, and non-blocking!
localforage.getItem('key', alert);

You can store any type in localForage; you aren't limited to strings like in localStorage. Even if localStorage is your storage backend, localForage automatically does JSON.parse() and JSON.stringify() when getting/setting values.

Promises

Promises are pretty cool! If you'd rather use promises than callbacks, localForage supports that too:

function doSomethingElse(value) {
    console.log(value);
}

// With localForage, we allow promises:
localforage.setItem('key', 'value').then(doSomethingElse);

localForage relies on native ES6 Promises, but ships with an awesome polyfill for browsers that don't support ES6 Promises yet.

Storing Blobs, TypedArrays, and other JS objects

localForage supports storing all native JS objects that can be serialized to JSON, as well as ArrayBuffers, Blobs, and TypedArrays. Check the API docs for a full list of types supported by localForage.

All types are supported in every storage backend, though storage limits in localStorage make storing many large Blobs impossible.

Driver Selection (i.e. forcing localStorage)

For development, it can be easier to use the slower--but easier to debug--localStorage driver (mostly because localStorage can easily be inspected from the console). You can use the setDriver() method to change the driver localForage is using at any time.

// If you aren't using JS modules, things are loaded synchronously.
localforage.setDriver('localStorageWrapper');
alert(localforage.driver());
  => 'localStorageWrapper'

// If you're using modules, things load asynchronously, so you should use
// callbacks or promises to ensure things have loaded.
localforage.setDriver('localStorageWrapper', function() {
    alert(localforage.driver());
});
  => 'localStorageWrapper'

// The promises version:
localforage.setDriver('localStorageWrapper').then(function() {
    alert(localforage.driver());
});
  => 'localStorageWrapper'

You can actually force any available driver with this method, but given that the best driver will be selected automatically when the library is loaded, this method is mostly useful in forcing localStorage.

Note that trying to load a driver unavailable on the current browser (like trying to load WebSQL in Gecko) will fail and the previously loaded "best choice" will continue to be used.

Configuration

You can set database information, by giving the window.localForageConfig variable a hash of options. Available options are name, storeName, version, and description.

Example:

localforage.config({
    name        : 'myApp',
    version     : 1.0,
    size        : 4980736, // Size of database, in bytes. WebSQL-only for now.
    storeName   : 'keyvaluepairs',
    description : 'some description'
});

Note: you must call config() before you interact with your data. This means calling config() before using getItem(), setItem(), removeItem(), clear(), key(), or length().

RequireJS

You can use localForage with RequireJS, but note that because of the way drivers are loaded using RequireJS, you'll want to make sure localforage.ready's Promise has been fulfilled to ensure all of localForage is ready to use before you make set/get calls. Essentially, to use localForage with RequireJS, your code should look like this:

define(['localforage'], function(localforage) {
    // As a callback:
    localforage.ready(function() {
        localforage.setItem('mykey', 'myvalue', console.log);
    });

    // With a Promise:
    localforage.ready().then(function() {
        localforage.setItem('mykey', 'myvalue').then(console.log);
    });
});

Web Workers

Web Worker support in Firefox is blocked by bug 701634. Until it is fixed, web workers are not officially supported by localForage.

Framework Support

If you use a framework listed, there's a localForage storage driver for the models in your framework so you can store data offline with localForage. We have drivers for the following frameworks:

If you have a driver you'd like listed, please open an issue to have it added to this list.

Working on localForage

You'll need node/npm, bower, and Grunt.

To work on localForage, you should start by forking it and installing its dependencies. Replace USERNAME with your GitHub username and run the following:

git clone git@github.com:USERNAME/localForage.git
cd localForage
npm install
bower install

Omitting the bower dependencies will cause the tests to fail!

Running Tests

You need PhantomJS installed to run local tests. Run npm test (or, directly: grunt test). Your code must also pass the linter.

localForage is designed to run in the browser, so the tests explicitly require a browser environment. Local tests are run on a headless WebKit (using PhantomJS), but cross-browser tests are run using Sauce Labs.

If you have Sauce Labs credentials on your machine, localForage will attempt to connect to Sauce Labs to run the tests on Sauce Labs as well. To skip Sauce Labs tests, run grunt test:local.

When you submit a pull request, tests will be run against all browsers that localForage supports.

License

This program is free software; it is distributed under an Apache License.

thebengeu/localForage