Conflict Resolution

The Two Conflict Strategies

Replace Strategy

The existing app is completely replaced with the bundle content. All pages, panes, and widgets not in the bundle are deleted. All local modifications to the target app are lost.

// Replace strategy behavior:
// Before: target app has pages [A, B, C] with local tweaks
// Bundle contains: pages [A, B, D]
// After Replace: target app has pages [A, B, D] — page C deleted, tweaks on A/B overwritten

Use Replace when: the target is a clean environment (staging or prod), you want the target to exactly match the source, and no local customizations need preserving.

Merge Strategy

The importer applies changes at the element level. Elements present in the bundle are updated; elements in the target but absent from the bundle are left untouched; new elements in the bundle are added.

// Merge strategy behavior:
// Before: target app has pages [A, B, C] with local tweaks on C
// Bundle contains: pages [A, B, D]
// After Merge:
//   - Page A: updated to bundle version (local tweaks on A overwritten)
//   - Page B: updated to bundle version
//   - Page C: kept as-is (not in bundle — untouched)
//   - Page D: added (new in bundle)

Use Merge when: the target has local customizations that should survive, you are applying a partial update, or you want additive updates without removing existing content.

Conflict Strategy Comparison

Conflict Resolution in API Mode

When using the Import API, specify the strategy in the request body:

POST /api/apps/import
Content-Type: application/json

{
  "bundle": { ... },           // The bundle JSON
  "conflictStrategy": "replace"  // "replace" | "merge"
}