@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)	Native key-value storage (C++ backend (Tencent/MMKV))
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
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.