Examples overview

The framework ships runnable examples under examples/ in the repo. Each is a fully-working app you can clone + run.

What ships

Example	Demonstrates
Chat sample	Cluster + DistributedPubSub + DistributedData + sharded persistent chat-room / direct-message entities + HTTP/WS endpoint.
Voice sample	WebSocket + Receptionist + DistributedPubSub + DistributedData ORSets — ephemeral by design (no sharding, no persistence).
Stand-alone snippets	Bite-sized examples per concept — Counter, Saga, Health, etc.

For first contact with actor-ts, start with the Quickstart — it’s a 5-minute hello-actor. Then the chat or voice sample for a working multi-feature app.

Running an example

# Clone the repo:
git clone https://github.com/pathosDev/actor-ts.git
cd actor-ts

# Install dependencies once, at the repo root:
bun install

# Run the chat sample — open three terminals, same command in each:
bun examples/chat/backend/main.ts

Each example has its own README with setup steps.

Verified in CI

The examples are a gate, not decoration. bun run test:examples spawns every runnable snippet as its own process and asserts on its output, and the examples workflow runs it on every push that touches src/ or examples/ — so a framework change that breaks an example is a red check rather than something a reader discovers.

bun run test:examples              # all of them, ~90 s
bun run test:examples persistence  # just the ones matching a substring

The classification lives in tests/examples/examples.manifest.json. Every standalone example is in it exactly once, as either:

• runnable — with a substring of its output that has to appear. Exit code 0 is not enough on its own: a snippet whose external dependency is missing can fail its actual work and still exit 0.
• skipped — with the reason it cannot run unattended. Those are the ones needing a Docker broker (Kafka, NATS, MQTT), cloud or Kubernetes credentials, or an optional peer dependency the repository does not declare.

The runner fails when that list and the tree disagree in either direction, so adding an example means deciding which of the two it is. The two application samples take part: the chat and voice smoke tests both run in the gate, each bringing up its own backend.

Picking an example

If you want to see…

• Cluster + entities → chat sample.
• PersistentActor patterns → chat sample.
• Distributed pub/sub → chat or voice sample.
• Receptionist + ephemeral (CRDT) rooms → voice sample.
• Broker integration (Kafka) → the examples/io/kafka-exactly-once.ts snippet.
• HTTP + WebSocket → both samples.
• A specific concept in isolation → stand-alone snippets.

Reading the examples

The examples follow a few conventions:

• backend/actors/ — actor classes.
• backend/main.ts — entry point; wiring only (cluster join, extensions, sharding, HTTP singleton).
• backend/routes.ts — HTTP directive-DSL routes.
• shared/ — code shared with the frontends: protocol.ts (WS message types), rooms.ts, users.ts.

Reading an example takes ~30 minutes for the full architecture; faster if you’re already familiar with the framework.

Contributing examples

If you build something with actor-ts and think it’d help others — a saga workflow, a Kafka-driven analytics pipeline, a multi-tenant SaaS skeleton — PRs welcome.

Examples that get included:

• Self-contained — work without external services beyond Docker / Compose.
• Documented — README with what it does + how it works.
• Realistic — solve a real problem (not just “show this feature”).

Where to next

• Chat sample — cluster + pubsub.
• Voice sample — ephemeral pub/sub + presence.
• Stand-alone snippets — per-concept code.
• Quickstart — the 5-minute introduction.