Node.js

actor-ts runs on Node.js 20 and later. Fully supported; the framework’s CI runs against Node alongside Bun.

Why Node

Reason	Detail
Managed-platform support	AWS Lambda, Cloud Functions, Vercel, Cloudflare Pages all accept Node.
Long-term-support reasons	Some compliance regimes require Node’s LTS branches.
Existing Node infrastructure	Existing build/deploy/monitor stacks integrate naturally.
Wider native-module support	Some native modules (e.g., specific encryption libraries) lag behind on Bun.

For new greenfield projects without these constraints, Bun is usually preferable — fewer peer deps, faster startup.

Installation

nvm install 20
nvm use 20
node --version    # v20.0.0 or later

For Docker:

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

Why Node 20 as the floor

The framework needs:

• globalThis.crypto.subtle (WebCrypto) — present on Node 20+; used for AES-GCM in object-storage encryption.
• Built-in fetch — stable on Node 18+.
• AsyncLocalStorage — long-stable.
• node:test — needs Node 20.

Node 18 may work for the core actor API but isn’t actively tested — file bugs against Node 20+ only.

A couple of features unlock natively on newer Node versions (without a peer-dep fallback):

• Native WebSocket — global WebSocket constructor is built in on Node 22+. On Node 20, install the ws peer dep for ServerWebSocketActor / WebSocketActor.
• Native zstd compression — node:zlib gained zstdCompress / zstdDecompress on Node 22.15. On older Node, install the fzstd peer dep for object-storage zstd codecs.

Both peer-dep paths are well-tested; “needing a peer dep” doesn’t mean “broken on Node 20.”

Peer dependencies

Node setups need a few peer deps the framework doesn’t bundle:

Subsystem	Peer dep
SQLite journal / snapshot store / state	better-sqlite3
WebSocket server (ServerWebSocketActor)	ws
Kafka	kafkajs
MQTT	mqtt
AMQP	amqplib
NATS	nats
Redis	redis
gRPC	@grpc/grpc-js @grpc/proto-loader
Cassandra	cassandra-driver
OTel	@opentelemetry/api @opentelemetry/sdk-* + exporter

Install only what you use:

npm install actor-ts ts-pattern
# Plus per-subsystem:
npm install better-sqlite3   # for SQLite persistence
npm install kafkajs           # for Kafka actor

The framework’s lazy imports mean missing peer deps don’t break unused features — if you never instantiate KafkaActor, you can skip kafkajs.

SQLite on Node

npm install better-sqlite3

Then:

import { SqliteJournal } from 'actor-ts';

// Auto-detects better-sqlite3 on Node.
new SqliteJournal({ path: '/var/lib/events.db' });

better-sqlite3 is a native module — first install requires build tools (gyp, Python, a C++ compiler). Most Linux base images include these; alpine-based images may need:

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

For pre-built binaries:

npm install better-sqlite3 --prefer-offline

Most platforms have pre-built artifacts; you rarely build from source.

Running tests

# With Node's native runner:
node --test --test-name-pattern="..."

# With Vitest:
npx vitest

# With Jest:
npx jest

TestKit works with all three. The framework’s own tests use bun:test, but the TestKit API is runner-agnostic.

ESM vs CommonJS

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

// In your app's package.json:
{
  "type": "module"
}

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

For CommonJS projects, you’d need a build step (esbuild, tsc with ES module interop) to bridge. Easier: use ESM throughout.

Performance on Node

Rough numbers vs Bun:

• Tell throughput: ~6-8M msgs/sec (slower than Bun).
• HTTP throughput: comparable for Fastify-based servers.
• Startup time: 300-500ms vs Bun’s sub-100ms.

For long-running production services, the startup gap doesn’t matter. For high-throughput tight-loop work, Bun wins.

Common platforms

AWS Lambda

# Lambda function definition:
Runtime: nodejs20.x
MemorySize: 1024
Handler: dist/main.handler

Cold-start dominates for short-lived invocations. Pre-warm via provisioned concurrency for latency-sensitive workloads.

The cluster model doesn’t fit Lambda well — actors expect a long-running process. For Lambda, use actor-ts as a single-actor-per-invocation pattern (or use a different architecture for short-lived workloads).

Cloud Functions / Vercel / Netlify

Same caveats — these platforms are short-lived-process environments. Single-actor patterns work; clustering doesn’t.

Long-running VMs / containers

Native fit. Use systemd / PM2 (see Process manager) or K8s (see Kubernetes deployment).

Native modules require build tools

npm install better-sqlite3
# → fails on minimal Alpine without g++/python3

Container images need build tools or pre-built binaries. Use the official node image (Debian-based) rather than node:alpine to avoid this.

Node version drift between dev and prod

package.json

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

Pin the Node version in engines. Without it, dev might use Node 24 and prod Node 18 — subtle API differences cause weird bugs.

Where to next

• Runtime overview — the bigger picture.
• Bun — the primary alternative.
• Compatibility matrix — feature-by-feature support.
• Installation — install steps.