It was not the bundler, whose entire contribution was 22.5 MB. It was three other things, and they are not even measured in the same units: a filesystem holding 929 MB of node_modules as bytes, a persistence layer writing 4.7 GB to store 53 MB, and an editor spending 621 MB parsing one set of type definitions twice.

This post is the autopsy rather than a list of tips, because the useful part is which assumptions turned out to be wrong.

Where the 3 GB actually was​

The tab had already come down to 3.09 GB when it was measured properly. The split, on one machine running one project:

Inside that 1.87 GB dev server, the in-process esbuild Go heap was 22.5 MB.

That single measurement killed the plan everyone arrives with. Isolating esbuild, tearing it down between builds, moving it to its own worker: all of it would have saved approximately nothing, and all of it would have been weeks. The Go heap is 1.2% of the process it lives in.

Meanwhile the filesystem worker, which holds nothing but bytes, was the second largest thing in the tab and the largest one we could do anything about. The 1.87 GB above it is Nuxt's and Vite's heap, allocated by their code for their reasons. The 580 MB is ours. That is the finding.

Finding one: node_modules is the largest addressable object in the program​

Every file in this runtime lives in a Rust virtual filesystem compiled to Wasm, which means every byte of node_modules is sitting in one linear memory. A mid-sized project's dependency tree is a few hundred megabytes of text that is read once at startup and then almost never touched again.

Text compresses. So cold file contents are zlib-compressed in place, behind a gate of two constants:

const MIN_COMPRESS_BYTES: usize = 4096;
const MIN_COMPRESS_RATIO: f64 = 0.95;

Below 4096 bytes, do not bother: zlib's framing and the bookkeeping cost more than the win, and node_modules is full of eleven byte index.js files. Above a 0.95 ratio, do not bother either: the file is already compressed, storing it packed saves nothing measurable and every future read pays an inflate.

Measured on Nuxt, in Chrome: VFS content went from 929.0 MB to 273.6 MB, a 29% ratio and 655 MB saved, and the whole Chrome tab dropped from 2.9 GB to 2.1 GB.

It is on by default in the SDK, and only an explicit compress: false turns it off. The Rust struct itself defaults to compression off, which looks like a contradiction and is deliberate: it keeps the flag A/B testable from a benchmark without touching the shipped default.

The gate is four lines of arithmetic, and it is the reason the number above is 655 MB rather than something embarrassing. Here it is running against three kinds of file, using the same deflate from the same Rust crate the filesystem compresses with:

The third block is the one to read twice. A megabyte of random bytes deflates to 1,048,752 bytes, which is 176 bytes larger than what went in, and the gate correctly stores it raw. That is the whole case for the ratio test: without it, every .tgz, .png and .wasm in a dependency tree would be stored slightly bigger than it arrived and would pay an inflate on every read for the privilege.

One honest note about that demo, because it matters. The virtual filesystem does not tell guest code what it decided about a file, so the script recomputes the gate in front of you rather than reading its verdict. It is the same test on the same bytes with the same compressor, and it is not instrumentation.

The edit to make is SIZE. Drop it to 2048 and every sample is stored raw, including the one that deflates to a thousandth of its size, because it failed the size test and the size test is the one the VFS checks first. The script still prints a ratio for each, since it computes both tests rather than short-circuiting the way the Rust does, and seeing beats 0.95 true sit next to the VFS keeps it RAW is the clearest possible statement of what the first constant is for.

Finding two: persisting 53 MB cost 4.7 GB of writes​

A session survives a page reload by mirroring the filesystem into OPFS, the browser's origin-private file storage. The steady state is small: about 53 MB for a real project. Getting there was costing 4.7 GB of writes.

Three offenders, and none of them is a large file:

• npm's own cache temp directory. One _cacache/tmp/<uuid> cost 1,461 MB across 76 writes, and npm deletes it moments later. We were faithfully persisting a scratch directory so that it could be faithfully persisted again as it changed, and then removed.
• npm's debug log. _logs/*-debug-0.log cost 607 MB across 3,799 writes, because a log file is appended a line at a time and a mirror that does not understand appends rewrites the file each time.
• The manifest. The index of which paths exist was rewritten 12,847 times, totalling roughly 2.1 GB, to describe about 3,000 paths. Every write touched the whole thing.

Total after fixing all three: about 144 MB, for the same 53 MB of durable state.

The general shape here is worth naming, because it is not specific to browsers. Write amplification is invisible in every profiler you would normally reach for: memory looked fine, the filesystem looked fine, and the only symptom was that installs felt slower than the network could explain. You have to go and count the writes.

Finding three: the IDE was paying twice for one thing​

Monaco runs a separate full language service for each of its typescript and javascript modes. Each one parses the whole dependency .d.ts payload into roughly 310 MB, so a project with both kinds of file naively pays about 621 MB, measured, for two services doing identical work over identical inputs.

Mapping .js files to the typescript mode halves it. TypeScript's language service handles JavaScript perfectly well; it is the same compiler.

That is a configuration change, and it is in this post rather than a footnote because 310 MB is larger than most of the things people spend a week optimising, and it was found by reading a memory profile rather than by reasoning about the code.

What is emphatically not the bottleneck​

Two things that look like they should be slow, measured so nobody has to guess:

Filesystem write throughput. Writing a 12,000 file tree, the first 1,000 files cost 6.9 microseconds each and files 11,000 to 12,000 cost 3.6 microseconds each. The whole tree lands in about 44 milliseconds. Install time lives in the network, in tar extraction, in npm's own JavaScript, and in the OPFS mirror. It does not live in the virtual filesystem.

Registry metadata, sort of. A full install pulled 421 MB of packuments without an .npmrc, and 108 MB with one that restricts the fields requested. The registry gzips them about tenfold, so the wire cost is around 45 MB while the cost of holding and parsing them is the full 421 MB. That is a case where the network number and the memory number differ by an order of magnitude and only one of them is the problem.

There is one more measurement in this family, from shipping a prebuilt node_modules snapshot for a template. Cold origin, Chrome, Starlight: fetch 0.4s, restore 4.0s for 13,459 entries, dev server listening at 31.8s, and OPFS holding 112 MB instead of 246 MB. The asset is 111.4 MB raw and 26.0 MB gzipped, and its buffer is transferred rather than copied between workers. The interesting row is the restore: 4.0s in the browser against 0.1s headless, and the entire difference is the OPFS mirror. Again the storage layer, not the compute.

How it fails, which is not what you would expect​

A Node process that runs out of memory throws, prints a heap trace, and dies alone. Under a memory ceiling, a browser tab does not do that.

Running the tab in a container with a roughly 1.6 GB ceiling, the kernel SIGKILLs the renderer, with error code 9 and a cgroup failure count climbing. Not one worker: the whole tab. What the user sees is Chrome's crash page, not a frozen terminal and not an error in the console, and nothing in the runtime gets a chance to report anything.

That changes what the memory work is for. It is not about being tidy. Past the ceiling there is no graceful degradation available, because the process that would have degraded gracefully no longer exists.

What is honest to claim​

• Every number here is one machine, one browser, one project. Nuxt in Chrome, Starlight in Chrome. They are here to show the shape and the ordering of the costs, not to be benchmarks anyone should quote.
• You cannot reproduce these from inside the VM. process.memoryUsage() in a guest process returns fixed constants, so a script running in the sandbox cannot observe any of this. Every figure above comes from browser task manager and profiler measurements taken outside the runtime, which is also why the demo above measures the gate rather than the saving.
• Compression is a tradeoff and the ratio test is where it is made. A cold file that is read again pays an inflate. The 0.95 constant is a judgement, arrived at by measurement on one kind of workload, and a workload that reads its dependency tree constantly would want a different one.
• The OPFS numbers are about write volume, not about durability. Nothing here changes what survives a reload; it changes how many bytes it costs to keep it surviving.
• The Monaco figure is a Monaco figure. It is what two language services cost on one dependency payload, and it will move with the size of your .d.ts files.

The general version​

Three findings, and the thing they have in common is that none of them is about the code that was doing the work.

The bundler, the compiler, the dev server: those are what a profile looks like it should be about, and between them they were a rounding error against a filesystem full of text, a mirror writing gigabytes to store megabytes, and an editor holding two copies of the same parse.

In a browser tab, the interesting resources are the ones the platform makes you implement yourself. On a laptop, node_modules costs page cache that the kernel reclaims when it feels like it, and nobody counts it. Here it is a Rust HashMap you allocated, and it is on your bill. Persistence is a mirror you wrote rather than a filesystem the OS provides, so its write amplification is yours too. The platform is not doing you any invisible favours, which is inconvenient and, occasionally, clarifying: everything that costs something is something you can see.

More on the architecture in the how-it-works docs, and the post that explains why the filesystem lives in a Rust module at all is the one about the single blocking primitive.

Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no per-seat fee, self-host every asset. The code is on GitHub and the Studio runs in your browser.

So bun index.ts in a page is not Bun. It is Bun's API, implemented on top of the Node runtime these posts keep describing, and the honest version of that sentence is the whole subject here. A compatibility shim is only useful if you can tell, from inside it, which parts are real. Most of this post is about the parts that are not, and how they say so.

What is actually on PATH​

bun and bunx are ordinary coreutils, installed eagerly rather than lazily unpacked on first use, because unlike the real vendored npm, yarn and pnpm CLIs there is no tarball to unpack: they are purpose-built shims running on the same runtime your code runs on. bun run, bun test, bun build and the Bun global are all implemented here. bun install is not: it delegates to the real npm CLI, because reimplementing a resolver would be a worse lie than borrowing one. The TypeScript in index.ts is handled by the synchronous stripper that every other .ts file in the runtime goes through, not by Bun's transpiler.

Most of the surface is uninteresting in the good way. Bun.escapeHTML, Bun.deepEquals, Bun.stringWidth, Bun.semver, Bun.Glob, Bun.which, Bun.gzipSync are small pure functions with a specification and a test. There are two places where that stopped being true.

The one module that could not be shimmed​

Every other Bun API had something underneath it to delegate to. bun:sqlite did not: there is no SQLite in the Node runtime to borrow, and the API is synchronous by design. db.query(sql).all() returns rows, not a promise. There is nowhere to await an engine booting.

The engine is the official @sqlite.org/sqlite-wasm build, the same C source SQLite's own test suite covers, compiled by the SQLite authors. It is committed to the repository at 844 KiB alongside a manifest recording the upstream version and SHA-256, rather than fetched at build time, because both spike tiers need it on a bare checkout and a spike that skips when its artifact is missing looks green while proving nothing. The refresh script validates the binary it pulls: magic bytes, required exports, that its imports are a subset of what the loader supplies, and that its declared memory minimum still fits. An upstream build that changed its ABI fails the refresh rather than failing at somebody's first query.

The Emscripten glue is not used. The package ships 578 KB of it, and it is useless here twice over: it is async-init, meaning it fetches and calls WebAssembly.instantiate, and it routes file I/O through MEMFS or NODEFS, neither of which exists in this environment. So the loader supplies the module's 36 imports itself and instantiates with a bare new WebAssembly.Module(bytes) followed by new WebAssembly.Instance(...). Both are synchronous, which is illegal on a main thread and legal on a worker, which is where all guest code runs. It is the same trick the llhttp binding uses.

The memory is created on this side, 128 pages initial and 2 GiB maximum, unshared, because the build imports memory rather than exporting it. Growth goes through emscripten_resize_heap, and every cached typed-array view has to be re-derived whenever memory.buffer identity changes, since growth detaches the old ArrayBuffer. That is the sort of detail the glue would normally handle and the reason people use the glue.

And then the part that makes it worth doing. A sqlite3_vfs is registered whose xOpen, xRead, xWrite, xTruncate, xFileSize, xDelete, xAccess and xFullPathname call the runtime's own fs, which is the SharedArrayBuffer syscall bridge. So a .sqlite file is an ordinary file in the virtual filesystem. It shows up in the file tree, it outlives the process that made it, and the next process reads it. The reads and writes take explicit offsets, which is exactly the pread and pwrite a SQLite VFS wants.

SQLite needs real C function pointers for those callbacks, and WebAssembly.Table.prototype.set will not accept a plain JavaScript function. So each callback is wrapped in a hand-assembled 40-byte Wasm module that imports the function and re-exports it, and the export goes into __indirect_function_table. Forty bytes of hand-written Wasm per callback is either the ugliest thing in this repository or the most satisfying, depending on the day.

