npm package: @homielab/react-native-persistent-storage
Description: React Native Persistent Storage
Author: homielab
Latest version: 1.0.3

# @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](https://developer.android.com/reference/android/content/SharedPreferences)
- iOS: [NSUserDefaults](https://developer.apple.com/documentation/foundation/nsuserdefaults)

# Installation

Using npm:

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

Using bun:

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

Then install pods (iOS):

```sh
cd ios && pod install
```

## Usage

```js
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.