1 | # localForage [![Build Status](https://travis-ci.org/mozilla/localForage.svg?branch=master)](http://travis-ci.org/mozilla/localForage)
|
2 |
|
3 | localForage is a fast and simple storage library for JavaScript. localForage
|
4 | improves the offline experience of your web app by using asynchronous storage
|
5 | (IndexedDB or WebSQL) with a simple, `localStorage`-like API.
|
6 |
|
7 | localForage uses localStorage in browsers with no IndexedDB or
|
8 | WebSQL support. See [the wiki for detailed compatibility info][supported browsers].
|
9 |
|
10 | To use localForage, just drop a single JavaScript file into your page:
|
11 |
|
12 | ```html
|
13 | <script src="localforage.js"></script>
|
14 | <script>localforage.getItem('something', myCallback);</script>
|
15 | ```
|
16 |
|
17 | Download the [latest localForage from GitHub](https://github.com/mozilla/localForage/releases/latest), or install with
|
18 | [npm](https://www.npmjs.com/):
|
19 |
|
20 | ```bash
|
21 | npm install localforage
|
22 | ```
|
23 |
|
24 | or [bower](http://bower.io):
|
25 |
|
26 | ```bash
|
27 | bower install localforage
|
28 | ```
|
29 |
|
30 | localForage is compatible with [browserify](http://browserify.org/).
|
31 |
|
32 | [supported browsers]: https://github.com/mozilla/localForage/wiki/Supported-Browsers-Platforms
|
33 |
|
34 | ## Support
|
35 |
|
36 | Lost? Need help? Try the
|
37 | [localForage API documentation](https://mozilla.github.io/localForage).
|
38 |
|
39 | If you're stuck using the library, running the tests, or want to contribute
|
40 | to localForage, you can visit
|
41 | [irc.freenode.net](https://freenode.net/) and head to the `#localforage`
|
42 | channel to ask questions about localForage.
|
43 |
|
44 | The best person to ask about localForage is [**tofumatt**][tofumatt], who
|
45 | is usually online from 8am-8pm GMT (London Time).
|
46 |
|
47 | [tofumatt]: http://tofumatt.com/
|
48 |
|
49 | # How to use localForage
|
50 |
|
51 | ## Callbacks vs Promises
|
52 |
|
53 | Because localForage uses async storage, it has an async API.
|
54 | It's otherwise exactly the same as the
|
55 | [localStorage API](https://hacks.mozilla.org/2009/06/localstorage/).
|
56 |
|
57 | localForage has a dual API that allows you to either use Node-style callbacks
|
58 | or [Promises](https://www.promisejs.org/). If you are unsure which one is right for you, it's recommend to use Promises.
|
59 |
|
60 | Here's an example of the Node-style callback form:
|
61 |
|
62 | ```js
|
63 | localforage.setItem('key', 'value', function (err) {
|
64 | // if err is non-null, we got an error
|
65 | localforage.getItem('key', function (err, value) {
|
66 | // if err is non-null, we got an error. otherwise, value is the value
|
67 | });
|
68 | });
|
69 | ```
|
70 |
|
71 | And the Promise form:
|
72 |
|
73 | ```js
|
74 | localforage.setItem('key', 'value').then(function () {
|
75 | return localforage.getItem('key');
|
76 | }).then(function (value) {
|
77 | // we got our value
|
78 | }).catch(function (err) {
|
79 | // we got an error
|
80 | });
|
81 | ```
|
82 |
|
83 | For more examples, please visit [the API docs](http://mozilla.github.io/localForage).
|
84 |
|
85 | ## Storing Blobs, TypedArrays, and other JS objects
|
86 |
|
87 | You can store any type in localForage; you aren't limited to strings like in
|
88 | localStorage. Even if localStorage is your storage backend, localForage
|
89 | automatically does `JSON.parse()` and `JSON.stringify()` when getting/setting
|
90 | values.
|
91 |
|
92 | localForage supports storing all native JS objects that can be serialized to
|
93 | JSON, as well as ArrayBuffers, Blobs, and TypedArrays. Check the
|
94 | [API docs][api] for a full list of types supported by localForage.
|
95 |
|
96 | All types are supported in every storage backend, though storage limits in
|
97 | localStorage make storing many large Blobs impossible.
|
98 |
|
99 | [api]: https://mozilla.github.io/localForage/#setitem
|
100 |
|
101 | ## Configuration
|
102 |
|
103 | You can set database information with the `config()` method.
|
104 | Available options are `driver`, `name`, `storeName`, `version`, `size`, and
|
105 | `description`.
|
106 |
|
107 | Example:
|
108 | ```javascript
|
109 | localforage.config({
|
110 | driver : localforage.WEBSQL, // Force WebSQL; same as using setDriver()
|
111 | name : 'myApp',
|
112 | version : 1.0,
|
113 | size : 4980736, // Size of database, in bytes. WebSQL-only for now.
|
114 | storeName : 'keyvaluepairs', // Should be alphanumeric, with underscores.
|
115 | description : 'some description'
|
116 | });
|
117 | ```
|
118 |
|
119 | **Note:** you must call `config()` _before_ you interact with your data. This
|
120 | means calling `config()` before using `getItem()`, `setItem()`, `removeItem()`,
|
121 | `clear()`, `key()`, `keys()` or `length()`.
|
122 |
|
123 | ## Multiple instances
|
124 |
|
125 | You can create multiple instances of localForage that point to different stores
|
126 | using `createInstance`. All the configuration options used by
|
127 | [`config`](#configuration) are supported.
|
128 |
|
129 | ``` javascript
|
130 | var store = localforage.createInstance({
|
131 | name: "nameHere"
|
132 | });
|
133 |
|
134 | var otherStore = localforage.createInstance({
|
135 | name: "otherName"
|
136 | });
|
137 |
|
138 | // Setting the key on one of these doesn't affect the other.
|
139 | store.setItem("key", "value");
|
140 | otherStore.setItem("key", "value2");
|
141 | ```
|
142 |
|
143 | ## RequireJS
|
144 |
|
145 | You can use localForage with [RequireJS](http://requirejs.org/):
|
146 |
|
147 | ```javascript
|
148 | define(['localforage'], function(localforage) {
|
149 | // As a callback:
|
150 | localforage.setItem('mykey', 'myvalue', console.log);
|
151 |
|
152 | // With a Promise:
|
153 | localforage.setItem('mykey', 'myvalue').then(console.log);
|
154 | });
|
155 | ```
|
156 |
|
157 | ## Browserify and Webpack
|
158 |
|
159 | localForage 1.3+ works with both Browserify and Webpack. If you're using an
|
160 | earlier version of localForage and are having issues with Browserify or
|
161 | Webpack, please upgrade to 1.3.0 or above.
|
162 |
|
163 | If you're using localForage in your own build system (eg. browserify or
|
164 | webpack) make sure you have the
|
165 | [required plugins and transformers](https://github.com/mozilla/localForage/blob/master/package.json#L24)
|
166 | installed (eg. `npm install --save-dev babel-plugin-system-import-transformer`).
|
167 |
|
168 | ## TypeScript
|
169 |
|
170 | To import localForage in TypeScript:
|
171 |
|
172 | ```javascript
|
173 | const localForage:LocalForage = require("localforage");
|
174 | ```
|
175 |
|
176 | Note that the ES6 style import is not supported for our module type. Check out the following to know why:
|
177 | * http://stackoverflow.com/questions/29596714/new-es6-syntax-for-importing-commonjs-amd-modules-i-e-import-foo-require
|
178 | * http://www.jbrantly.com/es6-modules-with-typescript-and-webpack/
|
179 |
|
180 | ## Framework Support
|
181 |
|
182 | If you use a framework listed, there's a localForage storage driver for the
|
183 | models in your framework so you can store data offline with localForage. We
|
184 | have drivers for the following frameworks:
|
185 |
|
186 | * [AngularJS](https://github.com/ocombe/angular-localForage)
|
187 | * [Backbone](https://github.com/mozilla/localForage-backbone)
|
188 | * [Ember](https://github.com/genkgo/ember-localforage-adapter)
|
189 |
|
190 | If you have a driver you'd like listed, please
|
191 | [open an issue](https://github.com/mozilla/localForage/issues/new) to have it
|
192 | added to this list.
|
193 |
|
194 | ## Custom Drivers
|
195 |
|
196 | You can create your own driver if you want; see the
|
197 | [`defineDriver`](https://mozilla.github.io/localForage/#definedriver) API docs.
|
198 |
|
199 | There is a [list of custom drivers on the wiki][custom drivers].
|
200 |
|
201 | [custom drivers]: https://github.com/mozilla/localForage/wiki/Custom-Drivers
|
202 |
|
203 | # Working on localForage
|
204 |
|
205 | You'll need [node/npm](http://nodejs.org/) and
|
206 | [bower](http://bower.io/#installing-bower).
|
207 |
|
208 | To work on localForage, you should start by
|
209 | [forking it](https://github.com/mozilla/localForage/fork) and installing its
|
210 | dependencies. Replace `USERNAME` with your GitHub username and run the
|
211 | following:
|
212 |
|
213 | ```bash
|
214 | # Install bower globally if you don't have it:
|
215 | npm install -g bower
|
216 |
|
217 | # Replace USERNAME with your GitHub username:
|
218 | git clone git@github.com:USERNAME/localForage.git
|
219 | cd localForage
|
220 | npm install
|
221 | bower install
|
222 | ```
|
223 |
|
224 | Omitting the bower dependencies will cause the tests to fail!
|
225 |
|
226 | ## Running Tests
|
227 |
|
228 | You need PhantomJS installed to run local tests. Run `npm test` (or,
|
229 | directly: `grunt test`). Your code must also pass the
|
230 | [linter](http://jshint.com/).
|
231 |
|
232 | localForage is designed to run in the browser, so the tests explicitly require
|
233 | a browser environment. Local tests are run on a headless WebKit (using
|
234 | [PhantomJS](http://phantomjs.org)).
|
235 |
|
236 | When you submit a pull request, tests will be run against all browsers that
|
237 | localForage supports on Travis CI using [Sauce Labs](https://saucelabs.com/).
|
238 |
|
239 | ## Building the API Documentation
|
240 |
|
241 | We currently use a Ruby tool to build our
|
242 | [API documentation](https://mozilla.github.io/localForage). You can install the Ruby dependencies with [Bundler](http://bundler.io):
|
243 |
|
244 | ```bash
|
245 | # From inside the localForage directory
|
246 | bundle install
|
247 | ```
|
248 |
|
249 | Then use `grunt` to serve the site:
|
250 |
|
251 | ```bash
|
252 | grunt site
|
253 | ```
|
254 |
|
255 | Navigate to [localhost:4567](http://localhost:4567/) in your browser to see the
|
256 | docs.
|
257 |
|
258 | There is an [open issue to move to a node tool for the docs](https://github.com/mozilla/localForage/issues/192).
|
259 |
|
260 | # License
|
261 |
|
262 | This program is free software; it is distributed under an
|
263 | [Apache License](https://github.com/mozilla/localForage/blob/master/LICENSE).
|
264 |
|
265 | ---
|
266 |
|
267 | Copyright (c) 2013-2015 [Mozilla](https://mozilla.org)
|
268 | ([Contributors](https://github.com/mozilla/localForage/graphs/contributors)).
|