Two semantics are implemented rather than approximated, because approximating them corrupts data. safeIntegers governs reads: true returns exact BigInts, false returns Numbers, lossily above 2^53, which is Bun's documented behaviour and the reason the toggle has to exist. Binding is exact either way, so a bigint argument goes in through sqlite3_bind_int64 and one outside int64 range throws a RangeError naming the value instead of wrapping it. And db.transaction() nests through SAVEPOINT, with nesting decided by sqlite3_get_autocommit rather than a counter we keep, so a hand-written BEGIN in the middle of things does not desync it.

Two sentences, and the difference between them is load-bearing​

Roughly thirty Bun APIs in this shim do nothing but throw. That file is the best writing in the repository, and its argument is this: there are two reasons an API can fail, and telling someone the wrong one wastes their afternoon.

"<api> is not supported in Vivari (browser sandbox): <reason>"
"<api> is not implemented in the Vivari shim: <reason>"

The first means the capability does not exist in a page. A raw socket, dlopen(3), an OS keychain, engine internals. No amount of shim work changes it, and the code has to run somewhere else. The second means it could work here and nobody has written it: a gap, not a limit.

Conflating them is its own kind of dishonesty. "Not supported" tells you to stop and redesign. "Not implemented" tells you to file an issue or send a patch. Where an API is half of each, and a TCP client is exactly that, since it can reach another in-VM process forever but can never reach the internet, the message says both, in that order.

There is a second rule, and it is the one that keeps projects alive. The symbol is always exported. The throw is always on the call. So import { dlopen } from "bun:ffi" still loads, and a property read during some dependency's module-level feature detection still returns a function. A load-time throw is strictly worse: one unused import at the top of a transitive dependency takes down a project that never touches the API.

The catalogue covers Bun.listen, Bun.connect, Bun.udpSocket, Bun.RedisClient, Bun.sql, Bun.postgres, Bun.Terminal, Bun.WebView, Bun.mmap, Bun.peek, Bun.secrets, Bun.dlopen, the zstd helpers, Bun.generateHeapSnapshot, Bun.openInEditor and the whole of bun:ffi. The native addon half of the same file is not Bun-specific at all: require("bcrypt") from plain Node code hits precisely the same wall, and one catalogue of "impossible in a browser, and here is what to do instead" beats two that drift apart.

All of that is checkable rather than something to take my word for. The script below is running Bun's API in this page: a block of one-line results, a visible pause while argon2id does its 64 MiB of work, real SQLite reporting its own version number and three rows, and then a refusal.

The block at the bottom is the part to play with. Uncomment any line and run it again, and you get the exact sentence that API throws. The two message shapes are visibly different, which is the entire point of there being two.

The ones that are real, and one that was not​

Bun.password is genuine argon2id at Bun's own documented cost parameters: 64 MiB of memory, two passes, one lane. Measured in Wasm under Node on one machine, hashing takes about 97ms and verifying takes about the same, and in a browser tab it is somewhat slower again, which is the pause you just sat through in the demo. That number is supposed to be large. A password hash that returns instantly is a password hash that is not doing its job, and the most common way to get compatibility wrong here would have been to substitute something cheaper and call it argon2id.

Bun.hash was wrong and is now pinned. It started as a bespoke multiply-xor hash that agreed with real Bun on nothing at all, which is a perfectly good hash function and a completely useless compatibility shim, since the entire value of Bun.hash is that two systems compute the same number. It is now wyhash final v3, checked against published vectors.

Bun.sleepSync used to spin. Right duration, one core pinned at 100% for it. It now parks on Atomics.wait, with the spin left in as a documented fallback for a browser main thread, where parking is illegal.

bun:test is stricter than real Bun in one place. expect(settledPromise).rejects.toThrow() returns undefined in real Bun; this runner always returns a real promise, and drains outstanding async assertions after each test body. A snapshot file written here has been read and passed by a real bun test, which is the strongest compatibility evidence in the shim.

What Bun.build is not​

It is not esbuild. There is no tree shaking and no minifier, and minify, splitting, sourcemap, bytecode and --compile throw rather than silently producing something that does not match the option you asked for. It bundles, and that is the extent of the claim.

Streaming is the other place to be careful. A ReadableStream response body is buffered in full: measured at 25 MB into an unread socket with writableLength never leaving zero. Backpressure never engages. It is left honestly buffered rather than half-implemented, which is the right call and is also a real limit if you were planning to stream a large file out of Bun.serve.

What is honest to claim​

• This is not Bun and will never be byte-for-byte Bun. It is Bun's API on the Node runtime, so anything that depends on JavaScriptCore semantics, Bun's transpiler output, or Bun's process startup is out of scope by construction.
• bun:sqlite has three limits, each a sandbox fact rather than a shortcut. xSync is a no-op because the runtime's fsync is, so the rollback journal is still written and replayed and a crash mid-transaction recovers, but power loss is not survivable the way real SQLite promises. There is no file locking, so two processes writing one database can corrupt it, and this matches what upstream ships: the official build's default VFS is literally unix-none, SQLite's lock-free one. And journal_mode = WAL needs shared memory across processes, so it is declined with a one-time warning and SQLite stays in delete mode, which is SQLite's own documented behaviour when a VFS cannot do WAL. ORMs that set WAL opportunistically therefore keep working.
• The argon2id timing is measured in Wasm under Node on one machine, and a tab is slower again. Treat it as an order of magnitude, not a benchmark.
• The refusal list is a snapshot. Several entries are "not implemented" rather than "not supported", which is a promise that they could move.

The general version​

The temptation in a compatibility layer is to make the surface as wide as possible, because the surface is what a table on a marketing page measures. Every API you stub to return a plausible empty value makes that table better and makes the layer worse, because the failure moves from your code to the user's, six frames deep, with a message that names neither of you.

The two sentences at the top of that refusal file are worth more than any of the APIs underneath them. A shim's honesty is a feature with a spec: name the API, say which of the two kinds of failure this is, and say what to do instead. It costs one string per function and it is the difference between a limitation and a bug report.

More on the Bun surface in the Bun docs, and the previous post covers why every import in this runtime is rewritten to CommonJS at load time.

Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no per-seat fee, self-host every asset. The code is on GitHub and the Studio runs in your browser.

Node can refuse, because import() is always sitting there as an escape hatch. Tell the user to await it and the problem is theirs.

In a browser worker there is no escape hatch. require() is synchronous all the way down because the filesystem under it is, and a project's entry point is required by a loader that cannot return a promise to anyone. Every import becomes CommonJS at load time or the program does not start. Refusing was not on the menu.

What the rewrite actually is​

There is no bundler here and no compile step. Each module is rewritten as it is read, by es-module-lexer, into the same synchronous CommonJS everything else in the runtime lives in. import becomes a require, export becomes a property on an exports object, import.meta becomes a small object built from the filename, and dynamic import() becomes a helper that returns an already resolved promise.

Every generated identifier is namespaced: __oc_require, __oc_import, __oc_exports, __oc_module. That is not tidiness. User code is allowed to declare its own require and its own module, and a great deal of published code does.

The interop helpers are all emitted on one leading line, which looks like somebody minifying for no reason. It is so that line numbers in the rewritten file still match the file you have open, which is what makes breakpoints land on the right line.

That is the easy part. What follows is four years of other people's module graphs.

Live bindings, and the half of them that is not implemented​

An ESM export is a binding, not a value. If a module exports let count and increments it later, an importer that already read it sees the new number. Real ESM gets that by being lazy at both ends: the exporter exposes a binding rather than a copy, and the importer reads it at the point of use rather than at the point of import.

This loader is lazy at one end and eager at the other, and the asymmetry is worth stating before anything else in this section, because it is the one place where the rewrite is knowingly not ESM.

The export side is getters. A module's own exports are exposed as accessors on the exports object, which is how esbuild and rollup model the same thing.

The import side is a snapshot. A used import { X } from './m' compiles to const X = __oc_m['X']: one read, at the top of the importing module, and that value is what the rest of the body sees. Increment X in the source module afterwards and the importer will not notice.

Most code never sees the difference, because most imported names are functions, and a function is the same object before and after. It shows up on a mutable let, and it shows up hard in a cycle, which is the rest of this section.

The load-bearing detail on the export side is not the getters. It is that they are emitted before the import requires.

Consider a cycle, which npm is full of. Module A imports B, B imports A back. B runs while A's body is still on the stack. If A emitted its export getters after its own imports, B reads undefined from A, because A has not got to that line yet. yargs is the canonical case in the wild: command.js imports isYargsInstance from yargs-factory.js, which imports command.js right back. Put the getters first and an exported function, which is hoisted anyway, is reachable through its getter before A's body has run at all.

The failure mode when this is wrong is what makes it expensive. You do not get "circular import detected". You get Astro's middleware reporting Function.prototype.apply was called on undefined, four frames from anything you wrote.

A second, subtler version of the same bug: a barrel file that imports a name and then re-exports it. Astro's render/index.js does import { Fragment } from './common.js' and then export { Fragment }. When common.js is mid-cycle, the eager const Fragment = common.Fragment snapshot hits a const that is still in its temporal dead zone, and you get Cannot access 'Fragment' before initialization. So a re-export is compiled to a lazy live binding to the source module rather than a read of the snapshot, which defers the read until the cycle has settled, exactly as export { X } from 'm' already did.

And the getters have to close over their own key. export * copies names in a loop, and a getter that closes over the shared loop variable resolves every name to the last key of the object. Vue's index.mjs re-exports everything, so createApp quietly became withScopeId, and Nuxt's server rendering then read .config off the wrong object. Per-iteration closure, one line, found the expensive way.

The fallback that buys back the other half​

That leaves the general case. A cycle whose imported name is a const, a class or a singleton has no barrel shape to exploit: the eager const X = __oc_m['X'] simply runs too early and throws Cannot access 'X' before initialization. Astro's runtime is full of them, apiContextRoutesSymbol, AstroConfigSchema, globalContentLayer, telemetry.

So there is a second compiler. When a module's eager attempt throws a ReferenceError whose message matches "before initialization" or "is not defined", the loader recompiles that one module with every import bound as a getter on an __oc_live object, and runs the whole body inside with (__oc_live) { ... }. A bare reference to an imported name then resolves lazily through the getter, at use, which is what real ESM does, while a local declaration that shadows the name still wins natively. That is what makes it scope-correct without rewriting a single reference, and rewriting references correctly is the part nobody wants to hand-roll.

Two reasons it is a fallback rather than the default. with deoptimises the whole body and requires sloppy mode, so a normal module should not pay for it. And it is safe to re-run only because the eager attempt threw in the prelude, before the body ran: the retry re-defines configurable export getters and re-runs already cached requires, so there are no double side effects.

Here is a module graph doing all of this, written into the virtual filesystem by the script itself and then imported. The line to look at is the first reporter: line, which prints count = 0 from inside the cycle while counter.mjs is still evaluating.

The last reporter: line is the whole section, and it is worth separating from the line under it. That third reporter: line is reporter.mjs printing its own bare named import, count, after two bump() calls, and it says 2. That looks like a live binding and is not one. It is the fallback: reporter.mjs reads count while counter.mjs's let count is still in its temporal dead zone, that throws, and the recompile is what made the read lazy.

The line below it, read from the namespace, also says 2 and proves nothing of the sort. That one is counter.count, a property access on the namespace object, which goes through the export getter every time it is evaluated. It is live with a cycle and without one, because the export side was never the problem.

Take the cycle away and the two lines stop agreeing. A plain non-cyclic module that does import { count, bump }, calls bump() twice and then logs count, prints 0 here and 2 under Node, because nothing threw, so nothing was recompiled. Read the same value off a namespace instead and you get 2 either way. Nothing warns you which of the two you wrote. That is the sharpest edge in this loader and it is the reason the honest list at the end of this post has the bullet it has.

Every module body in the demo is a string you can edit. The other instructive change is to delete the __esModule line from legacy.cjs and run it again, for the reason in the next section.

__esModule is not proof of a default export​

When you import x from a CommonJS module, what should x be? Node's answer is simple and total: module.exports, always. Babel's answer, which the entire transpiled ecosystem is built on, is that a module carrying the __esModule flag was originally ESM, so x should be its .default.

Both are defensible. The trouble is that tsc --module commonjs stamps __esModule on every file it emits, including the ones that only ever assign named exports. The flag means "transpiled", and the unwrap needs "has a default".

@embroider/core is one of those files: flag set, no default key. So import core from '@embroider/core' handed @embroider/vite undefined, and Ember's config load died at const { cleanUrl } = core. The fix is to require the key to exist as well as the flag, which keeps the Babel unwrap that real export default code depends on and falls back to Node's answer otherwise.

