Installation

actor-ts wird als einzelnes npm-Paket ausgeliefert. Der Kern hat zwei kleine Runtime-Dependencies (ts-pattern für erschöpfendes Matching, fastify für das Default-HTTP-Backend); alles andere — Kafka, Redis, S3, Cassandra, gRPC — ist opt-in über Peer-Dependencies, die Du nur installierst, wenn Du die entsprechende Extension verwendest.

Runtime-Anforderungen

Runtime	Mindestversion	Hinweise
Bun	1.3	Empfohlen für Entwicklung — schnellster Startup, natives SQLite via bun:sqlite, nativer WebSocket-Server.
Node.js	24.0	Bringt alles nativ mit: WebSocket-Client, zstd-Kompression, WebCrypto, fetch. SQLite über das eingebaute node:sqlite oder better-sqlite3, wenn du es installierst.
Deno	2.2	Verwende den npm:-Specifier — import { ... } from 'npm:actor-ts'. Mit --allow-net / --allow-read ausführen, wenn nötig. SQLite braucht Deno 2.2 für node:sqlite; alles andere läuft ab 2.0.

Das Framework erkennt automatisch, unter welcher Runtime es ausgeführt wird, und wählt die richtigen Backends transparent — siehe Runtime Overview für den Erkennungsalgorithmus und die per-Runtime-Vorbehalte.

Core-Installation

Bun

bun add actor-ts

Node

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

Deno

Kein Installationsschritt nötig. Direkt importieren:

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

Deno holt das Paket beim ersten Lauf und cached es. Füge eine import_map.json hinzu, wenn Du actor-ts über mehrere Dateien hinweg auf einen kürzeren Specifier aliasen willst.

Optionale Peer-Dependencies

Jede Integration wird durch eine Peer-Dep gesperrt — installiere nur die, die Du tatsächlich verwendest. Nichts wird automatisch geladen; die relevante Extension wirft einen klaren “missing peer dep”-Fehler, wenn Du versuchst, sie ohne das installierte Paket zu verwenden.

Warum Peer-Deps?

Die Core-Installation klein zu halten (nur zwei Runtime-Deps) bedeutet, dass ein Chat-Beispiel eine Handvoll MB zieht. Ein Nutzer, der Kafka braucht, fügt selbst kafkajs hinzu; ein Nutzer, der S3 braucht, fügt @aws-sdk/client-s3 hinzu. Kein Bundle-Bloat für Features, die Du nicht verwendest.

HTTP-Backends

Paket	Aktiviert
fastify (Default)	Fastify-basiertes HttpServerBackend — beste Bun + Node Performance.
express	Express-basiertes Backend, für Projekte, die bereits auf Express laufen.
hono + @hono/node-server (nur Node)	Hono mit runtime-aware Serve-Primitives — Bun.serve, @hono/node-server, Deno.serve pro Runtime.

bun add fastify                   # oder
bun add express                   # oder
bun add hono @hono/node-server    # @hono/node-server ist Node-only

Persistenz

Paket	Aktiviert
(nichts nötig)	SQLite-Journal + Snapshot Store. Jede Runtime hat einen eingebauten Treiber: bun:sqlite auf Bun, node:sqlite auf Node >= 22.13 und Deno >= 2.2.
better-sqlite3 (nur Node, optional)	Wird auf Node gegenüber node:sqlite bevorzugt, wenn installiert — etwas schneller, und das, was bestehende Deployments schon einsetzen.
@libsql/client	libSQL- / Turso-Journal + Snapshot + Durable-State Store — SQLite über HTTP, braucht daher auf keiner Runtime ein natives Binding.
pg	PostgreSQL Journal + Snapshot + Durable-State Store.
mariadb	MariaDB / MySQL Journal + Snapshot + Durable-State Store.
mssql	Microsoft SQL Server Journal + Snapshot + Durable-State Store. Reiner JavaScript-Treiber (tedious), kein nativer Build-Schritt.
mongodb (auf ^6 pinnen)	MongoDB Journal + Snapshot + Durable-State Store + indizierte Tag-Query. Version 7 lässt sich auf Bun nicht importieren — siehe die MongoDB-Seite.
cassandra-driver	Cassandra / ScyllaDB Journal + Tag-Index.
@aws-sdk/client-s3	S3-kompatibles Object-Storage-Backend (funktioniert mit MinIO, R2, Backblaze B2).
@aws-sdk/client-dynamodb	DynamoDB Journal + Snapshot + Durable-State Store.
(nichts nötig)	Cloudflare D1 Journal + Snapshot + Durable-State Store — über D1s REST-API mit dem eingebauten HTTP-Client.
fzstd (optional)	zstd-Kompression für Object-Storage-Blobs, wenn kein nativer Runtime-Support verfügbar ist.

Cache

Paket	Aktiviert
ioredis	Redis-backed Cache.
memjs	Memcached-backed Cache.

Message Broker

Paket	Aktiviert
kafkajs	KafkaActor — Producer + Consumer.
mqtt	MqttActor.
amqplib	AmqpActor — RabbitMQ + AMQP-kompatible Broker.
nats	NatsActor — inklusive JetStream-Subjects.
@grpc/grpc-js + @grpc/proto-loader	GrpcClientActor + GrpcServerActor.
ws	Serverseitige WebSocket-Upgrades auf dem Express-Backend. (Der WebsocketClientActor nutzt das native WebSocket der Runtime — keine Peer-Dep.)
@fastify/websocket	websocket()-Routen auf dem Fastify-Backend.
@hono/node-ws	websocket()-Routen auf dem Hono-Backend (nur Node — Bun/Deno liefern die Helper in hono mit).

Discovery + Koordination

KubernetesApiSeedProvider und KubernetesLease benötigen keine Peer-Dependency — beide erreichen die Kubernetes-API über eingebautes node:https + node:fs und verwenden standardmäßig das ServiceAccount-Token im Pod.

Paket	Aktiviert
@kubernetes/client-node (optional)	Nicht erforderlich. Optionaler Austausch für den fetchEndpoints-Hook des KubernetesApiSeedProvider, falls du lieber den offiziellen Client statt des eingebauten HTTPS-Aufrufs verwenden möchtest.

TypeScript-Konfiguration

Füge die folgenden Compiler-Optionen in Deiner tsconfig.json hinzu (oder verifiziere sie):

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

Das Framework verlässt sich auf noImplicitOverride, um Lifecycle-Method-Typo-Bugs zu fangen (z. B. onRecieve statt onReceive). Lass es weg, wenn Du es vorziehst, aber Du verlierst dieses Sicherheitsnetz.

Installation verifizieren

Speichere das als 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

Erwartete Ausgabe:

pong
install OK

Wenn Du beide Zeilen siehst, funktioniert die Installation. Wenn pong fehlt, ist Deine Runtime unter der Mindestversion (siehe die Tabelle oben auf dieser Seite) — aktualisiere sie und führe erneut aus.

Fehlerbehebung

`Cannot find module 'actor-ts'`

• Bun / Node: Prüfe, ob node_modules/ existiert. Führe bun add actor-ts oder npm install erneut aus, falls nicht.
• Deno: Verwende den npm:-Specifier — import { ... } from 'npm:actor-ts'. Bare Specifier lösen sich in Deno ohne Import Map nicht auf.

Ältere Node-Versionen

actor-ts benötigt Node ≥ 24.0 (die älteste aktive LTS-Linie; Node 20 hat im April 2026 sein End-of-Life erreicht). Serverseitige websocket()-Routen brauchen ws auf dem Express-Backend, @fastify/websocket auf dem Fastify-Backend oder @hono/node-ws auf dem Hono-Backend, wenn sie auf Node laufen. Node ≤ 23 wird nicht unterstützt.

Fehlende Peer-Dependency zur Laufzeit

Der Versuch, eine Integration ohne ihre Peer-Dep zu verwenden, erzeugt einen klaren Fehler wie:

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

Installiere das genannte Paket und führe erneut aus. Siehe die Peer-Dep-Tabellen oben für die vollständige Liste pro Integration.

Wie es weitergeht

• Quickstart — fünf Minuten zu einem laufenden Actor.
• Warum Actors? — die Philosophie hinter dem Framework.
• Lernpfad — empfohlene Lesereihenfolge basierend auf dem, was Du bauen willst.