Required dependencies

This is a pure Rust crate. There are no npm packages to install. Add it to your Cargo.toml:

# No npm install needed. Add to Cargo.toml instead:
# automerge = "0.5"   # check crates.io for the latest version
cargo add automerge

If you are compiling to WebAssembly (via automerge-wasm), you also need:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli wasm-opt

No iOS pod install, Android linking, or Expo prebuild steps are required for pure Rust targets.

Project setup

1. Clone or copy the source/ directory (which maps to rust/automerge) into your workspace, e.g. vendor/automerge.

2. In your workspace Cargo.toml, add a path dependency:

   [dependencies]
   automerge = { path = "vendor/automerge" }
   

3. Alternatively, use the published crate directly and treat source/ as a reference:

   [dependencies]
   automerge = "0.5"
   

4. Enable optional features as needed in Cargo.toml:

   automerge = { version = "0.5", features = ["serde"] }
   

5. No environment variables or tsconfig changes are required. This is a native Rust crate with no Node.js surface until you layer automerge-wasm on top.

6. Run tests to verify the vendored source is intact:

   cd vendor/automerge
   cargo test
   

Public API

The file listing exposes several primary surfaces. Because no source excerpts were provided, the symbols below are derived from the canonical module names, the README, and the examples directory.

Automerge

use automerge::{Automerge, ReadDoc, ROOT};

let mut doc: Automerge = Automerge::new();

The main document type. Holds the full CRDT state including the operation set, change graph, and actor ID. Use this when you need explicit control over when changes are committed (pair with a Transaction). Load an existing document with Automerge::load(&bytes).

AutoCommit

use automerge::{AutoCommit, ObjType, ReadDoc, ROOT};

let mut doc = AutoCommit::new();
let map = doc.put_object(ROOT, "config", ObjType::Map)?;
doc.put(&map, "version", 1u64)?;

A convenience wrapper around Automerge that commits after every operation. Use this when you do not need to batch multiple writes into a single atomic change. Ideal for simple CLI tools and scripts.

ReadDoc (trait)

use automerge::{ReadDoc, ROOT};

// Implemented by both Automerge and AutoCommit
let val = doc.get(ROOT, "version")?;

The unified read interface. Any type that implements ReadDoc supports get, keys, values, length, text, marks, and cursor-based access. Code your read-only helpers against &impl ReadDoc so they work with both Automerge and AutoCommit.

sync::State and sync::Message

use automerge::sync::{Message, State, SyncDoc};

let mut sync_state = State::new();
let msg: Option<Message> = doc.generate_sync_message(&mut sync_state);

The sync protocol state machine. One State instance per remote peer tracks what that peer has seen. Call generate_sync_message to produce a message to send, and receive_sync_message to apply an incoming one. No transport is prescribed; wrap messages in whatever framing your network layer uses.

Working examples

Scenario - Creating and reading a collaborative map

A local-first settings store where two "users" independently edit and then merge.

// This is a Rust snippet — paste into src/main.rs

use automerge::{AutoCommit, ObjType, ReadDoc, ROOT};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Actor A creates a document
    let mut doc_a = AutoCommit::new();
    let settings = doc_a.put_object(ROOT, "settings", ObjType::Map)?;
    doc_a.put(&settings, "theme", "dark")?;
    doc_a.put(&settings, "fontSize", 14u64)?;

    // Save and hand to actor B
    let bytes = doc_a.save();
    let mut doc_b = AutoCommit::load(&bytes)?;

    // B makes an independent change
    let settings_b = doc_b.get(ROOT, "settings")?
        .and_then(|(_, id)| id.into_object())
        .unwrap();
    doc_b.put(&settings_b, "theme", "light")?;

    // A merges B's changes
    doc_a.merge(&mut doc_b)?;

    // Both actors now converge — last-write-wins on "theme"
    let (val, _) = doc_a.get(&settings, "theme")?.unwrap();
    println!("theme = {:?}", val);
    Ok(())
}