Now the honest part, and it is in the source as a signed confession rather than something I am volunteering. The dynamic import() helper deliberately does not use that narrower test. It still treats __esModule as proof of an ESM namespace, so (await import('<tsc-emitted-cjs>')).default is undefined here where Node gives you module.exports.

That is not laziness. Narrowing it the same way would break the other direction: our own transpiled ESM sets __esModule too, and a module with no export default would then get a synthesised ns.default = m that Node never gives it. Telling those two cases apart needs a marker that __esModule cannot carry. It is a known divergence, recorded rather than papered over, and it is the one place in the loader where two correct behaviours cannot both be had.

There is a related constraint pulling the other way. Dynamic import() has to resolve to a module namespace, not the raw require() value. Returning the bare exports left a CommonJS default import with no default key, which almost nothing noticed because real code mostly reads it through the static path. Vite's server-side module runner does notice: it asserts 'default' in mod for externalised CommonJS dependencies, and threw Named export 'default' not found. The requested module 'cssesc' is a CommonJS module on Astro.

Top-level await, and a compile error that lies​

Top-level await is the case Node declines outright, and it is not optional here: Vite's own binary starts with await import('node:inspector').

The wrapper each module is compiled into is a plain, non-async function, so new Function rejects the parse. The fix is to recompile the ESM body as an AsyncFunction, which makes the module evaluate to a promise that gets threaded through the entry point so the top-level body can await while the loop pumps.

Deciding when to do that is where it got interesting, because the parser will not tell you. At the top level of a non-async function, await x parses await as an identifier, so the error names the next token. You do not get "await is only valid in async functions". SvelteKit's core/sync/ts.js does ts = (await import('ts')).default, which after the import rewrite is await __oc_import('ts'), and the parser's verdict is SyntaxError: Unexpected identifier '__oc_import'.

Sniffing that message reliably is hopeless, so the loader does not try. Any compile failure on an ESM file is retried as an AsyncFunction. Real top-level await then compiles; a genuine syntax error fails again and is reported with the filename appended. The retry is on the error path only, so the happy path pays nothing.

The limit, stated plainly: only the entry module can block on top-level await. A dependency deep in the graph that uses it is still not supported, and that is why PGlite ships in the templates as its CommonJS build rather than its ESM one. Choosing CJS there avoids the problem instead of discovering it.

It is a lexer, which is fast and occasionally wrong​

es-module-lexer does not build an AST. It skims for the constructs it cares about, which is why this is affordable to do on every module of every install rather than once in a build step.

The cost is that skimming has to be exactly right about where strings, template literals and comments end. A coarse template skip that ignores ${} interpolation desyncs on modern bundled code: a regex inside an interpolation in @vitest/pretty-format was misread as a string, which swallowed the matching brace and lost every top-level export after it. The module then compiled with no exports and the importer got an empty object.

So the skimmer descends into interpolations properly. It is still a skimmer, and that is the trade being made: a parse of every file would be correct and would cost more than the rest of module loading put together.

The TypeScript in front of it​

Node's loader is not the only thing that has to be synchronous. A .ts file has to become JavaScript before the ESM rewrite sees it, with no tsc, no esbuild, and no await, which means a dependency-free token rewriter whose output has to parse.

The hard problem in a type stripper is <. Deciding whether it opens a generic or is a less-than comparison needs the previous token: an identifier, a closing parenthesis or a closing angle bracket means a generic at a declaration or call site. A generic arrow function is a separate case, because it begins an expression rather than a declaration.

Three of its bugs made it into a release, and their symptoms are a nice ladder. The type skipper counted braces only at depth zero, so Array<{ detail: string }> left }>; behind as live code, which at least fails loudly at load. as and satisfies were treated as cast keywords after any token, so Bun.semver.satisfies(...) was eaten as a type assertion: the call vanished, the importer got undefined, and the process exited zero. A stripper bug that throws is a bug. A stripper bug that succeeds is a support ticket six months later.

What is honest to claim​

• This is a rewrite, not an ESM implementation. There is no module map, no linking phase, no import.meta.resolve against a real registry of module records. The semantics that survive are the ones that can be modelled in CommonJS plus getters, which turns out to be most of them, and it is not all of them.
• Named imports are eager snapshots on the default path. Import-side liveness exists, and it is a recompile that only fires when the eager read throws. So a module that imports a mutable let from a module with no cycle, and expects to see later writes to it, reads the value it saw at import time and is given no warning. Two smaller consequences of the fallback itself: assigning to an imported binding inside it is a silent no-op where real ESM throws, and an import used at top-level initialisation inside a cycle still cannot be satisfied, because the source genuinely is not ready.
• Top-level await works in the entry module only.
• (await import(x)).default differs from Node for a tsc-emitted CommonJS module, deliberately, for the reason above.
• The scanner can be wrong on pathological source. Every case found so far is fixed and the fix is tested, which is not the same as a proof.
• export * from a module that later mutates its own exports object is outside what getters copied at load time can model.

Every one of the bugs in this post came from running a real project rather than a test suite, which is a statement about coverage as much as about the bugs. Yargs, Vue, Astro, Ember, SvelteKit, Vitest and Vite each found something no fixture had.

The general version​

The interesting thing about this subsystem is that it exists because of a constraint one layer down. Nothing about ESM demanded a lexer and a getter protocol; the synchronous filesystem did, and the filesystem is synchronous because Node's require() is, and require() is synchronous because 2009.

Node gets to draw a line and say ERR_REQUIRE_ASYNC_MODULE. That line is a luxury of having somewhere else to send people. Take it away and you find out which parts of the module system are semantics and which parts were always just scheduling.

Mostly it is scheduling. The two exceptions, real top-level await in a dependency and the __esModule ambiguity, are documented above rather than hidden, because a loader that is quietly wrong about a module's shape is the worst possible thing to have underneath a package manager.

More on the runtime in the architecture docs, and the post that explains why any of this has to be synchronous is the one about the single blocking primitive.

Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no per-seat fee, self-host every asset. The code is on GitHub and the Studio runs in your browser.

A Web Worker has no inspector. There is no --inspect port to open, no inspector binding to require, no way to ask the engine to stop. So the first question here was not how to build a debug UI. It was where a pause could possibly come from.

The pause has to come from the program itself​

If the engine will not stop your code, your code has to stop itself. That means the source that runs is not the source you wrote.

acorn parses the guest's own file and weaves in probes: __vvdbg.line before each statement, __vvdbg.brk for a literal debugger;, __vvdbg.push and __vvdbg.pop around calls so there is a shadow call stack to report. Each lexical block also gets a __vv_ev eval closure, which is the unglamorous piece that makes Variables and evaluateOnCallFrame show the block you are actually standing in rather than the function's outermost scope.

Where this happens in the pipeline is the part that took thought. The instrumentation runs after the TypeScript and JSX strip, so acorn is looking at plain ES rather than syntax it does not know, and before the ESM to CommonJS rewrite, so line numbers still match the file the reader has open in the editor. One layer earlier and the parse fails on a type annotation. One layer later and every breakpoint lands on the wrong line.

There is a bailout, and it matters more than it looks. If acorn throws for any reason, the module self-heals to the original source and runs uninstrumented. You lose breakpoints in that one file. You do not lose the program.

The whole thing lives in a lazy import() chunk of roughly 195 KB, fetched only when a debug buffer is present. A normal run never parses a byte of it.

The second SharedArrayBuffer​

Everything else in the runtime rides one 1 MiB SharedArrayBuffer per process: write a request, Atomics.wait, get notified, read the response. The debugger cannot use it, and the reason is a nice one.

A process parked at a breakpoint is not sitting in the syscall loop. It is parked in the middle of a __vvdbg.line probe, halfway down the user's own call stack. The syscall buffer is a channel for a client that is asking questions. A paused process is answering them.

So a debug target gets a second, independent buffer, allocated only when VV_DEBUG is set:

[ control: Int32 STATE, Int32 LEN ][ data region: JSON CDP command bytes ]

STATE values: DBG_STATE_EMPTY = 0, DBG_STATE_CMD = 1
LEN:          byte length of the command JSON

The paused worker blocks on Atomics.wait(STATE, EMPTY). The kernel writes a CDP command into the data region, stores DBG_STATE_CMD, and notifies. The worker wakes up inside the probe, with the user's stack still intact above it, runs the command, and parks again. stepOver, getProperties, evaluateOnCallFrame, all of it happens on a thread that is technically in the middle of executing line 41.

That gives two transports for one protocol, and the split is by state rather than by message type. A running process receives commands by postMessage, because it is still turning its event loop and can pick them up. A paused process receives them through the buffer, because it is not turning anything. There is also a --inspect-brk-style start gate, since a twelve line script would otherwise be finished before the frontend finished attaching.

Why Chrome DevTools Protocol, when nothing here is Chrome​

Speaking CDP to a runtime with no inspector looks like cargo cult. It was the best decision in this subsystem, and we only found out later.

The alternative was a bespoke debug API, which would have been smaller and would have fit the shape of what actually exists here. What CDP bought instead was a contract that already had two consumers: the studio's debug panel drives Monaco gutter breakpoints, the paused-line highlight, and a VS Code style Call Stack, Variables and Watch tree, all in the vocabulary of Debugger.scriptParsed, Debugger.paused and Runtime.getProperties. None of that had to be invented.

Then came Python.

The second backend, and the file that did not change​

.py files now get the same pause, step, inspect and evaluate over the same protocol and the same buffer. The studio is unchanged. It speaks CDP, it keeps breakpoints per virtual filesystem path, and it never had a reason to know what language is on the other end of the socket that is not a socket.

Two things differ from the Node backend, and both differ in the same direction: CPython already has what the JavaScript side had to build.

No instrumentation. CPython's frames are real. There is no acorn, no probe weaving, no shadow call stack, no line number preservation problem. What is left is the protocol and the transport, and those were reused as they stood.

PEP 669, not sys.settrace. This is the interesting half, because it is the difference between a debugger you can leave attached and one you have to remember to turn off. A settrace hook is called on every line of every function and has no way to say "stop calling me about this one". Measured on this build, on one machine, with a 300,000 iteration loop:

A debugger that makes the program ten times slower is not observing the program; it is changing it. PEP 669 landed in 3.12 and this interpreter is 3.14, so the callback can return sys.monitoring.DISABLE, which permanently retires that bytecode location. A line that is not a breakpoint is asked about exactly once and then costs nothing for the rest of the run. The 83ms row is a breakpoint on the hot line itself, which is a line you were about to stop on anyway.

That table is the whole argument, and it is the kind of claim that is easy to make and boring to take on trust. The interpreter below is running in this page, and it measures all three for itself. Watch the middle number, and then watch the two counts underneath it:

The timings depend on your machine and on what else it is doing, and the ratio between them is the part that holds. The counts do not depend on anything: settrace is handed 600,006 line events and sys.monitoring is handed 10. That is the same loop, the same breakpoint table, and five orders of magnitude between how often the debugger was asked.

The edit worth making is at the bottom of the file. Put a line number from inside hot() into BREAKPOINTS and run it again: the third number climbs, because that one location stops answering DISABLE and CPython goes back to asking about it on every iteration. It does not climb all the way to the settrace figure, and the gap between the two is exactly what DISABLE is buying on every other line in the function.

There is a price for DISABLE, and stepping is where you pay it. Once a location has been retired it never fires again, so single stepping has to call restart_events() to un-retire everything it disabled. Code outside the user's project roots is dropped on its first line, which is what keeps a breakpoint anywhere in your file from tracing all of import pandas.

The hot path stays in Python: a set lookup per candidate line. JavaScript only gets involved once a pause has been decided, and then it runs the entire CDP conversation by calling back into the interpreter for frames, scopes, reprs and eval. JavaScript inside a Python call, calling Python again, is the same re-entrant shape as the blocking stdin syscall, which is either reassuring or alarming depending on your temperament.

Which backend attaches is decided, not guessed​

python and python3 used to be on the debug skip list. They now carry a debugLang: "python" label that travels with the buffer from the kernel worker through the process worker into the runtime, and exactly one of the two backends attaches.

Without the label the JavaScript backend does what it is supposed to do, which is the wrong thing: python is itself a Node program, so it would instrument our own four thousand line launcher shim and offer you breakpoints in it. That is a debugger correctly debugging a program nobody asked about.

A related bug took a while to find and is worth writing down because the symptom was silence. Running python main.py compiled the script under the name main.py, while breakpoints are keyed on absolute virtual filesystem paths. So nothing ever matched, no breakpoint ever bound, and the program simply ran to completion. A debugger that does not stop looks exactly like a debugger that is not attached.

Ctrl-C into an interpreter that is not in JavaScript​

