Examples

Runnable examples live in examples/. Clone the repo and run pnpm install first.

chat — roles in one room

A human (user) and an AI participant (agent) join the same room with different surfaces. Shows a shared join + message event, role-specific verbs (say vs announce), and conn.role.

pnpm --filter @super-line/example-chat start

Demonstrates: roles, shared requests, events & rooms.

react-chat — browser app

A live React chat (Vite + a WS server). Open two browser tabs to chat in real time; shows the React hooks, a presence topic, and a room broadcast.

pnpm --filter @super-line/example-react-chat dev   # http://localhost:5173

store — a permissioned document store

A scripted, single-process demo of the Store primitive on the in-memory LWW backend. The server creates a permissioned note and assigns per-user access; two users open it and one's write reaches the other live; a read-only user is denied a write (FORBIDDEN); a third user can't open the doc until the server grants access at runtime; and the server co-writes the document.

pnpm --filter @super-line/example-store start

Demonstrates: stores, roles, errors.

store-sync-json — a collaborative JSON editor (CRDT)

A React app over the CRDT Store (@super-line/store-sync — Yjs via super-store): a @visual-json editor bound to one shared Resource via useResource. Open two tabs (or add ?name=bob), edit any field, and watch edits merge live — concurrent edits to different fields both survive, unlike last-writer-wins. Server nudge triggers a server co-write.

pnpm --filter @super-line/example-store-sync-json dev   # http://localhost:5273

Demonstrates: synced state (CRDT), stores, React hooks.

synced-canvas — roll-your-own CRDT (no Store seam)

Two browser apps demonstrating synced JSON state over super-line, backed by a CRDT — a collaborative canvas where multiple tabs and the server co-edit one document, persisted server-side. super-line stays CRDT-agnostic: it relays opaque base64 update bytes per room and never parses the doc. A debug side panel mirrors the live state and logs each patch tagged by origin (local / peer / server), so you can watch the server's edits land. Built once with Yjs and once with Automerge — open either in two windows (run one at a time).

pnpm --filter @super-line/example-synced-canvas-yjs dev         # http://localhost:5173
pnpm --filter @super-line/example-synced-canvas-automerge dev   # http://localhost:5173

Demonstrates: synced state (CRDT), events & rooms, requests.

hono — one server for HTTP + WebSockets

super-line attached to a Hono app (@hono/node-server) on one process, one port: Hono serves the built frontend and REST routes while super-line owns the WebSocket bus, both on the same Node http.Server (the { server } option — no library changes). Three live cards — a server-uptime topic, shared todos (req/res + a topic), and shared cursors whose identity is assigned server-side into ctx — plus a POST /api/todos REST→WS bridge: curl a todo in and watch it appear in every open tab. The bridge route and the WS upgrade share one auth rule. Open a few tabs and move your mouse.

pnpm --filter @super-line/example-hono build
pnpm --filter @super-line/example-hono start   # http://localhost:3000

Demonstrates: topics, requests, middleware & lifecycle, composing with an HTTP framework.

auth — roles as an authorization boundary

Token auth with an admin and a user role. whoami is shared; secret is admin-only. A user calling secret gets NOT_FOUND; a bad token is rejected at the upgrade.

pnpm --filter @super-line/example-auth start

Demonstrates: auth, NOT_FOUND enforcement, errors.

presence — introspection, targeted send & server→client requests

Boots two nodes sharing one in-memory bus (no Docker needed) and shows the server-side toolkit across nodes: cluster.count/topology/isOnline, a toUser(...).emit from the node that doesn't hold the socket, and a toConn(id).request(...) where one node asks a client a question and awaits the typed reply (the client answers via client.implement).

pnpm --filter @super-line/example-presence start

Demonstrates: introspection & presence.

event-bus — single-process cluster event bus

One process shows the cluster event bus on a shared topic: a server.publish fans out to several in-process server.subscribe listeners (showing local echo — your own publish fires in-process, no round-trip) plus one client subscriber over WS. No Redis needed.

pnpm --filter @super-line/example-event-bus start

Demonstrates: the cluster event bus.

bus-cluster — multi-node server.subscribe showcase

A cluster via Docker Compose: Redis + Caddy + 3 server nodes + watcher clients. Every node bumps a counter and server.subscribes to every node's bumps, converging a shared tally — own bumps land in-process via local echo, peers' arrive over Redis. node-1 publishes a client-facing total snapshot. Needs Docker.

cd examples/bus-cluster && docker compose up

Demonstrates: the cluster event bus, scaling & adapters.

scaling — a real multi-node cluster

A genuine cluster via Docker Compose: Redis + a Caddy load balancer + 3 server nodes + 6 client containers. Caddy round-robins each client onto a node; you watch room broadcasts, a topic, and stats gossip — migrated to a shared stats topic over the cluster event bus — fan out across separate processes. Needs Docker.

cd examples/scaling && docker compose up

See examples/scaling/README.md for what to watch, how to connect your own client to the load balancer, and --scale.

Demonstrates: scaling & adapters, the cluster event bus.

react-chat-cluster — the browser app, across two servers

react-chat behind a real cluster via Docker Compose: Redis + 2 server nodes + a Caddy that serves the built SPA and round-robins /ws across the nodes. Open http://localhost:8080 in several tabs — each lands on a different node (shown in the header), yet messages cross servers via a room.broadcast over the Redis adapter, and the online count is cluster-wide via cluster.room(...). Needs Docker.

cd examples/react-chat-cluster && docker compose up

See examples/react-chat-cluster/README.md for the topology and what each tab shows.

Demonstrates: React hooks, scaling & adapters, introspection & presence.

react-chat-cluster-libp2p — the same cluster, no broker

The same browser app and Control Center as react-chat-cluster above, but with no Redis — the two nodes peer directly over libp2p gossipsub via @super-line/adapter-libp2p. Same React SPA, same cross-node messages and cluster-wide (gossip-replicated) presence; the only structural change is the adapter line. Ports are offset (web :8090, Control Center :8091) so it runs alongside the Redis variant. Needs Docker.

cd examples/react-chat-cluster-libp2p && docker compose up --build

Demonstrates: React hooks, scaling & adapters, introspection & presence.