Skip to content
actor-ts
English

Examples overview

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

What ships

Section titled “What ships”
ExampleDemonstrates
Chat sampleCluster + DistributedPubSub + DistributedData + sharded persistent chat-room / direct-message entities + HTTP/WS endpoint.
Voice sampleWebSocket + Receptionist + DistributedPubSub + DistributedData ORSets — ephemeral by design (no sharding, no persistence).
Stand-alone snippetsBite-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

Section titled “Running an example”
Terminal window
# 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.

Picking an example

Section titled “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

Section titled “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

Section titled “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

Section titled “Where to next”