Automerge Documentation

Automerge is a library providing fast implementations of several different CRDTs (Conflict-free Replicated Data Types), a compact compression format for these CRDTs, and a sync protocol for efficient network transmission. It is designed to support local-first applications by providing persistence mechanisms that abstract away distributed computing complexities.

Key components include:

• JavaScript: A stable package @automerge/automerge is available for web and Node.js environments.
• Rust: A core implementation that serves as a performant backend, often compiled to WebAssembly.
• C: A C library available in rust/automerge-c via FFI bindings.

To validate that different Automerge implementations (e.g., Rust, JavaScript, WASM) correctly interpret values across platforms, use the exemplar file. This file contains a document with a diverse set of data types including scalars, text objects, timestamps, and counters.

The exemplar document contains the following key-value pairs:

• title: String ("Hello 🇬🇧👨‍👨‍👧‍👦😀")
• notes: Automerge Text object ("🇬🇧👨‍👨‍👧‍👦😀")
• timestamp: ISO8601 timestamp (1941-04-26T08:17:00.123Z)
• location: URL ("https://automerge.org/")
• counter: Automerge counter (5)
• int: Integer (-4)
• uint: Unsigned integer (18446744073709551615)
• fp: Floating point (3.14159267)
• bytes: Hex data (0x856f4a83)
• bool: Boolean (true)

Because @automerge/automerge wraps a Rust core compiled to WebAssembly, browsers require a bundler to handle the WebAssembly modules. If using Webpack 5, you must enable the asyncWebAssembly experiment and adjust performance hints to prevent warnings regarding the WASM blob size.

module.exports = {
  ...
  experiments: { asyncWebAssembly: true },
  performance: {       // we dont want the wasm blob to generate warnings
     hints: false,
     maxEntrypointSize: 512000,
     maxAssetSize: 512000
  }
};

The ColumnData<C> API from version 0.2 has been removed. In v1, the API is available at the crate root. Use hexane::PrefixColumn<T> if you need prefix sums (counting, seeking by accumulated value, range sums) or hexane::Column<T> if you only need random access, iteration, and splicing without the overhead of a Fenwick tree (BIT).

Type Requirements: PrefixColumn<T> requires T: PrefixValue. Supported types include bool, u32, u64, i64, Option<u32>, Option<u64>, Option<i64>, NonZeroU32, etc.

To build and install the automerge-c library, ensure you have the required prerequisites installed, then use CMake to build and install it to a directory of your choice (e.g., /usr/local).

Prerequisites

• Cargo >= 1.71.0
• CMake >= 3.25
• CMocka >= 1.1.5
• Doxygen >= 1.9.1
• Ninja >= 1.10.1

Note: It is highly recommended to use the installation process because generated headers like automerge-c/config.h and automerge-c/utils/enum_string.h are only guaranteed to be found in their installed locations.

cmake -E make_directory automerge-c/build
cmake -S automerge-c -B automerge-c/build
cmake --build automerge-c/build
cmake --install automerge-c/build --prefix "/usr/local"

To build and test the Automerge JavaScript package from source, run the following commands in the javascript directory. Note that if you modify the Rust code in ../rust/*, you must re-run the build command.

npm install
npm run build
npm test

To run benchmarks for the Automerge 1.0 implementation using the Rust backend, use node automerge-rs.js.

Note: This requires the automerge repository to be checked out in a directory adjacent to this repository.

If you have Nix installed, you can use the provided Nix flake to set up a development environment with all dependencies pre-configured. Use nix develop to enter the shell, which provides various helper scripts for building different targets (Deno, Node.js, WASI, etc.).

$ nix develop