Skip to main content

React Native Cloud Sync

iCloud key-value store, CloudKit, iCloud Drive and Google Drive behind one API - iOS, Android, web, both architectures.

Same data on iPhone, iPad, Mac, Android and the web, synced both ways.

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 Drive appDataFolder. Use each directly or through one facade.
  • 🔄 Two-way sync between iOS and Android: mirror writes to iCloud and Drive together, resolve reads whichever copy is newest.
  • 🍏 CloudKit on Android and web via CloudKit Web Services, against the same private database as iOS.
  • 📂 icloudDocuments writes 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_LIMITED with retryAfterMs, ...). null only means "key doesn't exist".
  • 👤 All five CKAccountStatus values, plus onAccountChange with identityChanged, which drops the previous account's caches and queued writes.
  • 🔔 onRemoteChange on 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 CKRecord field, binary to a CKAsset or 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/clear send one request per provider.
  • 🪝 Hooks from /hooks: useCloudItem, useCloudItems, useCloudCollection, useAccountStatus, usePendingWrites. Stale responses are dropped, no setState after unmount.
  • 🔐 cloudKitEncrypted uses CloudKit encryptedValues, so only ciphertext leaves the device. Other providers take a codec for 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

NSUbiquitousKeyValueStoreThe iCloud key-value store; 1 MB / 1024-key limits
CloudKit · CKDatabase · CKRecordRecords in the user's private database
CKAsset · CKRecordZoneBinary assets and custom zones
CKAccountStatusThe five account states this package surfaces verbatim
CloudKit Web ServicesThe REST API behind the Android and web paths
Authentication · Data size limits · Error codesWorth reading before shipping CloudKit on Android
iCloud entitlementsThe keys the config plugin writes
CloudKit ConsoleWhere containers, schemas, API tokens and the sign-in callback live

Google

The appDataFolderThe hidden per-app folder this package stores into
Drive files resourceThe REST endpoints behind the provider
Drive API scopesWhy the scope is drive.appdata