Signals are the other half of interrupting a program, and CPython broke the model. The pending signal bitmask is only ever observed by JavaScript, either at a syscall park or on an event loop turn. A guest running CPython in Wasm is doing neither: the worker thread is inside the interpreter's eval loop and will not return to JavaScript until the Python code finishes. The kernel's only option was the one it takes for any guest with no handler, which is to kill it.

CPython's Emscripten build already solves its half by polling a byte of shared memory and raising KeyboardInterrupt at the next bytecode boundary. So SIGINT, and only SIGINT, is mirrored into the first byte of control[5], previously reserved padding in the syscall control block. Wasm is little-endian by specification, so that is byte 20 everywhere this runs. The interpreter clears the byte itself when it acts. Measured latency is about 5ms.

The handler is registered only while the interpreter is running user code, because registering it is what tells the kernel not to kill this process, and that is a promise you can only keep while there is an interpreter running to take the interrupt.

What is honest to claim​

The Node debugger is verified by a spike with 27 assertions covering instrumentation, breakpoint binding including conditional breakpoints, pause and step, scope and evaluateOnCallFrame including the temporal dead zone, a top-level debugger;, the real buffer channel, and an end-to-end worker_threads pause, evaluate and resume over that buffer. That is what it is tested to do.

Four limits, by name:

• Preview browser JavaScript cannot be debugged this way, and may never be. A page in the preview iframe runs on a main thread, where Atomics.wait is illegal. Pausing it needs a resumable transform, continuation passing or generators, over the guest's source. Nobody has written that.
• A REPL parked at its prompt still cannot be interrupted. Ctrl-C works while the interpreter is running your code. Idle, parked in the blocking stdin read, it keeps its old meaning, because interrupting a park needs the read itself to return EINTR and it does not do that yet.
• Instrumented code is not your code. Line numbers survive and the bailout keeps a parse failure from being fatal, but anything that reads its own source text, or measures its own throughput, is measuring the woven version.
• The timings are one machine, one build. They are here to show that the gap between 217ms and 23ms is a factor of roughly ten, not to be a benchmark anyone should quote.

The general version​

The Node half of this is a workaround. Instrumenting source to fake a capability the platform withholds is not elegant, and if a browser worker ever grows an inspector, most of instrument.js should be deleted that afternoon.

The part worth keeping is the protocol choice. Picking Chrome DevTools Protocol when there was no Chrome in the picture cost a little up front and paid for itself the day a second language arrived, because the expensive half of a debugger is the frontend, and the frontend never learned that Python existed. Two backends, one of which needs a parser and a shadow stack and one of which needs neither, meet at the same twenty CDP methods and the same three events.

Picking somebody else's interface when you have no obligation to is usually overengineering. It is occasionally the cheapest thing you will ever do.

More on the runtime in the architecture docs, and the previous post covers why every import pandas in a tab used to be the first one.

Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no per-seat fee, self-host every asset. The code is on GitHub and the Studio runs in your browser.

Run Python inside a browser tab, where every command is its own process with its own interpreter and a freshly unpacked copy of every package, and something uncomfortable follows. There is no second time. Every import pandas is the first one.

Whose work this is​

Pyodide compiled CPython to WebAssembly, including the C extension modules that make NumPy and pandas possible at all. That is theirs, and this post does not improve on it. Vivari runs Pyodide's build of CPython 3.14 unmodified.

What Vivari adds is the operating system around it: a filesystem that outlives a process, a process table, and the caches described below. The first half of this post uses a Pyodide API and says so. The second half is a CPython behaviour that Pyodide deliberately turns off, and turning it back on correctly turned out to be the interesting part.

The problem, measured​

Every python command in Vivari is a real process with its own worker, and therefore its own interpreter. That is what makes a crashing script harmless, and it has an obvious cost: python a.py && python b.py boots CPython twice.

On the vendored build, booting CPython costs 1843ms. That is not a slow import or a slow download. It is the interpreter initialising itself, producing the same bytes it produced the last time and will produce the next time.

Paying nearly two seconds before a one line script can print anything is the single worst thing about Python in this environment, and it is worth noticing that it is a pure waste rather than a tradeoff. Nothing about the result varies.

Saving the interpreter instead of rebuilding it​

Pyodide can serialise a just-booted interpreter's linear memory and start another interpreter from it. The API is _makeSnapshot on load and makeMemorySnapshot() afterwards, it is marked experimental, and it does the hard part. Vivari's contribution is narrower: making one process's snapshot usable by the next process.

Measured on the same build:

So the first command of a session boots the slow way and keeps the bytes, and every command after it spends about 250ms getting an interpreter instead of 1843ms. The REPL, pip, pytest, all of them.

Why the filesystem and not memory. The snapshot has to outlive the process that made it and be visible to a process that does not exist yet. Those processes share exactly one thing, which is the virtual filesystem. It goes in /var/cache, where the kernel already keeps transient caches and which the filesystem worker excludes from OPFS persistence.

That exclusion is deliberate rather than incidental. A snapshot is only valid for the interpreter build that made it, and it is 31 MB. Persisting it across page reloads would spend a real and permanent storage cost to save 1.6 seconds on one command per session. So a reload starts cold, on purpose.

Why it is safe to share between processes. Restoring a snapshot in a different JavaScript realm from the one that made it is the load-bearing assumption here, and it is tested rather than hoped: the test tier makes a snapshot in one worker thread and restores it in two others, then imports packages, writes files and raises a traceback in each. Two Web Workers are two realms in the same way.

Two guards, because a corrupt interpreter is a terrible failure mode. The snapshot bytes are written first and a small JSON sidecar second, which makes the sidecar a commit record: a half-written cache is one whose sidecar does not agree with it, and it is ignored rather than restored. Then a restored interpreter is asked to prove it is one:

__import__('json').dumps([__import__('sys').version_info[0], 1 + 1])

That costs about a millisecond, and it is deliberately not 2 + 2. Arithmetic would survive a restore that had destroyed the import system. This touches the frozen stdlib and string formatting, which is the machinery a bad restore takes out. It cannot prove that subtle corruption is absent. What it buys is that an obviously broken snapshot costs one cold boot rather than a baffling failure inside somebody's own program.

If anything at all goes wrong, the command boots the slow way and says nothing, because a cache that has to be explained is a cache with a bug. VV_PYTHON_SNAPSHOT=0 turns it off.

The bigger number underneath​

Removing interpreter start-up exposes the thing it was hiding, which is larger. On the same build:

• import pandas: 2.3s
• import matplotlib.pyplot: 1.9s
• import numpy: 0.5s

Almost none of that is the package doing anything. It is CPython compiling around a thousand .py files to bytecode, having compiled the same files to byte-identical bytecode a moment earlier in a different process.

CPython solved this decades ago. The reason its solution does not apply here is one line: Pyodide sets sys.dont_write_bytecode. Which is a perfectly reasonable default when every interpreter is thrown away, and exactly wrong once one of them can leave something behind.

Unsetting it is free. Measured on numpy, an import with bytecode writing enabled costs 423ms against 420ms with it disabled. So there is no compile step anywhere in what follows. There is only keeping what an import already produced.

Both of those are checkable rather than something to take my word for, so check them. The interpreter below is running in this page, and it prints its own version and the two settings this section is about:

It is the standard library only, which is the stable part of Python here. Run it once and you pay for fetching the interpreter and a cold boot. Run it a second time and you are watching the snapshot from the first half of this post do its job, because that is a new process with a new interpreter in it.

Where it goes wrong: .pyc files have opinions about time​

Turning the flag back on and copying the __pycache__ tree between processes does not work, and the reason is the good part of this post.

A .pyc file records the mtime and size of the source it was compiled from. On import, CPython compares that recorded mtime against the source file's current mtime, and if they differ it throws the cached bytecode away and recompiles. This is correct, it is why editing a file takes effect, and it is fatal here.

Pyodide's loadPackage unpacks the wheel afresh into each new interpreter. So the source files' mtimes are the time of the unpack, which is different on every single run. Every cached .pyc would be stale the moment it arrived, every time, and the cache would do nothing except cost disk.

PEP 552 has the answer, and has had it since Python 3.7. A .pyc can be hash-based instead of timestamp-based: it records a hash of the source rather than its mtime. That is precisely what a package installer writes, for precisely this reason, because an installer also cannot promise anything about the mtimes of the files it just wrote.

Converting a timestamp-based .pyc to a hash-based one is header surgery, not compilation. The marshalled code object, which is the whole expensive part, is byte-identical. Only the sixteen byte header changes. Harvesting the entire bytecode tree for numpy and pandas costs 115ms.

PEP 552 also defines two flavours of hash-based .pyc, checked and unchecked, and the choice here matters. A checked one re-reads and re-hashes the source on every import, which is most of the I/O this cache exists to avoid. Unchecked files are taken on trust.

The claim being made by choosing unchecked is that a wheel's files do not change while its version stays the same. That is not a shortcut invented here. It is the same claim pip makes, and the cache is keyed on package name and version so that the claim stays true.

Three details that were not obvious​

The bytecode does not land next to the source. sys.pycache_prefix puts it in a tree of its own. Otherwise __pycache__ directories appear inside the user's project, show up in the file explorer, and get mirrored back into the virtual filesystem as though the script had written them.

That setting has a trap in it worth writing down, because it fails silently. CPython builds the directory tree under the prefix by walking up from the .pyc's intended directory until it finds something that already exists. If that walk runs off the top without finding one, it starts creating directories relative to the current working directory instead, says nothing, and no bytecode is ever written where you are looking for it. The prefix's root has to exist before the first import.

Only installed packages are cached, never your own modules. The user's own code gets bytecode too, since it is the same interpreter setting, but theirs stays in the per-process prefix and dies with the process, keeping CPython's ordinary mtime checking. A released package's files do not change. Yours change constantly, and a file you just edited must never be at risk of running as a stale copy.

The cache is keyed on the interpreter's magic number as well as on package name and version, because bytecode from a different CPython is not bytecode.

Like the snapshot, this lives in the session's filesystem and goes when you reload, and VV_PYTHON_BYTECODE=0 turns it off.

What is honest to claim​

CPython 3.14, pip and the REPL are shipped as stable in Vivari. The scientific stack that this post uses for its measurements, NumPy, pandas, Matplotlib, SciPy and scikit-learn, is experimental, along with pytest and the notebook. The caching described here applies to every Python command either way, and it is not what decides those labels.

Two limits worth stating plainly:

• Both caches are per session. A page reload starts cold, by design, for the reason given above. Neither one is a persistent build cache and neither is trying to be.
• The interpreter snapshot rests on an experimental Pyodide API. If it cannot be made or restored, everything still works and simply costs 1843ms. That fallback is not decoration; it is the reason it was acceptable to build on an experimental API at all.

The numbers in this post are from the vendored build on one machine. They are here to show the shape of the problem, which is a factor of about seven on interpreter start-up once the read is counted, not to be a benchmark you should quote.

The general version​

Both halves of this came from the same question, asked twice: what is this program recomputing that it already computed?

The interpreter produces identical bytes on every boot. Compiling pandas produces identical bytecode on every run. Neither is a hard problem in principle, and in both cases the actual work was not making the cache fast but making it correct: a commit record so a half-written snapshot is never restored, a probe so a broken one is caught, hash-based .pyc files so a cached compile is never wrongly trusted, and a hard line at the boundary of the user's own code so an edit always wins.

That last one is the rule the whole thing hangs on. A cache that is occasionally wrong about your own source is worse than no cache, by a margin that no amount of saved seconds closes.

More on all of this in the Python docs, and the previous post covers how Flask, Django and FastAPI serve real requests with no socket underneath.

Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no per-seat fee, self-host every asset. The code is on GitHub and the Studio runs in your browser.

sock.bind((host, port))
sock.listen(backlog)

A browser tab does not have that. There is no TCP stack in a page, no file descriptor to bind, and no amount of WebAssembly changes it. So the interesting question is not whether you can run Flask's Python in a browser, because you can. It is what happens when someone types flask run.

What is Pyodide's, and what is not​

Worth being exact about this up front, because the rest of the post only makes sense once the line is drawn.

Pyodide compiled CPython to WebAssembly. That is their work, it is a large piece of engineering, and nothing here reimplements any of it. The interpreter running in Vivari is Pyodide's build of CPython 3.14, with its standard library and its C extension modules, unmodified. When this post says "the interpreter", it means theirs.

What Pyodide does not ship, because it cannot, is an operating system: a filesystem shared with other programs, a process table, a port registry, a socket. Vivari is the layer that supplies those. This post is about exactly one of them, and it is the one people ask about first.

A socket that accepts everything and carries nothing​

