Async local storage for Angular
Efficient client-side storage module for Angular:
- simplicity: simple API like native
- perfomance: internally stored via the asynchronous
- Angular-like: wrapped in RxJS
- security: validate data with a JSON Schema,
- compatibility: works around some browsers issues and heavily tested via GitHub Actions,
- documentation: API fully explained, and a changelog!
What started as a personal project is now one of the most used Angular library for client-side storage, with more than 10 000 downloads on npm each week.
It's a lot of free work. So if your company earns money with projects using this lib, it would be nice to consider becoming a sponsor.
By the same author
- Angular schematics extension for VS Code (GUI for Angular CLI commands)
- typescript-strictly-typed: reliable code with TypeScript strictly typed
- Popular Angular posts on Medium
- Follow updates of this lib on Twitter
- Angular onsite trainings (based in Paris, so the website is in French, but my English bio is here)
Why this module?
localStorage API is simple to use but synchronous, so if you use it too often,
your app will soon begin to freeze.
indexedDB API is asynchronous and efficient, but it's a mess to use:
you'll soon be caught by the callback hell, as it does not support
Mozilla has done a very great job with the
a simple API based on native
but internally stored via the asynchronous
indexedDB for performance.
But it's built in ES5 old school way and then it's a mess to include into Angular.
This module is based on the same idea as
localForage, but built in ES6+
and additionally wrapped into RxJS
to be homogeneous with other Angular modules.
Install the package, according to your Angular version:
# For Angular LTS (Angular >= 9):ng add @ngx-pwa/local-storage
You should stick to these commands. If for any reason
ng add does not work,
be sure to follow the manual installation guide,
as there are additionnal steps to do in addition to the package installation for some versions.
If you have multiple applications in the same project, as usual, you need to choose the project:
ng add @ngx-pwa/local-storage --project yourprojectname
To update to new versions, see the migration guides.
This service API follows the
which is similar to the standard
Map API, and close to the
except it's based on RxJS
Observables instead of
Note: there is also a
LocalStorage service available,
but only for compatibility with old versions of this lib.
You can store any value, without worrying about serializing. But note that:
undefinedmakes no sense and can cause issues in some browsers, so the item will be removed instead,
- you should stick to JSON data, ie. primitive types, arrays and literal objects.
Bloband other special structures can cause issues in some scenarios. See the serialization guide for more details.
To delete one item:
To delete all items:
To get the current value:
Not finding an item is not an error, it succeeds but returns
Note you will only get one value: the
Observable is here for asynchrony but
is not meant to emit again when the stored data is changed.
If you need to watch the value, see the watching guide.
Don't forget it's client-side storage: always check the data, as it could have been forged.
You can use a JSON Schema to validate the data.
See the full validation guide to see how to validate all common scenarios.
You DO NOT need to unsubscribe: the
Observable autocompletes (like in the Angular
But you DO need to subscribe, even if you don't have something specific to do after writing in storage
(because it's how RxJS
As usual, it's better to catch any potential error:
For read operations, you can also manage errors by providing a default value:
See the errors guide for some details about what errors can happen.
This lib, as native
indexedDb, is about persistent storage.
Wanting temporary storage (like
sessionStorage) is a very common misconception:
an application doesn't need that. More details here.
In addition to the classic
this lib also provides a
Map-like API for advanced operations:
See the documentation for more info and some recipes. For example, it allows to implement a multiple databases scenario.
We follow Angular LTS support.
This module supports AoT pre-compiling and Ivy.
This module supports Universal server-side rendering via a mock storage.
If you have multiple apps on the same subdomain and you don't want to share data between them, see the prefix guide.
For interoperability when mixing this lib with direct usage of native APIs or other libs like
(which doesn't make sense in most cases),
see the interoperability documentation.