Getting Started

Prerequisites

• Node.js 18+ (LTS recommended)
• pnpm 9+ (npm install -g pnpm)
• Git

Clone and install

git clone https://github.com/crs48/xNet.git
cd xNet
pnpm install

Build all packages

pnpm build

This builds all packages in dependency order (crypto → identity → storage → sync → data → react → etc.).

Run tests

# All tests (~4,700)
pnpm test

# Single package
pnpm --filter @xnetjs/sync test
pnpm --filter @xnetjs/data test

# Single file
pnpm --filter @xnetjs/sync vitest run src/clock.test.ts

# Watch mode
pnpm --filter @xnetjs/sync test:watch

Type checking

pnpm typecheck

Linting

pnpm lint

Run the Electron app

cd apps/electron && pnpm dev

This starts the Vite dev server, signaling server, and Electron app. The app is available at http://localhost:5177 for debugging.

Two-instance sync testing

cd apps/electron && pnpm dev:both

Launches two Electron windows connected to the same signaling server for testing real-time sync.

Project structure

packages/           # Core libraries (@xnetjs/*)
  crypto/           # BLAKE3, Ed25519, XChaCha20
  identity/         # DID:key, UCAN tokens
  storage/          # SQLite adapter
  sync/             # Lamport clocks, Change<T>, Yjs security
  data/             # Schema system, NodeStore, 15 property types
  react/            # useQuery, useMutate, useNode hooks
  plugins/          # 4-layer plugin system
  canvas/           # Infinite canvas with spatial indexing
  editor/           # TipTap rich text editor
  network/          # libp2p, WebRTC, peer security
  devtools/         # Debug panels (7 panels)
apps/
  electron/         # Desktop app (full features)
  web/              # PWA (pages only)
site/               # Documentation site (Astro + Starlight)

Workflow

1. Create a feature branch from main
2. Make changes in the relevant package(s)
3. Run tests for affected packages
4. Run pnpm typecheck and pnpm lint
5. Commit with a descriptive message following conventional commits
6. Open a pull request

If your change alters an architectural invariant — a protocol/wire contract, a package boundary, a security or trust rule, a storage or sync decision — add or supersede a record on the Architecture Decisions page in the same PR. Decisions are usually worked out first as an exploration in docs/explorations/; the ADR page is the distilled, immutable outcome.

Useful commands

Command	Description
pnpm install	Install all dependencies
pnpm build	Build all packages
pnpm test	Run all tests
pnpm typecheck	Type check all packages
pnpm lint	Lint all packages
pnpm --filter @xnetjs/sync test	Test a single package
pnpm --filter @xnetjs/sync test:watch	Watch mode for a package