Conflict resolution

Rebase strategies, field-level conflict detection, and manual resolution for concurrent edits.

When multiple clients modify the same data, the rebase algorithm resolves conflicts automatically. This guide covers detection, strategies, and manual intervention.

Server-sequenced model

The server assigns global order. See Sync protocol for details.

How rebase works

When a server delta arrives for a model with pending local transactions, the client replays local changes on top of the new server state.


flowchart TD
    A[Server delta arrives] --> B[Index pending txs by model+id]
    B --> C{For each server action}
    C --> D{Is this our own tx?}
    D -->|Yes| E[Mark as confirmed]
    D -->|No| F{Conflicts with pending tx?}
    F -->|No| G[Keep pending tx]
    F -->|Yes| H[Detect conflict type]
    H --> I[Apply resolution strategy]
    I --> J[Update in-memory model]
    C --> K[Remaining txs stay pending]

Three outcomes per server action:

Own transaction: clientTxId matches: confirmed and removed from outbox.
No conflict: Different model/ID or different fields. Pending transaction stays.

Conflict resolution

Rebase strategies, field-level conflict detection, and manual resolution for concurrent edits.

When multiple clients modify the same data, the rebase algorithm resolves conflicts automatically. This guide covers detection, strategies, and manual intervention.

Server-sequenced model

The server assigns global order. See Sync protocol for details.

How rebase works

When a server delta arrives for a model with pending local transactions, the client replays local changes on top of the new server state.


flowchart TD
    A[Server delta arrives] --> B[Index pending txs by model+id]
    B --> C{For each server action}
    C --> D{Is this our own tx?}
    D -->|Yes| E[Mark as confirmed]
    D -->|No| F{Conflicts with pending tx?}
    F -->|No| G[Keep pending tx]
    F -->|Yes| H[Detect conflict type]
    H --> I[Apply resolution strategy]
    I --> J[Update in-memory model]
    C --> K[Remaining txs stay pending]

Three outcomes per server action:

Own transaction: clientTxId matches: confirmed and removed from outbox.
No conflict: Different model/ID or different fields. Pending transaction stays.

Type	Local action	Server action	Example
`update-update`	Update	Update	Both changed the same field
`update-delete`	Update	Delete	Client edited, server deleted
`delete-update`	Delete	Update	Client deleted, server edited
`insert-insert`	Insert	Insert	Both inserted the same ID (rare)

Scenario	Recommended strategy
General purpose (forms, settings)	`rebaseStrategy: "merge"` + `fieldLevelConflicts: true` (default)
Simple apps, few concurrent users	`rebaseStrategy: "server-wins"` (default)
Collaborative text editing	Use Yjs CRDTs instead
Critical data (finance, legal)	`rebaseStrategy: "server-wins"` with `rebaseConflict` event handler for custom UI
Force-update operations	`rebaseStrategy: "client-wins"`

"use client"; import { useState, useEffect } from "react"; import { useSyncClient } from "@stratasync/react"; interface ConflictRecord { modelName: string; modelId: string; conflictType: string; resolution: string; } export function ConflictResolver() { const { client } = useSyncClient(); const [conflicts, setConflicts] = useState<ConflictRecord[]>([]); useEffect(() => { const unsubscribe = client.onEvent((event) => { if (event.type !== "rebaseConflict") { return; } setConflicts((prev) => [ ...prev, { modelName: event.modelName, modelId: event.modelId, conflictType: event.conflictType, resolution: event.resolution, }, ]); }); return unsubscribe; }, [client]); if (conflicts.length === 0) { return null; } function dismiss(conflict: ConflictRecord) { setConflicts((prev) => prev.filter((c) => c !== conflict)); } async function retryWithClient(conflict: ConflictRecord) { await client.update(conflict.modelName, conflict.modelId, {}); setConflicts((prev) => prev.filter((c) => c !== conflict)); } return ( <div className="fixed bottom-4 right-4 bg-white border rounded-lg shadow-lg p-4 max-w-md"> <h3 className="font-bold mb-2"> {conflicts.length} conflict{conflicts.length > 1 ? "s" : ""} detected </h3> {conflicts.map((conflict, i) => ( <div key={i} className="border-t pt-2 mt-2"> <p className="text-sm"> {conflict.conflictType} on {conflict.modelName}:{conflict.modelId} </p> <div className="flex gap-2 mt-1"> <button onClick={() => dismiss(conflict)} className="text-xs px-2 py-1 bg-gray-100 rounded" > Keep server version </button> <button onClick={() => retryWithClient(conflict)} className="text-xs px-2 py-1 bg-blue-100 rounded" > Keep my changes </button> </div> </div> ))} </div> ); }

Conflict resolution

Server-sequenced model

How rebase works

Conflict resolution

Server-sequenced model

How rebase works

Conflict types

Resolution strategies

server-wins (default)

client-wins

merge

Choosing a strategy

Field-level conflict detection

Handling conflicts manually

Subscribing to the rebaseConflict event

Surfacing conflicts in the UI

Concurrent edit examples

Field-level conflicts + merge (recommended)

Without field-level conflicts (server-wins)

Next steps