The obvious expectation is that import socket fails and the frameworks fail loudly with it. That is not what happens, and the real behaviour is the reason this needed designing rather than documenting.

There is a socket module, inherited from the POSIX layer underneath the WebAssembly build. connect() succeeds. bind() succeeds. listen() succeeds. Then no bytes ever move, and select() never reports the socket readable. That is not a defect anybody introduced; it is what a POSIX shaped API looks like when there is no network stack beneath it to say no.

Point Django's development server at that and it does the worst possible thing. It prints its banner:

Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

and then answers nothing, for as long as you leave it running. Nothing raised, nothing logged, no clue in the output that the server you are looking at is incapable of serving. A missing feature that announces itself is a small problem. A missing feature that looks like a working one costs somebody an afternoon.

So the design rule for everything below is that a socket must never be the thing we quietly rely on.

The launcher is not a Python program​

Here is the piece that makes the rest possible, and it is an accident of how Vivari is put together rather than anything clever about Python.

python in Vivari is not a Python program. It is a Node program, running on Vivari's Node-compatible runtime, and it boots Pyodide inside itself. That runtime has a real require("http"), a real event loop, and a working server.listen(port), because Vivari's kernel implements virtual ports: an Express app in this environment gets a preview tab, and it does so without a TCP stack either.

Which means the interpreter that cannot bind a port is running inside a process that already can.

browser  ->  service worker  ->  kernel virtual port
                                       |
                                       v
                          guest Node http.createServer()      <- the "socket"
                                       |
                                 JSON, base64 body
                                       v
                                    Pyodide
                                       |
                          WSGI environ / ASGI scope
                                       v
                              your Flask or FastAPI app

Nothing in the Python half of that diagram believes it is talking to a network. It is handed a request the way a WSGI server hands one over, because that is precisely what the layer above it has become.

Writing the environ by hand​

WSGI is a good specification to be stuck with here, because it was never about sockets in the first place. PEP 3333 says a server calls app(environ, start_response) and reads the iterable that comes back. It says nothing about where the bytes came from.

So the Node side parses the request it received, and the Python side builds the dict:

environ = {
    "REQUEST_METHOD": d["method"],
    "SCRIPT_NAME": d.get("root_path", ""),
    "PATH_INFO": d["path"],
    "QUERY_STRING": d.get("query", ""),
    "SERVER_PROTOCOL": "HTTP/" + d.get("http_version", "1.1"),
    "wsgi.input": io.BytesIO(body),
    "wsgi.errors": sys.stderr,
    "wsgi.multithread": False,
    "wsgi.multiprocess": False,
    "wsgi.run_once": False,
}

wsgi.multithread and wsgi.multiprocess are both False and, unusually, both are honestly False. There is one interpreter and there are no OS threads, so an app that checks those flags before deciding whether a cache can be a plain dict gets a true answer rather than a conservative one.

Request bodies and response bodies cross the JavaScript and Python boundary as base64 inside a JSON string. That is not elegant and it was chosen anyway: JSON strings convert to Python str with no ambiguity, whereas handing typed arrays across the boundary means reasoning about proxy object lifetimes at every call site. The bridge is on the request path, so the failure mode that matters is a subtle one, not a slow one.

That is a claim you should not take on trust, so here it is running. The code below is real CPython executing in this page, and you can edit it and run it again. It builds the environ above, hands it to a WSGI application, and passes the whole thing through wsgiref.validate, which is CPython's own PEP 3333 conformance checker. If the standard library's validator returns without raising, what the bridge gives your app is a real WSGI call and not an impression of one.

Two honest notes about that demo. It uses only the standard library, because the CPython core is stable here while Flask, FastAPI and Django are shipped as experimental templates, and a live demo is the wrong place to blur that distinction. And it exercises the conversion rather than the tunnel: the environ, the application call and the validation are the real thing, while the part that carries bytes in from the browser is the guest Node server described above. The first run also has to fetch the interpreter, so it is slower than the ones after it, which is the subject of the next post.

The ASGI scope, and the bug that took longest​

ASGI needs more of the same, plus one thing that is easy to get wrong and produces a symptom that points nowhere near the cause.

Previews in Vivari are served under a path prefix, /preview/<port>/. The preview tunnel strips that prefix before the request reaches your process and sets x-forwarded-prefix so the app can learn what it was mounted under. The Node side reads that header and passes it along as root_path.

The obvious thing to do next is to set scope["root_path"] to the prefix and scope["path"] to the path the tunnel handed over. That is wrong, and it is wrong in a way that only shows up on Mount().

ASGI defines path as the full request path, including root_path. root_path names the prefix, it does not remove it. Starlette's get_route_path() subtracts root_path from path to get the routable remainder, so if you hand it a path that has already been stripped, it subtracts a prefix that is not there. Top-level routes still match, because the subtraction falls through harmlessly. Every Mount() misses, including the StaticFiles mount that a FastAPI app usually has, so the app comes up, the JSON endpoints work, and the CSS 404s.

The fix is to put the prefix back before building the scope:

_vv_root = d.get("root_path", "")
_vv_path = _vv_root + d["path"] if _vv_root else d["path"]

WSGI needs no equivalent, and the reason is a small piece of design history worth appreciating. SCRIPT_NAME and PATH_INFO are already the split form: the prefix and the remainder are separate keys, so there is nothing to subtract and nothing to get wrong. ASGI collapsed them into one string plus a length convention, and this is the bug that convention buys you.

No threads, which FastAPI has an opinion about​

Starlette and FastAPI let you write def endpoints as well as async def ones. A sync endpoint cannot be awaited, so Starlette runs it on a threadpool through anyio.to_thread.run_sync, which ends at threading.Thread, which under Pyodide raises RuntimeError: can't start new thread.

That would make every synchronous route in a FastAPI app a 500, which is most routes in most tutorials.

There is one interpreter and nothing else can be running in it, so the threadpool is not buying isolation here, only a thread that does not exist. Running the callable inline is the correct answer for this execution model:

import anyio.to_thread as _vv_att

async def _vv_run_sync(func, *args, **kwargs):
    return func(*args)

_vv_att.run_sync = _vv_run_sync

Starlette reads run_sync at call time rather than binding it at import, so this takes effect for every sync route and every sync dependency, including ones defined after the patch.

The entrypoints do not import what they are named after​

uvicorn, flask and gunicorn exist as commands. None of them imports the package it is named after.

uvicorn main:app --port 8000                   # FastAPI and other ASGI apps
flask --app main run --port 8000               # Flask
gunicorn wsgi:application --bind 0.0.0.0:8000  # Django and any other WSGI app

Each one parses argv the way the real tool does, works out which module and attribute you meant, and hands that to the bridge. Calling them shims undersells what they have to get right: the observable contract of gunicorn is "your WSGI app is now served on this port", and that contract is met. What cannot be met is gunicorn's process model, so those flags say so out loud rather than being accepted and ignored. -w 4 warns that there is exactly one worker. --worker-class gevent stops, because serving you a different concurrency model than the one you asked for is not a warning-level event.

Choosing gunicorn as the WSGI entrypoint rather than writing a django command is the reason Django works at all here. gunicorn is the seam every WSGI framework already reaches for, so Bottle and Pyramid arrive for free.

The argv parsing has one decision in it that is more interesting than argv parsing has any right to be. To know whether --log-level debug main:app has two tokens or three, you need to know which flags take a value. gunicorn's own --help declares about a dozen store-true flags and several dozen that take a value, and the shim hardcodes the boolean list rather than the value list.

That is smaller, but the real reason is which way it fails. Mistake a boolean for a value-taker and it eats the next token, which is the app spec, and the command exits with no app specified. The user sees that immediately. Mistake a value-taker for a boolean and its value is left lying in argv to be picked up as the app spec, and the server cheerfully starts serving something nobody asked for. Both are bugs. Only one of them is quiet.

Django's runserver is refused, on purpose​

python manage.py runserver does not run. It stops and says why, and points at the command that works.

This is the only refusal in the Python support that blocks something people demonstrably want, so it is worth defending. Every other entrypoint here hands you an app object, which is a thing the bridge can serve. runserver binds the socket itself. Given Pyodide's socket, that means it would start, print its banner, and answer nothing, which is the failure mode described at the top of this post.

The rest of manage.py is untouched. migrate, makemigrations, shell and createsuperuser all run normally, because none of them is a socket.

Keeping CPython's own HTTP server, minus the socket​

python -m http.server is the neatest case, because it shows what the bridge makes possible when the thing being served is already in the standard library.

Reimplementing a static file server is easy and would have been the wrong answer. The value of -m http.server is that it is the directory listing you know, the mimetypes table you know, the Range and If-Modified-Since handling you know, and the 404 you know. A lookalike is worth much less than the real one.

So the handler stays and the socket goes. BaseHTTPRequestHandler does all of its I/O through self.rfile and self.wfile, which StreamRequestHandler.setup() builds from self.connection by calling makefile(). It never touches the socket directly. So a socket, as far as that class is concerned, is an object with makefile() and sendall():

class _VvConn:
    """Everything StreamRequestHandler.setup() asks of a socket, and no more."""
    def __init__(self, data):
        self._data = data
        self.out = bytearray()
    def makefile(self, mode="rb", bufsize=-1, *a, **k):
        return io.BytesIO(self._data) if "r" in mode else io.BytesIO()
    def sendall(self, b):
        self.out += bytes(b)

Feed it the raw request bytes, let CPython's own SimpleHTTPRequestHandler do the work, and collect the raw response bytes out of out. The same guest Node server carries them that carries Flask's.

Duck typing gets used to defend some questionable things. This is the case it was invented for.

Two things that fell out for free​

Neither of these was designed. Both are consequences of the constraints, noticed afterwards, which is usually a sign the layering is right.

There is an exact moment when the filesystem is consistent. A served app that writes a file, an upload or a SQLite commit, needs those writes mirrored back into the editor. On a normal server there is no clean moment to do that, because another thread is always mid-write. Here the handler has returned and there are no threads, so the end of a request is a point where "everything the app has written" is a complete and correct answer. Persistence happens there, after the response bytes are already out, and costs nothing on a request that wrote nothing.

--reload works, without a watcher thread or a subprocess. Real reloaders need both: something to poll the filesystem, and a process to kill and respawn. Neither exists here and neither is needed. The virtual filesystem already pushes change notifications, because that is how Vite's dev server sees your edits. And there is no server process to restart, because your app is an object imported into the bridge's process, so a reload re-imports the module and rebinds one name. A failed re-import puts the previous modules back and the old app keeps serving, which matters because a syntax error in a file you just saved is the normal case rather than the exceptional one.

What is honest to claim​

The Python web frameworks here are shipped as experimental templates. That is the project's own word for them, it is what the README says, and this post is not the place to quietly upgrade it. Vivari's CPython core, pip and the REPL are stable. Flask, FastAPI and Django sit above them and are not.

The limits worth knowing before you try it:

• Buffered request and response only. Each request is converted, run and returned whole. No streaming responses, no Server-Sent Events, no WebSocket from Python. This is a property of the bridge, not a bug in it.
• One request at a time. One interpreter, no threads.
• runserver is refused, as described above.
• Generate your URLs. The preview is served under a prefix, and the bridge tells your framework what it is, so url_for(), reverse() and request.url_for() stay inside the preview. A hardcoded /about escapes it.
• Nothing here makes an unbuilt C extension work. psycopg2 still has no wheel. Streamlit still stops on watchdog. This bridge is about serving an app you can already import.

What is not caveated: a real Flask app, a real FastAPI app with real Starlette routing, and a real Django app served through real gunicorn argv handling, all answering real HTTP requests in a browser tab with no server anywhere and no socket underneath.

The pattern, again​

Every one of these posts has ended in the same place from a different direction. The synchronous bridge works because Atomics.wait is a real blocking primitive and the whole system was built to respect it. Node's real lib/ works because Node already had a seam and we cut along it.

WSGI and ASGI are that same seam, and Python drew it years before any of this existed, with none of it in mind. The frameworks were already written against an interface that says nothing about sockets. All that was missing was something standing on the other side of it.

The next post is about a different Python problem entirely: why the first python command in a session costs nearly two seconds, why the second one used to as well, and what PEP 552 has to do with fixing it. There is more detail on everything above in the Python docs.

Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no per-seat fee, self-host every asset. The code is on GitHub and the Studio runs in your browser.

That verdict was wrong, and it was wrong in the most ordinary way: we had decided something was impossible and then stopped rechecking it.

next dev --webpack now boots inside a browser tab, compiles an App Router page, renders React Server Components, and answers GET / → 200 with real HTML. No server. The kernel, the filesystem, the process model, the dev server and the React render all live in one tab.

