Overview
Islands-based multithreading: pools and shared workers joined to your app through one shared-memory fabric. Threads share a fixed-layout SharedArrayBuffer contract; work is offloaded two ways, task commands (dispatch → result) and state reactivity (field changes drive behavior), a fluid model that would deadlock or serialize in a single-threaded app.
Install
npm install @atolljs/coreThe core package ships the SDK: imported as @atolljs/core. Framework bindings are separate, independently published packages, @atolljs/<framework>, so you only install the framework you actually use.
How it fits together
main thread worker(s)
┌─────────────────────────────┐ postMessage ┌──────────────────────────┐
│ connectWorker client │ ─── task ─────▶ │ defineWorker methods │
│ counter.increment(n) │ ◀── result ──── │ scan / sort / mutate │
│ │ │ │ │
│ connector reads / watches │ │ ▼ │
└──────────────┬──────────────┘ └──────────┬───────────────┘
│ SharedArrayBuffer │
▼ (same bytes, zero copy) ▼
┌─────────────────────────────────────────────────────────┐
│ contract: list rows · strings · objects · numbers │
└─────────────────────────────────────────────────────────┘Three layers: contracts (defineSharedMemory + field.*) declare the memory layout once for both threads; the worker pair (defineWorker on the worker side, connectWorker on the main thread) dispatches typed method calls over a lazily-spawned pool; reactivity (observe, watch, defineTask) turns shared fields and task runs into subscribable snapshots the framework bindings adapt.
Import paths
| Import path | Contents | Bundlephobia |
|---|---|---|
@atolljs/core | Shared-memory contracts, worker pool, worker bootstrap, observables, tasks, codecs, logging | size report ↗ |
@atolljs/react | useObservable, useSharedValue, useTask, React hooks | size report ↗ |
@atolljs/vue | useObservable, useSharedValue, useTask, Ref-producing composables | size report ↗ |
@atolljs/solidjs | createObservable, createSharedValue, createTask, Accessors | size report ↗ |
@atolljs/svelte | observableValue, sharedValue, taskState, rune-backed state | size report ↗ |
@atolljs/angular | observableSignal, sharedValue, taskState, Signals | size report ↗ |
@atolljs/nextjs | Re-exports the React binding, App Router safe, SSR-ready | size report ↗ |
@atolljs/node | createNodePool, createNodeWorker, /shim, withSharedBuffer/bindSharedBuffer; /http adds createHttpCluster, serveHttp, routeHttpGateway, proxyToWorker, HTTP served from inside workers | size report ↗ |
@atolljs/nestjs | AtollModule, @AtollService, @AtollTask, runAtollWorker, pools and housed APIs on node:worker_threads | size report ↗ |
@atolljs/islands | mountIsland, connectIslandWorker, callbackProp, islandApp, main-thread mounting; /worker exports definePolyWorker/defineMonoWorker, the proxy DOM, emit, framework-neutral, no renderer built in | size report ↗ |
@atolljs/react-island | React island shell, <Island>, islandComponent, lazyIsland + react-reconciler worker renderer | size report ↗ |
@atolljs/vue-island | Vue island shell, AtollIsland, useIsland + createRenderer worker renderer | size report ↗ |
@atolljs/svelte-island | Svelte island shell, island action, createIslandState + Svelte 5 worker renderer | size report ↗ |
@atolljs/solid-island | SolidJS island shell, <Island>, createIsland, islandComponent, lazyIsland + solid-js/universal worker renderer | size report ↗ |
@atolljs/angular-island | Angular island shell, islandComponent facades, atollIsland directive + Renderer2 worker renderer | size report ↗ |
@atolljs/vite | Dev-server plugin, worker entries served as esbuild bundles; rebuild + respawn on change, so browser transforms (fast-refresh, @vite/client) never reach a worker | size report ↗ |
Bindings contain zero domain code: they adapt the SDK's observable primitives to each framework's reactivity model. Your app owns the domain: contracts, worker handlers, and composition. The islands layer is separate: it moves the whole render tree into a worker: see Islands for when that's the right trade. On the server, @atolljs/node/http moves HTTP itself into workers: see Node.js → Clustering.