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 default | wasm in one Web Worker, main thread stays free | wasm in a worker, pthreads started from there: needs COOP/COEP; OPFS on by default |
useWorker: false | wasm on the main thread, synchronous calls | pthreads through SharedArrayBuffer on the main thread: needs COOP/COEP |
| You want | Pick |
|---|---|
| The quickest path to C++ in the browser | st, the defaults |
| Synchronous calls from the page | useWorker: false |
| Persistent storage in the browser (OPFS) | mt, with the default worker |
| CPU-bound parallelism (image, geo, crypto) | mt |
| Cloudflare Workers, Deno Deploy, Vercel Edge | st only, with no worker |
| React Native | always mt; no host configuration needed |
Turning on multithreading
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:
Without them SharedArrayBuffer is undefined and init fails quietly. Check it from the console on the deployed page:
| Host | Where the headers go |
|---|---|
| Vite dev server and preview | sent by @crossbind/plugin-vite |
| Webpack and Rspack dev servers | sent by @crossbind/plugin-webpack |
| Vercel | the headers array in vercel.json |
| Netlify, Cloudflare Pages | a _headers file |
| nginx | add_header Cross-Origin-Opener-Policy same-origin; and the COEP twin |
| Express or your own server | middleware that sets both on every response |
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:stonly, withm.FSin memory. - React Native builds are always
mt, with the device's own threads: no headers are needed, anduseWorkerdoes not apply. - Node.js runs
mtwithout any host configuration.
Pitfalls
- Works in dev, fails in production. An
mtbuild needs the headers the dev server sends and your host may not. CheckcrossOriginIsolated. - Mixed builds. Mixing
mtandstbuilds in one bundle fails with a streaming-compile error. Rebuild from clean after switching.