Automerge Repo

The repository is organized into several functional categories:

Core

• automerge-repo: The central library that handles event dispatching and shared logic, such as peer connection decisions and storage write triggers.

Front-end Adapters

• @automerge/automerge-repo-react-hooks: React hooks for integrating with Automerge Repo.
• @automerge/automerge-repo-svelte-store: A custom Svelte store.
• @automerge/automerge-repo-solid-primitives: Primitives for Solid JS.

Storage Adapters

• @automerge/automerge-repo-storage-indexeddb: Persists data within a browser using IndexedDB.
• @automerge/automerge-repo-storage-nodefs: Writes changes to the local filesystem (Node.js).

Network Adapters

• @automerge/automerge-repo-network-websocket: Enables client/server communication over WebSockets.
• @automerge/automerge-repo-network-messagechannel: Uses the Web MessageChannel API for communication between browser tabs.
• @automerge/automerge-repo-network-broadcastchannel: Provides tab-to-tab synchronization via the BroadcastChannel API.

Remote heads gossiping allows a peer to learn about the state of other peers that are not directly connected to it, by routing information through intermediate nodes.

The Mechanism

1. Subscription: A peer sends a remote-subscription-changed message to a recipient to specify which storage_ids it wants to watch on its behalf.
2. Detection: When a peer receives a sync message, it checks if the sender's storage_id is in any remote peer's subscription list and if the remote peer has permission to access the document (via sharePolicy).
3. Notification: If checks pass, the local peer sends a remote-heads-changed message to the subscribing remote peer.
4. Forwarding: When a peer receives a remote-heads-changed message, it verifies the timestamp is newer than the last known update for that storage_id/document combination before forwarding it.

Example Scenario

In a browser <-> sync server <-> browser setup, a browser tab subscribes to the sync server with the storage_id of another tab. The sync server then pushes remote-heads-changed messages to the first tab whenever the second tab's document heads change.

Before synchronization begins, peers must complete a handshake to exchange identities and agree on a protocol version. The protocol distinguishes between the initiating peer (the client) and the receiving peer (the server).

Handshake Steps

1. Join: The initiating peer sends a join message containing its senderId and supportedProtocolVersions (currently only "1").
2. Validation: The receiving peer validates the protocol version. If invalid, it sends an error message and terminates.
3. Peer Exchange: The receiving peer stores the initiator's ID, emits a peer-candidate event, and responds with a peer message containing the targetId (the initiator's ID) and the selectedProtocolVersion.
4. Completion: The initiating peer receives the peer message, stores the receiver's ID, emits a peer-candidate event, and begins the sync phase.

Peer IDs vs. Storage IDs

• Peer ID: An ephemeral ID tied to the lifetime of a specific process or browser tab.
• Storage ID: An optional, persistent ID (e.g., tied to IndexedDB) advertised in join and peer messages. Multiple Peer IDs can share the same Storage ID. This allows peers to know whether to save and reload sync states for a specific persistent storage.

To set up a React application with Automerge Repo, follow these steps:

1. Initialize Vite project:

yarn create vite
# Project name: hello-automerge-repo
# Select a framework: React
# Select a variant: TypeScript

2. Install dependencies:

cd hello-automerge-repo
yarn
yarn add @automerge/automerge @automerge/automerge-repo-react-hooks @automerge/automerge-repo-network-broadcastchannel @automerge/automerge-repo-storage-indexeddb vite-plugin-wasm

3. Configure Vite for WASM: Update vite.config.ts to include vite-plugin-wasm to handle Automerge's WASM requirements.

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"
import wasm from "vite-plugin-wasm"

export default defineConfig({
  plugins: [wasm(), react()],
  worker: {
    format: "es",
    plugins: () => [wasm()],
  },
})

4. Initialize Repo in src/main.tsx: Create the Repo instance and provide it via RepoContext.Provider from @automerge/automerge-repo-react-hooks.

5. Use documents in components: Use the useDocument hook to access and modify documents.

import { useDocument } from "@automerge/automerge-repo-react-hooks"
import { DocumentId } from "@automerge/automerge-repo"

interface Doc {
  count: number
}

export default function App(props: { documentId: DocumentId }) {
  const [doc, changeDoc] = useDocument<Doc>(props.documentId)

  return (
    <button
      onClick={() => {
        changeDoc((d: any) => {
          d.count = (d.count || 0) + 1
        })
      }}
    >
      count is: {doc?.count ?? 0}
    </button>
  )
}