Getting there was mostly unremarkable engineering, plus one problem that has no correct solution.

Why the wall was not a wall​

Three things had to be true at once, and all three already were:

Next 16 kept the Wasm SWC fallback. @next/swc-wasm-nodejs still exists, because Next still has to run in environments without a native binding. Next's own loadBindings prefers it when process.versions.webcontainer is set, which our runtime now reports, because that is exactly what we are.

webpack is still selectable. Turbopack is native Rust with no Wasm build, so it genuinely is unavailable. But --webpack remains a supported flag, and webpack is JavaScript.

npm skips the native optional dependencies. On arch wasm32, the @next/swc-<platform> optionalDeps do not install, so the Wasm build is not merely preferred, it is the only binding present.

So the wall was three assumptions that had each expired. Worth remembering next time something gets filed as impossible.

The rest of the work was the usual: vm.runInNewContext had to make the sandbox the real global, so that globalThis.__RSC_MANIFEST = ... assignments in Next's generated manifest files actually land on the context object; without that the client-reference manifest never loads. child_process.fork needed a genuine IPC channel, because next dev forks its dev server and gates startup on process.send existing. pathToFileURL had to resolve relative to absolute like Node does. A handful of modules had to exist: dns/promises, stream/web, an inspector stub, module.findSourceMap, and the complete Console method surface that @edge-runtime/primitives binds.

All generic. None of it Next-specific. Then there was the interesting one.

The trap​

The App Router's internals rely on AsyncLocalStorage. Its workStore and workUnitAsyncStorage carry per-request context, and React's server rendering reads them from deep inside component code. If getStore() returns undefined at the wrong moment, you get:

Expected workStore to be initialized

In real Node, AsyncLocalStorage works because V8 exposes a PromiseHook. The engine tells async_hooks when a promise is created, resolved, and continued, so the context can follow execution across a native await. Our runtime delegates to the host's async_hooks through the internalBinding seam when one exists, which is exact.

A browser has no PromiseHook. There is no way to observe a native await. You cannot know that this continuation belongs to that async context, because the engine never tells you.

This is worth sitting with, because it is a genuinely different class of problem from everything else in this series. Every other gap was work: read Node's source, implement the binding, be precise. This one is a capability the platform does not have and cannot be made to have.

Three rules, and why each exists​

What we could do was stop trying to solve the general problem. A dev preview handles one request at a time. That is a much weaker requirement than a production server, and within it the context can be tracked well enough to be deterministic, not merely usually correct.

Three rules, each of which exists because a specific thing broke.

Rule 1: a thenable-returning run(store, cb) holds its store until the promise settles, then pops only if still top, and never back to undefined.

The "only if still top" clause stops out-of-order settling from clobbering a live nested scope. The "never back to undefined" clause is the one that took real debugging. A streaming RSC render returns its promise early, as soon as the stream is created, while React carries on rendering components detached across native awaits. Zeroing the store when that early promise settles throws Expected workStore to be initialized in code that is still running. Restoring a defined parent store is safe and keeps nested scopes correct; restoring undefined is not.

Rule 2: a plain, non-thenable return does not restore at all.

Next's renderToFlightStream returns a stream synchronously and does the actual rendering later, across raw awaits, with no promise for us to observe. If the store is popped when run() returns, all of that detached work runs with no context. Leaving the store current keeps getStore() correct until the next run() overwrites it.

This rule is, straightforwardly, a leak. In a general-purpose implementation it would be wrong. Under one-request-at-a-time it is the behaviour that makes the detached render work, and the next run() cleans up after it.

Rule 3: propagate a per-hop snapshot of every live store through the scheduling primitives React uses.

Specifically Promise.prototype.then, queueMicrotask, setImmediate and setTimeout. React's scheduler hops through these constantly, and each hop is a place context would otherwise be lost. Snapshotting at schedule time and restoring at run time recovers most of what a PromiseHook would have given us.

The patches install once at boot, and only on the polyfill path. The timing matters: after the runtime's own timer globals are in place, and before any framework code loads, so React captures the wrapped primitives rather than the originals. When the host provides real async_hooks, none of this is active.

Proving it, given the failure mode​

A context bug that only appears under specific interleavings is the worst kind to claim you have fixed. "It worked when I tried it" is not evidence when the mechanism is inherently timing-sensitive.

So the polyfill is tested by forcing it. VV_NO_HOST_ALS=1 disables the host async_hooks delegation even where it is available, which means the headless test suite exercises the browser path on a machine where the real one exists. That gives two things: an oracle, and the ability to run the comparison under load.

The specific case that matters is the RSC refresh render: the App Router's "on save" re-render, the request with RSC: 1 that the HMR flow issues. That is the path that threw workStore in the studio, so it is the path that has to be green.

The results we hold it to: GET / returns 200; the refresh render returns 200 with zero invariant errors across repeats; and the output is byte-identical to the host async_hooks path, under heavy-I/O perturbation, which is the whole point. Byte-identical against a known-correct implementation is a much stronger claim than "no errors observed", and it is the only reason we are comfortable describing the behaviour as deterministic rather than lucky.

One more detail that is easy to get wrong: Next resolves the Wasm SWC by downloading it into its own cache on first compile. That is its intended behaviour in Wasm environments and real Node does the same thing. The template's postinstall seeds that cache from the already-installed package so the first compile is offline, with Next's own on-demand download left in place as the fallback.

What is honest to claim​

Next.js is shipped as a stable template, in TypeScript and JavaScript, and the caveats are real:

• Turbopack does not work and will not. It is native Rust with no Wasm build. --webpack is the path.
• The AsyncLocalStorage polyfill targets a dev preview. It is correct for one request at a time. It is not a general-purpose implementation and we would not present it as one.
• First compile is heavy. A Wasm SWC compiling an App Router page is not fast, and you will notice.

What is not caveated: this is real Next.js from npm, real webpack, real SWC, real React Server Components, rendering real HTML, with no server involved anywhere. You can open the Studio and pick the Next.js template right now.

The thread running through all of this​

Every post in this series has landed in the same place, from a different direction.

The synchronous bridge works because Atomics.wait is a real blocking primitive and we built the entire system around respecting it. Node's real lib/ works because Node already had a seam and we cut along it. npm, yarn and pnpm work because the layers underneath implemented real specifications instead of the subset our demos needed.

AsyncLocalStorage is the exception that proves the rule. There is no seam to cut, no specification to implement completely, no primitive to respect. V8's PromiseHook simply is not there. So the only honest move was to narrow the problem until it was solvable, be explicit about the boundary, and test against the real implementation rather than against our own expectations.

Sometimes the interesting engineering is admitting exactly how much of the problem you actually solved.

Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no per-seat fee, self-host every asset. The code is on GitHub and the Studio runs in your browser.

Part one: the HTTP parser​

Node's lib/http does not parse HTTP. It delegates to internalBinding('http_parser'), which in real Node is llhttp, a C parser compiled into the binary.

We had written a pure-JavaScript HTTP/1.1 parser to fill that binding. It worked, in the sense that ordinary requests went in and ordinary responses came out. It also had the failure profile every hand-written protocol parser has: the common path is fine and the edges are a long tail of things you have not thought about yet. Trailers. HEAD responses, which have Content-Length but no body. 204, which has neither. Chunked encoding with extensions. Pipelining. Upgrade and CONNECT hand-off, where the parser has to stop parsing mid-stream and hand the raw socket over.

The right answer is to run the same parser Node runs.

We did not build a toolchain to do it. Standing up wasi-sdk and clang just to recompile llhttp would produce an artifact essentially identical to one that already ships publicly. undici bundles a prebuilt llhttp.wasm from the same upstream project, under the same MIT licence. So a vendoring script pins the undici version and regenerates a binding module with the binary base64-embedded, about 54 KB. No fetch at runtime, no build dependency.

Two details made it interesting.

It has to compile synchronously. The binding is constructed at process bootstrap, inside the synchronous world everything else lives in, so the module is built with new WebAssembly.Module() rather than the async compile. That is allowed on a worker thread, which is where guest processes run. On the main thread there is a 4 KB size cap on synchronous compilation, and a 54 KB module throws, which turns out to be a convenient way to detect the environment. Exceeding the cap is precisely what trips the pure-JS fallback, so the JS parser stays in the tree as the main-thread path rather than as dead code. VV_HTTP_PARSER=js|wasm forces either side, with wasm failing loudly instead of falling back, so tests can assert which one they exercised.

The bridge has to be numerically exact. llhttp reports progress through span callbacks: on_url, on_status, on_header_field, on_header_value, on_body, on_headers_complete, on_message_complete. Node's lib/_http_common.js does not consume those; it expects a specific set of numeric kOn* slots. The binding mirrors what Node's own node_http_parser.cc does: drive llhttp's callbacks, fold them onto the exact kOn* contract, for both requests and responses. allMethods follows llhttp's method enum, so allMethods[llhttp_get_method()] round-trips the way callers assume.

When the Wasm backend is live it advertises process.versions.llhttp, exactly as real Node does. Twenty offline checks guard it in CI, plus an extended HTTP case covering HEAD, 204, chunked requests and responses, trailers and keep-alive, run against both backends, because a fallback nobody tests is a fallback that does not work.

You can watch it parse. The server below binds a port inside this tab and then fetches from itself:

Part two: databases​

"No native database" is the limitation every in-browser runtime lists, and the documentation usually stops at suggesting workarounds.

It is worth asking why the limitation exists. The blocker is not SQL. It is that database clients are native addons, and there is no compiler in the tab. So the question becomes: what do you need in order for a Wasm-compiled engine to work, and do we already have it?

The answer was yes, and it had nothing to do with databases. A Wasm SQL engine needs a real fs to read its data files, a working url module, and the host's WebAssembly, all of which exist because of decisions made for other reasons. So this was less a feature than a discovery.

SQLite via sql.js. SQLite compiled to Wasm. initSqlJs() finds its .wasm next to itself with locateFile: (f) => require.resolve('sql.js/dist/' + f), which resolves over the virtual filesystem like any other module path.

PostgreSQL via PGlite. This is real PostgreSQL, currently 18, compiled to Wasm. About 16 MB of pglite.wasm and pglite.data, read out of node_modules through the virtual filesystem: the package resolves them from __filename, builds a new URL('./pglite.wasm', ...), and calls fs.readFile. Every step of that is ordinary Node behaviour, which is the whole point.

One deliberate choice: we use PGlite's CommonJS build. The ESM build relies on top-level await, and in-VM only the entry module can block on TLA. Choosing CJS avoids the problem entirely.

And one we deliberately did not ship. libSQL is not available as an in-VM template, and the reason is worth stating rather than leaving as a gap in a table. @libsql/client in local mode is a native N-API addon with no wasm32 build. @libsql/client/web works, but only talks to a remote Turso server, which is a network client, not a database in the tab. Neither is self-contained, so neither belongs in a list of things that run with no server. sql.js remains the local SQLite path.

Both engines were confirmed end-to-end in plain Node first, against the same fs, url and WebAssembly primitives the runtime exposes, before either was wired into a template. Both are then gated by network spikes in CI that install the dependency, bind a port, and assert that the API reports the right engine version and returns seeded rows, with a longer budget for PGlite, whose install and first-boot Wasm compile are genuinely heavy.

The pattern​

Both of these landed for the same reason, and it is not cleverness.

The HTTP parser worked because Node had already defined the seam (internalBinding('http_parser')) and someone had already compiled the C to Wasm. The databases worked because the runtime implemented fs and url properly rather than implementing the subset our own demos needed.

Neither was planned. Both fell out of building the layer underneath correctly and then discovering what it supported. That is a much better position to be in than the alternative, and it is most of the argument for the architecture these posts keep coming back to.

That is what we did, and it is a security problem.

Same origin means the same cookie jar, the same localStorage, the same IndexedDB, the same OPFS, the same Cache Storage, the same Service Worker scope. Preview code, which includes every npm package the project installed and anything an AI assistant just generated, sits inside the IDE's origin. It can read the editor's session state, corrupt its persistence, and call its same-origin APIs. Previews are not isolated from the IDE, and they are not isolated from each other.

Fixing this properly took three attempts, and each one ran into a different piece of web platform trivia.

Mode A: same origin​

The default, and the one to move away from.

https://ide.example.com/preview/5173/

The Service Worker intercepts requests under /preview/<port>/, strips the prefix, and relays them to the kernel, which it can find directly because it is same-origin with the tab holding it.

Zero extra infrastructure, and it works. But beyond the storage problem, path routing quietly breaks things that a real server would get right:

