Skip to content
actor-ts

Bun

Bun is the primary runtime actor-ts targets. Tested first; performance benchmarks run against Bun; the docs assume Bun by default.

Why Bun

Section titled “Why Bun”
ReasonDetail
Fast startup~3-5× faster cold start vs Node.
Built-in SQLitebun:sqlite — no peer deps.
Built-in test runnerbun:test — works for the framework’s tests + your own.
Native HTTP / WebSocketBun.serve for production-grade HTTP.
Fewer peer depsBun replaces ws, better-sqlite3, and several others.

Installation

Section titled “Installation”
Terminal window
curl -fsSL https://bun.sh/install | bash
# or via Homebrew: brew install oven-sh/bun/bun

Check:

Terminal window
bun --version    # need 1.1+

For Docker:

FROM oven/bun:1.1
WORKDIR /app
COPY . .
RUN bun install
CMD ["bun", "run", "dist/main.js"]

Creating a project

Section titled “Creating a project”
Terminal window
bun init
bun add actor-ts
bun add ts-pattern    # peer dep used by the framework's examples

For specific protocol actors:

Terminal window
bun add kafkajs       # for KafkaActor
bun add mqtt          # for MqttActor
bun add amqplib       # for AmqpActor
bun add nats          # for NatsActor / JetStreamActor
bun add redis         # for RedisStreamsActor
bun add @grpc/grpc-js @grpc/proto-loader   # for GrpcActor

Most peer deps you skip unless using that specific protocol.

Running tests

Section titled “Running tests”
Terminal window
bun test

Bun’s test runner is drop-in compatible with Jest’s API (describe / it / expect). TestKit works directly:

import { describe, it, beforeEach, afterEach } from 'bun:test';
import { TestKit } from 'actor-ts/testkit';


describe('Counter', () => {
  let tk: TestKit;
  beforeEach(() => { tk = TestKit.create(); });
  afterEach(async () => { await tk.shutdown(); });


  it('increments', async () => {
    // ...
  });
});

For Bun-specific test features, see the Bun docs.

SQLite on Bun

Section titled “SQLite on Bun”
import { SqliteJournal } from 'actor-ts';


// Bun auto-detects bun:sqlite — no driver setup needed.
new SqliteJournal({ path: '/var/lib/events.db' });

bun:sqlite is a built-in. No better-sqlite3 install required.

TCP + HTTP

Section titled “TCP + HTTP”

Bun has native APIs for both, but the framework picks them automatically via runtime detection. No config needed.

For HTTP backend, you can opt into Bun’s native:

import { BunServeBackend } from 'actor-ts/http';


await http.newServerAt('0.0.0.0', 8080)
  .useBackend(new BunServeBackend())
  .bind(routes);

Bun’s HTTP is fast (faster than Fastify in benchmarks). Worth using if your hot path is HTTP-heavy. For broader ecosystem (Fastify plugins, middleware), stick with the default Fastify backend.

Performance on Bun

Section titled “Performance on Bun”

Rough numbers (single Bun process, M-series Mac):

  • Tell throughput: ~10M msgs/sec on MicrotaskDispatcher.
  • HTTP throughput: ~150K req/sec for trivial routes.
  • SQLite append throughput: ~50K events/sec.

Bun consistently wins on startup time (sub-100ms vs Node’s ~300-500ms). Helpful for fast test iteration.

Bun-specific limitations

Section titled “Bun-specific limitations”

Where to next

Section titled “Where to next”