localforage
Advanced tools
The localForage npm package is a fast and simple storage library for JavaScript. It improves the offline experience of web apps by using asynchronous storage (IndexedDB or WebSQL) with a simple, localStorage-like API. localForage uses a driver system that supports IndexedDB, WebSQL, and localStorage.
Storing Data
This feature allows you to store data in the browser's asynchronous storage. The code sample demonstrates setting and then getting an item.
localforage.setItem('key', 'value').then(function () { return localforage.getItem('key'); }).then(function (value) { console.log(value); }).catch(function (err) { console.error(err); });Retrieving Data
This feature allows you to retrieve data from the browser's asynchronous storage. The code sample demonstrates getting an item.
localforage.getItem('key').then(function (value) { console.log(value); }).catch(function (err) { console.error(err); });Removing Data
This feature allows you to remove data from the browser's asynchronous storage. The code sample demonstrates removing an item.
localforage.removeItem('key').then(function () { console.log('Key is removed'); }).catch(function (err) { console.error(err); });Clearing Storage
This feature allows you to clear all data from the browser's asynchronous storage. The code sample demonstrates clearing the storage.
localforage.clear().then(function () { console.log('Storage is now empty'); }).catch(function (err) { console.error(err); });Iterating Over Keys
This feature allows you to iterate over all key-value pairs in the browser's asynchronous storage. The code sample demonstrates iterating over keys.
localforage.iterate(function (value, key, iterationNumber) { console.log([key, value]); }).then(function () { console.log('Iteration has completed'); }).catch(function (err) { console.error(err); });Dexie is a wrapper library for indexedDB, which is a low-level API for client-side storage of significant amounts of structured data. Dexie provides a more powerful query language than localForage and is designed to work with complex data structures.
PouchDB is an open-source JavaScript database inspired by Apache CouchDB that is designed to run well within the browser. PouchDB was created to help web developers build applications that work as well offline as they do online. It is more feature-rich than localForage, with synchronization capabilities.
idb-keyval is a super-simple-small promise-based keyval store implemented with IndexedDB, providing a localStorage-like API. It is much smaller in size than localForage but does not have the same level of browser support or features.
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
localForage works in all modern browsers (IE 8 and above). Asynchronous storage is available in all browsers in bold, with localStorage fallback in parentheses.
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!
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.
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 support ES6 Promises yet.
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.
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.
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().
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', console.log);
});
});
Web Worker support in Firefox is blocked by bug 701634. Until it is fixed, web workers are not officially supported by localForage.
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.
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!
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.
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.
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).
This release drops support for some legacy browsers, though not actually the ones you might think. localForage's new policy is to support the current version of all major browsers plus up to three versions back.
dist/ directory. (#172)keys() method. (#180)FAQs
Offline storage, improved.
The npm package localforage receives a total of 3,149,436 weekly downloads. As such, localforage popularity was classified as popular.
We found that localforage demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.