Skip to content
Branch: gh-pages
Go to file

Latest commit


Failed to load latest commit information.
Latest commit message
Commit time


Deprecated Warning!

I am now using LocalForage from Mozilla and so I will not maintain this code anymore.

Build Status

Run the tests in your browser

Watch the tests on saucelabs

Simple key/value based storage abstraction lib for usage in browser based environments. Uses IndexedDB with fallback to [deprecated but still widely supported and needed] WebSQL. If none of both storage adapters is available or the initialization fails, the ready-callback will be called with an error as the first parameter.


JSFiddle (Use chrome dev tools to inspect the stored IndexedDB data)


Via bower

$ bower info vanilla-storage
$ bower install vanilla-storage

From source

$ git clone
$ cd VanillaStorage
$ npm install && bower install
$ grunt test

Note that gh-pages is the default branch to make sure to update the project site and tests on every push (see this tweet). That's why we commit the bower_components too.

Optimized source

See dist/vanilla-storage.js, or if you want to build it yourself:

$ grunt build # creates dist/vanilla-storage.js ready for production usage


  • none (-;

Global vs. AMD

Either include the files via script tags:

<script src="path/to/vanilla-storage/src/storageHelpers.js"></script>
<script src="path/to/vanilla-storage/src/WebSQLStorage.js"></script>
<script src="path/to/vanilla-storage/src/IDBStorage.js"></script>
<script src="path/to/vanilla-storage/src/VanillaStorage.js"></script>

...or add something like the following to your requirejs config:

    paths: {
        VanillaStorage: 'path/to/src/VanillaStorage',
        WebSQLStorage:  'path/to/src/WebSQLStorage',
        IDBStorage:     'path/to/src/IDBStorage',
        storageHelpers: 'path/to/src/storageHelpers'


The API is all async and pretty simple, basically there are 5 public methods:

  • get(key, fn) // fetch data for key
  • getAll(fn) // fetch data for all keys ("all rows")
  • save(key, data, fn) // store data for key
  • drop(key, fn) // drop data for key
  • nuke(fn) // drop data for all keys ("all rows")

Callback functions always have the error as first parameter, data as second if any. So if the first parameter of a callback is undefined it means the operation was successful.


Default usage

var options = {
        storeName: 'my_data_store', // name of the store ("name of database")
        version: '1.0' // string for websql, on idb we parseInt
    KEY       = 'some-key',
    DEMO_DATA = {foo: 'bar', num:42};

// vanilla api ready to use
var readyToUseAPI = function(err) {
    console.log(err, this); // -> this instanceof VanillaStorage, DEMO_DATA, function _saved(err) {
        console.log(err); // should be undefined

        vanilla.get(KEY, function _fetched(err, data) {
            console.log(data); // -> DEMO_DATA

            vanilla.drop(KEY, function _deleted_(err) {
                // calling get(KEY) now should have the error passed with message not found

// pre-checks possible:

// NOTE: you must provide a `ready`-calback
vanilla = new VanillaStorage(options, readyToUseAPI);

Standalone usage

// you can also use the adapters standalone
var wsql = new WebSQLStorage({
    storeName: 'my_store',
    version: '1.0'

wsql.init(function ready(err) {
    if(!err) {'some-key', {foo:'bar'}, function __saved(err, data) {
            console.log(err, data);
        // ...

var idb = new IDBStorage({
    storeName: 'my_data_store',
    version: 1.0
if(idb.isValid()) {
    idb.init(function ready(err) {
        if(!err) {
  'some-key', {foo:'bar'}, function __saved(err, data) {
                console.log(err, data);
            // ...


$ grunt test

# or:
$ grunt test-server&
$ phantomjs --debug=false --local-storage-path=. --local-storage-quota=100000000000??? ./node_modules/mocha-phantomjs/lib/ http://localhost:1234/test

Run the suite in real browsers via testem:

$ grunt testem



Simple key/value based client side storage abstraction lib using IndexedDB with fallback to WebSQL


You can’t perform that action at this time.