That last row is the one users actually report. Any app that assumes it is served from / needs a prefix hack somewhere: in the SW, in the URL rewriter, or in the app's own config.

Mode B: a second origin​

Move previews to a different origin entirely and the browser's same-origin policy does the work for you. The kernel still lives in the IDE tab, so the preview's Service Worker reaches it through a hidden bridge iframe and a MessagePort.

Here the hosting platform pushes back. A Cloudflare Pages project only gets <project>.pages.dev, and you cannot mint preview.myproject.pages.dev. A second origin means a second Pages project.

Which sounds fine, and introduces the first real trap.

pages.dev is on the Public Suffix List. That makes myproject.pages.dev and myproject-preview.pages.dev different sites, not merely different origins. As an isolation boundary that is stronger than you asked for: cookies cannot be shared even deliberately.

It also breaks popping a preview out into its own tab, in a way that cannot be worked around.

Chrome storage-partitions cross-site contexts. The kernel is reached through a bridge iframe living in the editor tab; for a standalone preview tab to use that bridge's Service Worker registration and MessagePort, both have to be in the same storage partition. Cross-site, they are not. And requestStorageAccess() un-partitions cookies, not Service Worker registrations, so the "connect this tab to its project" gate can never actually bridge the two partitions. The gate appears, you grant it, and nothing changes.

Two subdomains of one registrable domain fix it. Serve the IDE at ide.example.com and previews at preview.example.com, both CNAMEd to their Pages projects, and the two are same-site: no partition wall exists, so the popped-out tab shares the bridge's Service Worker and reaches the kernel with no gate at all. Storage is still origin-scoped, so preview code still cannot touch IDE storage.

The residual leak with same-site subdomains is domain-wide cookies: anything set with Domain=example.com is visible to both. So do not set domain-wide cookies on the IDE. For trusted first-party code this is the right trade. For untrusted code at scale you want the cross-site boundary and you accept the gate, which is exactly the choice StackBlitz made, and it is a reasonable one for their threat model, not an oversight.

There is one important caveat: you have to open the editor at ide.example.com. Loading it via the raw .pages.dev hostname reintroduces cross-site and the gate comes back.

Mode C: one origin per port​

Mode B isolates previews from the IDE, but every preview still shares one origin with every other preview, and the port is still in the path. Mode C gives each in-VM port its own origin:

https://k3f9a2xh--5173-vv.example.com/

The port moves into the hostname, so each preview gets genuine localhost:<port> semantics, with its own cookies, its own storage and its own CORS behaviour, and previews are isolated from each other as well as from the IDE. Everything on the "breaks under path routing" list above stops being a problem, and the prefix hacks come out of the codebase.

This is the model StackBlitz uses, and their URLs decode neatly:

https://vitejsvitelqrjey5b-c0kn--5173--87cf54cd.local-credentialless.webcontainer.io/
        └────── instance / project id ────┘  └port┘ └session hash┘ └ COEP mode ┘ └base┘

Getting there involves three constraints that each look arbitrary until they bite.

Cloudflare Pages cannot do wildcard custom domains. They are exact hostnames only. So the wildcard origin has to be a Worker bound to a route, serving the static Service Worker runtime and the bridge document. It runs no kernel and no IDE; it is pure static hosting for an origin that has to exist per port.

