Offline-First Sync for SwiftData in Rork Max — Merging Changes Without Conflicts

How to detect and resolve conflicts

There are roughly three strategies, each trading implementation cost against safety. Choose by the nature of your app.

As an indie developer who has run a number of apps solo, I recommend starting with field-level merge. Last Write Wins is light to build but reproduces exactly the "order snaps back" incident above. CRDTs are powerful but too heavy to maintain for a domain that is little more than settings and favorites. With field-level merge, edits to separate attributes coexist, and you only fall back to a timestamp when the same attribute collides.

Implementing the merge

Compare the server's version (remote) with the local current value, field by field. The axis is "which side touched this field more recently." Rather than carry a per-attribute timestamp, here is a practical approximation using the record-level updatedAt and the local dirty flag.

func merge(local: WallpaperItem, remote: RemoteItem) {
    // a delete propagates first, as a tombstone
    if remote.isDeleted {
        local.isDeleted = true
        local.dirty = false
        local.revision = remote.revision
        return
    }
 
    if local.dirty {
        // unsent local edits exist. Keep whichever side "touched" each attribute.
        if remote.updatedAt > local.updatedAt {
            // take only the attributes remote changed; keep local edits
            local.title = remote.titleChanged ? remote.title : local.title
            local.sortIndex = remote.sortChanged ? remote.sortIndex : local.sortIndex
        }
        // do not clear dirty until the push succeeds
    } else {
        // local is clean. Apply remote directly.
        local.title = remote.title
        local.sortIndex = remote.sortIndex
        local.isFavorite = remote.isFavorite
        local.updatedAt = remote.updatedAt
    }
    local.revision = remote.revision
}

The key is to advance revision but never clear dirty while it is set. Clearing it would treat an edit that hasn't reached the server as "synced," and the next pull would erase it. Only after the push is acknowledged do you return to clean.

An outbox that never drops edits

The heart of offline-first is not pushing changes to the server immediately, but queuing them into a local outbox and sending in a batch once connectivity returns. Because the SwiftData record carries dirty, the send set is simply "a query for dirty rows."

@MainActor
func flushOutbox(context: ModelContext, api: SyncAPI) async {
    let pending = try? context.fetch(
        FetchDescriptor<WallpaperItem>(predicate: #Predicate { $0.dirty })
    )
    guard let pending, !pending.isEmpty else { return }
 
    for item in pending {
        do {
            // the idempotencyKey neutralizes duplicate sends
            let ack = try await api.push(
                item: item,
                idempotencyKey: "\(item.id)-\(item.updatedAt.timeIntervalSince1970)"
            )
            item.revision = ack.revision
            item.dirty = false           // clean only after success
        } catch {
            // on failure it stays dirty and is resent next time online
            break
        }
    }
    try? context.save()
}

Building the idempotencyKey from id plus the update timestamp means that if the success response is lost to a dead signal and the item is resent, the server processes the same key only once. Without it, entering and leaving a tunnel registers the same edit twice — a quiet, hard-to-reproduce bug that bites in production.

Trigger the flush from two places: when the app returns to the foreground (scenePhase becoming .active) for perceived immediacy, and from a BGAppRefreshTask to collect changes that piled up while it was closed.

Production judgments that paid off

Chasing perfect sync from day one never ends, so I hardened it in this order. First, add delete tombstones before anything else. Hard-deleting a record lets it resurrect from a device that hasn't heard about the deletion — the worst experience for a user: "I deleted it and it came back."

Second, always commit the local save before sending to the server. Show it as saved in the UI and let sync follow. What I learned running six apps in parallel is that the user is watching their own edit, not the network. As long as the edit survives, a sync delayed by a few minutes bothers no one.

Last, keep an escape hatch that falls back to a full re-fetch when you detect a revision mismatch. When field-level merge rarely drifts out of consistency, taking the server as truth and pulling fresh recovers faster than reasoning it through. Held as a safety valve, it spares you from burning hours on edge cases.

As a next step, add just updatedAt / isDeleted / dirty to your single most-edited model and wire flushOutbox to scenePhase. Even getting ordering and deletion to stay stable across devices noticeably changes how your support inbox feels. I hope it helps with your own build.