Firestore Offline Persistence โ
TIP
Interactive Architecture Tour: Open Live Tour (Offline Persistence)
This document details client-side IndexedDB caching, multi-tab synchronization, private browsing fallbacks, and conflict resolution strategies.
1. Offline Caching & Multi-Tab Synchronization โ
To support uninterrupted scripture study during commutes or connectivity drops, Firestore caches data locally in IndexedDB:
typescript
db = initializeFirestore(app, {
localCache: persistentLocalCache({
tabManager: persistentMultipleTabManager()
})
});โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Client App โ
โ Tab 1 (Active Chat) Tab 2 (Dashboard) โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ persistentMultipleTabManager (Shared Lock) โ
โ Coordinating access and mutation syncing โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ IndexedDB Local Cache โ
โ Document cache and offline write mutation queue โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โผ
[ Firestore Cloud Sync ]- Multi-Tab Coordination (
persistentMultipleTabManager): Allows multiple tabs and WebViews to share the same IndexedDB store safely without locking conflicts. - Offline Mutation Queue: Writes made offline are queued locally and automatically committed to Cloud Firestore once connectivity is restored.
2. Private Browsing & Fallback Strategies โ
To prevent startup crashes in environments where IndexedDB is blocked (e.g. iOS Safari Private Browsing):
typescript
let db: Firestore;
try {
db = initializeFirestore(app, {
localCache: persistentLocalCache({
tabManager: persistentMultipleTabManager()
})
});
} catch (e) {
console.warn("IndexedDB not available, falling back to memory cache:", e);
db = getFirestore(app); // Safe fallback to in-memory caching
}3. Offline Conflict Resolution & Safeguards โ
- Personal Notes & Settings: Stored within dedicated user subcollections (
users/{uid}/notes), eliminating multi-user edit collisions. - Transaction Gating: Operations requiring server-side validation (such as joining a group with a 5-member cap) are cleanly blocked when offline, prompting the user to reconnect.
- Optimistic UI for Messages: New chat messages are assigned temporary IDs (
tempId) for instant rendering, cleanly resolved once the backend commits the record.