React Native Cloud Sync
iCloud key-value store, CloudKit, iCloud Drive and Google Drive behind one API - iOS, Android, web, both architectures.
Install the package:
npx expo install react-native-cloud-sync
The config plugin and the setup for bare React Native projects are covered in Installation.
✨ Features
- ☁️ Four providers, one API:
NSUbiquitousKeyValueStore(iCloud key-value store), CloudKit records, iCloud Drive documents and Google DriveappDataFolder. Use each directly or through one facade. - 🔄 Two-way sync between iOS and Android:
mirrorwrites to iCloud and Drive together,resolvereads whichever copy is newest. - 🍏 CloudKit on Android and web via CloudKit Web Services, against the same private database as iOS.
- 📂
icloudDocumentswrites to the user's iCloud Drive, visible in Files.app. - 🚨 Every failure is a typed rejection (
ERR_NOT_SIGNED_IN,ERR_QUOTA_EXCEEDED,ERR_RATE_LIMITEDwithretryAfterMs, ...).nullonly means "key doesn't exist". - 👤 All five
CKAccountStatusvalues, plusonAccountChangewithidentityChanged, which drops the previous account's caches and queued writes. - 🔔
onRemoteChangeon every provider and the facade, Google Drive included (via its change cursor). - 📦 Size tiering: small values go to the key-value store, larger ones to a
CKRecordfield, binary to aCKAssetor a resumable Drive upload. - 🔁 Durable, bounded outbox for retryable failures: backoff honours retry hints, drains on foreground, never overwrites a newer write.
- 🧺 Real batching:
multiGet/multiSet/multiRemove/clearsend one request per provider. - 🪝 Hooks from
/hooks:useCloudItem,useCloudItems,useCloudCollection,useAccountStatus,usePendingWrites. Stale responses are dropped, nosetStateafter unmount. - 🔐
cloudKitEncrypteduses CloudKitencryptedValues, so only ciphertext leaves the device. Other providers take acodecfor your own cipher. - 🧪 Exported in-memory provider with fault injection and a native mock (
/testing,/jest-mock): test every failure path in Jest. - ⚙️ React Native 0.71 to 0.86+, old and new architecture.
💡 Why?
Existing React Native cloud storage libraries each wrap one provider and repeat the same defects. Two ship a setItem that reports a failed write as success (one checks the wrong error variable, the other ignores the result). A third flattens five iCloud account states into one boolean.
A catch { return null } makes "not signed in", "offline", "out of storage" and "no such key" look the same, so the app can't tell the user what happened or decide whether to retry.
This library starts from the error contract; providers come second.
📚 Upstream documentation
This package is a wrapper. When something behaves unexpectedly, check Apple's or Google's docs.
Apple
NSUbiquitousKeyValueStore | The iCloud key-value store; 1 MB / 1024-key limits |
CloudKit · CKDatabase · CKRecord | Records in the user's private database |
CKAsset · CKRecordZone | Binary assets and custom zones |
CKAccountStatus | The five account states this package surfaces verbatim |
| CloudKit Web Services | The REST API behind the Android and web paths |
| Authentication · Data size limits · Error codes | Worth reading before shipping CloudKit on Android |
| iCloud entitlements | The keys the config plugin writes |
| CloudKit Console | Where containers, schemas, API tokens and the sign-in callback live |
The appDataFolder | The hidden per-app folder this package stores into |
Drive files resource | The REST endpoints behind the provider |
| Drive API scopes | Why the scope is drive.appdata |