{"id":13406554,"url":"https://github.com/ionic-team/ionic-storage","last_synced_at":"2025-05-15T11:06:28.183Z","repository":{"id":21531875,"uuid":"69055032","full_name":"ionic-team/ionic-storage","owner":"ionic-team","description":"Ionic Storage module for Ionic apps","archived":false,"fork":false,"pushed_at":"2024-03-30T03:01:17.000Z","size":5082,"stargazers_count":447,"open_issues_count":71,"forks_count":99,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-05-11T18:04:03.271Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ionic-team.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-23T19:33:28.000Z","updated_at":"2025-05-05T17:31:33.000Z","dependencies_parsed_at":"2024-06-18T12:23:47.410Z","dependency_job_id":"41d4c36b-1d13-4785-9e0d-d8973fd44cc9","html_url":"https://github.com/ionic-team/ionic-storage","commit_stats":{"total_commits":200,"total_committers":27,"mean_commits":7.407407407407407,"dds":0.745,"last_synced_commit":"e1ec9f96100f905d34385edde8addaa069e6f636"},"previous_names":["driftyco/ionic-storage"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2Fionic-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2Fionic-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2Fionic-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionic-team%2Fionic-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ionic-team","download_url":"https://codeload.github.com/ionic-team/ionic-storage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253609633,"owners_count":21935560,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T19:02:33.457Z","updated_at":"2025-05-15T11:06:28.165Z","avatar_url":"https://github.com/ionic-team.png","language":"TypeScript","readme":"[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fionic-team%2Fionic-storage%2Fbadge%3Fref%3Dmain\u0026style=flat)](https://actions-badge.atrox.dev/ionic-team/ionic-storage/goto?ref=main)\n\n# Ionic Storage\n\nA simple key-value Storage module for Ionic apps. This utility uses the best storage engine available on the platform without having to interact with it directly (some configuration required, see docs below).\n\nAs of 3.x, this library now supports any JavaScript project (old versions only supported Angular), and Angular-specific functionality has been moved to a new `@ionic/storage-angular` package.\n\nOut of the box, Ionic Storage will use `IndexedDB` and `localstorage` where available. To use SQLite for native storage, see the [SQLite Installation](#sqlite-installation) instructions.\n\nFor teams building security sensitive applications requiring encryption, 3.x now supports encryption through Ionic Secure Storage, see [Encryption Support](#encryption-support) for instructions on using it.\n\n## Installation\n\n```shell\nnpm install @ionic/storage\n```\n\nIf using Angular, install the `@ionic/storage-angular` library instead:\n\n```shell\nnpm install @ionic/storage-angular\n```\n\nIf you'd like to use SQLite as a storage engine, see the [SQLite Installation](#sqlite-installation) instructions.\n\n## Usage\n\n### With React, Vue, Vanilla JavaScript\n\n```typescript\nimport { Storage } from '@ionic/storage';\n\nconst store = new Storage();\nawait store.create();\n```\n\nSee the [API](#api) section below for an overview of the supported methods on the storage instance.\n\n### With Angular\n\nUsage in Angular using Services and Dependency Injection requires importing the `IonicStorageModule` and then injecting the `Storage` class.\n\nFirst, edit your NgModule declaration in `src/app/app.module.ts` or in the module for the component you'll use the storage library in, and add  `IonicStorageModule` as an import:\n\n```typescript\nimport { IonicStorageModule } from '@ionic/storage-angular';\n\n@NgModule({\n  imports: [\n    IonicStorageModule.forRoot()\n  ]\n})\nexport class AppModule { }\n```\n\nNext, inject `Storage` into a component. Note: this approach is meant for usage in a single component (such as `AppComponent`). In this case, `create()` should only be called once. For use in multiple components, we recommend creating a service (see next example).\n\n```typescript\nimport { Component } from '@angular/core';\nimport { Storage } from '@ionic/storage-angular';\n\n@Component({\n  selector: 'app-root',\n  templateUrl: 'app.component.html'\n})\nexport class AppComponent {\n\n  constructor(private storage: Storage) {\n  }\n\n  async ngOnInit() {\n    // If using a custom driver:\n    // await this.storage.defineDriver(MyCustomDriver)\n    await this.storage.create();\n  }\n}\n```\n\nFor more sophisticated usage, an Angular Service should be created to manage all database operations in your app and constrain all configuration and database initialization to a single location. When doing this, don't forget to register this service in a `providers` array in your `NgModule` if not using `providedIn: 'root'`, and ensure that the `IonicStorageModule` has been initialized in that `NgModule` as shown above. Here's an example of what this service might look like:\n\n```typescript\nimport { Injectable } from '@angular/core';\n\nimport { Storage } from '@ionic/storage-angular';\n\n@Injectable({\n  providedIn: 'root'\n})\nexport class StorageService {\n  private _storage: Storage | null = null;\n\n  constructor(private storage: Storage) {\n    this.init();\n  }\n\n  async init() {\n    // If using, define drivers here: await this.storage.defineDriver(/*...*/);\n    const storage = await this.storage.create();\n    this._storage = storage;\n  }\n\n  // Create and expose methods that users of this service can\n  // call, for example:\n  public set(key: string, value: any) {\n    this._storage?.set(key, value);\n  }\n}\n```\n\nThen, inject the `StorageService` into your pages and other components that need to interface with the Storage engine.\n\n## API\n\nThe Storage API provides ways to set, get, and remove a value associated with a key, along with clearing the database, accessing the stored keys and their quantity, and enumerating the values in the database.\n\nTo set an item, use `set(key, value)`:\n\n```javascript\nawait storage.set('name', 'Mr. Ionitron');\n```\n\nTo get the item back, use `get(name)`:\n\n```javascript\nconst name = await storage.get('name');\n```\n\nTo remove an item:\n\n```javascript\nawait storage.remove(key);\n```\n\nTo clear all items:\n\n```javascript\nawait storage.clear();\n```\n\nTo get all keys stored:\n\n```javascript\nawait storage.keys()\n```\n\nTo get the quantity of key/value pairs stored:\n\n```javascript\nawait storage.length()\n```\n\nTo enumerate the stored key/value pairs:\n```javascript\nstorage.forEach((key, value, index) =\u003e {\n});\n```\n\nTo enable encryption when using the [Ionic Secure Storage](https://ionic.io/docs/secure-storage) driver:\n\n```javascript\nstorage.setEncryptionKey('mykey');\n```\n\nSee [Encryption Support](#encryption-support) below for more information.\n\n## Configuration\n\nThe Storage engine can be configured both with specific storage engine priorities, or custom configuration\noptions to pass to localForage. See the localForage config docs for possible options: https://github.com/localForage/localForage#configuration\n\n### In React/Vue/Vanilla JavaScript configuration\n\nPass configuration options in the `Storage` constructor:\n\n```typescript\nconst storage = new Storage({\n  name: '__mydb',\n  driverOrder: [Drivers.IndexedDB, Drivers.LocalStorage]\n});\n```\n\n### Angular configuration\n\n```typescript\nimport { Drivers, Storage } from '@ionic/storage';\nimport { IonicStorageModule } from '@ionic/storage-angular';\n\n@NgModule({\n  //...\n  imports: [\n   IonicStorageModule.forRoot({\n     name: '__mydb',\n     driverOrder: [Drivers.IndexedDB, Drivers.LocalStorage]\n   })\n ],\n //...\n})\nexport class AppModule { }\n```\n\n## SQLite Installation\n\nThe 2.x version of this plugin hard coded in the [localForage-cordovaSQLiteDriver](https://github.com/thgreasi/localForage-cordovaSQLiteDriver). This driver has been removed from the core code as of 3.x to provide more options for SQLite storage engines.\n\nIn 3.x there are at least two good options for SQLite usage:\n\n1) For non-enterprise apps, the old `localForage-cordovaSQLiteDriver` is still a fine choice but does not support encryption and is community maintained. See below for installation instructions.\n\n2) For enterprise apps, we strongly recommend [Ionic Secure Storage](https://ionic.io/docs/secure-storage) which is an enterprise SQLite engine with full encryption support out of the box and is fully supported and maintained by the Ionic team.\n\n### Using `localForage-CordovaSQLiteDriver`\n\n#### Installation\n\n```\n# If using Cordova, install the plugin using \nionic cordova plugin add cordova-sqlite-storage\n# If using Capacitor, install the plugin using\nnpm install cordova-sqlite-storage\n\n# Then, install the npm library\nnpm install localforage-cordovasqlitedriver\n```\n\n#### Adding driver to configuration\n\nFor non-Angular projects, pass the `CordovaSQLiteDriver._driver` to the `driverOrder` config option:\n\n```typescript\nimport CordovaSQLiteDriver from 'localforage-cordovasqlitedriver';\n\nconst store = new Storage({\n  driverOrder: [CordovaSQLiteDriver._driver, Drivers.IndexedDB, Drivers.LocalStorage]\n});\n```\n\nIn Angular, pass the same configuration when importing the `IonicStorageModule` in your page or app `NgModule`:\n\n```typescript\nimport CordovaSQLiteDriver from 'localforage-cordovasqlitedriver';\n\n@NgModule({\n  imports: [\n    // ...,\n    IonicStorageModule.forRoot({\n      driverOrder: [CordovaSQLiteDriver._driver, Drivers.IndexedDB]\n    })\n  ],\n  // ...\n})\nexport class MyPageModule { }\n```\n\n#### Registering Driver\n\nFinally, to register the driver, run `defineDriver()` on the storage instance to register the driver, making sure to call this before any data operations:\n\n```typescript\nimport CordovaSQLiteDriver from 'localforage-cordovasqlitedriver'\n\nconst store = new Storage({\n  driverOrder: [CordovaSQLiteDriver._driver, Drivers.IndexedDB, Drivers.LocalStorage]\n});\n\nawait this.storage.defineDriver(CordovaSQLiteDriver);\n```\n\n### Using Ionic Secure Storage\n\n\n[Ionic Secure Storage](https://ionic.io/docs/secure-storage) is 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](https://ionic.io/products/identity-vault), developers can securely manage encryption keys and build fully offline-enabled apps with biometric authentication using the fullest security capabilities available on modern mobile devices and operating systems.\n\nIonic 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](https://ionic.io/products/offline-storage).\n\n#### Installation\n\nFollow the [official installation guide](https://ionic.io/docs/secure-storage) to set up and install `@ionic-enterprise/secure-storage`.\n\n### Usage\n\n#### With React, Vue, Vanilla JavaScript\n\n```typescript\nimport { Drivers } from '@ionic/storage';\nimport IonicSecureStorageDriver from '@ionic-enterprise/secure-storage/driver';\n\nconst store = new Storage({\n  driverOrder: [Drivers.SecureStorage, Drivers.IndexedDB, Drivers.LocalStorage]\n});\n\nawait store.defineDriver(IonicSecureStorageDriver);\n```\n\n#### With Angular\n\nUsage in Angular using Services and Dependency Injection requires importing the `IonicStorageModule` and then injecting the `Storage` class.\n\nFirst, 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:\n\n```typescript\nimport { Drivers } from '@ionic/storage';\nimport { IonicStorageModule } from '@ionic/storage-angular';\n\n@NgModule({\n  declarations: [\n    ...\n  ],\n  imports: [\n    IonicStorageModule.forRoot({\n      driverOrder: [Drivers.SecureStorage, Drivers.IndexedDB, Drivers.LocalStorage]\n    })\n  ],\n  // ...\n})\nexport class AppModule { }\n```\n\nThen register the driver in your component:\n\n```typescript\n\n  async ngOnInit() {\n    await this.storage.defineDriver(IonicSecureStorageDriver);\n    await this.storage.create();\n  }\n```\n\nThen follow the instructions below to configure encryption support:\n\n## Encryption Support\n\n3.x adds a new method `setEncryptionKey` to support encryption when using with [Ionic Secure Storage](https://ionic.io/docs/secure-storage) (see instructions above).\n\nThis is an enterprise feature for teams with high security needs and provides the ability to use the simple `@ionic/storage` key-value API, or drop down to SQL for more powerful query and relational data support, all with full encryption. When paired with [Ionic Identity Vault](https://ionic.io/docs/identity-vault) teams can safely manage encryption keys and provide biometric authentication when on or offline.\n\nVisit the [Secure Storage](https://ionic.io/products/secure-storage) product page to learn more about Secure Storage and inquire about a trial.\n\n### Encrypting an Existing SQLite Database\n\nA one-time migration must be performed to move to a new, encrypted database powered by [Ionic Secure Storage](https://ionic.io/docs/secure-storage).\n\nFirst, follow the installation steps above to update to Ionic Storage v3, install the `localForage-CordovaSQLiteDriver` SQLite driver, and integrate Ionic Secure Storage.\n\nNext, remove the database name and drivers, if used, from `app.module.ts`:\n\n```typescript\n@NgModule({\n  imports: [\n    // ...,\n    IonicStorageModule.forRoot()\n  ],\n  // ...\n})\nexport class MyPageModule { }\n```\n\nFinally, in the service class, create a one time migration function that migrates data to an encrypted database. Execute this function on app load.\n\n```typescript\nasync migrateDatabase() {\n  const origStore = new Storage({\n    name: 'originalDB', // the original database name\n    driverOrder: [CordovaSQLiteDriver._driver, Drivers.IndexedDB, Drivers.LocalStorage]\n  });\n  await origStore.defineDriver(CordovaSQLiteDriver);\n\n  const newStore = new Storage({\n    name: 'encryptedDB', // pick a new db name for the encrypted db\n    driverOrder: [Drivers.SecureStorage, Drivers.IndexedDB, Drivers.LocalStorage]\n  });\n  await newStore.defineDriver(IonicSecureStorageDriver);\n  newStore.setEncryptionKey('mykey');\n\n  if (await origStore.length() \u003e 0) {\n    // copy existing data into new, encrypted format\n    await origStore.forEach((key, value, index) =\u003e {\n      newStore.set(key, value);\n    });\n\n    // remove old data\n    await origStore.clear();\n  }\n\n  this._storage = newStore;\n}\n```\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionic-team%2Fionic-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fionic-team%2Fionic-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionic-team%2Fionic-storage/lists"}