# @solid-primitives/workers
[](https://bundlephobia.com/package/@solid-primitives/workers)
[](https://www.npmjs.com/package/@solid-primitives/workers)
[](https://github.com/solidjs-community/solid-primitives#contribution-process)
[](https://vitest.dev)
A set of primitives for working with Web Workers:
- `createWorker` — Spawns a worker from an object of named functions; each method becomes a **typed** async RPC call.
- `createWorkerPool` — Like `createWorker` but round-robins calls across a fixed pool of workers.
- `createWorkerQuery` — Reactive async query backed by a worker call; integrates with ``.
- `createReactiveWorker` — Full reactive bridge between the main thread and a worker using Solid stores.
- `workerScope` — Worker-side companion to `createReactiveWorker`; provides a reactive `inputs` store and a `setOutputs` setter inside the worker.
## Installation
```bash
npm install @solid-primitives/workers
# or
yarn add @solid-primitives/workers
# or
pnpm add @solid-primitives/workers
```
---
## How to use it
### `createWorker`
Spawn a worker from an object of self-contained functions. Each method becomes a typed async RPC call on the returned worker object. The worker is automatically terminated when the reactive owner is disposed.
```tsx repl
import { render } from "@solidjs/web";
import { createSignal } from "solid-js";
import { createWorker } from "@solid-primitives/workers";
// Serialized into the worker: must be self-contained (no closures, no imports)
function fib(n: number): number {
return n < 2 ? n : fib(n - 1) + fib(n - 2);
}
function Demo() {
const [worker] = createWorker({ fib });
const [n, setN] = createSignal(35);
const [result, setResult] = createSignal("—");
const run = () => {
setResult("computing in worker…");
worker.fib(n()).then(
r => setResult(String(r)),
e => setResult(`error: ${e}`),
);
};
return (
<>
setN(Math.min(40, Math.max(1, e.currentTarget.valueAsNumber || 1)))}
/>
{result()}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
const [worker] = createWorker({
add(a: number, b: number) {
return a + b;
},
multiply(a: number, b: number) {
return a * b;
},
});
console.log(await worker.add(1, 2)); // 3 — fully typed, no cast required
console.log(await worker.multiply(3, 4)); // 12
```
**Returns:** `[worker, start, stop, exports]`
- `worker` — the underlying `Worker` instance with typed async methods attached. Each method returns a `CancellablePromise` — a standard Promise extended with an `.abort()` method.
- `start` — re-attaches the RPC message listener; called automatically on creation. Safe to call again (replaces the old listener rather than stacking).
- `stop` — removes the listener and terminates the worker. Idempotent — subsequent calls (e.g. from `onCleanup`) are no-ops.
- `exports` — `Set` of the exported function names
**Signature:**
```ts
function createWorker>(
fns: T,
options?: WorkerOptions,
): CreateWorkerResult;
```
#### Cancellation
Every RPC call returns a `CancellablePromise` with an `.abort()` method. Calling it immediately rejects the promise with an `AbortError` and notifies the worker to stop:
```ts
const [worker] = createWorker({ wait });
const call = worker.wait(5000);
call.catch(e => console.log(e.name)); // "AbortError"
setTimeout(() => call.abort(), 500); // cancel after 500 ms
```
Worker functions receive an `AbortSignal` as their **last argument** automatically. Self-contained async functions can use it to terminate early:
```ts
const [worker] = createWorker({
async wait(ms: number, signal?: AbortSignal): Promise {
await new Promise((resolve, reject) => {
const t = setTimeout(resolve, ms);
signal?.addEventListener(
"abort",
() => {
clearTimeout(t);
reject(new DOMException("Aborted", "AbortError"));
},
{ once: true },
);
});
},
});
```
#### ⚠️ Functions must be self-contained
Worker functions are serialized via `Function.prototype.toString` and run in a separate thread. They have **no access to the surrounding scope** — closures over outer variables and `import` statements are silently unavailable at runtime.
```ts
// ❌ broken — `multiplier` is not in the worker's scope
const multiplier = 2;
const [w] = createWorker({
double(n: number) {
return n * multiplier;
}, // ReferenceError at runtime
});
// ✅ correct — self-contained
const [w] = createWorker({
double(n: number) {
return n * 2;
},
});
```
---
### `createWorkerPool`
Like `createWorker`, but distributes calls across `concurrency` workers using round-robin scheduling. The round-robin index is captured at method-access time, so storing a reference to a method and calling it later dispatches to the expected worker.
```tsx repl
import { render } from "@solidjs/web";
import { createSignal, For } from "solid-js";
import { createWorkerPool } from "@solid-primitives/workers";
function fib(n: number): number {
return n < 2 ? n : fib(n - 1) + fib(n - 2);
}
function Demo() {
const [pool] = createWorkerPool(3, { fib });
const inputs = [28, 30, 32, 34, 36];
const [results, setResults] = createSignal([]);
const [pending, setPending] = createSignal(0);
const runAll = () => {
setResults(inputs.map(() => "…"));
setPending(inputs.length);
inputs.forEach((n, i) =>
pool
.fib(n)
.then(r => setResults(prev => prev.map((v, j) => (j === i ? String(r) : v))))
.finally(() => setPending(p => p - 1)),
);
};
return (
<>
{(r, i) => (
fib({inputs[i]}) = {r()}
)}
>
);
}
render(() => , document.getElementById("app")!);
```
```ts
const [pool] = createWorkerPool(4, {
add(a: number, b: number) {
return a + b;
},
});
// Calls are spread across 4 worker instances
const results = await Promise.all([pool.add(1, 2), pool.add(3, 4), pool.add(5, 6)]);
// [3, 7, 11]
```
**Returns:** `[proxy, start, stop]`
- `start` — spawns the worker pool. Called automatically on creation; subsequent calls while the pool is running are no-ops. After `stop()`, calling `start()` again respawns all workers.
- `stop` — terminates all workers and resets the pool.
**Signature:**
```ts
function createWorkerPool>(
concurrency: number,
fns: T,
options?: WorkerOptions,
): CreateWorkerPoolResult;
```
> The same self-contained function constraint from `createWorker` applies.
---
### `createWorkerQuery`
A reactive async query that re-runs whenever reactive inputs inside `fn` change. Built on Solid's async `createMemo`, so it integrates with `` for suspense-aware rendering. Returns `undefined` until the first resolution (on the server, always `undefined`).
```tsx repl
import { render } from "@solidjs/web";
import { createSignal, isPending, Loading } from "solid-js";
import { createWorker, createWorkerQuery } from "@solid-primitives/workers";
function square(n: number): Promise {
return new Promise(resolve => setTimeout(() => resolve(n * n), 500));
}
function Demo() {
const [worker] = createWorker({ square });
const [n, setN] = createSignal(4);
const result = createWorkerQuery(() => worker.square(n()));
return (
<>
calculating…}>
>
);
}
render(() => , document.getElementById("app")!);
```
When inputs change before a previous call resolves, the previous call is **automatically aborted** if it returned a `CancellablePromise` — no stale results reach the accessor.
```ts
import { createWorker, createWorkerQuery } from "@solid-primitives/workers";
import { createSignal, Loading } from "solid-js";
const [worker] = createWorker({
add([a, b]: [number, number]) {
return a + b;
},
});
const [input, setInput] = createSignal<[number, number]>([1, 1]);
const result = createWorkerQuery(() => worker.add(input()));
// In JSX:
// calculating…}>
// {result()}
//
setInput([3, 4]); // aborts the previous call and dispatches a new one
```
**Returns:** `Accessor`
Errors thrown by the worker promise propagate to the nearest `` boundary. There is no inline error option — wrap with `` to handle them.
---
### `createReactiveWorker` + `workerScope`
A full reactive bridge between the main thread and a **module worker** using Solid stores. Input changes on the main thread are automatically forwarded to the worker; output changes written inside the worker propagate back — all reactively.
```tsx repl
import { render } from "@solidjs/web";
import { onCleanup } from "solid-js";
import { createReactiveWorker } from "@solid-primitives/workers";
// Normally a module file using `workerScope` (see below). Inlined here as a tiny
// hand-written worker speaking the same bridge protocol so the demo is self-contained.
const workerSource = `let inputs = {};
onmessage = ({ data }) => {
if (data.type === "init") inputs = data.inputs;
if (data.type === "input") inputs[data.key] = data.value;
postMessage({ type: "outputs", snapshot: { squared: inputs.n * inputs.n } });
};`;
function Demo() {
const workerUrl = URL.createObjectURL(new Blob([workerSource], { type: "text/javascript" }));
onCleanup(() => URL.revokeObjectURL(workerUrl));
const { inputs, setInputs, outputs, error } = createReactiveWorker(workerUrl, {
inputs: { n: 3 },
outputs: { squared: 0 },
});
return (
<>
squared in worker: {outputs.squared}
{error() &&
worker error: {error()!.message}
}
>
);
}
render(() => , document.getElementById("app")!);
```
#### Main thread
```ts
import { createReactiveWorker } from "@solid-primitives/workers";
const { inputs, setInputs, outputs, error } = createReactiveWorker(
new URL("./my.worker.ts", import.meta.url),
{
inputs: { data: [] as number[], threshold: 0.5 },
outputs: { result: 0 },
},
);
// Write to inputs — changes are deep-tracked and forwarded to the worker
setInputs(s => {
s.threshold = 0.8;
});
// Read outputs reactively (store proxy — no `()`)
createEffect(
() => outputs.result,
value => console.log("worker result:", value),
);
// Surface worker errors
createEffect(
() => error(),
ev => {
if (ev) console.error("worker crashed:", ev.message);
},
);
```
**Returns:** `{ inputs, setInputs, outputs, error }`
| Field | Type | Description |
| ----------- | ------------------------------ | ------------------------------------------------------------------- |
| `inputs` | `I` (store proxy) | Read-only on main thread; mutate via `setInputs` |
| `setInputs` | `StoreSetter` | Draft-first store setter; changes deep-track and sync to the worker |
| `outputs` | `Readonly` (store proxy) | Updated whenever the worker writes new values |
| `error` | `Accessor` | Last unhandled worker error, or `null` |
> **Large data:** each input key change serializes the full value of that key. For large arrays or deeply nested objects, prefer `Transferable` objects (e.g. `ArrayBuffer`) or chunked updates to avoid serialization overhead.
#### Worker module (`my.worker.ts`)
Import from the `/worker` sub-entry so the bundle only includes worker-side code:
```ts
import { createEffect } from "solid-js";
import { workerScope } from "@solid-primitives/workers/worker";
workerScope<{ data: number[]; threshold: number }, { result: number }>(({ inputs, setOutputs }) => {
createEffect(
() => ({ data: inputs.data, threshold: inputs.threshold }),
({ data, threshold }) => {
const filtered = data.filter(v => v > threshold);
setOutputs(s => {
s.result = filtered.length;
});
},
);
});
```
The `setup` callback runs inside a `createRoot`, so all reactive primitives created there (`createEffect`, `createMemo`, etc.) are owned for the worker's lifetime.
> **Do not** use `await workerScope()` and then create reactive primitives after the await — they will have no reactive owner and produce `NO_OWNER_EFFECT` warnings. Always put reactive code inside the callback.
> **SSR:** `workerScope` must not be called on the server. Guard with `isServer` if your worker module is imported in an SSR context.
#### Worker TypeScript configuration
Add `"WebWorker"` to `lib` in the worker file's `tsconfig.json` so TypeScript recognises `self`, `postMessage`, etc.:
```json
{
"compilerOptions": {
"lib": ["ESNext", "WebWorker"]
}
}
```
#### Bridge message protocol
| Direction | Message type | Purpose |
| ------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| main → worker | `{ type: "init", inputs, outputs }` | Sent once on construction with initial store values |
| main → worker | `{ type: "input", key, value }` | Sent whenever an input key changes (full key value, not a diff) |
| worker → main | `{ type: "outputs", snapshot }` | Sent whenever any output changes; carries a full plain-object snapshot |
---
## SSR behaviour
All primitives are SSR-safe. On the server (`isServer === true`):
| Primitive | SSR stub |
| ---------------------- | ------------------------------------------------------------------- |
| `createWorker` | Returns `[EventTarget, noop, noop, Set()]` — no worker spawned |
| `createWorkerPool` | Returns `[EventTarget, noop, noop]` — no workers spawned |
| `createWorkerQuery` | Returns `() => undefined` |
| `createReactiveWorker` | Returns stores initialised from schema values + `error: () => null` |
| `workerScope` | Safe to import; do not call on the server |
---
## Changelog
See [CHANGELOG.md](./CHANGELOG.md)
## Inspiration
Inspired by Jason Miller's worker function. Borrows the RPC and function-export approach.