Repository files navigation

localForage is a fast and simple storage library for JavaScript. localForageimproves the offline experience of your web app by using asynchronous storage(IndexedDB or WebSQL) with a simple,localStorage-like API.

localForage uses localStorage in browsers with no IndexedDB orWebSQL support. Seethe wiki for detailed compatibility info.

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

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

Try thelive example.

Download thelatest localForage from GitHub, or install withnpm:

npm install localforage

Lost? Need help? Try thelocalForage API documentation.localForage API文档也有中文版。

If you're having trouble using the library, running the tests, or want to contribute to localForage, please look through theexisting issues for your problem first before creating a new one. If you still need help,feel free to file an issue.

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

localForage has a dual API that allows you to either use Node-style callbacksorPromises. If you are unsure which one is right for you, it's recommended to use Promises.

Here's an example of the Node-style callback form:

localforage.setItem('key','value',function(err){// if err is non-null, we got an errorlocalforage.getItem('key',function(err,value){// if err is non-null, we got an error. otherwise, value is the value});});

And the Promise form:

localforage.setItem('key','value').then(function(){returnlocalforage.getItem('key');}).then(function(value){// we got our value}).catch(function(err){// we got an error});

Or, useasync/await:

try{constvalue=awaitlocalforage.getItem('somekey');// This code runs once the value has been loaded// from the offline store.console.log(value);}catch(err){// This code runs if there were any errors.console.log(err);}

For more examples, please visitthe API docs.

You can store any type in localForage; you aren't limited to strings like inlocalStorage. Even if localStorage is your storage backend, localForageautomatically doesJSON.parse() andJSON.stringify() when getting/settingvalues.

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

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

You can set database information with theconfig() method.Available options aredriver,name,storeName,version,size, anddescription.

Example:

localforage.config({driver      :localforage.WEBSQL,// Force WebSQL; same as using setDriver()name        :'myApp',version     :1.0,size        :4980736,// Size of database, in bytes. WebSQL-only for now.storeName   :'keyvaluepairs',// Should be alphanumeric, with underscores.description :'some description'});

Note: you must callconfig()before you interact with your data. Thismeans callingconfig() before usinggetItem(),setItem(),removeItem(),clear(),key(),keys() orlength().

You can create multiple instances of localForage that point to different storesusingcreateInstance. All the configuration options used byconfig are supported.

varstore=localforage.createInstance({name:"nameHere"});varotherStore=localforage.createInstance({name:"otherName"});// Setting the key on one of these doesn't affect the other.store.setItem("key","value");otherStore.setItem("key","value2");

You can use localForage withRequireJS:

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

If you have theallowSyntheticDefaultImports compiler option set totrue in yourtsconfig.json (supported in TypeScript v1.8+), you should use:

importlocalForagefrom"localforage";

Otherwise you should use one of the following:

import*aslocalForagefrom"localforage";// or, in case that the typescript version that you are using// doesn't support ES6 style imports for UMD modules like localForageimportlocalForage=require("localforage");

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

• AngularJS
• Angular 4 and up
• Backbone
• Ember
• Vue
• NuxtJS

If you have a driver you'd like listed, pleaseopen an issue to have itadded to this list.

You can create your own driver if you want; see thedefineDriver API docs.

There is alist of custom drivers on the wiki.

You'll neednode/npm andbower.

To work on localForage, you should start byforking it and installing itsdependencies. ReplaceUSERNAME with your GitHub username and run thefollowing:

# Install bower globally if you don't have it:npm install -g bower# Replace USERNAME with your GitHub username:git clone git@github.com:USERNAME/localForage.gitcd localForagenpm installbower install

Omitting the bower dependencies will cause the tests to fail!

You need PhantomJS installed to run local tests. Runnpm test (or,directly:grunt test). Your code must also pass thelinter.

localForage is designed to run in the browser, so the tests explicitly requirea browser environment. Local tests are run on a headless WebKit (usingPhantomJS).

When you submit a pull request, tests will be run against all browsers thatlocalForage supports on Travis CI usingSauce Labs.

As of version 1.7.3 the payload added to your app is rather small. Served using gzip compression, localForage will add less than 10k to your total bundle size:

minified

`~29kB`

gzipped

`~8.8kB`

brotli'd

`~7.8kB`

This program is free software; it is distributed under anApache License.

Copyright (c) 2013-2016Mozilla(Contributors).