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.3	Recommended for development — fastest startup, native SQLite via bun:sqlite, native WebSocket server.
Node.js	24.0	Ships everything natively: WebSocket client, zstd compression, WebCrypto, fetch. SQLite via the built-in node:sqlite, or better-sqlite3 if you install it.
Deno	2.2	Use the npm: specifier — import { ... } from 'npm:actor-ts'. Run with --allow-net / --allow-read as needed. SQLite needs Deno 2.2 for node:sqlite; everything else works on 2.0.

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 } 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
(none needed)	SQLite journal + snapshot store. Every runtime has a built-in driver: bun:sqlite on Bun, node:sqlite on Node >= 22.13 and Deno >= 2.2.
better-sqlite3 (Node only, optional)	Preferred over node:sqlite on Node when installed — slightly faster, and what existing deployments already run.
@libsql/client	libSQL / Turso journal + snapshot + durable-state store — SQLite over HTTP, so it needs no native binding on any runtime.
pg	PostgreSQL journal + snapshot + durable-state store.
mariadb	MariaDB / MySQL journal + snapshot + durable-state store.
mssql	Microsoft SQL Server journal + snapshot + durable-state store. Pure-JavaScript driver (tedious), no native build step.
mongodb (pin ^6)	MongoDB journal + snapshot + durable-state store + indexed tag query. Version 7 cannot be imported on Bun — see the MongoDB page.
cassandra-driver	Cassandra / ScyllaDB journal + tag-index.
@aws-sdk/client-s3	S3-compatible object-storage backend (works with MinIO, R2, Backblaze B2).
@aws-sdk/client-dynamodb	DynamoDB journal + snapshot + durable-state store.
(none needed)	Cloudflare D1 journal + snapshot + durable-state store — spoken over D1’s REST API with the built-in HTTP client.
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	Server-side WebSocket upgrades on the Express backend. (WebsocketClientActor uses the runtime’s native WebSocket — no peer dep.)
@fastify/websocket	websocket() routes on the Fastify backend.
@hono/node-ws	websocket() routes on the Hono backend (Node only — Bun/Deno ship the helpers inside hono).

Discovery + Coordination

KubernetesApiSeedProvider and KubernetesLease need no peer dependency — both reach the Kubernetes API over built-in node:https + node:fs, using the in-pod ServiceAccount token by default.

Package	Enables
@kubernetes/client-node (optional)	Not required. Optional swap-in for KubernetesApiSeedProvider’s fetchEndpoints hook, if you’d rather use the official client than the built-in HTTPS call.

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 } from 'actor-ts';

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

const system = ActorSystem.create('verify');
const ref = system.spawnAnonymous(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 ≥ 24.0 (the oldest active LTS line; Node 20 reached end-of-life in April 2026). Server-side websocket() routes need ws on the Express backend, @fastify/websocket on the Fastify backend, or @hono/node-ws on the Hono backend when running on Node. Node ≤ 23 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.