Announcing Ionic Storage v3

Photo by Lucas van Oort on Unsplash

Today I’m thrilled to announce the release of Ionic Storage v3, an open-source library that offers an easy way to store simple data in Ionic apps. Ionic Storage is useful for building single code-base apps on iOS, Android, and the Web, while automatically using the best storage engine available on the platform the app is running on.

Introduced several years ago, Ionic Storage was originally built with only Angular support in mind. However, given its popularity with the Ionic community, we knew it was time for an update and to bring it to the rest of the Ionic ecosystem.

Read on to learn what’s new in v3 and how to migrate if you’re using Ionic Storage 2.x today.

What’s New?

We’re excited to open up Ionic Storage to more developers. To achieve this, v3 adds support for React, Vue, or any JavaScript project. The existing Angular implementation is still there, of course. See usage instructions below.

Older versions of Ionic Storage had a driver called localforage-cordovaSQLiteDriver hardcoded into the library. While this made it easier to use SQLite when running on native mobile, it restricted options for other storage engines. This dependency has been removed, but you can still install it by following the SQLite instructions here.

The ready() function, originally built for a manual promises-based approach, has been removed. Since the async/await pattern is now available, Ionic Storage v3 replaces ready() with a cleaner create() function which instantiates the database immediately. If you happen to call other Storage functions before the database has been created, an exception will be thrown. Each call to create() creates a separate instance of the underlying storage engine, though we recommend using a different name for multiple active database instances. More on this below.

For teams looking for encryption support, we also added integration with Ionic’s Secure Storage premium solution. There’s a new setEncryptionKey method available for security-sensitive use cases using Secure Storage.

Finally, we closed over 30+ issues to improve the overall stability and health of the plugin.

Usage

Add data storage capabilities to your Ionic app with a few lines of code.

With React, Vue, or Vanilla JavaScript

import { Storage } from '@ionic/storage';
const store = new Storage({/* config */});
await store.create();

With Angular

Usage in Angular using Services and Dependency Injection requires importing the IonicStorageModule and then injecting the Storage class.

First, edit your NgModule declaration in src/app/app.module.ts or in the module for the page you’ll use the storage library in, and add IonicStorageModule as an import:

import { IonicStorageModule } from '@ionic/storage-angular';

@NgModule({
  declarations: [
    ...
  ],
  imports: [
    IonicModule.forRoot(MyApp),
    IonicStorageModule.forRoot({/* config */})
  ],
  bootstrap: [IonicApp],
  entryComponents: [
    ...
  ],
  providers: [
    ...
  ]
})

export class AppModule { }

Next, inject Storage into a component:

import { Component } from '@angular/core';
import { Storage } from '@ionic/storage';

@Component({
  selector: 'page-home',
  templateUrl: 'home.html'
})

export class HomePage {

  constructor(private storage: Storage) {  }

  async ngOnInit() {
    // If using a custom driver:
    // await this.storage.defineDriver(MyCustomDriver)
    await this.storage.create();
  }
}

Once that is complete, begin using the Storage API to set, get, and remove values associated with a key. Some basic examples:

// Set an item
await storage.set('name', 'Mr. Ionitron');

// Get an item back
const name = await storage.get('name');

// Remove an item
await storage.remove(‘name’);

To enable encryption when using the Ionic Secure Storage driver:

storage.setEncryptionKey('mykey');

For complete info including code examples, configuration options, and more, see the Ionic Storage repository.

Migrating to v3

Have an existing Angular app that uses Ionic Storage? There are just a few steps to migrate to the new version.

Angular users should now use the @ionic/storage-angular package:

# Remove Ionic Storage v2
npm uninstall @ionic/storage

## Install v3
npm install @ionic/storage-angular

If you’d like to use SQLite as a storage engine, follow the new SQLite installation instructions to install the previously used SQLite engine or Ionic Secure Storage for enterprise encrypted SQLite use cases.

The ready() method has been removed. Instead, use the storage create() method:

export class HomePage {
  constructor(private storage: Storage) { }

  async ngOnInit() {
    // v2 and below syntax
    storage.ready().then(() => {
       this.storage.set('name', 'Mr. Ionitron');
    });

    // v3 syntax
    await this.storage.create();
    await storage.set('name', 'Mr. Ionitron');
  }
}

If you have existing data stored in an app, you’ll want to be sure to use the same database name as before. If you didn’t provide an explicit name, no changes need to be made.

If you previously named the database explicitly, then ensure the name remains the same:

// src/app/app.module.ts
imports: [
   IonicStorageModule.forRoot({
     // Ensure name is the same here
     name: '__mydb',
     driverOrder: [Drivers.IndexedDB, Drivers.LocalStorage]
   })
 ],

Finally, instead of using explicit strings for driverOrder, a new Drivers enum should be used:

// src/app/app.module.ts
import { Drivers } from '@ionic/storage';

imports: [
   IonicStorageModule.forRoot({
     driverOrder: [Drivers.IndexedDB, Drivers.LocalStorage]
   })
 ],

The actual storage API is essentially unchanged, so your remaining app code should port over with minimal modifications.

Also note: Web SQL is deprecated and should no longer be used. Make sure to remove any references to Web SQL in your driverOrder configuration.

What about the Capacitor Storage plugin?

Fans of Capacitor, our open-source native runtime for building cross-platform web and mobile apps, might be wondering how the Capacitor Storage plugin fits in. Yes, it’s similar to Ionic Storage in that it provides a key/value API for storing simple data objects. Its implementation is slightly different: on the web, it uses LocalStorage and on mobile, UserDefaults on iOS and SharedPreferences on Android.

Here’s how to decide which one to pick: For apps with very simple storage needs that want the most lightweight option, use Capacitor Storage. Examples of appropriate data here include user preferences or app settings. For medium-sized apps and above that require storage engine flexibility but don’t require relational or high-performance query support for large datasets, Ionic Storage is a great option. Finally, for apps with large data sets, a relational data model, or encryption requirements, we recommend Ionic Secure Storage.

Building a security-sensitive app?

For teams building security-sensitive applications requiring encryption, v3 now supports encryption through Ionic Secure Storage, an enterprise-ready, high-performance data store with SQL or key/value support and offering 256-bit AES encryption. When used in tandem with Ionic Identity Vault, developers can securely manage encryption keys and build fully offline-enabled apps with biometric authentication using the full security capabilities available on modern mobile devices and operating systems.

Ionic Secure Storage is an enterprise product and requires an active enterprise subscription or trial. To learn more and request a demo, visit the Secure Storage product page.

Add data storage to your apps now

We’re thrilled to roll out this new version of Ionic Storage and hope you enjoy using it in your Angular, React, and Vue apps. Happy app building!