Skip to content
Get packs

Guide · Open source

How to use automerge-classic: install and merge JSON data

Updated · written with AI from the project's own documentation and checked against our catalogue data

automerge-classic is the original pure JavaScript version of Automerge, a library that stores JSON-like data so several people can change it at the same time, even offline, and then merges the changes automatically. This guide explains what it is, how to install it with npm or yarn, and when you should choose a different option. It is aimed at JavaScript developers who maintain existing code or want to study how CRDT merging works.

Automergeautomerge/automerge-classic · ★ 14.7k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Node.js or a browser environment, and npm or yarn available.
  2. 2Decide whether this version fits. If the project is new, use the newer implementation at github.com/automerge/automerge instead, as the README recommends.
  3. 3Install the package. Run npm install automerge or yarn add automerge in your project folder.
  4. 4Import the library. Use require('automerge') or import * as Automerge from 'automerge' depending on your module setup.
  5. 5Read the documentation. Follow the documentation linked from the README at automerge.org for usage details.
  6. 6Run the tests if you clone the repo. After cloning, run yarn install and then yarn test to run the suite in Node.

What automerge-classic is

Automerge is a JavaScript library for building collaborative applications. It stores JSON-like data in a structure that several people can modify concurrently. When the changes are combined later, the library merges them automatically using CRDT (conflict-free replicated data type) methods.

The README describes this repository as the original pure JavaScript implementation. It is a library of data structures, not an end-user app.

  • Stores JSON-like data
  • Supports concurrent changes, including offline edits
  • Merges changes automatically using CRDT methods
  • Intended as a building block for collaborative apps

Important: this repository is deprecated

The README contains a deprecation notice. Development has shifted to a newer implementation at https://github.com/automerge/automerge, which is written in Rust so it can be ported to other platforms more easily.

If you are starting a new project, the README points you to the newer implementation rather than this one.

Install automerge with npm or yarn

You need Node.js or a browser environment, plus npm or yarn. Install the package with one of the commands from the README, then import it in your code.

The README shows require for CommonJS and import for ES2015 or TypeScript.

  • Install with npm: npm install automerge
  • Install with yarn: yarn add automerge
npm install automerge // or yarn add automerge // CommonJS const Automerge = require('automerge') // ES2015 or TypeScript import * as Automerge from 'automerge'

Work on the repository itself

If you want to develop or study the code rather than use the package, clone the repository and use the commands listed in the README. These run the test suite in Node and in browsers, and build a bundled file for use in a script tag.

  • yarn install: installs dependencies
  • yarn test: runs the test suite in Node
  • yarn run browsertest: runs the test suite in web browsers
  • yarn build: creates dist/automerge.js for web browsers, including dependencies
yarn install yarn test yarn run browsertest yarn build

Choose between this version and alternatives

This version fits teams with an existing app built on it, and developers who want to read how CRDT merging is implemented in JavaScript. For new projects, the README directs you to the newer Rust-based Automerge.

The README also links to automerge-repo, a set of extensible examples in TypeScript. Yjs is another project often compared with Automerge.

  • Existing app on this version: keep it and maintain it
  • New project: use the newer Automerge implementation at github.com/automerge/automerge
  • Studying CRDT merging in JavaScript: this repository is suitable
  • Non-developer who wants a ready-made collaborative app: this library is not an end-user tool

What people use it for

  • Maintaining an existing collaborative JavaScript app built on the original Automerge library
  • Studying how CRDT merging of JSON-like data works in JavaScript
  • Building a prototype of concurrent editing that merges changes automatically
  • Building a bundled browser file with yarn build for loading through a script tag

Frequently asked questions

Is automerge-classic free to use?

Yes. The repository is released under the MIT license, which the README references via its LICENSE file. Check the LICENSE file in the repository for the full terms.

What do I need to install automerge-classic?

You need Node.js or a browser environment, plus npm or yarn. Install the package with npm install automerge or yarn add automerge.

Should I use automerge-classic for a new project?

The README says this repository is deprecated and development has moved to the newer Rust-based implementation at github.com/automerge/automerge. For new projects, start with that version.

What is a CRDT?

CRDT stands for conflict-free replicated data type. It is a method that lets several copies of data change independently and then merge automatically, as Automerge does with JSON-like data.

What are the alternatives to automerge-classic?

Yjs is a comparable project. The newer Rust-based Automerge is the successor recommended by the README. The README also links automerge-repo for TypeScript examples.

Is automerge-classic an app I can use directly?

No. It is a JavaScript library of data structures for building collaborative applications, so you need to write code that uses it.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

automerge-classic suits JavaScript developers who maintain an existing app on this original version or want to study CRDT merging in code. For new projects, the README recommends the newer Rust-based Automerge, and people wanting a ready-made collaborative app should look elsewhere.

Install options & downloads