Join the Automerge Slack community

Automerge is a library of data structures for building collaborative applications in JavaScript.

A common approach to building JavaScript apps involves keeping the state of your application in model objects, such as a JSON document. For example, imagine you are developing a task-tracking app in which each task is represented by a card. In vanilla JavaScript you might write the following:

var doc = { cards: [] }

// User adds a card
doc.cards.push({ title: 'Reticulate splines', done: false })

// User marks a task as done
doc.cards[0].done = true

Automerge is used in a similar way, but the big difference is that it supports automatic syncing and merging:

You can have a copy of the application state locally on several devices (which may belong to the same user, or to different users). Each user can independently update the application state on their local device, even while offline, and save the state to local disk.

(Similar to git, which allows you to edit files and commit changes offline.)

When a network connection is available, Automerge figures out which changes need to be synced from one device to another, and brings them into the same state.

(Similar to git, which lets you push your own changes, and pull changes from other developers, when you are online.)

If the state was changed concurrently on different devices, Automerge automatically merges the changes together cleanly, so that everybody ends up in the same state, and no changes are lost.

(Different from git: **no merge conflicts to resolve!**)

Features and design principles

• Network-agnostic. Automerge is a pure data structure library that does not care about what kind of network you use: client/server, peer-to-peer, Bluetooth, USB drive in the mail, whatever, anything goes. Bindings to particular networking technologies are handled by separate libraries; see the section on Sending and receiving changes for examples.
• Immutable state. An Automerge object is an immutable snapshot of the application state at one point in time. Whenever you make a change, or merge in a change that came from the network, you get back a new state object reflecting that change. This fact makes Automerge compatible with the functional reactive programming style of React and Redux, for example.
• Automatic merging. Automerge is a Conflict-Free Replicated Data Type (CRDT), which allows concurrent changes on different devices to be merged automatically without requiring any central server. It is based on academic research on JSON CRDTs, but the details of the algorithm in Automerge are different from the JSON CRDT paper, and we are planning to publish more detail about it in the future.
• Fairly portable. We're not yet making an effort to support old platforms, but we have tested Automerge in Node.js, Chrome, Firefox, Safari, MS Edge, and Electron. For TypeScript users, Automerge comes with type definitions that allow you to use Automerge in a type-safe way.

Setup

If you're using npm, npm install automerge. If you're using yarn, yarn add automerge. Then you can import it with require('automerge') as in the example below (or import * as Automerge from 'automerge' if using ES2015 or TypeScript).

Otherwise, clone this repository, and then you can use the following commands: