Skip to content
English

Deno

actor-ts works on Deno, but with caveats. Core actor APIs (Actor, ActorSystem, ActorRef, supervision, etc.) work identically. Subsystems with native dependencies are where support varies.

SubsystemStatus
Core actor API✓ Works
Cluster transport (TCP)✓ Works (via Deno.connect / Deno.listen)
Persistence — in-memory✓
Persistence — SQLite✗ Not supported
Persistence — Cassandra⚠ Untested
HTTP — Fastify✓ Works
HTTP — Bun.serve✗ (Bun-only)
WebSocket server (websocket() route)✓ Works (via Hono backend)
Broker actors (Kafka, MQTT, etc.)⚠ Depends on Deno-compat of underlying npm package

For production, we recommend Bun or Node unless your organization is committed to Deno.

Terminal window
curl -fsSL https://deno.land/install.sh | sh
deno --version # need 2.0+
// deno.json
{
"imports": {
"actor-ts": "npm:actor-ts",
"ts-pattern": "npm:ts-pattern"
}
}
// main.ts
import { ActorSystem } from 'actor-ts';
const system = ActorSystem.create('my-app');
// ...

Deno’s npm-compat lets you import actor-ts directly via npm: specifiers.

  • Core actor model — Actor, ActorSystem, dispatchers, mailboxes, supervision.
  • Cluster transport — Deno’s TCP APIs are wired up.
  • In-memory persistence — works for tests + dev.
  • DistributedData — pure-JS, works.
  • Event stream, receptionist, sharding singleton — all work.

Not supported. Deno doesn’t have a built-in SQLite, and neither bun:sqlite nor better-sqlite3 work natively.

Workarounds:

  • deno_sqlite (a Deno-native package) — implement Journal against it manually.
  • HTTP-backed journal — wrap a remote journal service.
  • Use Cassandra instead — no SQLite needed for multi-node persistence.

The websocket() route (backed by a WebsocketServerActor) relies on the HTTP backend’s upgrade support — @fastify/websocket or ws on Node, Bun.serve on Bun. On Deno, use the Hono backend (DenoHonoRunner), which wires up websocket() on top of Deno.serve

  • Deno.upgradeWebSocket for you — just install hono with deno add npm:hono. No hand-written adapter is needed.

Deno’s permission system requires explicit flags:

Terminal window
deno run \
--allow-net \
--allow-read \
--allow-write \
--allow-env \
main.ts

For most actor-ts apps:

  • --allow-net — cluster + HTTP traffic.
  • --allow-read — config files, certs.
  • --allow-write — for SQLite / file persistence (if using).
  • --allow-env — for env vars.

For production, narrow to specific allowances:

Terminal window
deno run --allow-net=:2552,:8080 \
--allow-read=./reference.conf,./application.conf,./secrets.conf,./.env \
--allow-env=ACTOR_TS_*,DB_PASSWORD main.ts

A narrow grant has to name what the config loader touches, because a missing grant is no missing file to Deno — it is a refusal:

  • --allow-read — the four files Config.load looks for: the project reference.conf, application.conf, the secrets file and the .env file, in the working directory or wherever an ACTOR_TS_* variable or the code names them. A file you never ship can stay out of the list only if the code says false for it (withReferenceConfigFile(false) and its siblings); otherwise startup fails with a ConfigError naming the file it was refused.
  • --allow-env — the ACTOR_TS_* names the loader reads, and every variable a ${VAR} in those files names. Deno grants the environment variable by variable, so one left out is refused when the substitution reads it, even when only the .env file holds it. Measured on Deno 2.6.8.

Deno Deploy is Deno’s edge-style serverless platform. Short-lived isolates, no long-running process — doesn’t fit clustering.

For Deno Deploy use cases:

  • Single-actor patterns — spawn one actor per request, then stop.
  • Use actor-ts as a library for actor patterns within an HTTP handler, not as a clustering primitive.
import { TestKit } from 'actor-ts/testkit';
Deno.test('counter increments', async () => {
const tk = TestKit.create();
// ...
await tk.shutdown();
});

Deno’s built-in test runner works with TestKit.

If you’re considering moving from Node / Bun to Deno:

  1. Verify your peer deps work on Deno — most NPM packages are usable via npm:, but a few (especially those with complex native bindings) fail.
  2. Replace SQLite if you use it — switch to in-memory (tests) or Cassandra (production).
  3. Replace websocket() routes if used — write a Deno adapter or use SSE instead.
  4. Test cluster formation thoroughly — Deno’s TCP backend has less production hours.