sync
Real-time sync with Supabase, Loro CRDT, and IndexedDB. Use when working on files in src/lib/sync/.
When & Why to Use This Skill
This Claude skill provides a robust framework for implementing and maintaining real-time data synchronization systems using Supabase, Loro CRDT, and IndexedDB. It focuses on offline-first architecture, ensuring data integrity through a 'server as source of truth' model while leveraging local caching for performance. By following strict persistence flows and conflict resolution rules, it enables developers to build resilient, collaborative applications with built-in encryption and crash safety.
Use Cases
- Architecting offline-first web applications that require seamless data persistence between local IndexedDB storage and remote Supabase databases.
- Implementing complex real-time collaborative features using Loro CRDTs to handle multi-user conflict resolution automatically.
- Designing secure data synchronization pipelines that prioritize end-to-end encryption for sensitive user data at rest.
- Optimizing application performance and reliability through throttled background synchronization and efficient snapshot management.
| name | sync |
|---|---|
| description | Real-time sync with Supabase, Loro CRDT, and IndexedDB. Use when working on files in src/lib/sync/. |
Sync Guidelines
Core Principles
- Server is source of truth - IndexedDB is a cache
- All ops kept forever - no pruning, enables full audit trail
- Shallow snapshots for fast start - performance only, not compaction
- Encryption at rest - server sees encrypted blobs + plaintext version metadata
Persistence Flow
| Event | IndexedDB | Server |
|---|---|---|
| Local change | Immediate | Throttled (~2s) |
| Tab hidden/close | Immediate | Flush pending |
| Cold start | Load snapshot → usable | Background sync |
Critical Rules
- IndexedDB writes immediate - crash safety
- Server pushes throttled - use
lodash-esthrottle, ~2s - Encrypt before storage - never plaintext in IndexedDB or server
- Version vector plaintext - enables server filtering without decryption
has_unpushedflag critical - server must send ops (not snapshot) if client has local changes- Flush on visibility change - don't lose data on tab switch
Key Details
- loro-mirror auto-commits on
setState()- no manual debouncing subscribeLocalUpdatesfires after each commit with binary update- Snapshot refresh: ops > 1000 OR bytes > 1MB (not time-based)
Conflict Resolution
Loro handles automatically: last-write-wins per field, set union for arrays.
UI States
- Saved - all pushed
- Saving... - pending in buffer
- Offline - can't reach server