# Automerge — CRDT Library for Collaborative Real-Time Apps

> A JSON-like data structure library that enables automatic conflict-free merging, powering local-first and real-time collaborative applications.

## Install

Save in your project root:

# Automerge — CRDT Library for Collaborative Real-Time Apps

## Quick Use
```javascript
import { next as Automerge } from "@automerge/automerge"
let doc = Automerge.init()
doc = Automerge.change(doc, d => {
  d.title = "Shopping List"
  d.items = ["Milk", "Eggs"]
})
```

## Introduction
Automerge is a conflict-free replicated data type (CRDT) library that lets multiple users or devices edit shared data independently, then merge changes automatically without conflicts. It is a foundational building block for local-first software.

## What Automerge Does
- Provides a JSON-like mutable document model backed by CRDTs
- Merges concurrent edits automatically without requiring a central server
- Tracks full change history with efficient binary encoding
- Supports text editing with character-level collaborative editing
- Works across JavaScript, Rust, Python, Swift, and C via a shared core

## Architecture Overview
Automerge's core is written in Rust and compiled to WebAssembly for JavaScript environments. Documents are represented as operation logs that record every change. The CRDT algorithms ensure that applying the same set of operations in any order produces identical state. A compact binary format keeps sync payloads small, and incremental saves avoid rewriting the full document on every change.

## Self-Hosting & Configuration
- Install with `npm install @automerge/automerge` or `cargo add automerge`
- Use `automerge-repo` for a higher-level networking and storage layer
- Pair with a sync server for relay-based collaboration or use peer-to-peer transports
- Configure storage adapters for IndexedDB, filesystem, or S3-compatible backends
- Integrate with React using `@automerge/automerge-repo-react-hooks`

## Key Features
- Deterministic conflict resolution without coordination
- Compact binary format for efficient storage and network transfer
- Full history tracking with point-in-time document reconstruction
- Cross-language support via a shared Rust core
- Offline-capable with seamless reconnection merging

## Comparison with Similar Tools
- **Yjs** — another CRDT library; Automerge provides richer history and a Rust core for multi-language use
- **Liveblocks** — managed real-time service; Automerge is self-hostable and works offline
- **ShareDB** — OT-based; Automerge uses CRDTs and does not require a central server
- **Gun** — distributed graph database; Automerge focuses on document-level merge semantics

## FAQ
**Q: Does Automerge require a server?**
A: No. Peers can sync directly. A relay server is optional for convenience.

**Q: How does Automerge handle text editing?**
A: It includes a dedicated text type that tracks per-character insertions and deletions for collaborative editing.

**Q: What happens when two users make conflicting changes?**
A: The CRDT algorithm resolves conflicts deterministically. Both changes are preserved; last-writer-wins applies to scalar values.

**Q: Is Automerge production-ready?**
A: Yes. Automerge 2.x is stable and used in production by multiple companies building local-first applications.

## Sources
- https://github.com/automerge/automerge
- https://automerge.org/

---
Source: https://tokrepo.com/en/workflows/asset-920b0f42
Author: AI Open Source