localForage is a handy library that improves the offline experience of your web
app by using asynchronous storage (via IndexedDB or WebSQL where available) but
with a simple, localStorage-like API.
localForage includes a localStorage-backed fallback store for 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.
localForage works in all modern browsers (IE 8 and above). Asynchronous storage is available in all browsers in bold, with their version that supports localStorage 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)
Note that, because of WebSQL support, apps packaged with Phonegap will also use asynchronous storage. Pretty slick!
Lost? Need help? This README has some simple guides and the code has decent
documentation, but I'm working on a real API guide. In the meantime, if you're
stuck using the library, running the tests, or want to contribute, you can
visit irc.mozilla.org and head to the #apps
channel to ask questions about localForage.
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 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 yet support ES6 Promises natively.
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.
localForage includes a Backbone.js storage library that you can use to store your Backbone collections offline with only a few lines of really simple code. The is a Backbone example available if you're interested in using Backbone and localForage together.
Of course, Backbone.js is entirely optional and you can use localForage without it.
tl;dr: You need PhantomJS and SlimerJS installed to run tests. Then, just
run npm test (or, directly, grunt test).
Note for Windows users: SlimerJS doesn't seem to work on Windows for our
tests, so run the tests with grunt test --force. The SlimerJS versions will
be run on Travis when you submit a pull request.
localForage is designed to run in the browser, so the tests explicitly require a browser environment instead of any JavaScript environment (i.e. node.js). The tests are run on both a headless WebKit (using PhantomJS) and "headless" Gecko (using SlimerJS). The tests are written using CasperJS's tester module. We run tests against Gecko and WebKit to ensure that IndexedDB and WebSQL support is functioning as-expected.
On Mac OS X, you'll need to install both PhantomJS and SlimerJS like so:
brew install phantomjs slimerjs
If you're using Windows or Linux, you can get get PhantomJS and get SlimerJS from their websites. I haven't tried it myself, but it seems easy enough.
Generally you'll need a version of Firefox or XULRunner installed for SlimerJS to run your tests. The exact steps how to install and setup SlimerJS are described on the project homepage.
Once everything is installed you can simply type grunt test
to make sure the code is working as expected.
TODO: Provide Windows/Linux instructions; check into XULRunner setup.
Maybe. If it's legacy storage (< IE 8), for a dead platform (WebOS), or really obscure (Apple Newton), I'm going to say "no". If it's for a new browser technology or a platform-specific driver like Chrome Web Apps or Firefox OS, then "yes" is probably the answer.
Yes. If you have an adapter for EmberJS, Angular, whatever, please add it, along with tests, and submit a pull request. The more frameworks this library can support, the better.
No. This is a library focused on offline storage inside a web browser. Node.js
already has lots of storage solutions. The problem this library aims to solve
is that web browsers differ greatly in their support for a common API for
dealing with the same kind of data. Node.js doesn't have that problem; if you
want to use an API, you just add a library to your package.json.
This program is free software; it is distributed under an Apache License.
Copyright (c) 2013-2014 Mozilla (Contributors).