The wildcard must be a prefix, so the tag must be a suffix. Cloudflare routes only allow * at the start of a hostname. vv-*.example.com is an infix wildcard and is rejected. That is why the marker is a suffix and the route reads *-vv.example.com/*, which has the pleasant side effect of being narrow: it matches Vivari preview hosts and nothing else on the zone. Anything else that reaches the Worker is passed straight through untouched.

Free TLS covers exactly one label. Cloudflare's Universal SSL issues a certificate for the apex plus a single-level wildcard: *.example.com matches abc.example.com but not abc.def.example.com. So a scheme like *.preview.example.com is two levels deep, is not covered, and produces a TLS error rather than a helpful message. Paid Advanced Certificate Manager fixes it; staying free means keeping preview hostnames one level under the apex and packing the port into that single label, hence <token>--<port>-vv, all in one label.

Each preview response is then stamped with COOP: same-origin, COEP: credentialless and CORP: cross-origin, so the IDE (which is require-corp) can embed the bridge iframe, and the Service Worker is allowed to claim root scope.

The limitation nobody can engineer away​

One thing worth being honest about, because it applies to every client-side container including this one.

A preview URL is not a network address. It is a capability ticket that only works inside the browser holding a kernel-connected Service Worker. The Service Worker is a per-origin proxy running in your browser, and its live link to the kernel is a MessagePort held in its memory.

The consequences are observable on StackBlitz and we inherit all of them:

• Paste the URL into a new tab on the same browser and it works, because that tab is claimed by the same Service Worker, which already holds the port.
• "Open in new tab" sometimes needs a popup and a reload. That happens when the Service Worker's in-memory port has lapsed because it was killed while idle, and the popup provides a window.opener channel to re-handshake.
• Open it on another machine and it fails, even with the project still open elsewhere. The kernel lives in the first machine's tab RAM. postMessage does not cross the network.
• Close the editor tab and the preview dies.

None of that is fixable within the no-server model, because the thing serving the preview genuinely is not a server. A persistent, shareable preview URL requires a real backend, which is a different product decision, not a bug to file.

Choosing​

The modes are a deploy-time choice rather than a runtime toggle, which keeps the core simple. Start at A if you are running your own trusted code and want zero infrastructure. Move to B with same-site subdomains as soon as anyone else's code runs in your previews. Go to C when previews need to be isolated from each other, or when apps genuinely need to believe they are on their own host.

The deployment guide has the full setup for each.

They do. npm, yarn, pnpm and corepack in Vivari are the actual published releases, vendored and executed as-is. But "should run" and "runs" are separated by every Node API each tool happens to touch, and the four of them touch almost disjoint sets. Each one, in turn, walked into a different corner of the runtime and found the wall.

Not a reimplementation​

The retired approach was a Turbo-style installer that resolved a lockfile and wrote node_modules itself. It was fine for a demo and wrong for a product: it was not npm, so it did not behave like npm, and every gap between the two was a support burden. The shipped studio boots the real thing instead.

Delivering a real CLI to a tab is a packaging problem. Each package manager is installed at a pinned version on the build host, its file tree is walked, and the whole thing is written into one archive that ships as a static asset under packages/studio/public/vendor/. The archive is a deliberately boring custom format rather than a tarball:

[u32le headerLen][header JSON][file bytes ...]      then gzip the whole lot

Two decisions in that one line earned their comments. The format is custom because we control both ends and would rather not meet tar's long-path and GNU-extension edge cases, and npm's @npmcli/* paths are long enough to hit them. And the gzipped output is named *-pack.bin, not *.gz, on purpose:

Static servers (Vite's sirv, many CDNs) treat a .gz file as TRANSFER-encoded and serve it with Content-Encoding: gzip, so the browser transparently decompresses it before our fetch sees it, and our own gunzip then fails on already-decompressed bytes. A neutral extension is served verbatim.

At boot the kernel worker fetches npm-pack.bin, gunzips it with the browser's DecompressionStream, and writes the tree into the virtual filesystem at /usr/lib/node_modules/npm in one batched transfer. A three-line shim lands on PATH at /bin/npm.js and does nothing but require the real bin/npm-cli.js. npm is loaded eagerly because almost every project needs it; yarn, pnpm and corepack are registered as lazy loaders and only fetched the first time you actually spawn them, so the sizes below are costs you opt into.

None of that is the hard part. The hard part is that a real CLI calls real Node.

npm: the fidelity pass​

npm booted first, and getting npm -v to print 10.9.2 and exit 0 closed three gaps that a reimplementation would never have surfaced, because they are about being Node, not about installing packages. process had to be a genuine EventEmitter (npm's proc-log attaches listeners to it). A dynamic import() inside a CommonJS module had to route through our loader (npm does await import('chalk')). And stdout.write(cb), process.exitCode and a single 'exit' event all had to behave the way npm's exit-handler assumes. Fixing those was less "supporting npm" and more "finishing Node".

Then there is the thing every in-browser runtime has to answer for: native addons. There is no compiler in a tab, and a .node binary could not be loaded if there were, because we run Wasm. But real npm runs a package's install/rebuild lifecycle script, which for a native package is node-gyp rebuild, and a non-zero exit there aborts the entire install. So node-gyp is stubbed to a non-fatal no-op:

To keep installs working we make node-gyp a non-fatal no-op: the build is skipped and the script "succeeds". This mirrors how browser WebContainers handle native deps: the package's JS fallback (or its wasm32-wasi build, auto-selected via optionalDependencies) is what actually loads at runtime.

The rest of npm's needs are environmental. Registry requests go through a fetcher that strips the non-safelisted headers a browser would otherwise preflight and reject; downloads run through an async fetch op so npm's parallel tarball fetches are actually parallel; large writes bypass the shared buffer pool; and npm_config_audit, npm_config_fund and the update-notifier are switched off, with the cache pointed at an OPFS-backed directory so it survives a reload.

yarn: five gaps in one bundle​

Yarn classic is trivial to deliver (a bin/yarn.js entry and a ~5 MB webpack cli.js, eleven files total) and instructive to run. It exercises a set of Node internals npm simply never reached, and lighting it up filled five more compatibility gaps, all fixed down in packages/runtime/ where they help every program and not just yarn.

The memorable one is graceful-fs, which yarn bundles through fs-extra. graceful-fs patches fs by subclassing fs.WriteStream with fs$WriteStream.apply(this, arguments), the old prototypal-inheritance move, which throws against a modern class. Alongside it: process.memoryUsage() (yarn's reporter tracks peak memory), and internal/fs/dir for fs.opendir, which yarn trips indirectly because thenify-all runs promisifyAll(fs) over every method it can find. A package manager that reflects over the whole fs module is an excellent conformance test you did not have to write.

pnpm: worker threads, symlinks, and shell shims​

pnpm was the one we expected to be hardest, and it was, because it uses the features the others avoid. It drives real worker_threads for fetch and extract. It builds a symlinked node_modules: a content-addressable store plus symlinks into it, which means the virtual filesystem has to implement symlink, readlink and lstat as first-class operations rather than approximations. The store's packages are shared via hard links, so the VFS also grew a real link(2). What it does not get is reflink/copy-on-write, so the prebuilt *.node reflink addons, which only exist for macOS and Windows, are dropped at vendor time rather than shipped as dead weight on a Linux target.

The subtle failure was in how pnpm writes the executables in node_modules/.bin. npm makes them POSIX symlinks to the real .js; pnpm writes a #!/bin/sh cmd-shim that exec node "$basedir/../vite/bin/vite.js" "$@". Our loader cannot run a shell script, so without help it hands that shell wrapper to the JS compiler and gets SyntaxError: missing ) after argument list the first time you run a pnpm-installed binary. The fix is a small, unit-tested unwrapper that parses the target .js out of the shell shim before runMain execs it. The only genuinely missing runtime primitive was util.types.isBoxedPrimitive, which pnpm's JSON path uses; it went in with the rest of the boxed-primitive and typed-array predicates.

corepack: a package manager for package managers​

corepack is the odd one out, because it is not a package manager at all. It is a version manager: it reads a project's packageManager field, downloads that exact yarn or pnpm release, verifies it, and execs it. So it gets only a /bin/corepack.js shim and deliberately leaves the direct npm/yarn/pnpm shims alone: those stay the defaults, and corepack is the extra "run the project-pinned version" path.

Its download-then-extract-then-exec pipeline surfaced five more gaps, again fixed generically: require('module').runMain, which corepack uses to exec the downloaded manager in-process; Readable.fromWeb, so it can stream the tarball out of the global fetch() response body; WHATWG stream readers whose read()/cancel() promises properly ref the event loop, so a download does not race the loop to exit; and crypto.Hash extending stream.Writable, so the idiomatic stream.pipe(createHash(algo)) works and the sha512 integrity check passes. The one thing our crypto layer cannot do is corepack's registry ECDSA signature check (there is no crypto.verify), so the shell sets COREPACK_INTEGRITY_KEYS=0, which is corepack's own supported escape hatch. The tarball's sha512 integrity is still checked.

The pattern, again​

None of these four required code that knows anything about installing packages. npm needed process to be a real EventEmitter; yarn needed graceful-fs to be able to subclass fs.WriteStream; pnpm needed symlinks and hard links to be real filesystem operations; corepack needed WHATWG streams to ref the loop. Every one of those fixes lives in the runtime, not in a shim, so it is there for the next program too, which is exactly why the next thing to run took less work than this did.

That is the whole bet behind running Node's real source: you do not implement the tools, you implement the platform, and then the tools run because they were always just programs. The argument is spelled out in more detail in the architecture docs.

Path A is the obvious one: hand-write the core modules. Implement fs on top of your virtual filesystem, implement path as string manipulation, implement events as a small emitter, and keep going. It feels productive immediately. path takes an afternoon. events takes a morning. fs takes a week and mostly works.

Then you reach stream, and progress stops.

Where Path A dies​

stream is not a big module because Node's authors were verbose. It is big because backpressure is genuinely hard, and because fifteen years of packages have come to depend on the exact observable behaviour of that difficulty.

You can write something called Readable in a day. Making it emit 'readable' at the right moments, respect highWaterMark, handle a pipe target that returns false from write, unpipe cleanly on error, support both flowing and paused modes, implement readableEnded versus readableFinished, and behave correctly when a subclass calls the constructor without new: that is not a day. And when you get one of those wrong, you do not get a clean error. You get a dev server that hangs at 40% of a build, in a package four levels deep in someone's dependency tree.

http is worse, because it is a protocol parser plus a connection agent plus a stream implementation. crypto is worse still, because it is an ABI over OpenSSL. zlib needs a compression codec.

We had a runtime that could run a small Express app and could not run anything real, with a queue of modules ahead of us that each represented months of work and would still be, at the end of all that effort, an imitation.

Taking apart the competition​

StackBlitz's WebContainer had clearly solved this. So we did the obvious thing and read their bundle, a ~2.1 MB file called builtins.2896b7f3.js.

The finding reframed the entire project:

They do not hand-write Node's core modules. They ship Node's actual lib/ JavaScript.

The evidence is not subtle once you look. The bundle exports an object with roughly 300 keys, and those keys are not a curated public API. They are Node's internal module tree. Alongside fs, http, stream, crypto, zlib, net, tls and worker_threads sit internal/streams/readable, _http_agent, internal/crypto/*, and internal/bootstrap/realm. Every module is wrapped in a function taking (exports, require, module, process, internalBinding, primordials).

internalBinding and primordials are internal-only Node machinery. You do not end up with those identifiers by writing a compatibility layer. You end up with them by shipping Node's source.

The seam​

Once you see it, the architecture of real Node becomes the architecture of the solution.

Node is two layers. On top is lib/*.js, tens of thousands of lines of JavaScript implementing streams, HTTP, crypto, the module loader, everything a package actually touches. Underneath is C++, reached through exactly one door:

const binding = internalBinding("fs");

lib/fs.js does not know what happens inside internalBinding('fs'). It knows the shape of what comes back. That is a seam, and a seam is something you can cut along.

So: keep Node's JavaScript layer verbatim, and replace the C++ layer underneath with your own implementation. When lib/fs.js calls internalBinding('fs'), it gets an object backed by a Rust/Wasm virtual filesystem and a synchronous shared-memory bridge instead of libuv.

The economics are what make this decisive. internal/bootstrap/realm lists the bindings a running Node needs, and the list is short:

buffer, cares_wrap, config, constants, contextify, fs, fs_event_wrap,
icu, inspector, js_stream, os, pipe_wrap, process_wrap, spawn_sync,
stream_wrap, tcp_wrap, tls_wrap, tty_wrap, udp_wrap, uv, zlib
(+ async_wrap, crypto, http_parser, signal_wrap, url, v8)

Roughly twenty-five bindings, against hundreds of JavaScript modules. Everything above the line is Node's own code, already correct, already battle-tested against the entire npm ecosystem. All the remaining work is below the line.

That is the whole trade. Path A means writing hundreds of modules and getting them approximately right. Path B means writing twenty-five bindings and getting them exactly right, because Node's internal callers are unforgiving about shapes. Harder in a smaller place.

Here is the result. Every module below is Node's own source, unmodified, executing in this page:

Why the foundation survived the pivot​

The uncomfortable question when you decide to throw away months of work is how much of the rest goes with it. In this case, almost none, and understanding why is the most useful part of the story.

The realisation was that our existing fs-client.js, the thing user code called to reach the virtual filesystem, was already an internalBinding('fs') in everything but name. It took a syscall opcode and arguments, packed them into shared memory, parked the thread, and returned bytes or an errno. That is precisely the contract Node's C++ fs binding fulfils.

The same held everywhere. The Rust virtual filesystem is what internalBinding('fs') needs to sit on. The PID table and process supervisor are what process_wrap and spawn_sync need. The virtual network is what tcp_wrap needs. The Atomics bridge is what makes any of them able to be synchronous.

So Path B was a pivot in the upper layers, not a rewrite. Everything below the binding line, the part that had been genuinely hard to build, was the part worth keeping. Path A had not been wasted either: writing the hand-rolled builtins is how we learned what the binding contract actually needed to be.

What it costs​

Being honest about the other side of the ledger:

The internal ABI is undocumented and unstable. You are writing against Node's private contract. Nobody upstream owes you compatibility, and pinning to a Node version is not optional.

Failures are opaque. When a binding returns a subtly wrong shape, the error surfaces somewhere in internal/streams/* with a stack trace full of Node internals and no mention of your code. Debugging means reading Node's source, which is a genuine skill investment.

Delivery gets heavier. Node's lib/ is a lot of JavaScript to ship into a tab, which pushes you into lazy loading and compression decisions you would rather not think about.

Against that: http, stream and crypto work, correctly, for real packages, today. That trade is not close.

The real test​

Compatibility claims are cheap. The honest test of whether you have a Node runtime is not whether hello world prints. It is whether software written by people who assumed a real Node install runs unmodified.

The hardest such software is the package managers. npm, yarn and pnpm are large, old, gnarly programs that touch every corner of the runtime and were absolutely not written with charity toward reimplementations. Getting them to run is the subject of the next post, and each one broke the runtime in a different, instructive way.

const config = fs.readFileSync("/app/package.json", "utf8");

That call has to return bytes. Not a promise, not a callback: bytes, on the next line. And reading those bytes means asking something else for them, which in a browser means waiting. Browsers are built on exactly one promise to the user: nothing blocks. So the very first thing Node requires is the one thing the platform refuses to do.

There is precisely one exception, and this post is about building on top of it.

Why you cannot just make it async​

The obvious dodge is to give up on synchronous I/O: rewrite the runtime around fs.promises, tell users to await everything, and move on. It does not work, for a reason that has nothing to do with taste.

Synchronous I/O is not a convenience in Node; it is load-bearing. require() is synchronous all the way down: resolving a specifier means statSync on a dozen candidate paths, then readFileSync on the winner, then compiling and executing it, before the calling module's next statement runs. execSync blocks a parent until its child exits. zlib.gunzipSync, child_process.spawnSync, crypto.randomBytes in its sync form. The whole ecosystem sits on this.

You cannot make require() async without breaking every CommonJS package ever published, which is most of npm. And you certainly cannot ship the real npm CLI, which is what we actually wanted to do. So the synchronous surface is not negotiable. Something has to genuinely block.

The exception: Atomics.wait on a worker​

The main thread may not block. A Web Worker may.

// Only legal off the main thread. This parks the OS thread (no spinning, no
// event loop, nothing runs on it) until someone notifies or it times out.
Atomics.wait(control, STATE, REQUEST);

Atomics.wait puts the calling thread to sleep on a word of shared memory. It is not a busy-loop and not a trick with XMLHttpRequest; the thread is actually parked, and it resumes when another thread calls Atomics.notify on the same word. Browsers allow it off the main thread precisely because a blocked worker cannot freeze anyone's tab.

That single primitive is the whole foundation. Run user code on a worker, give that worker a SharedArrayBuffer, and a synchronous call can become: write a request into shared memory, park, let another thread do the async work, get notified, read the response out. From inside user code, readFileSync returned bytes. Nothing async leaked.

process code (Web Worker thread)
   │  fs.readFileSync("/x")        ← looks synchronous to user code
   ▼
 write request into the SAB, Atomics.store(STATE, REQUEST), ring a doorbell
   │
   ▼  Atomics.wait(STATE, REQUEST)  (the thread genuinely blocks)
 ...another worker services it against the Rust/Wasm VFS...
   ▲
   └─ writes the response into the SAB, Atomics.notify(STATE)
   ▼
 returns bytes (still synchronous, no async leaked to user code)

Here it is running for real. Nothing below is awaited, and the round-trip is timed with performance.now() so you can see what a blocking syscall costs inside a browser tab:

The tax: cross-origin isolation​

SharedArrayBuffer was restricted after Spectre, and getting it back requires the page to prove it is not sharing a browsing context group with anything it does not trust. Concretely, every page that hosts the runtime must be served with:

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

Miss either header and SharedArrayBuffer is simply undefined. There is no degraded mode to fall back to; the runtime does not start.

This propagates further than it first appears. require-corp means every subresource on the page must opt in to being embedded, so a third-party image without a Cross-Origin-Resource-Policy header stops loading. An iframe is only cross-origin isolated if its embedder is too, which is why the page you are reading carries the headers as well: the live example above is an iframe, and it would not have SharedArrayBuffer otherwise.

It is worth being blunt about this cost, because it is the part people discover late. Adopting a browser Node runtime is not just an npm install; it is a decision about your document's headers, and therefore about every third-party script, font, and pixel on the page.

The layout, and the invariant that bites​

Every client (the kernel and each process) gets one SharedArrayBuffer, laid out as a small control block followed by a data region:

[ control: 4 × Int32 = 16 bytes ][ data region: 1 MiB ]

control[0] = STATE    (Atomics.wait / notify on this word)
control[1] = OPCODE   (which syscall)
control[2] = REQ_LEN  (request bytes in the data region)
control[3] = RES_LEN  (response bytes in the data region)

STATE moves between IDLE, REQUEST, RESPONSE_OK and RESPONSE_ERR; the error case carries a UTF-8 errno like ENOENT so that Node's own error construction upstack behaves normally. The request frame itself is self-describing ([flags:u32][fieldCount:u32]([len:u32][bytes])*) with scalars packed little-endian and everything else as raw bytes.

The interesting part is not the encoding. It is DATA_BYTES = 1 << 20.

Every request and every response must fit in one megabyte. That single constant has caused more bugs than anything else in the system, because it is invisible until a payload crosses it, and payloads cross it constantly:

• File I/O is chunked. Reads and writes loop at a 512 KiB chunk size, so arbitrarily large files transfer in pieces. There is a separate writeLarge path that skips the shared buffer entirely and transfers an ArrayBuffer instead. That becomes necessary the moment you try to write something like yarn's 5 MB bundled cli.js into the filesystem.
• HTTP responses are chunked. A Vite dev server happily serves a 2.8 MB pre-bundled dependency file. That body cannot cross in one message, so it is split into sequential frames reassembled by request id. It also travels as a raw length-prefixed field rather than inside JSON: escaping quotes and newlines inflates a body unpredictably, and the failure mode is a silent overflow rather than a clean error.
• Downloads bypass the window entirely. A fetch streams its body straight into the virtual filesystem through a dedicated worker; the caller then reads it back with ordinary chunked file reads. This is why npm tarballs of any size work.

If there is one lesson here, it is that a fixed-size shared window is not a detail of the transport. It is a constraint that reaches up through every layer above it, and every subsystem eventually has to answer for how it handles a payload larger than the window.

Who is actually awake​

Blocking is only safe if the thread you blocked is not the one that has to answer you. So the work is split:

• The main thread runs the UI and no runtime work at all. It never blocks, because it never participates.
• A kernel worker owns the PID table, process supervision, the virtual port registry, and HTTP routing.
• A filesystem worker owns the Rust/Wasm virtual filesystem. Every client registers its shared buffer with it and wakes it through a MessagePort doorbell.
• A fetcher worker performs all real outbound network requests, so downloading and decompressing a large tarball never stalls syscall servicing.
• Each process is its own worker with its own shared buffer, and its own event loop.

Some syscalls are deferred rather than serviced immediately: accept, spawn and blocking fetch leave the caller parked until the awaited event actually arrives. That is not a workaround, it is the point: it is how blocking accept() and execSync() get their semantics. A parked worker costs nothing while it waits.

What this buys​

None of the above is exotic on its own. Atomics.wait is a documented API and SharedArrayBuffer has shipped for years. What is interesting is how much falls out of taking the one available blocking primitive seriously and building the entire system to respect it: real require(), real execSync, real child processes, and, because the synchronous surface is honest, the ability to run Node's own source code rather than an approximation of it.

That last point is the subject of the next post: running Node's real lib/ in a browser tab, and why hand-writing stream and http was never going to work.

Vivari is MIT-licensed and the code is on GitHub.