automerge/automerge-repo

Contribute to automerge/automerge-repo development by creating an account on GitHub.

Summary

Automerge Repo is a TypeScript wrapper around the Automerge CRDT library that handles many documents at once and exposes pluggable networking and storage adapters. It ships as a monorepo with a core package, front-end bindings for React, Svelte, and Solid, plus storage and network adapters. The project is licensed under MIT.

What it is useful for

The library is useful when an application needs to keep multiple Automerge documents synchronized across peers or persisted locally without rebuilding that plumbing each time. Instead of wiring Automerge to a transport by hand, engineers can pick a network adapter (WebSocket for client/server, MessageChannel for tab-to-tab, BroadcastChannel for experimentation) and a storage adapter (IndexedDB in the browser, NodeFS on a server). Front-end adapters reduce the boilerplate of subscribing to document updates: React hooks, a Svelte custom store, and Solid primitives are all included in the monorepo.

A practical fit is a collaborative app where several users edit shared data offline or in real time. The MessageChannel adapter lets two tabs of the same browser app stay in sync without a server, while the WebSocket adapter lets a browser app sync with a Node peer. Storage adapters handle persistence so documents survive page reloads or process restarts.

How engineers can use it

After cloning the repository, the README documents two commands: pnpm install followed by pnpm build to build the workspace. From there, engineers typically start with the automerge-repo package, which the README describes as the core library handling event dispatch and shared functionality like peer selection and storage writes.

For a quick ramp-up, the monorepo includes three runnable examples: a React to-do list, a React counter, and a Svelte counter. There is also a minimal sync-server example that the other demos can connect to, which the README explicitly distinguishes from the separate automerge-repo-sync-server repository. Combining these, an engineer can stand up a React app, add the IndexedDB storage adapter and a WebSocket network adapter, then point two browser tabs at the same document to see changes flow between them.

One documented caveat: the BroadcastChannel network adapter is marked as "likely only useful for experimentation" because it is inefficient, and the in-repo sync-server example is intentionally simpler than the standalone automerge-repo-sync-server. Engineers looking for a production-grade relay should consult that separate repository rather than the bundled example. Full API details beyond what is described above are not laid out in the supplied README, so further setup guidance belongs in the package-level READMEs inside the monorepo.