Skip to content
execbox

Runtime Choices

Execbox v1 has one executor package: @execbox/quickjs. Start inline, then move to worker-hosted QuickJS when your application needs off-main-thread execution or pooled worker shells.

Inline QuickJS

Section titled “Inline QuickJS”

Inline QuickJS is the default constructor path and the smallest setup.

import { QuickJsExecutor } from "@execbox/quickjs";


const executor = new QuickJsExecutor();

Use it when you are proving out provider shape, running trusted code paths, or optimizing for the fewest moving parts. Each execution gets fresh QuickJS runtime state while host tools stay in the application process.

Worker-hosted QuickJS

Section titled “Worker-hosted QuickJS”

Worker-hosted QuickJS keeps the same QuickJsExecutor API and moves guest runtime work into a worker thread.

import { QuickJsExecutor } from "@execbox/quickjs";


const executor = new QuickJsExecutor({
  host: "worker",
});

Use it when you want worker lifecycle control, pooled worker reuse, and guest runtime work away from the main thread. Worker mode is pooled by default; use mode: "ephemeral" when a fresh worker shell per execution is more important than latency.

Decision guide

Section titled “Decision guide”
NeedRecommended path
Smallest install and development pathnew QuickJsExecutor()
Lowest local latencyInline QuickJS
Off-main-thread executionnew QuickJsExecutor({ host: "worker" })
Warm reusable worker shellsWorker-hosted QuickJS with pooled mode
Fresh worker shell per executionWorker-hosted QuickJS with ephemeral mode

Production boundary guidance

Section titled “Production boundary guidance”

Inline and worker-hosted QuickJS are local runtime placement choices. For hostile-code or multi-tenant deployments, put the application-level execution service behind a process, container, VM, or equivalent operational boundary and keep providers scoped to the capabilities each caller should receive.

Next: