Node.js

actor-ts läuft auf Node.js 24 und neuer. Voll unterstützt; die CI des Frameworks läuft neben Bun auch gegen Node.

Warum Node

Grund	Detail
Managed-Platform-Support	AWS Lambda, Cloud Functions, Vercel, Cloudflare Pages akzeptieren alle Node.
LTS-Gründe	Manche Compliance-Regime verlangen Node’s LTS-Branches.
Bestehende Node-Infrastruktur	Bestehende Build-/Deploy-/Monitor-Stacks integrieren sich natürlich.
Breitere native-Modul-Unterstützung	Manche nativen Module (z. B. spezifische Verschlüsselungsbibliotheken) hinken auf Bun hinterher.

Für neue Greenfield-Projekte ohne diese Einschränkungen ist Bun meist vorzuziehen — weniger Peer-Deps, schnellerer Start.

Installation

nvm install 24
nvm use 24
node --version    # v24.0.0 oder neuer

Für Docker:

FROM node:24-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
CMD ["node", "dist/main.js"]

Warum Node 24 als Untergrenze

Node 24 ist die älteste aktive LTS-Linie (Node 20 hat im April 2026 sein End-of-Life erreicht, Node 22 ist im Maintenance-Modus). Alles, worauf das Framework sich stützt, ist dort nativ an Bord:

• globalThis.crypto.subtle (WebCrypto) — genutzt für AES-GCM in Object-Storage-Verschlüsselung.
• Eingebautes fetch und ein nativer WebSocket-Client — kein ws-Fallback für den WebsocketClientActor nötig. (Serverseitige websocket()-Routen brauchen weiterhin ws auf Express, @fastify/websocket auf Fastify oder @hono/node-ws auf Hono.)
• Native zstd-Kompression — zstdCompress / zstdDecompress in node:zlib, Object-Storage-zstd funktioniert also ohne fzstd.
• AsyncLocalStorage und node:test — lang stabil.

Ältere Node-Versionen führen die Core-Actor-API vielleicht aus, werden aber weder getestet noch unterstützt — melde Bugs nur gegen Node 24+.

Peer-Dependencies

Node-Setups brauchen ein paar Peer-Deps, die das Framework nicht mitliefert:

Subsystem	Peer-Dep
SQLite-Journal / -Snapshot-Store / -State	better-sqlite3
WebSocket-Server (websocket()-Route)	@fastify/websocket (Fastify), @hono/node-ws (Hono) oder ws (Express)
Kafka	kafkajs
MQTT	mqtt
AMQP	amqplib
NATS	nats
Redis	ioredis
gRPC	@grpc/grpc-js @grpc/proto-loader
Cassandra	cassandra-driver
OTel	@opentelemetry/api @opentelemetry/sdk-* + Exporter

Installiere nur, was du nutzt:

npm install actor-ts ts-pattern
# Plus pro Subsystem:
npm install better-sqlite3   # für SQLite-Persistenz
npm install kafkajs           # für Kafka-Actor

Die Lazy-Imports des Frameworks heißen, fehlende Peer-Deps brechen ungenutzte Features nicht — wenn du nie einen KafkaActor instanziierst, kannst du kafkajs weglassen.

SQLite auf Node

npm install better-sqlite3

Dann:

import { SqliteJournal, SqliteJournalOptions } from 'actor-ts';

// Erkennt automatisch better-sqlite3 auf Node.
const sqliteJournalOptions = SqliteJournalOptions.create().withPath('/var/lib/events.db');
new SqliteJournal(sqliteJournalOptions);

better-sqlite3 ist ein natives Modul — Erst-Install verlangt Build-Tools (gyp, Python, einen C++-Compiler). Die meisten Linux-Base-Images haben diese; Alpine-basierte Images brauchen vielleicht:

RUN apk add --no-cache python3 make g++

Für vorgefertigte Binaries:

npm install better-sqlite3 --prefer-offline

Die meisten Plattformen haben vorgefertigte Artefakte; du baust selten aus dem Quellcode.

Tests laufen lassen

# Mit Node's nativem Runner:
node --test --test-name-pattern="..."

# Mit Vitest:
npx vitest

# Mit Jest:
npx jest

TestKit funktioniert mit allen dreien. Die eigenen Tests des Frameworks nutzen bun:test, aber die TestKit-API ist runner-agnostisch.

ESM vs CommonJS

actor-ts liefert ESM (type: "module" in package.json). In Node:

// In der package.json deiner App:
{
  "type": "module"
}

// actor-ts importieren:
import { ActorSystem } from 'actor-ts';

Für CommonJS-Projekte bräuchtest du einen Build-Schritt (esbuild, tsc mit ES-Module-Interop), um zu überbrücken. Einfacher: nutze ESM durchgängig.

Performance auf Node

Grobe Zahlen vs Bun:

• Tell-Durchsatz: ~6-8 M msgs/sec (langsamer als Bun).
• HTTP-Durchsatz: vergleichbar für Fastify-basierte Server.
• Start-Zeit: 300-500 ms vs Bun’s sub-100 ms.

Für lang laufende Produktionsdienste zählt die Start-Lücke nicht. Für hochdurchsatz-starke Tight-Loop-Arbeit gewinnt Bun.

Gängige Plattformen

AWS Lambda

# Lambda-Function-Definition:
Runtime: nodejs24.x
MemorySize: 1024
Handler: dist/main.handler

Cold-Start dominiert bei kurzen Invocations. Pre-warm via Provisioned Concurrency für latenz-sensitive Workloads.

Das Cluster-Modell passt nicht gut zu Lambda — Actor erwarten einen lang laufenden Prozess. Für Lambda nutze actor-ts als Single-Actor-per-Invocation-Muster (oder nutze eine andere Architektur für kurzlebige Workloads).

Cloud Functions / Vercel / Netlify

Dieselben Einschränkungen — diese Plattformen sind kurzlebige Prozess-Umgebungen. Single-Actor-Muster funktionieren; Clustering nicht.

Lang laufende VMs / Container

Natürlicher Fit. Nutze systemd / PM2 (siehe Process Manager) oder K8s (siehe Kubernetes-Deployment).

Native Module brauchen Build-Tools

npm install better-sqlite3
# → schlägt auf minimalem Alpine ohne g++/python3 fehl

Container-Images brauchen Build-Tools oder vorgefertigte Binaries. Nutze das offizielle node-Image (Debian-basiert) statt node:alpine, um das zu vermeiden.

Node-Version-Drift zwischen Dev und Prod

package.json

{ "engines": { "node": ">=24" } }

Pinne die Node-Version in engines. Ohne sie nutzt Dev vielleicht Node 24 und Prod Node 18 — subtile API-Unterschiede verursachen merkwürdige Bugs.

Wo es weitergeht

• Runtime — Überblick — das größere Bild.
• Bun — die primäre Alternative.
• Kompatibilitäts-Matrix — Feature-für-Feature-Unterstützung.
• Installation — Install-Schritte.