Getting Started with automerge

In automerge: R Bindings for 'Automerge' 'CRDT' Library

#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

What is Automerge?

Automerge is a library that enables automatic merging of concurrent changes without conflicts. It's built on the concept of Conflict-free Replicated Data Types (CRDTs), which are data structures designed to be safely replicated across multiple devices and automatically merged.

Key Benefits

• Automatic conflict resolution: Multiple users can edit the same document simultaneously without manual conflict resolution
• Offline-first: Changes can be made offline and synchronized later
• Cross-platform: Documents created in R can be synced with JavaScript, Python, and other implementations
• Version history: Complete change history is preserved for auditing and debugging
• Collaborative: Perfect for building collaborative applications like shared notebooks or data pipelines

Installation

#| eval: false
# From R-universe
install.packages("automerge", repos = "https://posit-dev.r-universe.dev")

# From GitHub
pak::pak("posit-dev/automerge-r")

Basic Usage

Let's start with the most fundamental operations:

#| label: setup
library(automerge)

Creating a Document

doc <- am_create()
print(doc)

Note: When you're done working with a document, you can explicitly free its resources with am_close(doc) if you don't want to wait for garbage collection.

Adding Data - Three Approaches

Automerge provides multiple ways to add data, from functional to R-idiomatic:

1. Functional API

am_put(doc, AM_ROOT, "name", "Alice")
am_put(doc, AM_ROOT, "age", 30L)
am_put(doc, AM_ROOT, "active", TRUE)
am_commit(doc, "Initial data")

am_get(doc, AM_ROOT, "name")
am_get(doc, AM_ROOT, "age")

2. S3 Operators (R-idiomatic)

doc[["email"]] <- "[e-mail]"
doc[["score"]] <- 95.5

doc[["name"]]
doc[["age"]]

# List all keys
names(doc)

3. Pipe-Friendly Style

doc2 <- am_create() |>
  am_put(AM_ROOT, "name", "Bob") |>
  am_put(AM_ROOT, "age", 25L) |>
  am_put(AM_ROOT, "active", TRUE) |>
  am_commit("Initial setup")

doc2 |> am_get(AM_ROOT, "name")

am_close(doc2)

Working with Nested Structures

Automerge supports nested data structures (maps within maps, lists within maps, etc.).

Recursive Conversion

The simplest approach is to use R's native list structures, which are automatically converted:

# Create document with nested structure in one call
doc3 <- am_create() |>
  am_put(
    AM_ROOT,
    "company",
    list(
      name = "Acme Corp",
      founded = 2020L,
      employees = list(
        list(name = "Alice", role = "Engineer"),
        list(name = "Bob", role = "Designer")
      ),
      office = list(
        address = list(
          street = "123 Main St",
          city = "Boston",
          zip = 02101L
        ),
        size = 5000.5
      )
    )
  ) |>
  am_commit("Add company data")

# Access nested data (verbose way)
company <- doc3[["company"]]
office <- am_get(doc3, company, "office")
address <- am_get(doc3, office, "address")
am_get(doc3, address, "city")

Path-Based Access

For deep structures, path-based helpers make navigation much easier:

# Much simpler - use path-based access
am_get_path(doc3, c("company", "office", "address", "city"))

# Create deep structure using paths
doc4 <- am_create()

am_put_path(doc4, c("config", "database", "host"), "localhost")
am_put_path(doc4, c("config", "database", "port"), 5432L)
am_put_path(doc4, c("config", "cache", "enabled"), TRUE)
am_put_path(doc4, c("config", "cache", "ttl"), 3600L)

# Retrieve values with paths
am_get_path(doc4, c("config", "database", "host"))

am_close(doc3)
am_close(doc4)

Converting R Data Structures

Use as_automerge() to convert entire R structures at once:

# Your existing R data
config_data <- list(
  app_name = "MyApp",
  version = "1.0.0",
  database = list(
    host = "localhost",
    port = 5432L,
    credentials = list(
      user = "admin",
      password_hash = "..."
    )
  ),
  features = list("auth", "api", "websocket")
)

# Convert to Automerge document
doc5 <- as_automerge(config_data)
am_commit(doc5, "Initial configuration")

# Easy access with paths
am_get_path(doc5, c("database", "port"))

am_close(doc5)

Working with Lists

Lists in R use 1-based indexing (standard R convention):

# Create a document with a list
doc6 <- am_create()
am_put(doc6, AM_ROOT, "items", AM_OBJ_TYPE_LIST)
items <- am_get(doc6, AM_ROOT, "items")

# Insert items
am_insert(doc6, items, 1, "first") # Insert at index 1
am_insert(doc6, items, 2, "second") # Insert at index 2
am_insert(doc6, items, 3, "third") # Insert at index 3

