@fullstackhouse/react-native-sync-storage

A synchronous storage library for React Native that provides immediate access to persisted data while maintaining async persistence in the background.


Features

- Synchronous API: Access stored data immediately without await
- Async Persistence: Background persistence to AsyncStorage
- React Integration: Built-in React Context and hooks
- Cross-Platform: Works on iOS, Android, and Web
- TypeScript Support: Fully typed with TypeScript
- Prefix Support: Namespace your storage keys
- Comprehensive Testing: 100% test coverage with Jest and Playwright

Installation

``sh
npm install @fullstackhouse/react-native-sync-storage


or


yarn add @fullstackhouse/react-native-sync-storage
`

$3

This library depends on @react-native-async-storage/async-storage. If you don't have it installed:

`sh
npm install @react-native-async-storage/async-storage


or


yarn add @react-native-async-storage/async-storage
`

Follow the AsyncStorage installation guide for platform-specific setup.

Usage

$3

`jsx
import React from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { SyncStorageProvider, useSyncStorage } from '@fullstackhouse/react-native-sync-storage';

function MyComponent() {
const { storage, loaded } = useSyncStorage();

const handleSave = () => {
// Synchronously set data
storage.setItem('user_preference', 'dark_mode');
};

const handleLoad = () => {
// Synchronously get data
const preference = storage.getItem('user_preference');
console.log('Preference:', preference); // 'dark_mode' or null
};

if (!loaded) {
return Loading...;
}

return (


Save Preference


Load Preference


);
}

export default function App() {
return (



);
}
`

$3

`jsx
import { SyncStorage } from '@fullstackhouse/react-native-sync-storage';

const storage = new SyncStorage({ prefix: 'myapp_' });

// Initialize storage (load from AsyncStorage)
await storage.load();

// Now use synchronously
storage.setItem('key', 'value');
const value = storage.getItem('key'); // 'value'

// Multiple operations
storage.multiSet([
['key1', 'value1'],
['key2', 'value2']
]);

const values = storage.multiGet(['key1', 'key2']);
// [['key1', 'value1'], ['key2', 'value2']]

// Get all keys
const keys = storage.getAllKeys(); // ['key1', 'key2']

// Clear all data
storage.clear();
`

API Reference

$3

#### Constructor

`typescript
new SyncStorage(options?: SyncStorageOptions)
`

Options:
- prefix?: string - Optional prefix for all keys

#### Methods

- load(): Promise - Load data from AsyncStorage (call once at app start)
- getItem(key: string): string | null - Get value synchronously
- setItem(key: string, value: string): void - Set value synchronously
- removeItem(key: string): void - Remove value synchronously
- clear(): void - Clear all data synchronously
- getAllKeys(): string[] - Get all keys synchronously
- multiGet(keys: string[]): Array<[string, string | null]> - Get multiple values
- multiSet(keyValuePairs: Array<[string, string]>): void - Set multiple values
- multiRemove(keys: string[]): void - Remove multiple values
- loaded: boolean - Whether storage has been loaded from AsyncStorage

$3

#### useSyncStorage()

`typescript
const { storage, loaded } = useSyncStorage();
`

Returns:
- storage: SyncStorage - The storage instance
- loaded: boolean - Whether storage has been loaded

$3

#### SyncStorageProvider

`typescript

{children}

`

Props:
- prefix?: string - Optional prefix for all keys
- children: ReactNode - Child components

How It Works

1. Initialization: Call storage.load() or use SyncStorageProvider to load existing data from AsyncStorage into memory
2. Synchronous Access: All read operations (getItem, multiGet, etc.) work immediately from memory
3. Async Persistence: All write operations (setItem, multiSet, etc.) update memory immediately and persist to AsyncStorage in the background
4. Error Handling: Persistence errors are logged but don't affect the synchronous operations

Platform Support

- ✅ iOS: Full support with AsyncStorage
- ✅ Android: Full support with AsyncStorage
- ✅ Web: Full support with localStorage fallback
- ✅ Expo: Full support with Expo AsyncStorage

Testing

The library includes comprehensive tests:

`sh


Unit tests

yarn test

Web integration tests

yarn playwright test
`

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

$3

`sh
git clone https://github.com/fullstackhouse/react-native-sync-storage.git
cd react-native-sync-storage
yarn install

Run tests

yarn test
yarn playwright test

Run example

yarn example ios # or android, web
``

License

MIT © FullStackHouse

Support

- 📧 Email: hello@fullstackhouse.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions

---

Made with ❤️ by FullStackHouse