webactor

Actor-model architecture for the browser. One programming model for every boundary in your app — components, tabs, and Web Workers — built on plain message passing.

import { createActor, request, response } from 'webactor';

const math = createActor('math', (ctx) => {
    ctx.addEventListener('message', (e) => {
        if (e.data.type === 'sum') response(ctx, e, e.data.a + e.data.b);
    });
});

math.launch();

const res = await request(math, { type: 'sum', a: 2, b: 3 });
console.log(res.data); // 5

Why actors, why now

Your app is already concurrent — workers, tabs, streams, agents — but the browser's primitives for it (Worker, SharedWorker, MessagePort, postMessage) are low-level and inconsistent. webactor is one uniform actor model over all of them.

• Isolated state. An actor owns its data; the only way in or out is a message.
• Location transparency. Same API in-thread, across tabs, across workers. Move an actor into a worker without touching its logic.
• Fault tolerance. Supervisors restart crashed actors and dead workers — "let it crash" on the client.
• Small blast radius. A mistake stops at one mailbox, which is what lets people and agents work on the same app in parallel.

Install

npm install webactor
# or: pnpm add webactor

Core idea in one picture

An actor is an isolated unit with a mailbox. You never call it — you send it an envelope (a typed message). Actors are wired together with connections. Once connected, three communication patterns cover almost everything:

| Pattern | Function | Use it for | | ---------------------- | -------------------------------- | -------------------------------------------------------- | | Fire-and-forget | postMessage | events, notifications, state broadcasts | | Request / response | request / response | "ask and await an answer", RPC-style calls | | Channel | openChannel / supportChannel | a dedicated, disconnect-aware session between two actors |

The same three patterns work identically across a Worker boundary.

60-second tour

Two actors talking

import { createActor, connectActors, ActorContext } from 'webactor';

// A stateful business actor — owns the counter, no one else can touch it.
const counter = createActor('counter', (ctx: ActorContext) => {
    let value = 0;
    ctx.addEventListener('message', (e) => {
        if (e.data.type === 'inc') value++;
        if (e.data.type === 'dec') value--;
        ctx.postMessage({ type: 'value', value }); // broadcast new state
    });
});

// A UI actor — renders, never owns business state.
const ui = createActor('ui', (ctx: ActorContext) => {
    ctx.addEventListener('message', (e) => {
        if (e.data.type === 'value') render(e.data.value);
    });
    document.querySelector('#inc')!.addEventListener('click', () => ctx.postMessage({ type: 'inc' }));
});

const disconnect = connectActors(ui, counter);
ui.launch();
counter.launch();

// later: disconnect(); ui.close(); counter.close();

Move an actor into a Worker — same code

counter doesn't care where it lives. Put it in a SharedWorker (shared across every tab) and connect the whole thing with a dense network:

// main.ts
import { createDenseNetwork } from 'webactor';
import { createUIActor } from './ui-actor';

const worker = new SharedWorker(new URL('./server.worker.ts', import.meta.url), { type: 'module' });
const network = createDenseNetwork(createUIActor(), worker); // auto-detects the worker
network.launch();

// server.worker.ts
import { createDenseNetwork, useContextMessagePort } from 'webactor';
import { createCounterActor } from './counter-actor';

createDenseNetwork(useContextMessagePort(), createCounterActor()).launch();

The UI actor's request(...) / postMessage(...) calls are unchanged. Routing across the thread boundary is automatic.

Keep it alive — supervision

import { applyActorSupervisor, Reasons } from 'webactor';

const supervised = applyActorSupervisor(
    () => createCounterActor(),
    { shouldRetry: (reason) => reason !== Reasons.Close }, // restart on crash, not on intentional close
);
supervised.launch(); // if the inner actor throws/closes unexpectedly, it's rebuilt

There's an applyWorkerSupervisor too — it detects a dead/crashed Worker (via the Web Locks API) and respawns it.

What's in the box

• createActor / createActorFactory — build isolated units.
• connectActors / connectActorToWorker / connectActorToMessagePort — wire units across any boundary.
• createDenseNetwork — full-mesh several actors and workers at once.
• createRetranslator — a transparent relay node for building hub/bridge topologies.
• request / response — awaitable RPC with automatic back-routing across the mesh.
• openChannel / supportChannel — dedicated, disconnect-aware pipes (great for per-client sessions).
• applyActorSupervisor / applyWorkerSupervisor — "let it crash" restart strategies.
• useContextMessagePort / onConnectMessagePort — the Worker/SharedWorker side of the wire.
• Envelopes, transferables, pluggable providers (timers, locks, logger) for testing & non-browser runtimes.

Full API, internals, routing model, and patterns: documentation.md.

DevTools

A Chrome DevTools panel ships alongside the library: the live actor graph across every thread, the connections between actors, and the envelopes flowing over them — plus per-actor message history with a payload inspector.

pnpm --filter webactor-devtools build   # load packages/devtools/dist as an unpacked extension

See packages/devtools. The recorder lives in the library but stays inert until something installs a sink, so there is no cost when the extension is not present. You can also drive it yourself:

import { enableDevtools, getDevtoolsSnapshot } from 'webactor';

enableDevtools();
console.log(getDevtoolsSnapshot()); // { thread, nodes, links, messages }

Repository layout

This is a pnpm workspace:

| Package | What it is | | --------------------------------------------- | ------------------------------------------------------------- | | packages/webactor | the library (src), unit tests (tests), load tests (e2e) | | packages/devtools | webactor-devtools, the Chrome DevTools extension | | examples/simple | minimal UI ↔ business actor split | | examples/chat | multi-tab chat over a SharedWorker |

pnpm install
pnpm build           # every package
pnpm test            # unit + e2e + devtools
pnpm test:unit       # vitest, packages/webactor/tests
pnpm test:e2e        # playwright load tests, packages/webactor/e2e
pnpm test:devtools   # playwright panel + unpacked-extension tests

When to use it (and when not)

Great fit

• Apps with heavy Worker / SharedWorker use, or that want to move work off the main thread.
• Multi-tab coordination and real-time sync through a SharedWorker.
• Clear separation of UI ↔ domain logic, offline-first, or long-lived background processing.
• Anything that needs fault isolation and automatic restart of subsystems.

Probably overkill

• "Call one function in a worker and get a result." Reach for Comlink — it's a thinner RPC wrapper.
• Small apps where a component tree + a state manager already fit comfortably.

webactor is a model, not just an RPC shim: you adopt actors, envelopes, and supervision. That's a real mental investment — worth it when the payoff (isolation, fault tolerance, location transparency) matters.

vs. Comlink

| | webactor | Comlink | | ------------------------------------- | ----------------------- | --------------------- | | Model | Actor / message passing | Proxy-based RPC | | In-thread + cross-worker with one API | ✅ | Worker-focused | | Request/response | ✅ | ✅ (as proxied calls) | | Fire-and-forget broadcasts | ✅ | Awkward | | Dedicated sessions (channels) | ✅ | Manual | | Supervision / restart | ✅ | ❌ | | Multi-node topologies (mesh, relay) | ✅ | ❌ | | Bundle / surface | Larger, opinionated | Tiny, minimal |

Status

Single-maintainer project · MIT. The API described here is exercised by the test suite (pnpm test). Feedback and issues welcome on the repository.

Releases are automated with changesets — see CONTRIBUTING.md for how to land a change and cut a version.