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