crossbind
GitHub

Threads and workers

Two independent switches: runtime: 'st' | 'mt' is a build-time choice of threads inside the wasm module, and useWorker a runtime choice of the JavaScript thread the module runs on. Use either, both or neither.

The two axes

runtime: 'st'runtime: 'mt'
useWorker: true, the browser defaultwasm in one Web Worker, main thread stays freewasm in a worker, pthreads started from there: needs COOP/COEP; OPFS on by default
useWorker: falsewasm on the main thread, synchronous callspthreads through SharedArrayBuffer on the main thread: needs COOP/COEP
You wantPick
The quickest path to C++ in the browserst, the defaults
Synchronous calls from the pageuseWorker: false
Persistent storage in the browser (OPFS)mt, with the default worker
CPU-bound parallelism (image, geo, crypto)mt
Cloudflare Workers, Deno Deploy, Vercel Edgest only, with no worker
React Nativealways mt; no host configuration needed

Turning on multithreading

crossbind.config.js
export default {
general: { name: 'myapp' },
paths: { config: import.meta.url },
target: { runtime: 'mt' },
};

If any dependency is mt, your project becomes mt too: a multithreaded library cannot be used single-threaded.

The COOP/COEP requirement

Multithreaded wasm needs SharedArrayBuffer, which browsers gate behind cross-origin isolation. Your host has to send two response headers:

response headers
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Without them SharedArrayBuffer is undefined and init fails quietly. Check it from the console on the deployed page:

browser console
console.log(crossOriginIsolated); // must be true
console.log(typeof SharedArrayBuffer); // must be 'function'
HostWhere the headers go
Vite dev server and previewsent by @crossbind/plugin-vite
Webpack and Rspack dev serverssent by @crossbind/plugin-webpack
Vercelthe headers array in vercel.json
Netlify, Cloudflare Pagesa _headers file
nginxadd_header Cross-Origin-Opener-Policy same-origin; and the COEP twin
Express or your own servermiddleware that sets both on every response
require-corp blocks third-party assets
Cross-origin images, fonts and scripts stop loading unless they send Cross-Origin-Resource-Policy: cross-origin. Either switch to Cross-Origin-Embedder-Policy: credentialless, or proxy those assets through your own origin.

What changes with useWorker

The module runs in its own Web Worker, and the page talks to it through proxies: the same API, but every call returns a promise. It is on by default in every browser; pass useWorker: false to keep the module on the page thread. Worker mode lists everything that changes.

Where it does not apply

  • Edge runtimes (Cloudflare Workers, Deno Deploy, Vercel Edge) have no Worker constructor and no SharedArrayBuffer: st only, with m.FS in memory.
  • React Native builds are always mt, with the device's own threads: no headers are needed, and useWorker does not apply.
  • Node.js runs mt without any host configuration.

Pitfalls

  • Works in dev, fails in production. An mt build needs the headers the dev server sends and your host may not. Check crossOriginIsolated.
  • Mixed builds. Mixing mt and st builds in one bundle fails with a streaming-compile error. Rebuild from clean after switching.
Type to search every guide page and section.
↑↓ navigate↵ openesc close