Quick start from source

In about five minutes, you will build the six Peerborne library workspaces and run the real browser example in Chromium. The smoke test initializes Helia and libp2p, opens an Automerge document, and fails on browser runtime errors.

Prerequisites

Node.js 22.19.0, matching the version pinned in .tool-versions
Corepack, included with Node.js 22.19.0
Git
A Chromium-compatible host for the browser smoke test

Docker is not required for this quick start.

Clone the repository and enable Yarn.
Terminal window
```
git clone https://github.com/Peerborne/peerborne.git peerborne
cd peerborne
corepack enable
```
Confirm that the active Node.js version satisfies the repository requirement:
Terminal window
```
node --version
```
Install the locked dependency graph.
Terminal window
```
yarn install --immutable
```
--immutable prevents Yarn from silently changing the lockfile, matching the project’s CI environment.
Build the library workspaces.
Terminal window
```
yarn build
```
This typechecks and emits the core, Yjs, Automerge, React, Redux, and indexing packages in dependency order.
Install Chromium and run the browser smoke test.
Terminal window
```
yarn exec playwright install chromium
yarn test:e2e:browser-test
```
On Linux hosts that need browser system libraries, use:
Terminal window
```
yarn exec playwright install chromium --with-deps
```
A successful run ends with one passing Playwright test. It proves that the Vite browser application starts without runtime errors and that a real Peerborne document opens using the configured Automerge, crypto, ACL, and keychain providers.
Run the example interactively.
Terminal window
```
yarn workspace @peerborne/browser-test start
```
Open the URL printed by Vite. In the Open Document field, enter a path such as /quick-start/demo, then open it. The page displays the document and the local libp2p node addresses.

What this verifies

This quick start exercises a real Peerborne document in one browser process:

workspace package compilation and TypeScript declarations;
browser initialization of Helia and libp2p;
document creation and local content-addressed storage;
Automerge provider, serializers, signing, encryption, ACL, and keychain setup;
browser runtime behavior checked by Playwright.

This one-browser quick start does not demonstrate persistence across browser restarts or collaboration by itself. The separate Docker-backed acceptance job below covers a narrow online, founder-plus-one invitation path. Sharing an identity signing key between tabs is not sufficient to transfer a document encryption key.

Additional verified paths

The repository also contains heavier acceptance suites:

yarn test:e2e builds and smoke-tests all four browser examples.
yarn test:integration exercises the integration topology after its Docker Compose services are running.
yarn test:nat exercises NAT traversal after its Docker Compose topology is running.
yarn test:peerborne-nat uses separate signing identities in two NAT-isolated Chromium processes, accepts a signed editor invitation through Circuit Relay without exposing a plaintext document key or injecting one through the test bridge, and verifies fresh Automerge mutations in both directions.

The Docker-backed suites are started and cleaned up by their corresponding CI jobs in the repository workflow. Use that workflow as the canonical command sequence rather than running the test commands without their services.

Current package boundaries

Release validation packs all six libraries and installs the exact tarballs in a clean Node 22.19.0 consumer. It checks all supported library ESM import paths, strict TypeScript typechecking with NodeNext module resolution, and a Vite build. The packages remain unpublished; this does not prove registry installation, browser runtime behavior, or packaged daemon execution. Until publication:

use Yarn workspace package names such as @peerborne/core;
do not copy future npm install commands from issues or old documentation;
treat private signing keys, KEM keys, and document keys as distinct persisted data when designing an application;
consult the feature and verification audit for the evidence behind capability claims.

Useful source examples

examples/browser-test shows the core Automerge and Redux stack.
examples/wiki-swarm is a larger collaborative editor example.
examples/password-manager demonstrates the React and Yjs integrations, but should not yet be treated as proof of distinct-identity invitation.
examples/peerborne-note is the bounded initial-release Automerge invitation demo. Read its identity, relay, and recovery boundaries before trying it with another browser.
Invite a collaborator documents the narrow online invitation API and its trust/recovery limits.

For a change to these packages, the minimum completion commands are:

yarn build
yarn test
yarn workspace @peerborne/site build

Run the focused browser or Docker-backed suite as well when changing the behavior it covers.

Next steps

Why Peerborne? — understand the value proposition and when to use it
Architecture — see how the pieces fit together with diagrams
Concepts — dive into local-first design, CRDTs, networking, storage, and security
Peerborne Note — try the initial-release demo and review its boundaries
Cookbook — try runnable recipes for wikis, password managers, React, Redux, and more
API reference — explore the generated API documentation for all six packages
FAQ — answers to common questions
Contributing — set up a development environment and make your first contribution