Generalized DNA for building real-time shared-state hApps on holochain
Syn: Etymology. From Ancient Greek συμ- (sum-), variant of συν- (sun-), from σύν (sún, “with, in company with, together with”).
This project makes it easy to build collaborative apps in the distributed peer-to-peer context of Holochain. The shared state of a document is an Automerge CRDT: participants exchange changes directly over Holochain's peer-to-peer signals as they type, and periodically commit the state to the DHT, which provides durability and data integrity.
Because the CRDT does the merging, an app developer doesn't define a delta format or a function to apply one. You need only:
- A shape for your document's state, as a plain JavaScript object
- A renderer for it
- User interactions that mutate it inside
sessionStore.change(...)
Anything that should be live but not durable — cursor positions, selections, presence — goes in the session's separate ephemeral state, which syncs the same way but is never committed.
For more details read the design overview, read the article, and check out the example app, SynText, in the /demo directory.
Syn ships as four npm packages:
| Package | What it is |
|---|---|
@holochain-syn/client |
Thin zome client and wire types |
@holochain-syn/store |
The engine: documents, workspaces, sessions, commits |
@holochain-syn/core |
Lit elements and contexts for building syn UIs |
@holochain-syn/text-editor |
Collaborative text editing element |
npm install @holochain-syn/store @holochain-syn/client- Install nix with flakes enabled.
- Clone this repo:
git clone https://github.com/holochain-apps/syn && cd ./syn - Enter the dev shell:
nix develop. - Run
npm install
Build the DNA (assumes you are still in the dev shell for correct rust/cargo versions from the step above):
npm run build:happWe have provided a sample UI that implements collaborative text editing in a minimal editor. To run it:
npm run startThis builds the hApp, watches the libraries for changes, and launches three agents via hc-spin, each in its own window. Edit text in one window and you should see it appear in the others. Set AGENTS to change the number of agents:
AGENTS=2 npm run startnpm run testThis rebuilds the hApp and the libraries before running the tryorama tests. To re-run the tests against an already-built hApp:
npm run test-quickThe docs site is built with VitePress from the /docs directory and published to https://holochain-apps.github.io/syn.
npm run docs:dev
Copyright (C) 2020-2026, Holochain Foundation
This program is free software: you can redistribute it and/or modify it under the terms of the license provided in the LICENSE file (CAL-1.0). This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.