ADR 0013: WebAssembly stand-ins for native toolchain packages
-
Status: accepted (2026-10-21); extended to rolldown and lightningcss (2026-10-22) and Tailwind’s oxide (2026-10-22)
-
Context: Native addons and binaries are a v1 non-goal (CLAUDE.md §3). The golden template is a stock Vite + React project, and Vite depends on two native packages:
- esbuild: a Go binary, spawned as a child process.
- rollup: a Rust addon, loaded with
require('…/rollup.linux-x64-gnu.node').
npm installs the platform build of each, and neither can run in ClientVM. Both projects also publish official WebAssembly builds with the same interface:
esbuild-wasm(the same CLI and service protocol) and@rollup/wasm-node(the same binding exports). Asking agents to addoverridesto every project would make ClientVM projects differ from normal ones. -
Decision:
- When a stock project reaches for one of these native parts, ClientVM uses the matching
WebAssembly build of the same version instead. It fetches that build from the registry on
first use, checks it against the registry’s published integrity, and unpacks it into
/usr/local/lib/clientvm/standins/<name>@<version>. - esbuild: the default environment sets
ESBUILD_BINARY_PATHto/usr/local/lib/clientvm/bin/esbuild. esbuild’s install script and runtime both honor this variable. The file is a marker for theclientvm-esbuildruntime, which runs esbuild-wasm on the node runtime. It takes the version from--service=<version>, which esbuild’s JS API passes, or else from the nearestnode_modules/esbuild. - rollup: the CommonJS loader’s
.nodehandler asks the stand-in table before it fails withERR_DLOPEN_FAILED. A rollup binding gets@rollup/wasm-node’sdist/native.js.require()is synchronous, so this download uses synchronous XHR, which dedicated workers allow. - lightningcss (Vite 8’s CSS minifier): its
.nodebinding getslightningcss-wasm’swasm-node.cjs, the synchronous Node build with the same exports. - rolldown (Vite 7+): its loader falls back to
require('@rolldown/binding-wasm32-wasi')when the platform binding fails. That package is not among rolldown’s dependencies, so the CommonJS resolver, when it cannot find it from inside rolldown, resolves it to the stand-in. It is napi-rs’s WASI build: it needsnode:wasi(ClientVM implements preview1 over the instance’sfs) andworker_threadscarrying a sharedWebAssembly.Memory(rolldown’s async work runs on a pool of four threads). - Tailwind CSS 4’s oxide (
@tailwindcss/oxide, the class scanner): the same fallback, to@tailwindcss/oxide-wasm32-wasi. That package declares"cpu": ["wasm32"], so its npm install passes--force(into an empty staging directory, where it skips only that check). Its WASI build has an upstream bug: a rescan reports no changed files, on real Node too, so the dev server never picked up new classes. The install adds a smallclientvm-scanner.cjsas the package’smain: eachscan()uses a fresh Scanner and returns every candidate seen so far, as the native build does. - WASI thread pools spawn worker threads and then block on shared memory until they start.
A
worker_threads.Workertherefore makes its own MessageChannel, postsiniton it at once, and hands the child’s end to the kernel with the spawn request (threadPort), so a thread starts without waiting for its parent’s event loop. - Stand-ins with dependencies (rolldown’s needs
@napi-rs/wasm-runtimeand@emnapi/*; lightningcss-wasm needsnapi-wasm) are installed by running npm in the instance, intostandins/<name>@<version>/node_modules.@emnapi/*ship only ES modules but are loaded withrequire(), which ClientVM cannot do for ES modules, so the install rewrites the ES modules of"type": "module"packages in that tree as CommonJS (module/esm-to-cjs.ts, static modules only). - A WASI binding and
@napi-rs/wasm-runtimemust share one@emnapi/*. rolldown 1.2.15’s binding pins emnapi 2.0.0-alpha.5, outside wasm-runtime’s peer range, so npm nests it under the binding and hoists 1.x; mixed, loading fails (this.bridge.setLastError is not a function, on Node too). The install removes the binding’s nested@emnapi/*copies that are also hoisted, and a lookup repairs stand-ins installed before that (2026-11-02). - The table is deliberately short: only packages whose authors publish a drop-in WebAssembly
build. Other native addons still fail with
ERR_DLOPEN_FAILED.
- When a stock project reaches for one of these native parts, ClientVM uses the matching
WebAssembly build of the same version instead. It fetches that build from the registry on
first use, checks it against the registry’s published integrity, and unpacks it into
-
Consequences:
- A stock Vite 6 project installs, serves with HMR, and builds without changes. The first use of each stand-in costs a download: about 4 MB for esbuild-wasm and 1.5 MB for @rollup/wasm-node.
- npm still downloads the unused native optional dependencies, such as
@esbuild/linux-x64(about 10 MB), becauseprocess.platform/archreport linux/x64. envshowsESBUILD_BINARY_PATH. A project that sets its own value takes precedence.- The integrity of a stand-in comes from the registry’s own metadata, not from a value pinned
in ClientVM as npm’s is (ADR 0012). It is as trustworthy as the registry over TLS, which is
the same trust
npm installalready places in it. - A stock Vite 8 project (rolldown, lightningcss) installs, serves with HMR and builds without changes. The first use costs about 11 MB for rolldown’s WebAssembly build and 16 MB for lightningcss’s, plus an npm run; the WebAssembly memory for rolldown is a 1 GiB (initial) shared reservation, as on Node.
- Tailwind 4 with Vite 8 works unchanged (dev server picking up new classes,
vite build). Each rescan is a full scan of the sources, which is fast for agent-sized projects. - These npm-installed stand-ins need the registry at first use through npm, not a single fetch. A transient npm failure (network, timeout, 5xx) is retried twice, after 1 s and 3 s, with a warning; after that, or offline, npm’s error is followed by the native-binding error.