Offline-First Edits with Realm Sync: Setup and Verification

The problem: edits that disappear when the device reconnects

Imagine a user opens your note-taking app on a train, changes a draft, and closes the app. The phone stays offline for hours. When the user finally reconnects, you expect the edit to appear on every device. Instead, the change is missing, or an older version from another device has overwritten it.

This is the offline-first consistency problem. Without a sync layer, developers must build a local write queue, detect reconnection, upload changes, and resolve conflicts by hand. Realm Sync is designed to handle that replication automatically: it keeps a client-side Realm in step with a server-side Realm Object Server over a persistent connection, typically a WebSocket.

Configure Realm Sync for offline-first writes

Realm Sync maintains a local copy of the data on the device and a canonical copy on the server. While offline, writes go to the local Realm. When connectivity returns, the client uploads those writes and merges any changes that happened on the server.

Below is an example configuration using the Realm Swift SDK with Flexible Sync. API names vary by SDK version, so treat this as a structural guide rather than a copy-paste snippet.

import RealmSwift

let config = Realm.Configuration(
    syncConfiguration: .init(
        user: app.currentUser,
        flexibleSync: true
    )
)
let realm = try! Realm(configuration: config)

// Subscribe to the subset of data this device needs.
let notes = realm.objects(Note.self)
try! realm.subscriptions.update {
    $0.append(QuerySubscription(name: "myNotes") {
        $0.ownerId == currentUserId
    })
}

// A write made while offline is stored locally first.
try! realm.write {
    let note = Note()
    note.title = "Draft"
    note.ownerId = currentUserId
    realm.add(note)
}

Flexible Sync lets the client request only the objects it needs, such as notes owned by the current user. A Realm Object Server is the server component that stores the authoritative copy and coordinates merges between devices.

Test the offline path and verify convergence

Do not assume sync works because the app builds. Test the full offline cycle on a physical device or emulator.

1. Enable airplane mode on the device.
2. Create or edit objects in the app.
3. Close and reopen the app to confirm local reads still return the changes.
4. Disable airplane mode.
5. Watch the console or logcat for sync session activity and upload progress.
6. Open the server Realm in Realm Studio or the server dashboard and confirm the new object appears.
7. Compare object counts and field values on the client and server before and after reconnection.

Run these steps where you develop the app: Xcode for iOS, Android Studio for Android. You need a configured Realm App ID and network access to the sync server. A risk is testing only on Wi-Fi; cellular reconnection can behave differently, so test both.

Trade-offs and limitations

• Network traffic. Every local write is replicated to the server, which increases data usage compared to a purely local database.
• Schema coordination. Changing an object model requires compatible schema versions on client and server, or sync can fail.
• Conflict resolution. The default policy is typically last-write-wins: the most recent write overwrites earlier concurrent changes. If your business logic requires merging field-level changes or preserving all edits, you must implement a custom resolver, which adds complexity.
• Operational overhead. A self-hosted Realm Object Server requires infrastructure and monitoring; the managed service shifts that cost to a subscription.

Default merge behavior can silently discard changes that do not match your expectations. Verify merge behavior with representative data sets before relying on it in production.

Closing checklist

• Enable Flexible Sync and subscribe to the data subsets each device needs.
• Write offline, reconnect, and confirm the object appears on the server.
• Compare client and server field values after sync to detect unexpected loss.
• Decide whether last-write-wins is acceptable or if you need custom conflict resolution.

Realm Sync removes the need to build a sync queue from scratch, but it does not remove the need to test what happens when the network disappears and comes back.