Repository files navigation

Cirrus provides simpleCloudKit sync forCodable Swift models. Rather than support every CloudKit feature, Cirrus is opinionated and prioritizes simplicity, reliability, and ergonomics with Swift value types.

Afterinstalling and following Apple's steps forEnabling CloudKit in Your App:

1. Register your app for remote CloudKit push notifications

// AppDelegate.swiftfunc application(  _ application:UIApplication,  didFinishLaunchingWithOptions launchOptions:[UIApplication.LaunchOptionsKey:Any]?)->Bool{...  application.registerForRemoteNotifications()...}

2. Conform your model(s) toCloudKitCodable

import CloudKitCodablestructLandmark:CloudKitCodable{structCoordinate:Codable{letlatitude:Doubleletlongitude:Double}letidentifier:UUIDletname:Stringletcoordinate:Coordinate  // MARK: - CloudKitCodable  /// A key that uniquely identifies the model. Use this identifier to update your   /// associated local models when the sync engine emits changes.varcloudKitIdentifier:CloudKitIdentifier{return identifier.uuidString}  /// Managed by the sync engine, this should be set to nil when creating a new model.  /// Be sure to save this when persisting models locally.varcloudKitSystemFields:Data?=nil  /// Describes how to handle conflicts between client and server models.publicstaticfunc resolveConflict(clientModel:Self, serverModel:Self)->Self?{    // Use `cloudKitLastModifiedDate` to check when models were last saved to the serverguardlet clientDate= clientModel.cloudKitLastModifiedDate,let serverDate= serverModel.cloudKitLastModifiedDateelse{return clientModel}return clientDate> serverDate? clientModel: serverModel}}

3. Initialize aSyncEngine for the model

import CirrusletsyncEngine=SyncEngine<Landmark>()

4. Configure theSyncEngine to process remote changes

// AppDelegate.swiftfunc application(  _ application:UIApplication, didReceiveRemoteNotification userInfo:[AnyHashable:Any]){  syncEngine.processRemoteChangeNotification(with: userInfo)...}

5. Start syncing

// Upload new or updated modelssyncEngine.upload(newLandmarks)// Delete modelssyncEngine.delete(oldLandmark)// Observe remote model changessyncEngine.modelsChanged.sink{ changein    // Update local modelsswitch change{caselet.updated(models):...caselet.deleted(modelIDs):...}}// Observe iCloud account status changessyncEngine.$accountStatus.sink{ accountStatusinswitch accountStatus{case.available:...case.noAccount:......}}

And that's it! Cirrus supports syncing multiple model types too, just initialize and configure a newSyncEngine for every type you want to sync.

To see an example of how Cirrus can be integrated into an app, clone this repository and open theCirrusExample Xcode project.

You can add Cirrus to an Xcode project by adding it as a package dependency.

1. From theFile menu, selectSwift Packages › Add Package Dependency…
2. Enter "https://github.com/jayhickey/cirrus" into the package repository URL text field
3. Depending on how your project is structured:
   • If you have a single application target that needs access to the library, add bothCirrus andCloudKitCodable directly to your application.
   • If you have multiple targets where your models are in one target but you would like to handle syncing with Cirrus in another, then addCloudKitCodable to your model target andCirrus to your syncing target.

Cirrus only supports private iCloud databases. If you need to store data in a public iCloud database, Cirrus is not the right tool for you.

NestedCodable types onCloudKitCodable models willnot be stored as separateCKRecord references; they are saved asData blobs on the top levelCKRecord. This leads to two important caveats:

1. CKRecord has a1 MB data limit, so large models may not fit within a single record. TheSyncEngine will not attempt to sync any models that are larger than 1 MB. If you are hitting this limitation, consider normalizing your data by creating discreteCloudKitCodable models that have identifier references to each other. You can use multipleSyncEngines to sync each model type.
2. If any child models have properties that reference on-disk file URLs, they will not be converted intoCKAssets and stored in CloudKit. If you have a need to store files that are referenced by local file URLs on child models, you can override theEncodableencode(to:) andDecodableinit(from:) methods on your model to set the file URLs as keys on the coding container of the top levelCloudKitCodable type. TheSyncEngine will then be able to sync your files to iCloud.

This library is released under the MIT license. SeeLICENSE for details.

Thanks toTim Bueno for helping to build Cirrus.