In Synch

The fastest path has no build tools at all. Make a folder, and drop one file in it: the pre-built bundle, which has Automerge and its WASM inlined, so it is entirely self-contained.

mkdir in-synch-demo && cd in-synch-demo

curl -O https://raw.githubusercontent.com/l3gacyb3ta/automergekiss/main/dist/automerge-kiss.bundle.js

Want to see the finished idea first? Clone the repo and double-click demo-standalone.html — it is a working collaborative task board with live presence, inlined into one file, no install and no server.

Browsers refuse to load module scripts from file://, so opening your own index.html by double-clicking will fail. Run any static server from the folder instead.

npx serve .            # node
python3 -m http.server # python

One function, one await. If there is a Space code in the page URL you join that Space; otherwise a new one is created from your starter data.

<script type="module">
  import { openSpace } from "./automerge-kiss.bundle.js";

  const space = await openSpace({ starter: { items: [] } });

  console.log(space.data);      // { items: [] }
  console.log(space.shareUrl);  // send this to a friend
</script>

space.data is the current value — read it whenever you like. space.shareUrl is a link straight to this Space; space.code is the bare code (it looks like automerge:4kP...) if you would rather share that.

onChange fires whenever the data changes — from you or from anyone else — and it also fires once immediately. That means one function can be your entire render path: you never write separate code for "draw the first time" and "draw again."

const list = document.getElementById("items");

space.onChange((data) => {
  list.replaceChildren(...data.items.map((item) => {
    const li = document.createElement("li");
    li.textContent = item.text;
    return li;
  }));
});

It returns an unsubscribe function, so const stop = space.onChange(...) then stop() if you ever need to detach.

Never assign to space.data directly — that change would be invisible to everyone else. Pass a function to update() and mutate the draft however you like. Saving and syncing happen for you.

space.update((data) => {
  data.items.push({ text: "buy snacks", done: false });
  data.items[0].done = true;
});

Push, splice, reassign a field, nest objects — ordinary JavaScript. Your onChange handler runs straight afterwards, so the screen updates without you calling render yourself.

This is the moment the project becomes real. Open your page, copy the shareUrl it printed, paste it into a second tab. Type in one. Watch the other. Then close one tab, add three things, and reopen it.

Two different things are easy to confuse. A Space's contents are always saved in the browser, with no setup. But which Space to reopen is your choice: by default the code rides in the URL, so revisiting the same link rejoins — and someone who opens the bare page gets a fresh empty Space. Pass remember to fix that.

const space = await openSpace({
  starter: { items: [] },
  remember: "in-synch-demo",   // or `true` for a default slot
});

Then a "start over" button forgets the slot and drops the code from the URL:

import { forgetSpace } from "./automerge-kiss.bundle.js";

forgetSpace("in-synch-demo");
location.href = location.pathname;

Use a different name per app so their memories stay separate. The other options worth knowing: code to join a specific Space, localOnly: true for this-device-only, useUrlHash: false to keep the code out of the URL, and joinTimeout (8000ms by default) for how long to wait before showing a friendly error.

Presence is the cheapest way to make a project feel alive: names, colours, cursors, "Alex is typing." It is not saved — it only pings the people currently connected, which is exactly what you want for something that stops being true the moment someone closes the tab.

space.setPresence({ name: "Alex", color: "#ff2d00" });

space.onPeers((peers) => {
  // peers = [{ id, presence: { name, color } }, ...]
  document.getElementById("who").textContent =
    peers.map((p) => p.presence.name).join(", ");
});

Call setPresence again any time the value changes — on mousemove for live cursors, on keypress for a typing indicator. And call space.leave() when you are finished, to drop the connection and clear its timers.

A complete, real-time, offline-capable, multiplayer shared list with presence. Save it as index.html next to the bundle, serve the folder, open the share link in a second tab. That is the ship requirement met, in 60 lines.

<!DOCTYPE html>
<meta charset="utf-8">
<title>shared list</title>

<p id="who"></p>
<form id="add">
  <input id="text" placeholder="add an item" autocomplete="off">
  <button>add</button>
</form>
<ul id="items"></ul>
<p>share: <a id="share"></a></p>

<script type="module">
  import { openSpace } from "./automerge-kiss.bundle.js";

  const space = await openSpace({
    starter: { items: [] },
    remember: "shared-list",
  });

  const share = document.getElementById("share");
  share.href = space.shareUrl;
  share.textContent = space.shareUrl;

  // one render path — used for the first paint and every update after
  space.onChange((data) => {
    document.getElementById("items").replaceChildren(
      ...data.items.map((item, i) => {
        const li = document.createElement("li");
        const box = document.createElement("input");
        box.type = "checkbox";
        box.checked = item.done;
        box.onchange = () => space.update((d) => {
          d.items[i].done = box.checked;
        });
        li.append(box, document.createTextNode(" " + item.text));
        return li;
      })
    );
  });

  document.getElementById("add").onsubmit = (event) => {
    event.preventDefault();
    const input = document.getElementById("text");
    const text = input.value.trim();
    if (!text) return;
    space.update((d) => { d.items.push({ text, done: false }); });
    input.value = "";
  };

  // presence: not saved, just who is here right now
  const me = { name: "guest-" + Math.floor(Math.random() * 999) };
  space.setPresence(me);
  space.onPeers((peers) => {
    const names = [me, ...peers.map((p) => p.presence)]
      .map((p) => (p && p.name) || "anon");
    document.getElementById("who").textContent =
      names.length + " here: " + names.join(", ");
  });
</script>

Now break it on purpose, because that is the interesting part. Turn off your wifi, add three items, turn it back on. Nothing is lost, and neither is anything the other tab did while you were gone.

Make it yours — the list is scaffolding, not the project. Then push the repo, write the README, record the GIF/pictures of two windows moving together, and submit. If you would rather use a bundler than a copied file, the library is a single TypeScript file: npm create vite@latest, npm install @automerge/vanillajs, drop src/automerge-kiss.ts in, import from it.

And when the simple API runs out: it re-exports Repo, the adapters, and isValidAutomergeUrl, so you can drop into full Automerge — lists, rich text, counters — without rewriting what already works.