# Or use the "end" marker to append
am_insert(doc6, items, "end", "fourth")
am_put(doc6, items, "end", "fifth")

# Get list length
am_length(doc6, items)

# Access by index
am_get(doc6, items, 1)
am_get(doc6, items, 2)

am_close(doc6)

Special Automerge Types

Text Objects (for Collaborative Editing)

Regular strings use deterministic conflict resolution (one value wins). For collaborative text editing, use text objects:

doc7 <- am_create()

# Regular string (last-write-wins)
am_put(doc7, AM_ROOT, "title", "My Document")

# Text object (CRDT - supports collaborative editing)
am_put(doc7, AM_ROOT, "content", am_text("Initial content"))
text_obj <- am_get(doc7, AM_ROOT, "content")

# Text supports character-level operations
# For the text "Hello":
#  H e l l o
# 0 1 2 3 4 5  <- positions (0-based, between characters)

am_text_splice(text_obj, 8, 0, "amazing ") # Insert at position 8
am_text_content(text_obj)

# For collaborative editors, use am_text_update() which computes
# and applies the minimal diff in one step:
old_text <- am_text_content(text_obj)
am_text_update(text_obj, old_text, "New content from user input")
am_text_content(text_obj)

am_close(doc7)

Counters (for CRDT Counting)

Counters are special values that can be incremented/decremented without conflicts:

doc8 <- am_create()

# Create a counter
am_put(doc8, AM_ROOT, "score", am_counter(0))

am_counter_increment(doc8, AM_ROOT, "score", 10)
am_counter_increment(doc8, AM_ROOT, "score", 5)
am_counter_increment(doc8, AM_ROOT, "score", -3)

doc8[["score"]]

am_close(doc8)

Timestamps

POSIXct timestamps are natively supported:

doc9 <- am_create()

am_put(doc9, AM_ROOT, "created_at", Sys.time())
am_put(doc9, AM_ROOT, "updated_at", Sys.time())

doc9[["created_at"]]

am_close(doc9)

Saving and Loading Documents

Documents can be saved to binary format and loaded later:

# Save to binary format
bytes <- am_save(doc)

# Save to file
temp_file <- tempfile(fileext = ".automerge")
writeBin(bytes, temp_file)

# Load from binary
doc_loaded <- am_load(bytes)

# Or load from file
doc_from_file <- am_load(readBin(temp_file, "raw", 1e6))

# Verify data persisted
doc_from_file[["name"]]

am_close(doc)
am_close(doc_loaded)
am_close(doc_from_file)

Document Lifecycle

Committing Changes

doc10 <- am_create()

# Make changes
doc10[["x"]] <- 1
doc10[["y"]] <- 2

# Commit with message
am_commit(doc10, "Add x and y coordinates")

# Make more changes
doc10[["z"]] <- 3
am_commit(doc10, "Add z coordinate")

Forking Documents

Create independent copies:

doc11 <- am_fork(doc10)

# Changes to fork don't affect original
doc11[["w"]] <- 4
doc10[["w"]] # NULL - not in original

am_close(doc10)
am_close(doc11)

Merging Documents

Merge changes from one document into another:

# Create two documents
doc12 <- am_create()
doc12[["source"]] <- "doc12"
doc12[["value1"]] <- 100

doc13 <- am_create()
doc13[["source"]] <- "doc13"
doc13[["value2"]] <- 200

# Merge doc13 into doc12
am_merge(doc12, doc13)

# doc12 now has both values
doc12[["value1"]]
doc12[["value2"]]
doc12[["source"]] # One value wins deterministically for conflicting keys

am_close(doc12)
am_close(doc13)

Basic Synchronization

Automerge's key feature is automatic synchronization between documents:

# Create two peers
peer1 <- am_create()
peer1[["edited_by"]] <- "peer1"
peer1[["data1"]] <- 100
am_commit(peer1)

peer2 <- am_create()
peer2[["edited_by"]] <- "peer2"
peer2[["data2"]] <- 200
am_commit(peer2)

# Bidirectional sync (documents modified in place)
rounds <- am_sync(peer1, peer2)
rounds

# Both documents now have all data
peer1[["data1"]]
peer1[["data2"]]
peer2[["data1"]]
peer2[["data2"]]

am_close(peer1)
am_close(peer2)

Next Steps

• Learn about CRDT Concepts to understand the theory behind Automerge
• Explore Synchronization Patterns for collaborative workflows
• Check the Quick Reference for a one-page guide to all functions

Getting Help

# Function help
?am_create
?am_put
?am_sync

# Package help
?automerge
help(package = "automerge")

# All vignettes
vignette(package = "automerge")

automerge documentation built on Feb. 5, 2026, 5:08 p.m.