Installation

actor-ts ships as a single npm package. The core has two small runtime dependencies (ts-pattern for exhaustive matching, fastify for the default HTTP backend); everything else — Kafka, Redis, S3, Cassandra, gRPC — is opt-in via peer dependencies you only install when you use the corresponding extension.

Runtime requirements

Runtime	Minimum version	Notes
Bun	1.1	Recommended for development — fastest startup, native SQLite via bun:sqlite, native WebSocket server.
Node.js	20.0	Core works on 20+. Node 22+ enables native WebSocket without the ws peer dep; Node 22.15+ enables native zstd compression without fzstd. SQLite via better-sqlite3 (peer-dep).
Deno	2.0	Use the npm: specifier — import { ... } from 'npm:actor-ts'. Run with --allow-net / --allow-read as needed.

The framework auto-detects which runtime it’s executing under and picks the right backends transparently — see Runtime overview for the detection algorithm and per-runtime caveats.

Core install

Bun

bun add actor-ts

Node

npm install actor-ts
# or
pnpm add actor-ts
# or
yarn add actor-ts

Deno

No install step needed. Import directly:

import { Actor, ActorSystem, Props } from 'npm:actor-ts';

Deno fetches the package on first run and caches it. Add an import_map.json if you want to alias actor-ts to a shorter specifier across multiple files.

Optional peer dependencies

Each integration is gated by a peer dep — install only the ones you’ll actually use. Nothing is auto-loaded; the relevant extension throws a clear “missing peer dep” error if you try to use it without the package installed.

Why peer deps?

Keeping the core install small (just two runtime deps) means a chat sample pulls a handful of MB. A user who needs Kafka adds kafkajs themselves; a user who needs S3 adds @aws-sdk/client-s3. No bundle bloat for features you don’t use.

HTTP backends

Package	Enables
fastify (default)	Fastify-based HttpServerBackend — best Bun + Node performance.
express	Express-based backend, for projects already on Express.
hono + @hono/node-server (Node only)	Hono with runtime-aware serve primitives — Bun.serve, @hono/node-server, Deno.serve per runtime.

bun add fastify                   # or
bun add express                   # or
bun add hono @hono/node-server    # @hono/node-server is Node-only

Persistence

Package	Enables
better-sqlite3 (Node only)	SQLite journal + snapshot store on Node. Bun uses bun:sqlite (built-in, no peer dep).
cassandra-driver	Cassandra / ScyllaDB journal + tag-index.
@aws-sdk/client-s3	S3-compatible object-storage backend (works with MinIO, R2, Backblaze B2).
fzstd (optional)	zstd compression for object-storage blobs when no native runtime support is available.

Cache

Package	Enables
ioredis	Redis-backed Cache.
memjs	Memcached-backed Cache.

Message brokers

Package	Enables
kafkajs	KafkaActor — producer + consumer.
mqtt	MqttActor.
amqplib	AmqpActor — RabbitMQ + AMQP-compatible brokers.
nats	NatsActor — including JetStream subjects.
@grpc/grpc-js + @grpc/proto-loader	GrpcClientActor + GrpcServerActor.
ws	WebSocketActor (outbound client connections).

Discovery + Coordination

Package	Enables
@kubernetes/client-node	KubernetesApiSeedProvider + KubernetesLease.

TypeScript configuration

Add (or verify) the following compiler options in your tsconfig.json:

{
  "compilerOptions": {
    "target":  "ES2022",
    "module":  "ESNext",
    "moduleResolution": "Bundler",
    "strict":  true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true
  }
}

The framework relies on noImplicitOverride to catch lifecycle-method- typo bugs (writing onRecieve instead of onReceive). Drop it if you prefer, but you’ll lose that safety net.

Verify the install

Save this as verify.ts:

import { Actor, ActorSystem, Props } from 'actor-ts';

class Ping extends Actor<'ping'> {
  override onReceive(msg: 'ping'): void {
    console.log('pong');
  }
}

const system = ActorSystem.create('verify');
const ref = system.actorOf(Props.create(() => new Ping()));
ref.tell('ping');
await new Promise((r) => setTimeout(r, 20));
await system.terminate();
console.log('install OK');

Bun

bun run verify.ts

Node

npx tsx verify.ts

Deno

deno run verify.ts

Expected output:

pong
install OK

If you see both lines, the install is working. If pong is missing, your runtime is below the minimum version (see the table at the top of this page) — bump it and re-run.

Troubleshooting

`Cannot find module 'actor-ts'`

• Bun / Node: check node_modules/ exists. Re-run bun add actor-ts or npm install if it doesn’t.
• Deno: use the npm: specifier — import { ... } from 'npm:actor-ts'. Bare specifiers don’t resolve in Deno without an import map.

Older Node versions

Actor-ts requires Node ≥ 20.0. On Node 20.x the core works, but some optional features fall back to peer-dep implementations: WebSocket needs the ws package (Node 22+ has it natively), and zstd compression needs fzstd (Node 22.15+ has it natively). Node ≤ 19 is not supported.

Missing peer dependency at runtime

Trying to use an integration without its peer dep produces a clear error like:

Missing peer dependency 'kafkajs'. Run 'bun add kafkajs' (or equivalent) to enable the Kafka broker.

Install the named package and re-run. See the peer-dep tables above for the full list per integration.

Where to next

• Quickstart — five minutes to a running actor.
• Why actors? — the philosophy behind the framework.
• Learning path — suggested reading order based on what you want to build.