Scenario - Collaborative text editing with marks

A rich-text document where one peer bolds a range and another inserts text; both changes are merged.

use automerge::{AutoCommit, ObjType, ReadDoc, ROOT, marks::Mark};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut doc = AutoCommit::new();
    let text = doc.put_object(ROOT, "body", ObjType::Text)?;
    doc.splice_text(&text, 0, 0, "Hello world")?;

    // Bold "world" (characters 6..11)
    doc.mark(
        &text,
        automerge::marks::MarkSet::from([(
            "bold",
            automerge::ScalarValue::Boolean(true),
        )]),
        6..11,
        automerge::marks::ExpandMark::None,
    )?;

    let content = doc.text(&text)?;
    println!("text = {}", content);

    let active_marks = doc.marks(&text)?;
    println!("marks = {:?}", active_marks);
    Ok(())
}

Scenario - Peer sync over a custom transport

Two in-process peers exchanging sync messages until quiescent.

use automerge::{AutoCommit, ObjType, ROOT};
use automerge::sync::{Message, State, SyncDoc};

fn sync_until_quiescent(a: &mut AutoCommit, b: &mut AutoCommit) {
    let mut state_a = State::new(); // A's view of B
    let mut state_b = State::new(); // B's view of A

    loop {
        let msg_from_a = a.generate_sync_message(&mut state_a);
        if let Some(m) = msg_from_a {
            b.receive_sync_message(&mut state_b, m).unwrap();
        }

        let msg_from_b = b.generate_sync_message(&mut state_b);
        if let Some(m) = msg_from_b {
            a.receive_sync_message(&mut state_a, m).unwrap();
        }

        if a.generate_sync_message(&mut state_a).is_none()
            && b.generate_sync_message(&mut state_b).is_none()
        {
            break;
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut peer_a = AutoCommit::new();
    let counter = peer_a.put_object(ROOT, "counter", ObjType::Map)?;
    peer_a.put(&counter, "value", 0u64)?;

    let mut peer_b = AutoCommit::load(&peer_a.save())?;
    peer_a.put(&counter, "value", 42u64)?;

    sync_until_quiescent(&mut peer_a, &mut peer_b);

    println!("peers converged");
    Ok(())
}

File walkthrough

• benches/ - Criterion benchmark suite covering load/save round-trips, map write throughput, range iteration, and sync message generation. Run with cargo bench.
• examples/ - quickstart.rs is the canonical first-use example; watch.rs shows change observation patterns.
• fuzz/ - Libfuzzer harness targeting Automerge::load. Run with cargo fuzz run load.
• src/automerge.rs - The Automerge struct: actor ID management, applying changes, forking, merging, and saving.
• src/autocommit.rs - AutoCommit thin wrapper; delegates to Automerge with an implicit per-operation commit.
• src/transaction.rs / src/transaction/ - Transaction type for grouping multiple mutations; committed or rolled back as a unit.
• src/sync.rs / src/sync/ - Bloom-filter peer-state tracking and message (de)serialization for the sync protocol.
• src/storage.rs / src/storage/ - Automerge binary format encoder and decoder (the .automerge file format).
• src/op_set2.rs / src/op_set2/ - The internal operation set: indexed, columnar storage of every CRDT operation.
• src/columnar/ - Low-level columnar encoding (RLE, delta, boolean, key, value columns) used by storage and op set.
• src/patches.rs / src/patches/ - PatchLog for computing incremental diffs; used for UI binding and testing.
• src/iter.rs / src/iter/ - Lazy iterators over keys, values, spans, marks, and list elements.
• src/hydrate.rs / src/hydrate/ - Converts internal op-set state into materialized Value trees.
• src/marks.rs - Rich-text Mark, MarkSet, and ExpandMark types for annotating text ranges.
• src/types.rs - Core type aliases and structs: ObjId, OpId, Prop, Clock, ActorId.
• src/value.rs - Value<'_> and ScalarValue enums wrapping all Automerge-typed data.
• src/error.rs - AutomergeError and related error variants.
• src/exid.rs - ExId (external object ID): the stable, serializable handle to any object in the document.
• src/cursor.rs - Cursor for stable text/list positions that survive concurrent insertions.
• src/read.rs - ReadDoc trait definition; implemented by Automerge, AutoCommit, Transaction.
• src/change.rs / src/change_graph.rs - Change struct and ChangeGraph for causal dependency tracking.
• src/clock.rs - Clock (state vector) used to determine causal ordering between changes.
• src/text_diff.rs / src/text_value.rs - Myers-diff-based text diffing and the TextValue abstraction.
• src/autoserde.rs - Optional serde serialize/deserialize implementations for Automerge types.
• src/convert.rs - Conversion utilities between internal types and public-facing types.
• src/legacy/ - Compatibility layer for older Automerge binary formats.
• src/query/ - Internal query engine for looking up values, parents, and list positions in the op set.
• src/sequence_tree.rs - B-tree backing sequence (list/text) operations.
• src/indexed_cache.rs - Interning cache mapping actor IDs and strings to compact integer indices.
• src/change_queue.rs - Queue of out-of-order changes awaiting causal dependencies.
• src/validation.rs - Change validation logic applied before insertion into the op set.
• Cargo.toml - Crate manifest; declares features (serde, wasm), dependencies, and bench targets.
• README.md - Project overview, status, build instructions, and community links.

Common pitfalls and fixes

• Rust edition mismatch: the crate uses Rust 2021 edition features; ensure your rustup toolchain is stable 1.65 or later (rustup update stable).
• wasm32 target missing: compiling for WASM fails with "can't find crate for std"; fix with rustup target add wasm32-unknown-unknown.
• Actor ID collisions in tests: creating two AutoCommit::new() documents in the same process may share the same random actor ID in some configurations; set distinct actors with AutoCommit::new().with_actor(ActorId::random()).
• ExId not Send across threads: ExId borrows the document's actor cache; clone the document or use Automerge::fork to work across threads rather than sharing a raw ExId.
• Binary format version mismatch: loading bytes produced by a newer Automerge version with an older library returns AutomergeError::InvalidChange; pin the crate version across all binaries in a system.
• Marks range panics: passing an out-of-bounds usize range to mark() panics rather than returning an error; always validate text length with doc.length(&text_obj) before computing ranges.

Vibe-coding prompt template

I have the Automerge Rust core library vendored at `vendor/automerge/` in my
project. I also have `USAGE.md` at the repo root describing its API and file
layout.

Please help me integrate Automerge into my existing Rust project step by step:

1. Read `USAGE.md` fully before generating any code.
2. Add the path dependency to my `Cargo.toml` (at `Cargo.toml` in the repo
   root, NOT inside `vendor/`).
3. Create a `src/collab.rs` module that exposes:
   - A `CollabDoc` struct wrapping `AutoCommit`.
   - A `new()` constructor.
   - A `apply_patch(key: &str, value: &str)` method that writes into a root
     map and returns the updated bytes via `save()`.
   - A `load(bytes: &[u8]) -> Result<CollabDoc, AutomergeError>` constructor.
4. Wire `collab::CollabDoc` into my existing `main.rs`.
5. Add a sync helper that takes two `&mut CollabDoc` and calls
   `generate_sync_message` / `receive_sync_message` in a loop until
   quiescent, using the `sync::State` + `SyncDoc` API shown in `USAGE.md`.
6. Use only symbols documented in `USAGE.md`; do not invent new Automerge API.
7. Add inline comments explaining the CRDT semantics at each step.

My project structure: [DESCRIBE YOUR STRUCTURE HERE]
My Rust edition: [2021 or 2018]

License and credit

Automerge is released under the MIT License. See source/LICENSE if present, or the upstream repository for the full license text. This AVCP block packages the Rust core library from the automerge crate maintained by Ink & Switch. Upstream documentation is available at docs.rs/automerge.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.