A TinyBase persister that uses Expo FileSystem for persistent storage in React Native Expo apps.
- Persists TinyBase stores to the device filesystem using Expo FileSystem API (v54)
- Auto-save and auto-load capabilities for seamless data synchronization
- Full TypeScript support with complete type definitions
- Compatible with both
StoreandMergeableStore - Built on TinyBase v6+ with zero additional runtime dependencies
- Automatic file change polling for multi-instance synchronization
TinyBase Stores exist only in memory by default. Persisters solve this by enabling you to save and load your Store data to various storage backends. This is essential for:
- Maintaining application state across app restarts and device reboots
- Preserving user data between sessions
- Creating offline-first mobile applications
- Synchronizing data with external storage
Learn more about TinyBase persistence.
Assumes your Expo app already has Tinybase installed.
# npm
npm install @mote-software/tinybase-persister-expo-file-system
# pnpm
pnpm add @mote-software/tinybase-persister-expo-file-system
# yarn
yarn add @mote-software/tinybase-persister-expo-file-systemThis package requires:
tinybase^6.0.0expo-file-system^19.0.17
import { createStore } from 'tinybase';
import { createExpoFileSystemPersister } from '@mote-software/tinybase-persister-expo-file-system';
import * as FileSystem from 'expo-file-system';
// Create a TinyBase store
const store = createStore();
// Define the file path (using Expo FileSystem v19+ API)
const filePath = `${new FileSystem.Directory(FileSystem.Paths.document).uri}/my-store.json`;
// Create the persister
const persister = createExpoFileSystemPersister(
store,
filePath,
(error) => {
console.error('Persister error:', error);
}
);
// Load existing data and start auto-saving
await persister.startAutoLoad();
await persister.startAutoSave();
// Now your store is automatically persisted!
store.setCell('pets', 'fido', 'species', 'dog');
// This change is automatically saved to the file systemCreates a new persister instance that uses Expo FileSystem for storage.
function createExpoFileSystemPersister(
store: Store | MergeableStore,
filePath: string,
onIgnoredError?: (error: any) => void
): ExpoFileSystemPersisterParameters:
store- The TinyBase Store or MergeableStore to persistfilePath- Absolute path to the file (e.g.,`${new FileSystem.Directory(FileSystem.Paths.document).uri}/store.json`)onIgnoredError- Optional callback for handling non-critical errors
Returns: An ExpoFileSystemPersister instance with all standard TinyBase Persister methods.
Extends the standard TinyBase Persister interface with an additional method:
Returns the file path used by this persister.
const filePath = persister.getFilePath();All standard TinyBase Persister methods are available:
// Manual operations
await persister.save(); // Manually save store to file
await persister.load(); // Manually load store from file
// Automatic synchronization
await persister.startAutoSave(); // Auto-save on store changes
await persister.startAutoLoad(); // Auto-load on file changes
await persister.stopAutoSave();
await persister.stopAutoLoad();
// Status
const stats = persister.getStats(); // Get persistence statisticsThis persister uses a polling mechanism (checking every 1 second) to detect external file changes when startAutoLoad() is active. This enables synchronization between multiple app instances or external file modifications.
Check out the complete example app in the apps/example directory of this repository for a working demonstration with a persistent counter.
See CONTRIBUTORS.md for development setup, building, testing, and contribution guidelines.
- TinyBase Documentation
- TinyBase Persistence Guide
- Expo FileSystem Documentation (v54)
- GitHub Repository
MIT