Synchronous storage library for React Native
npm install @fullstackhouse/react-native-sync-storageA synchronous storage library for React Native that provides immediate access to persisted data while maintaining async persistence in the background.


- 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
``sh`
npm install @fullstackhouse/react-native-sync-storageor
yarn add @fullstackhouse/react-native-sync-storage
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-storageor
yarn add @react-native-async-storage/async-storage
Follow the AsyncStorage installation guide for platform-specific setup.
`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
}
return (
);
}
export default function App() {
return (
);
}
`
`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();
`
#### 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 synchronouslysetItem(key: string, value: string): void
- - Set value synchronouslyremoveItem(key: string): void
- - Remove value synchronouslyclear(): void
- - Clear all data synchronouslygetAllKeys(): string[]
- - Get all keys synchronouslymultiGet(keys: string[]): Array<[string, string | null]>
- - Get multiple valuesmultiSet(keyValuePairs: Array<[string, string]>): void
- - Set multiple valuesmultiRemove(keys: string[]): void
- - Remove multiple valuesloaded: boolean
- - Whether storage has been loaded from AsyncStorage
#### useSyncStorage()
`typescript`
const { storage, loaded } = useSyncStorage();
Returns:
- storage: SyncStorage - The storage instanceloaded: boolean
- - Whether storage has been loaded
#### SyncStorageProvider
`typescript`
{children}
Props:
- prefix?: string - Optional prefix for all keyschildren: ReactNode
- - Child components
1. Initialization: Call storage.load() or use SyncStorageProvider to load existing data from AsyncStorage into memorygetItem
2. Synchronous Access: All read operations (, multiGet, etc.) work immediately from memorysetItem
3. Async Persistence: All write operations (, 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
- ✅ iOS: Full support with AsyncStorage
- ✅ Android: Full support with AsyncStorage
- ✅ Web: Full support with localStorage fallback
- ✅ Expo: Full support with Expo AsyncStorage
The library includes comprehensive tests:
`shUnit tests
yarn 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 installRun tests
yarn test
yarn playwright testRun example
yarn example ios # or android, web
``MIT © FullStackHouse
- 📧 Email: hello@fullstackhouse.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
---
Made with ❤️ by FullStackHouse