@homielab/react-native-persistent-storage

A lightweight, cross-platform key-value storage module for React Native built using Nitro Modules. This module provides a fast and simple API to persist small pieces of data directly on the device.

Under the hood, it uses the native storage systems:

• Android: SharedPreferences
• iOS: NSUserDefaults

Installation

Using npm:

npm install @homielab/react-native-persistent-storage react-native-nitro-modules

Using bun:

bun add @homielab/react-native-persistent-storage react-native-nitro-modules

Then install pods (iOS):

cd ios && pod install

Usage

import { PersistentStorage } from '@homielab/react-native-persistent-storage'

PersistentStorage.setItem('userToken', 'abc123')

const token = PersistentStorage.getItem('userToken')

PersistentStorage.removeItem('userToken')

PersistentStorage.clear()

Comparison: PersistentStorage vs AsyncStorage vs MMKV

| Feature | @homielab/react-native-persistent-storage | @react-native-async-storage/async-storage | react-native-mmkv | | -------------------- | -------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ | | Storage Type | Native key-value (SharedPreferences / NSUserDefaults) | JavaScript-backed storage (SQLite/rocksdb on some platforms) | Native key-value storage (C++ backend, memory-mapped) | | Performance | Fast for small values; uses native storage directly | Slower for large/frequent writes; JS bridge overhead | Extremely fast; near-native speed, memory-mapped | | Threading | Non-blocking; native APIs handle persistence efficiently | Async but uses JS thread; can block UI on heavy ops | Zero JS thread blocking; reads/writes are almost instant | | Data Size | Small values (strings) | Small to medium values (strings, JSON) | Small to medium values, optimized for large datasets | | Persistence | Persistent on device | Persistent on device | Persistent on device | | Encryption | None by default | None by default | Optional encryption built-in | | API Complexity | Simple: setItem, getItem, removeItem, clear | Similar: setItem, getItem, removeItem, clear | Simple: set, get, delete, clear; supports typed storage | | Platform Support | iOS / Android | iOS / Android / Web | iOS / Android | | Use Cases | Small persistent values: tokens, flags, settings | Medium persistent values; general-purpose | High-performance storage: large datasets, frequent reads/writes, caching |

🔹 Key Takeaways

• PersistentStorage
  Best for small persistent values that need fast, native-backed storage. Lightweight replacement for AsyncStorage when advanced features aren’t needed.

• AsyncStorage
  Easy and widely used, works cross-platform (even web via polyfill). Not suitable for heavy or frequent operations.

• MMKV
  Extremely fast and efficient, ideal for large or frequently updated datasets. Slightly heavier setup due to native dependencies.

Contributing

Pull requests and improvements are welcome! If you find a bug or want a new feature, feel free to open an issue.

License

MIT – free to use, modify, and distribute.