A tab running nuxt dev was using 3.46 GB. That is not a number you optimise\nyour way out of with a hunch, and the hunch everybody has is the same one:\nbundlers are memory hogs, so it must be the bundler.
It was not the bundler, whose entire contribution was 22.5 MB. It was three\nother things, and they are not even measured in the same units: a filesystem\nholding 929 MB of node_modules as bytes, a persistence layer writing 4.7 GB to\nstore 53 MB, and an editor spending 621 MB parsing one set of type definitions\ntwice.
This post is the autopsy rather than a list of tips, because the useful part is\nwhich assumptions turned out to be wrong.
\n\nThe tab had already come down to 3.09 GB when it was measured properly. The\nsplit, on one machine running one project:
\n| what | resident |
|---|---|
PID 8, the nuxt dev process worker | ~1.87 GB |
| the filesystem worker | ~580 MB |
| eight other small process workers | ~175 MB total |
Inside that 1.87 GB dev server, the in-process esbuild Go heap was 22.5 MB.
\nThat single measurement killed the plan everyone arrives with. Isolating\nesbuild, tearing it down between builds, moving it to its own worker: all of it\nwould have saved approximately nothing, and all of it would have been weeks. The\nGo heap is 1.2% of the process it lives in.
\nMeanwhile the filesystem worker, which holds nothing but bytes, was the second\nlargest thing in the tab and the largest one we could do anything about. The\n1.87 GB above it is Nuxt's and Vite's heap, allocated by their code for their\nreasons. The 580 MB is ours. That is the finding.
\nEvery file in this runtime lives in a Rust virtual filesystem compiled to Wasm,\nwhich means every byte of node_modules is sitting in one linear memory. A\nmid-sized project's dependency tree is a few hundred megabytes of text that is\nread once at startup and then almost never touched again.
Text compresses. So cold file contents are zlib-compressed in place, behind a\ngate of two constants:
\nconst 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\nthan the win, and node_modules is full of eleven byte index.js files. Above\na 0.95 ratio, do not bother either: the file is already compressed, storing it\npacked 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\n29% ratio and 655 MB saved, and the whole Chrome tab dropped from 2.9 GB to\n2.1 GB.
\nIt is on by default in the SDK, and only an explicit compress: false turns it\noff. The Rust struct itself defaults to compression off, which looks like a\ncontradiction and is deliberate: it keeps the flag A/B testable from a\nbenchmark without touching the shipped default.
The gate is four lines of arithmetic, and it is the reason the number above is\n655 MB rather than something embarrassing. Here it is running against three\nkinds of file, using the same deflate from the same Rust crate the filesystem\ncompresses with:
\nThe third block is the one to read twice. A megabyte of random bytes deflates to\n1,048,752 bytes, which is 176 bytes larger than what went in, and the gate\ncorrectly stores it raw. That is the whole case for the ratio test: without it,\nevery .tgz, .png and .wasm in a dependency tree would be stored slightly\nbigger 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\nnot tell guest code what it decided about a file, so the script recomputes\nthe gate in front of you rather than reading its verdict. It is the same test on\nthe same bytes with the same compressor, and it is not instrumentation.
\nThe edit to make is SIZE. Drop it to 2048 and every sample is stored raw,\nincluding the one that deflates to a thousandth of its size, because it failed\nthe size test and the size test is the one the VFS checks first. The script\nstill prints a ratio for each, since it computes both tests rather than\nshort-circuiting the way the Rust does, and seeing beats 0.95 true sit next to\nthe VFS keeps it RAW is the clearest possible statement of what the first\nconstant is for.
A session survives a page reload by mirroring the filesystem into OPFS, the\nbrowser's origin-private file storage. The steady state is small: about 53 MB\nfor a real project. Getting there was costing 4.7 GB of writes.
\nThree offenders, and none of them is a large file:
\n_cacache/tmp/<uuid> cost 1,461 MB\nacross 76 writes, and npm deletes it moments later. We were faithfully\npersisting a scratch directory so that it could be faithfully persisted again\nas it changed, and then removed._logs/*-debug-0.log cost 607 MB across 3,799 writes,\nbecause a log file is appended a line at a time and a mirror that does not\nunderstand appends rewrites the file each time.Total after fixing all three: about 144 MB, for the same 53 MB of durable state.
\nThe general shape here is worth naming, because it is not specific to browsers.\nWrite amplification is invisible in every profiler you would normally reach for:\nmemory looked fine, the filesystem looked fine, and the only symptom was that\ninstalls felt slower than the network could explain. You have to go and count\nthe writes.
\nMonaco runs a separate full language service for each of its typescript and\njavascript modes. Each one parses the whole dependency .d.ts payload into\nroughly 310 MB, so a project with both kinds of file naively pays about 621 MB,\nmeasured, for two services doing identical work over identical inputs.
Mapping .js files to the typescript mode halves it. TypeScript's language\nservice handles JavaScript perfectly well; it is the same compiler.
That is a configuration change, and it is in this post rather than a footnote\nbecause 310 MB is larger than most of the things people spend a week optimising,\nand it was found by reading a memory profile rather than by reasoning about the\ncode.
\nTwo things that look like they should be slow, measured so nobody has to guess:
\nFilesystem write throughput. Writing a 12,000 file tree, the first 1,000\nfiles cost 6.9 microseconds each and files 11,000 to 12,000 cost 3.6\nmicroseconds each. The whole tree lands in about 44 milliseconds. Install time\nlives in the network, in tar extraction, in npm's own JavaScript, and in the\nOPFS mirror. It does not live in the virtual filesystem.
\nRegistry metadata, sort of. A full install pulled 421 MB of packuments\nwithout an .npmrc, and 108 MB with one that restricts the fields requested.\nThe registry gzips them about tenfold, so the wire cost is around 45 MB while\nthe cost of holding and parsing them is the full 421 MB. That is a case where\nthe network number and the memory number differ by an order of magnitude and\nonly one of them is the problem.
There is one more measurement in this family, from shipping a prebuilt\nnode_modules snapshot for a template. Cold origin, Chrome, Starlight: fetch\n0.4s, restore 4.0s for 13,459 entries, dev server listening at 31.8s, and OPFS\nholding 112 MB instead of 246 MB. The asset is 111.4 MB raw and 26.0 MB gzipped,\nand its buffer is transferred rather than copied between workers. The\ninteresting row is the restore: 4.0s in the browser against 0.1s headless, and\nthe entire difference is the OPFS mirror. Again the storage layer, not the\ncompute.
A Node process that runs out of memory throws, prints a heap trace, and dies\nalone. Under a memory ceiling, a browser tab does not do that.
\nRunning the tab in a container with a roughly 1.6 GB ceiling, the kernel\nSIGKILLs the renderer, with error code 9 and a cgroup failure count\nclimbing. Not one worker: the whole tab. What the user sees is Chrome's crash\npage, not a frozen terminal and not an error in the console, and nothing in the\nruntime gets a chance to report anything.
\nThat changes what the memory work is for. It is not about being tidy. Past the\nceiling there is no graceful degradation available, because the process that\nwould have degraded gracefully no longer exists.
\nprocess.memoryUsage() in\na guest process returns fixed constants, so a script running in the sandbox\ncannot observe any of this. Every figure above comes from browser task\nmanager and profiler measurements taken outside the runtime, which is also\nwhy the demo above measures the gate rather than the saving..d.ts files.Three findings, and the thing they have in common is that none of them is about\nthe code that was doing the work.
\nThe bundler, the compiler, the dev server: those are what a profile looks like\nit should be about, and between them they were a rounding error against a\nfilesystem full of text, a mirror writing gigabytes to store megabytes, and an\neditor holding two copies of the same parse.
\nIn a browser tab, the interesting resources are the ones the platform makes you\nimplement yourself. On a laptop, node_modules costs page cache that the kernel\nreclaims when it feels like it, and nobody counts it. Here it is a Rust HashMap\nyou allocated, and it is on your bill. Persistence is a mirror you wrote rather\nthan a filesystem the OS provides, so its write amplification is yours too. The\nplatform is not doing you any invisible favours, which is inconvenient and,\noccasionally, clarifying: everything that costs something is something you can\nsee.
More on the architecture in\nthe how-it-works docs, and the post that\nexplains why the filesystem lives in a Rust module at all is\nthe one about the single blocking primitive.
\nVivari is an open-source, MIT-licensed WebContainer: no commercial licence, no\nper-seat fee, self-host every asset. The code is on\nGitHub and the\nStudio runs in your browser.
", "url": "https://vivari.run/blog/the-memory-budget-of-a-tab", "title": "A Nuxt dev server in a tab cost 3.46 GB, and the biggest thing we could actually shrink was the filesystem", "summary": "Three findings from profiling a real project in a browser tab, each of which contradicted the obvious guess. The largest addressable object in the process is node_modules, persisting 53 MB was costing 4.7 GB of writes, and the IDE was paying twice for one language service.", "date_modified": "2026-09-06T00:00:00.000Z", "tags": [ "Teardown", "Browser platform", "WebAssembly" ] }, { "id": "https://vivari.run/blog/bun-without-bun", "content_html": "Bun is a single native binary written in Zig around JavaScriptCore. There is no\nwasm32 build of it, there is not going to be one soon, and a browser tab\ncannot execute a Mach-O or ELF file regardless.
So bun index.ts in a page is not Bun. It is Bun's API, implemented on top of\nthe Node runtime these posts keep describing,\nand the honest version of that sentence is the whole subject here. A\ncompatibility shim is only useful if you can tell, from inside it, which parts\nare real. Most of this post is about the parts that are not, and how they say\nso.
bun and bunx are ordinary coreutils, installed eagerly rather than lazily\nunpacked on first use, because unlike the\nreal vendored npm, yarn and pnpm CLIs\nthere is no tarball to unpack: they are purpose-built shims running on the same\nruntime your code runs on. bun run, bun test, bun build and the Bun\nglobal are all implemented here. bun install is not: it delegates to the real\nnpm CLI, because reimplementing a resolver would be a worse lie than borrowing\none. The TypeScript in index.ts is handled by\nthe synchronous stripper that every other .ts file in the\nruntime goes through, not by Bun's transpiler.
Most of the surface is uninteresting in the good way. Bun.escapeHTML,\nBun.deepEquals, Bun.stringWidth, Bun.semver, Bun.Glob, Bun.which,\nBun.gzipSync are small pure functions with a specification and a test. There\nare two places where that stopped being true.
Every other Bun API had something underneath it to delegate to. bun:sqlite did\nnot: there is no SQLite in the Node runtime to borrow, and the API is\nsynchronous by design. db.query(sql).all() returns rows, not a promise.\nThere is nowhere to await an engine booting.
The engine is the official @sqlite.org/sqlite-wasm build, the same C source\nSQLite's own test suite covers, compiled by the SQLite authors. It is\ncommitted to the repository at 844 KiB alongside a manifest recording the\nupstream version and SHA-256, rather than fetched at build time, because both\nspike tiers need it on a bare checkout and a spike that skips when its artifact\nis missing looks green while proving nothing. The refresh script validates the\nbinary it pulls: magic bytes, required exports, that its imports are a subset of\nwhat the loader supplies, and that its declared memory minimum still fits. An\nupstream build that changed its ABI fails the refresh rather than failing at\nsomebody's first query.
The Emscripten glue is not used. The package ships 578 KB of it, and it is\nuseless here twice over: it is async-init, meaning it fetches and calls\nWebAssembly.instantiate, and it routes file I/O through MEMFS or NODEFS,\nneither of which exists in this environment. So the loader supplies the module's\n36 imports itself and instantiates with a bare new WebAssembly.Module(bytes)\nfollowed by new WebAssembly.Instance(...). Both are synchronous, which is\nillegal on a main thread and legal on a worker, which is where all guest code\nruns. It is the same trick\nthe llhttp binding uses.
The memory is created on this side, 128 pages initial and 2 GiB maximum,\nunshared, because the build imports memory rather than exporting it. Growth goes\nthrough emscripten_resize_heap, and every cached typed-array view has to be\nre-derived whenever memory.buffer identity changes, since growth detaches the\nold ArrayBuffer. That is the sort of detail the glue would normally handle and\nthe reason people use the glue.
And then the part that makes it worth doing. A sqlite3_vfs is registered\nwhose xOpen, xRead, xWrite, xTruncate, xFileSize, xDelete, xAccess\nand xFullPathname call the runtime's own fs, which is\nthe SharedArrayBuffer syscall bridge. So a .sqlite\nfile is an ordinary file in the virtual filesystem. It shows up in the file tree,\nit outlives the process that made it, and the next process reads it. The reads\nand writes take explicit offsets, which is exactly the pread and pwrite a\nSQLite VFS wants.
SQLite needs real C function pointers for those callbacks, and\nWebAssembly.Table.prototype.set will not accept a plain JavaScript function.\nSo each callback is wrapped in a hand-assembled 40-byte Wasm module that imports\nthe function and re-exports it, and the export goes into\n__indirect_function_table. Forty bytes of hand-written Wasm per callback is\neither the ugliest thing in this repository or the most satisfying, depending on\nthe day.
Two semantics are implemented rather than approximated, because approximating\nthem corrupts data. safeIntegers governs reads: true returns exact BigInts,\nfalse returns Numbers, lossily above 2^53, which is Bun's documented\nbehaviour and the reason the toggle has to exist. Binding is exact either way, so\na bigint argument goes in through sqlite3_bind_int64 and one outside int64\nrange throws a RangeError naming the value instead of wrapping it. And\ndb.transaction() nests through SAVEPOINT, with nesting decided by\nsqlite3_get_autocommit rather than a counter we keep, so a hand-written\nBEGIN in the middle of things does not desync it.
Roughly thirty Bun APIs in this shim do nothing but throw. That file is the best\nwriting in the repository, and its argument is this: there are two reasons an\nAPI can fail, and telling someone the wrong one wastes their afternoon.
\n\"<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,\ndlopen(3), an OS keychain, engine internals. No amount of shim work changes\nit, and the code has to run somewhere else. The second means it could work here\nand nobody has written it: a gap, not a limit.
Conflating them is its own kind of dishonesty. \"Not supported\" tells you to stop\nand redesign. \"Not implemented\" tells you to file an issue or send a patch.\nWhere an API is half of each, and a TCP client is exactly that, since it can\nreach another in-VM process forever but can never reach the internet, the\nmessage says both, in that order.
\nThere is a second rule, and it is the one that keeps projects alive. The\nsymbol is always exported. The throw is always on the call. So\nimport { dlopen } from \"bun:ffi\" still loads, and a property read during some\ndependency's module-level feature detection still returns a function. A\nload-time throw is strictly worse: one unused import at the top of a transitive\ndependency takes down a project that never touches the API.
The catalogue covers Bun.listen, Bun.connect, Bun.udpSocket,\nBun.RedisClient, Bun.sql, Bun.postgres, Bun.Terminal, Bun.WebView,\nBun.mmap, Bun.peek, Bun.secrets, Bun.dlopen, the zstd helpers,\nBun.generateHeapSnapshot, Bun.openInEditor and the whole of bun:ffi. The\nnative addon half of the same file is not Bun-specific at all: require(\"bcrypt\")\nfrom plain Node code hits precisely the same wall, and one catalogue of \"impossible\nin 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\nbelow is running Bun's API in this page: a block of one-line results, a visible\npause while argon2id does its 64 MiB of work, real SQLite reporting its own\nversion number and three rows, and then a refusal.
\nThe block at the bottom is the part to play with. Uncomment any line and run it\nagain, and you get the exact sentence that API throws. The two message shapes\nare visibly different, which is the entire point of there being two.
\nBun.password is genuine argon2id at Bun's own documented cost parameters:\n64 MiB of memory, two passes, one lane. Measured in Wasm under Node on one\nmachine, hashing takes about 97ms and verifying takes about the same, and in a\nbrowser tab it is somewhat slower again, which is the pause you just sat through\nin the demo. That number is supposed to be large. A password hash that returns\ninstantly is a password hash that is not doing its job, and the most common way to get\ncompatibility wrong here would have been to substitute something cheaper and\ncall it argon2id.
Bun.hash was wrong and is now pinned. It started as a bespoke\nmultiply-xor hash that agreed with real Bun on nothing at all, which is a\nperfectly good hash function and a completely useless compatibility shim, since\nthe entire value of Bun.hash is that two systems compute the same number. It\nis now wyhash final v3, checked against published vectors.
Bun.sleepSync used to spin. Right duration, one core pinned at 100% for\nit. It now parks on Atomics.wait, with the spin left in as a documented\nfallback for a browser main thread, where parking is illegal.
bun:test is stricter than real Bun in one place.\nexpect(settledPromise).rejects.toThrow() returns undefined in real Bun; this\nrunner always returns a real promise, and drains outstanding async assertions\nafter each test body. A snapshot file written here has been read and passed by a\nreal bun test, which is the strongest compatibility evidence in the shim.
Bun.build is notIt is not esbuild. There is no tree shaking and no minifier, and minify,\nsplitting, sourcemap, bytecode and --compile throw rather than silently\nproducing something that does not match the option you asked for. It bundles,\nand that is the extent of the claim.
Streaming is the other place to be careful. A ReadableStream response body is\nbuffered in full: measured at 25 MB into an unread socket with writableLength\nnever leaving zero. Backpressure never engages. It is left honestly buffered\nrather than half-implemented, which is the right call and is also a real limit\nif you were planning to stream a large file out of Bun.serve.
bun:sqlite has three limits, each a sandbox fact rather than a\nshortcut. xSync is a no-op because the runtime's fsync is, so the\nrollback journal is still written and replayed and a crash mid-transaction\nrecovers, but power loss is not survivable the way real SQLite promises.\nThere is no file locking, so two processes writing one database can corrupt\nit, and this matches what upstream ships: the official build's default VFS is\nliterally unix-none, SQLite's lock-free one. And journal_mode = WAL needs\nshared memory across processes, so it is declined with a one-time warning and\nSQLite stays in delete mode, which is SQLite's own documented behaviour when\na VFS cannot do WAL. ORMs that set WAL opportunistically therefore keep\nworking.The temptation in a compatibility layer is to make the surface as wide as\npossible, because the surface is what a table on a marketing page measures. Every\nAPI you stub to return a plausible empty value makes that table better and makes\nthe layer worse, because the failure moves from your code to the user's, six\nframes deep, with a message that names neither of you.
\nThe two sentences at the top of that refusal file are worth more than any of the\nAPIs underneath them. A shim's honesty is a feature with a spec: name the API,\nsay which of the two kinds of failure this is, and say what to do instead. It\ncosts one string per function and it is the difference between a limitation and\na bug report.
\nMore on the Bun surface in the Bun docs, and the\nprevious post covers\nwhy every import in this runtime is rewritten to CommonJS at load time.
\nVivari is an open-source, MIT-licensed WebContainer: no commercial licence, no\nper-seat fee, self-host every asset. The code is on\nGitHub and the\nStudio runs in your browser.
", "url": "https://vivari.run/blog/bun-without-bun", "title": "Bun runs in the tab and there is no Bun in it, so the interesting part is what refuses", "summary": "Bun is a Zig binary with no wasm32 build, so bun index.ts in a browser is an emulation over the Node runtime. The engineering worth reading about is bun:sqlite driving a bare sqlite3.wasm, and a refusal policy with two message shapes.", "date_modified": "2026-08-30T00:00:00.000Z", "tags": [ "Teardown", "Runtime", "Bun" ] }, { "id": "https://vivari.run/blog/synchronous-esm", "content_html": "Recent Node versions will let you require() an ES module. It is a genuinely\nhard thing to have shipped, and it comes with two documented refusals:\nERR_REQUIRE_ASYNC_MODULE if anything in the required graph uses top-level\nawait, and ERR_REQUIRE_CYCLE_MODULE if the graph has a cycle that crosses the\nCommonJS boundary.
Node can refuse, because import() is always sitting there as an escape hatch.\nTell the user to await it and the problem is theirs.
In a browser worker there is no escape hatch. require() is\nsynchronous all the way down because the filesystem\nunder it is, and a project's entry point is required by a loader that cannot\nreturn a promise to anyone. Every import becomes CommonJS at load time or the\nprogram does not start. Refusing was not on the menu.
There is no bundler here and no compile step. Each module is rewritten as it is\nread, by es-module-lexer, into the same synchronous CommonJS everything else\nin the runtime lives in. import becomes a require, export becomes a\nproperty on an exports object, import.meta becomes a small object built from\nthe filename, and dynamic import() becomes a helper that returns an already\nresolved promise.
Every generated identifier is namespaced: __oc_require, __oc_import,\n__oc_exports, __oc_module. That is not tidiness. User code is allowed to\ndeclare its own require and its own module, and a great deal of published\ncode does.
The interop helpers are all emitted on one leading line, which looks like\nsomebody minifying for no reason. It is so that line numbers in the rewritten\nfile still match the file you have open, which is what makes\nbreakpoints land on the right line.
\nThat is the easy part. What follows is four years of other people's module\ngraphs.
\nAn ESM export is a binding, not a value. If a module exports let count and\nincrements it later, an importer that already read it sees the new number. Real\nESM gets that by being lazy at both ends: the exporter exposes a binding rather\nthan a copy, and the importer reads it at the point of use rather than at the\npoint of import.
This loader is lazy at one end and eager at the other, and the asymmetry is\nworth stating before anything else in this section, because it is the one place\nwhere the rewrite is knowingly not ESM.
\nThe export side is getters. A module's own exports are exposed as accessors\non the exports object, which is how esbuild and rollup model the same thing.
\nThe import side is a snapshot. A used import { X } from './m' compiles to\nconst X = __oc_m['X']: one read, at the top of the importing module, and that\nvalue is what the rest of the body sees. Increment X in the source module\nafterwards and the importer will not notice.
Most code never sees the difference, because most imported names are functions,\nand a function is the same object before and after. It shows up on a mutable\nlet, 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\nare emitted before the import requires.
\nConsider a cycle, which npm is full of. Module A imports B, B imports A back. B\nruns while A's body is still on the stack. If A emitted its export getters after\nits own imports, B reads undefined from A, because A has not got to that line\nyet. yargs is the canonical case in the wild: command.js imports\nisYargsInstance from yargs-factory.js, which imports command.js right\nback. Put the getters first and an exported function, which is hoisted anyway,\nis 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\n\"circular import detected\". You get Astro's middleware reporting\nFunction.prototype.apply was called on undefined, four frames from anything\nyou wrote.
A second, subtler version of the same bug: a barrel file that imports a name and\nthen re-exports it. Astro's render/index.js does\nimport { Fragment } from './common.js' and then export { Fragment }. When\ncommon.js is mid-cycle, the eager const Fragment = common.Fragment snapshot\nhits a const that is still in its temporal dead zone, and you get\nCannot access 'Fragment' before initialization. So a re-export is compiled to\na lazy live binding to the source module rather than a read of the snapshot,\nwhich defers the read until the cycle has settled, exactly as\nexport { X } from 'm' already did.
And the getters have to close over their own key. export * copies names in a\nloop, and a getter that closes over the shared loop variable resolves every name\nto the last key of the object. Vue's index.mjs re-exports everything, so\ncreateApp quietly became withScopeId, and Nuxt's server rendering then read\n.config off the wrong object. Per-iteration closure, one line, found the\nexpensive way.
That leaves the general case. A cycle whose imported name is a const, a class\nor a singleton has no barrel shape to exploit: the eager const X = __oc_m['X']\nsimply runs too early and throws Cannot access 'X' before initialization. Astro's\nruntime is full of them, apiContextRoutesSymbol, AstroConfigSchema,\nglobalContentLayer, telemetry.
So there is a second compiler. When a module's eager attempt throws a\nReferenceError whose message matches \"before initialization\" or \"is not\ndefined\", the loader recompiles that one module with every import bound as a\ngetter on an __oc_live object, and runs the whole body inside\nwith (__oc_live) { ... }. A bare reference to an imported name then resolves\nlazily through the getter, at use, which is what real ESM does, while a local\ndeclaration that shadows the name still wins natively. That is what makes it\nscope-correct without rewriting a single reference, and rewriting references\ncorrectly is the part nobody wants to hand-roll.
Two reasons it is a fallback rather than the default. with deoptimises the\nwhole body and requires sloppy mode, so a normal module should not pay for it.\nAnd it is safe to re-run only because the eager attempt threw in the prelude,\nbefore the body ran: the retry re-defines configurable export getters and\nre-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\nthe script itself and then imported. The line to look at is the first\nreporter: line, which prints count = 0 from inside the cycle while\ncounter.mjs is still evaluating.
The last reporter: line is the whole section, and it is worth separating\nfrom the line under it. That third reporter: line is reporter.mjs printing\nits own bare named import, count, after two bump() calls, and it says 2.\nThat looks like a live binding and is not one. It is the fallback:\nreporter.mjs reads count while counter.mjs's let count is still in its\ntemporal 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\nof the sort. That one is counter.count, a property access on the namespace\nobject, which goes through the export getter every time it is evaluated. It is\nlive with a cycle and without one, because the export side was never the\nproblem.
Take the cycle away and the two lines stop agreeing. A plain non-cyclic module\nthat does import { count, bump }, calls bump() twice and then logs count,\nprints 0 here and 2 under Node, because nothing threw, so nothing was\nrecompiled. Read the same value off a namespace instead and you get 2 either\nway. Nothing warns you which of the two you wrote. That is the sharpest edge in\nthis loader and it is the reason the honest list at the end of this post has the\nbullet it has.
Every module body in the demo is a string you can edit. The other instructive\nchange is to delete the __esModule line from legacy.cjs and run it again,\nfor the reason in the next section.
__esModule is not proof of a default exportWhen you import x from a CommonJS module, what should x be? Node's answer is\nsimple and total: module.exports, always. Babel's answer, which the entire\ntranspiled ecosystem is built on, is that a module carrying the __esModule\nflag was originally ESM, so x should be its .default.
Both are defensible. The trouble is that tsc --module commonjs stamps\n__esModule on every file it emits, including the ones that only ever assign\nnamed exports. The flag means \"transpiled\", and the unwrap needs \"has a\ndefault\".
@embroider/core is one of those files: flag set, no default key. So\nimport core from '@embroider/core' handed @embroider/vite undefined, and\nEmber's config load died at const { cleanUrl } = core. The fix is to require\nthe key to exist as well as the flag, which keeps the Babel unwrap that real\nexport 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\nsomething I am volunteering. The dynamic import() helper deliberately does\nnot use that narrower test. It still treats __esModule as proof of an ESM\nnamespace, so (await import('<tsc-emitted-cjs>')).default is undefined here\nwhere Node gives you module.exports.
That is not laziness. Narrowing it the same way would break the other direction:\nour own transpiled ESM sets __esModule too, and a module with no\nexport default would then get a synthesised ns.default = m that Node never\ngives it. Telling those two cases apart needs a marker that __esModule cannot\ncarry. It is a known divergence, recorded rather than papered over, and it is\nthe 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\nresolve to a module namespace, not the raw require() value. Returning the\nbare exports left a CommonJS default import with no default key, which almost\nnothing noticed because real code mostly reads it through the static path. Vite's\nserver-side module runner does notice: it asserts 'default' in mod for\nexternalised CommonJS dependencies, and threw\nNamed export 'default' not found. The requested module 'cssesc' is a CommonJS module\non Astro.
Top-level await is the case Node declines outright, and it is not optional here:\nVite's own binary starts with await import('node:inspector').
The wrapper each module is compiled into is a plain, non-async function, so\nnew Function rejects the parse. The fix is to recompile the ESM body as an\nAsyncFunction, which makes the module evaluate to a promise that gets threaded\nthrough 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\nnot tell you. At the top level of a non-async function, await x parses await\nas an identifier, so the error names the next token. You do not get \"await is\nonly valid in async functions\". SvelteKit's core/sync/ts.js does\nts = (await import('ts')).default, which after the import rewrite is\nawait __oc_import('ts'), and the parser's verdict is\nSyntaxError: Unexpected identifier '__oc_import'.
Sniffing that message reliably is hopeless, so the loader does not try. Any\ncompile failure on an ESM file is retried as an AsyncFunction. Real top-level\nawait then compiles; a genuine syntax error fails again and is reported with the\nfilename appended. The retry is on the error path only, so the happy path pays\nnothing.
The limit, stated plainly: only the entry module can block on top-level\nawait. A dependency deep in the graph that uses it is still not supported, and\nthat is why PGlite ships in the templates as its CommonJS build\nrather than its ESM one. Choosing CJS there avoids the problem instead of\ndiscovering it.
\nes-module-lexer does not build an AST. It skims for the constructs it cares\nabout, which is why this is affordable to do on every module of every install\nrather than once in a build step.
The cost is that skimming has to be exactly right about where strings, template\nliterals and comments end. A coarse template skip that ignores ${}\ninterpolation desyncs on modern bundled code: a regex inside an interpolation in\n@vitest/pretty-format was misread as a string, which swallowed the matching\nbrace and lost every top-level export after it. The module then compiled with\nno exports and the importer got an empty object.
So the skimmer descends into interpolations properly. It is still a skimmer, and\nthat is the trade being made: a parse of every file would be correct and would\ncost more than the rest of module loading put together.
\nNode's loader is not the only thing that has to be synchronous. A .ts file has\nto become JavaScript before the ESM rewrite sees it, with no tsc, no esbuild,\nand no await, which means a dependency-free token rewriter whose output has to\nparse.
The hard problem in a type stripper is <. Deciding whether it opens a generic\nor is a less-than comparison needs the previous token: an identifier, a closing\nparenthesis or a closing angle bracket means a generic at a declaration or call\nsite. A generic arrow function is a separate case, because it begins an\nexpression rather than a declaration.
Three of its bugs made it into a release, and their symptoms are a nice ladder.\nThe type skipper counted braces only at depth zero, so Array<{ detail: string }>\nleft }>; behind as live code, which at least fails loudly at load. as and\nsatisfies were treated as cast keywords after any token, so\nBun.semver.satisfies(...) was eaten as a type assertion: the call vanished, the\nimporter got undefined, and the process exited zero. A stripper bug that\nthrows is a bug. A stripper bug that succeeds is a support ticket six months\nlater.
import.meta.resolve against a real registry of module\nrecords. The semantics that survive are the ones that can be modelled in\nCommonJS plus getters, which turns out to be most of them, and it is not all\nof them.let from a module with no cycle,\nand expects to see later writes to it, reads the value it saw at import time\nand is given no warning. Two smaller consequences of the fallback itself:\nassigning to an imported binding inside it is a silent no-op where real ESM\nthrows, and an import used at top-level initialisation inside a cycle still\ncannot be satisfied, because the source genuinely is not ready.(await import(x)).default differs from Node for a tsc-emitted CommonJS\nmodule, deliberately, for the reason above.export * from a module that later mutates its own exports object is\noutside what getters copied at load time can model.Every one of the bugs in this post came from running a real project rather than\na test suite, which is a statement about coverage as much as about the bugs.\nYargs, Vue, Astro, Ember, SvelteKit, Vitest and Vite each found something no\nfixture had.
\nThe interesting thing about this subsystem is that it exists because of a\nconstraint one layer down. Nothing about ESM demanded a lexer and a getter\nprotocol; the synchronous filesystem did, and the filesystem is synchronous\nbecause 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\nluxury of having somewhere else to send people. Take it away and you find out\nwhich parts of the module system are semantics and which parts were always just\nscheduling.
Mostly it is scheduling. The two exceptions, real top-level await in a\ndependency and the __esModule ambiguity, are documented above rather than\nhidden, because a loader that is quietly wrong about a module's shape is the\nworst possible thing to have underneath a package manager.
More on the runtime in the architecture docs,\nand the post that explains why any of this has to be synchronous is\nthe one about the single blocking primitive.
\nVivari is an open-source, MIT-licensed WebContainer: no commercial licence, no\nper-seat fee, self-host every asset. The code is on\nGitHub and the\nStudio runs in your browser.
", "url": "https://vivari.run/blog/synchronous-esm", "title": "Node can require() an ES module now, and it refuses two things. We could not refuse either", "summary": "ESM is asynchronous by design and require() is synchronous by contract. Node resolves that by declining the hard cases. In a browser worker there is no escape hatch, so every import is rewritten to CommonJS by a lexer at load time, and this is what that costs.", "date_modified": "2026-08-23T00:00:00.000Z", "tags": [ "Teardown", "Runtime", "Node.js" ] }, { "id": "https://vivari.run/blog/a-debugger-with-no-inspector", "content_html": "A breakpoint is not a feature you write. It is a favour the engine does you.\nWhen you set one in VS Code, nothing in your program changes: V8's inspector\nholds the isolate, walks the real call stack, and hands back scopes it already\nhad. Every step debugger you have used is a thin client in front of that.
\nA Web Worker has no inspector. There is no --inspect port to open, no\ninspector binding to require, no way to ask the engine to stop. So the first\nquestion here was not how to build a debug UI. It was where a pause could\npossibly come from.
If the engine will not stop your code, your code has to stop itself. That means\nthe source that runs is not the source you wrote.
\nacorn parses the guest's own file and weaves in probes: __vvdbg.line before\neach statement, __vvdbg.brk for a literal debugger;, __vvdbg.push and\n__vvdbg.pop around calls so there is a shadow call stack to report. Each\nlexical block also gets a __vv_ev eval closure, which is the unglamorous piece\nthat makes Variables and evaluateOnCallFrame show the block you are actually\nstanding in rather than the function's outermost scope.
Where this happens in the pipeline is the part that took thought. The\ninstrumentation runs after the TypeScript and JSX strip, so acorn is looking\nat plain ES rather than syntax it does not know, and before\nthe ESM to CommonJS rewrite, so line numbers still match the\nfile the reader has open in the editor. One layer earlier and the parse fails on\na type annotation. One layer later and every breakpoint lands on the wrong line.
\nThere is a bailout, and it matters more than it looks. If acorn throws for any\nreason, the module self-heals to the original source and runs uninstrumented.\nYou lose breakpoints in that one file. You do not lose the program.
\nThe whole thing lives in a lazy import() chunk of roughly 195 KB, fetched only\nwhen a debug buffer is present. A normal run never parses a byte of it.
Everything else in the runtime rides one 1 MiB\nSharedArrayBuffer per process: write a request, Atomics.wait, get notified,\nread 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\nparked in the middle of a __vvdbg.line probe, halfway down the user's own call\nstack. The syscall buffer is a channel for a client that is asking questions. A\npaused process is answering them.
So a debug target gets a second, independent buffer, allocated only when\nVV_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\nCDP command into the data region, stores DBG_STATE_CMD, and notifies. The\nworker wakes up inside the probe, with the user's stack still intact above it,\nruns the command, and parks again. stepOver, getProperties,\nevaluateOnCallFrame, all of it happens on a thread that is technically in the\nmiddle of executing line 41.
That gives two transports for one protocol, and the split is by state rather\nthan by message type. A running process receives commands by postMessage,\nbecause it is still turning its event loop and can pick them up. A paused\nprocess receives them through the buffer, because it is not turning anything.\nThere is also a --inspect-brk-style start gate, since a twelve line script\nwould otherwise be finished before the frontend finished attaching.
Speaking CDP to a runtime with no inspector looks like cargo cult. It was the\nbest decision in this subsystem, and we only found out later.
\nThe alternative was a bespoke debug API, which would have been smaller and would\nhave fit the shape of what actually exists here. What CDP bought instead was a\ncontract that already had two consumers: the studio's debug panel drives Monaco\ngutter breakpoints, the paused-line highlight, and a VS Code style Call Stack,\nVariables and Watch tree, all in the vocabulary of Debugger.scriptParsed,\nDebugger.paused and Runtime.getProperties. None of that had to be invented.
Then came Python.
\n.py files now get the same pause, step, inspect and evaluate over the same\nprotocol and the same buffer. The studio is unchanged. It speaks CDP, it keeps\nbreakpoints per virtual filesystem path, and it never had a reason to know what\nlanguage 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:\nCPython already has what the JavaScript side had to build.
\nNo instrumentation. CPython's frames are real. There is no acorn, no probe\nweaving, no shadow call stack, no line number preservation problem. What is left\nis the protocol and the transport, and those were reused as they stood.
\nPEP 669, not sys.settrace. This is the interesting half, because it is the\ndifference between a debugger you can leave attached and one you have to\nremember to turn off. A settrace hook is called on every line of every\nfunction and has no way to say \"stop calling me about this one\". Measured on\nthis build, on one machine, with a 300,000 iteration loop:
| what is attached | cost |
|---|---|
| nothing | 22ms |
sys.settrace with a hook that does a dict lookup and returns | 217ms |
sys.monitoring answering DISABLE | 23ms |
sys.monitoring with a breakpoint on the hot line | 83ms |
A debugger that makes the program ten times slower is not observing the program;\nit is changing it. PEP 669 landed in 3.12\nand this interpreter is 3.14, so the callback can return\nsys.monitoring.DISABLE, which permanently retires that bytecode location. A\nline that is not a breakpoint is asked about exactly once and then costs nothing\nfor the rest of the run. The 83ms row is a breakpoint on the hot line itself,\nwhich 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\nmake and boring to take on trust. The interpreter below is running in this page,\nand it measures all three for itself. Watch the middle number, and then watch\nthe two counts underneath it:
\nThe timings depend on your machine and on what else it is doing, and the ratio\nbetween them is the part that holds. The counts do not depend on anything:\nsettrace is handed 600,006 line events and sys.monitoring is handed 10. That\nis the same loop, the same breakpoint table, and five orders of magnitude\nbetween how often the debugger was asked.
The edit worth making is at the bottom of the file. Put a line number from\ninside hot() into BREAKPOINTS and run it again: the third number climbs,\nbecause that one location stops answering DISABLE and CPython goes back to\nasking about it on every iteration. It does not climb all the way to the\nsettrace figure, and the gap between the two is exactly what DISABLE is\nbuying on every other line in the function.
There is a price for DISABLE, and stepping is where you pay it. Once a\nlocation has been retired it never fires again, so single stepping has to call\nrestart_events() to un-retire everything it disabled. Code outside the user's\nproject roots is dropped on its first line, which is what keeps a breakpoint\nanywhere in your file from tracing all of import pandas.
The hot path stays in Python: a set lookup per candidate line. JavaScript only\ngets involved once a pause has been decided, and then it runs the entire CDP\nconversation by calling back into the interpreter for frames, scopes, reprs and\neval. JavaScript inside a Python call, calling Python again, is the same\nre-entrant shape as the blocking stdin syscall, which is either reassuring or\nalarming depending on your temperament.
python and python3 used to be on the debug skip list. They now carry a\ndebugLang: \"python\" label that travels with the buffer from the kernel worker\nthrough the process worker into the runtime, and exactly one of the two backends\nattaches.
Without the label the JavaScript backend does what it is supposed to do, which\nis the wrong thing: python is itself a Node program, so it would instrument\nour own four thousand line launcher shim and offer you breakpoints in it. That is a\ndebugger correctly debugging a program nobody asked about.
A related bug took a while to find and is worth writing down because the symptom\nwas silence. Running python main.py compiled the script under the name\nmain.py, while breakpoints are keyed on absolute virtual filesystem paths. So\nnothing ever matched, no breakpoint ever bound, and the program simply ran to\ncompletion. A debugger that does not stop looks exactly like a debugger that is\nnot attached.
Signals are the other half of interrupting a program, and CPython broke the\nmodel. The pending signal bitmask is only ever observed by JavaScript, either at\na syscall park or on an event loop turn. A guest running CPython in Wasm is\ndoing neither: the worker thread is inside the interpreter's eval loop and will\nnot return to JavaScript until the Python code finishes. The kernel's only\noption was the one it takes for any guest with no handler, which is to kill it.
\nCPython's Emscripten build already solves its half by polling a byte of shared\nmemory and raising KeyboardInterrupt at the next bytecode boundary. So SIGINT,\nand only SIGINT, is mirrored into the first byte of control[5], previously\nreserved padding in the syscall control block. Wasm is little-endian by\nspecification, so that is byte 20 everywhere this runs. The interpreter clears\nthe byte itself when it acts. Measured latency is about 5ms.
The handler is registered only while the interpreter is running user code,\nbecause registering it is what tells the kernel not to kill this process, and\nthat is a promise you can only keep while there is an interpreter running to\ntake the interrupt.
\nThe Node debugger is verified by a spike with 27 assertions covering\ninstrumentation, breakpoint binding including conditional breakpoints,\npause and step, scope and evaluateOnCallFrame including the temporal dead\nzone, a top-level debugger;, the real buffer channel, and an end-to-end\nworker_threads pause, evaluate and resume over that buffer. That is what it is\ntested to do.
Four limits, by name:
\nAtomics.wait is\nillegal. Pausing it needs a resumable transform, continuation passing or\ngenerators, over the guest's source. Nobody has written that.EINTR and it does not do that yet.The Node half of this is a workaround. Instrumenting source to fake a capability\nthe platform withholds is not elegant, and if a browser worker ever grows an\ninspector, most of instrument.js should be deleted that afternoon.
The part worth keeping is the protocol choice. Picking Chrome DevTools Protocol\nwhen there was no Chrome in the picture cost a little up front and paid for\nitself the day a second language arrived, because the expensive half of a\ndebugger is the frontend, and the frontend never learned that Python existed.\nTwo backends, one of which needs a parser and a shadow stack and one of which\nneeds neither, meet at the same twenty CDP methods and the same three events.
\nPicking somebody else's interface when you have no obligation to is usually\noverengineering. It is occasionally the cheapest thing you will ever do.
\nMore on the runtime in the architecture docs,\nand the previous post covers\nwhy every import pandas in a tab used to be the first one.
Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no\nper-seat fee, self-host every asset. The code is on\nGitHub and the\nStudio runs in your browser.
", "url": "https://vivari.run/blog/a-debugger-with-no-inspector", "title": "A step debugger with no inspector to talk to, and the second SharedArrayBuffer that makes it pause", "summary": "There is no V8 inspector in a Web Worker, so a breakpoint had to be built out of acorn probes and a second shared buffer. Then CPython arrived and needed none of it, which is how we found out the protocol was the right thing to have picked.", "date_modified": "2026-08-16T00:00:00.000Z", "tags": [ "Teardown", "Runtime", "Node.js", "Python" ] }, { "id": "https://vivari.run/blog/cpython-startup-in-a-tab", "content_html": "On your laptop, the first import pandas of the day is slow and every one after\nit is fast. You have probably never thought about why. CPython compiles the\npackage's .py files to bytecode, writes that bytecode into __pycache__, and\nnever does it again.
Run Python inside a browser tab, where every command is its own process with its\nown interpreter and a freshly unpacked copy of every package, and something\nuncomfortable follows. There is no second time. Every import pandas is the\nfirst one.
Pyodide compiled CPython to WebAssembly, including the C\nextension modules that make NumPy and pandas possible at all. That is theirs,\nand this post does not improve on it. Vivari runs Pyodide's build of CPython\n3.14 unmodified.
\nWhat Vivari adds is the operating system around it: a filesystem that outlives a\nprocess, a process table, and the caches described below. The first half of this\npost uses a Pyodide API and says so. The second half is a CPython behaviour that\nPyodide deliberately turns off, and turning it back on correctly turned out to\nbe the interesting part.
\nEvery python command in Vivari is a real process with its own worker, and\ntherefore its own interpreter. That is what makes a crashing script harmless,\nand 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\nimport or a slow download. It is the interpreter initialising itself, producing\nthe same bytes it produced the last time and will produce the next time.
\nPaying nearly two seconds before a one line script can print anything is the\nsingle worst thing about Python in this environment, and it is worth noticing\nthat it is a pure waste rather than a tradeoff. Nothing about the result varies.
\nPyodide can serialise a just-booted interpreter's linear memory and start\nanother interpreter from it. The API is _makeSnapshot on load and\nmakeMemorySnapshot() afterwards, it is marked experimental, and it does the\nhard part. Vivari's contribution is narrower: making one process's snapshot\nusable by the next process.
Measured on the same build:
\n| step | cost |
|---|---|
| boot CPython normally | 1843ms |
| restore from a snapshot | 205ms |
| write the 31 MB snapshot | 71ms |
| read it back through the VFS | 47ms |
So the first command of a session boots the slow way and keeps the bytes, and\nevery command after it spends about 250ms getting an interpreter instead of\n1843ms. The REPL, pip, pytest, all of them.
Why the filesystem and not memory. The snapshot has to outlive the process\nthat made it and be visible to a process that does not exist yet. Those\nprocesses share exactly one thing, which is the virtual filesystem. It goes in\n/var/cache, where the kernel already keeps transient caches and which the\nfilesystem worker excludes from OPFS persistence.
That exclusion is deliberate rather than incidental. A snapshot is only valid\nfor the interpreter build that made it, and it is 31 MB. Persisting it across\npage reloads would spend a real and permanent storage cost to save 1.6 seconds\non one command per session. So a reload starts cold, on purpose.
\nWhy it is safe to share between processes. Restoring a snapshot in a\ndifferent JavaScript realm from the one that made it is the load-bearing\nassumption here, and it is tested rather than hoped: the test tier makes a\nsnapshot in one worker thread and restores it in two others, then imports\npackages, writes files and raises a traceback in each. Two Web Workers are two\nrealms in the same way.
\nTwo guards, because a corrupt interpreter is a terrible failure mode. The\nsnapshot bytes are written first and a small JSON sidecar second, which makes\nthe sidecar a commit record: a half-written cache is one whose sidecar does not\nagree with it, and it is ignored rather than restored. Then a restored\ninterpreter is asked to prove it is one:
\n__import__('json').dumps([__import__('sys').version_info[0], 1 + 1])
That costs about a millisecond, and it is deliberately not 2 + 2. Arithmetic\nwould survive a restore that had destroyed the import system. This touches the\nfrozen stdlib and string formatting, which is the machinery a bad restore takes\nout. It cannot prove that subtle corruption is absent. What it buys is that an\nobviously broken snapshot costs one cold boot rather than a baffling failure\ninside somebody's own program.
If anything at all goes wrong, the command boots the slow way and says nothing,\nbecause a cache that has to be explained is a cache with a bug.\nVV_PYTHON_SNAPSHOT=0 turns it off.
Removing interpreter start-up exposes the thing it was hiding, which is larger.\nOn the same build:
\nimport pandas: 2.3simport matplotlib.pyplot: 1.9simport numpy: 0.5sAlmost none of that is the package doing anything. It is CPython compiling\naround a thousand .py files to bytecode, having compiled the same files to\nbyte-identical bytecode a moment earlier in a different process.
CPython solved this decades ago. The reason its solution does not apply here is\none line: Pyodide sets sys.dont_write_bytecode. Which is a perfectly\nreasonable default when every interpreter is thrown away, and exactly wrong once\none of them can leave something behind.
Unsetting it is free. Measured on numpy, an import with bytecode writing enabled\ncosts 423ms against 420ms with it disabled. So there is no compile step anywhere\nin what follows. There is only keeping what an import already produced.
\nBoth of those are checkable rather than something to take my word for, so check\nthem. The interpreter below is running in this page, and it prints its own\nversion and the two settings this section is about:
\nIt is the standard library only, which is the stable part of Python here. Run it\nonce and you pay for fetching the interpreter and a cold boot. Run it a second\ntime and you are watching the snapshot from the first half of this post do its\njob, because that is a new process with a new interpreter in it.
\n.pyc files have opinions about timeTurning the flag back on and copying the __pycache__ tree between processes\ndoes 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\nimport, CPython compares that recorded mtime against the source file's current\nmtime, and if they differ it throws the cached bytecode away and recompiles.\nThis 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\nthe source files' mtimes are the time of the unpack, which is different on every\nsingle run. Every cached .pyc would be stale the moment it arrived, every\ntime, and the cache would do nothing except cost disk.
PEP 552 has the answer, and has had it\nsince Python 3.7. A .pyc can be hash-based instead of timestamp-based: it\nrecords a hash of the source rather than its mtime. That is precisely what a\npackage installer writes, for precisely this reason, because an installer also\ncannot 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\ncompilation. The marshalled code object, which is the whole expensive part, is\nbyte-identical. Only the sixteen byte header changes. Harvesting the entire\nbytecode tree for numpy and pandas costs 115ms.
PEP 552 also defines two flavours of hash-based .pyc, checked and unchecked,\nand the choice here matters. A checked one re-reads and re-hashes the source on\nevery import, which is most of the I/O this cache exists to avoid. Unchecked\nfiles are taken on trust.
The claim being made by choosing unchecked is that a wheel's files do not change\nwhile its version stays the same. That is not a shortcut invented here. It is\nthe same claim pip makes, and the cache is keyed on package name and version so\nthat the claim stays true.
\nThe bytecode does not land next to the source. sys.pycache_prefix puts it\nin a tree of its own. Otherwise __pycache__ directories appear inside the\nuser's project, show up in the file explorer, and get mirrored back into the\nvirtual filesystem as though the script had written them.
That setting has a trap in it worth writing down, because it fails silently.\nCPython builds the directory tree under the prefix by walking up from the\n.pyc's intended directory until it finds something that already exists. If\nthat walk runs off the top without finding one, it starts creating directories\nrelative to the current working directory instead, says nothing, and no bytecode\nis ever written where you are looking for it. The prefix's root has to exist\nbefore the first import.
Only installed packages are cached, never your own modules. The user's own\ncode gets bytecode too, since it is the same interpreter setting, but theirs\nstays in the per-process prefix and dies with the process, keeping CPython's\nordinary mtime checking. A released package's files do not change. Yours change\nconstantly, and a file you just edited must never be at risk of running as a\nstale copy.
\nThe cache is keyed on the interpreter's magic number as well as on package\nname and version, because bytecode from a different CPython is not bytecode.
\nLike the snapshot, this lives in the session's filesystem and goes when you\nreload, and VV_PYTHON_BYTECODE=0 turns it off.
CPython 3.14, pip and the REPL are shipped as stable in Vivari. The\nscientific stack that this post uses for its measurements, NumPy, pandas,\nMatplotlib, SciPy and scikit-learn, is experimental, along with pytest and\nthe notebook. The caching described here applies to every Python command either\nway, and it is not what decides those labels.
Two limits worth stating plainly:
\nThe numbers in this post are from the vendored build on one machine. They are\nhere to show the shape of the problem, which is a factor of about seven on\ninterpreter start-up once the read is counted, not to be a benchmark you should\nquote.
\nBoth halves of this came from the same question, asked twice: what is this\nprogram recomputing that it already computed?
\nThe interpreter produces identical bytes on every boot. Compiling pandas\nproduces identical bytecode on every run. Neither is a hard problem in\nprinciple, and in both cases the actual work was not making the cache fast but\nmaking it correct: a commit record so a half-written snapshot is never\nrestored, a probe so a broken one is caught, hash-based .pyc files so a\ncached compile is never wrongly trusted, and a hard line at the boundary of the\nuser's own code so an edit always wins.
That last one is the rule the whole thing hangs on. A cache that is occasionally\nwrong about your own source is worse than no cache, by a margin that no amount\nof saved seconds closes.
\nMore on all of this in the Python docs, and\nthe previous post covers how Flask, Django and FastAPI serve real requests with\nno socket underneath.
\nVivari is an open-source, MIT-licensed WebContainer: no commercial licence, no\nper-seat fee, self-host every asset. The code is on\nGitHub and the\nStudio runs in your browser.
", "url": "https://vivari.run/blog/cpython-startup-in-a-tab", "title": "There was never a second import pandas, and PEP 552 is why there is now", "summary": "Every python command in the browser boots its own CPython, so __pycache__ never got a second run to be fast on. Fixing it took a memory snapshot and a twenty year old detail of how .pyc files decide they are stale.", "date_modified": "2026-08-09T00:00:00.000Z", "tags": [ "Teardown", "Python", "WebAssembly" ] }, { "id": "https://vivari.run/blog/python-web-servers-without-sockets", "content_html": "Every Python web framework bottoms out in the same two lines, whatever it calls\nthem:
\nsock.bind((host, port))
sock.listen(backlog)
A browser tab does not have that. There is no TCP stack in a page, no file\ndescriptor to bind, and no amount of WebAssembly changes it. So the interesting\nquestion is not whether you can run Flask's Python in a browser, because you\ncan. It is what happens when someone types flask run.
Worth being exact about this up front, because the rest of the post only makes\nsense once the line is drawn.
\nPyodide compiled CPython to WebAssembly. That is their\nwork, it is a large piece of engineering, and nothing here reimplements any of\nit. The interpreter running in Vivari is Pyodide's build of CPython 3.14, with\nits standard library and its C extension modules, unmodified. When this post\nsays \"the interpreter\", it means theirs.
\nWhat Pyodide does not ship, because it cannot, is an operating system: a\nfilesystem shared with other programs, a process table, a port registry, a\nsocket. Vivari is the layer that supplies those. This post is about exactly one\nof them, and it is the one people ask about first.
\nThe obvious expectation is that import socket fails and the frameworks fail\nloudly with it. That is not what happens, and the real behaviour is the reason\nthis needed designing rather than documenting.
There is a socket module, inherited from the POSIX layer underneath the\nWebAssembly build. connect() succeeds. bind() succeeds. listen() succeeds.\nThen no bytes ever move, and select() never reports the socket readable. That\nis not a defect anybody introduced; it is what a POSIX shaped API looks like\nwhen there is no network stack beneath it to say no.
Point Django's development server at that and it does the worst possible thing.\nIt prints its banner:
\nStarting 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,\nnothing logged, no clue in the output that the server you are looking at is\nincapable of serving. A missing feature that announces itself is a small\nproblem. A missing feature that looks like a working one costs somebody an\nafternoon.
\nSo the design rule for everything below is that a socket must never be the thing\nwe quietly rely on.
\nHere is the piece that makes the rest possible, and it is an accident of how\nVivari is put together rather than anything clever about Python.
\npython in Vivari is not a Python program. It is a Node program, running on\nVivari's Node-compatible runtime, and it boots Pyodide inside itself. That\nruntime has a real require(\"http\"), a real event loop, and a working\nserver.listen(port), because Vivari's kernel implements virtual ports: an\nExpress app in this environment gets a preview tab, and it does so without a TCP\nstack either.
Which means the interpreter that cannot bind a port is running inside a process\nthat already can.
\nbrowser -> 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.\nIt is handed a request the way a WSGI server hands one over, because that is\nprecisely what the layer above it has become.
\nWSGI is a good specification to be stuck with here, because it was never about\nsockets in the first place. PEP 3333 says a server calls\napp(environ, start_response) and reads the iterable that comes back. It says\nnothing about where the bytes came from.
So the Node side parses the request it received, and the Python side builds the\ndict:
\nenviron = {
\"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\nare honestly False. There is one interpreter and there are no OS threads, so\nan app that checks those flags before deciding whether a cache can be a plain\ndict gets a true answer rather than a conservative one.
Request bodies and response bodies cross the JavaScript and Python boundary as\nbase64 inside a JSON string. That is not elegant and it was chosen anyway: JSON\nstrings convert to Python str with no ambiguity, whereas handing typed arrays\nacross the boundary means reasoning about proxy object lifetimes at every call\nsite. The bridge is on the request path, so the failure mode that matters is a\nsubtle one, not a slow one.
That is a claim you should not take on trust, so here it is running. The code\nbelow is real CPython executing in this page, and you can edit it and run it\nagain. It builds the environ above, hands it to a WSGI application, and passes\nthe whole thing through wsgiref.validate, which is CPython's own PEP 3333\nconformance checker. If the standard library's validator returns without\nraising, what the bridge gives your app is a real WSGI call and not an\nimpression of one.
Two honest notes about that demo. It uses only the standard library, because\nthe CPython core is stable here while Flask, FastAPI and Django are shipped as\nexperimental templates, and a live demo is the wrong place to blur that\ndistinction. And it exercises the conversion rather than the tunnel: the\nenviron, the application call and the validation are the real thing, while the\npart that carries bytes in from the browser is the guest Node server described\nabove. The first run also has to fetch the interpreter, so it is slower than\nthe ones after it, which is the subject of the next post.
\nASGI needs more of the same, plus one thing that is easy to get wrong and\nproduces a symptom that points nowhere near the cause.
\nPreviews in Vivari are served under a path prefix, /preview/<port>/. The\npreview tunnel strips that prefix before the request reaches your process and\nsets x-forwarded-prefix so the app can learn what it was mounted under. The\nNode 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\nscope[\"path\"] to the path the tunnel handed over. That is wrong, and it is\nwrong in a way that only shows up on Mount().
ASGI defines path as the full request path, including root_path.\nroot_path names the prefix, it does not remove it. Starlette's\nget_route_path() subtracts root_path from path to get the routable\nremainder, so if you hand it a path that has already been stripped, it subtracts\na prefix that is not there. Top-level routes still match, because the subtraction\nfalls through harmlessly. Every Mount() misses, including the StaticFiles\nmount that a FastAPI app usually has, so the app comes up, the JSON endpoints\nwork, and the CSS 404s.
The fix is to put the prefix back before building the scope:
\n_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\nworth appreciating. SCRIPT_NAME and PATH_INFO are already the split form:\nthe prefix and the remainder are separate keys, so there is nothing to subtract\nand nothing to get wrong. ASGI collapsed them into one string plus a length\nconvention, and this is the bug that convention buys you.
Starlette and FastAPI let you write def endpoints as well as async def ones.\nA sync endpoint cannot be awaited, so Starlette runs it on a threadpool through\nanyio.to_thread.run_sync, which ends at threading.Thread, which under Pyodide\nraises RuntimeError: can't start new thread.
That would make every synchronous route in a FastAPI app a 500, which is most\nroutes in most tutorials.
\nThere is one interpreter and nothing else can be running in it, so the\nthreadpool is not buying isolation here, only a thread that does not exist.\nRunning the callable inline is the correct answer for this execution model:
\nimport 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\nthis takes effect for every sync route and every sync dependency, including ones\ndefined after the patch.
uvicorn, flask and gunicorn exist as commands. None of them imports the\npackage 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\nattribute you meant, and hands that to the bridge. Calling them shims\nundersells what they have to get right: the observable contract of gunicorn is\n\"your WSGI app is now served on this port\", and that contract is met. What\ncannot be met is gunicorn's process model, so those flags say so out loud rather\nthan being accepted and ignored. -w 4 warns that there is exactly one worker.\n--worker-class gevent stops, because serving you a different concurrency model\nthan the one you asked for is not a warning-level event.
Choosing gunicorn as the WSGI entrypoint rather than writing a django command\nis the reason Django works at all here. gunicorn is the seam every WSGI\nframework already reaches for, so Bottle and Pyramid arrive for free.
The argv parsing has one decision in it that is more interesting than argv\nparsing has any right to be. To know whether --log-level debug main:app has\ntwo tokens or three, you need to know which flags take a value. gunicorn's own\n--help declares about a dozen store-true flags and several dozen that take a\nvalue, 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\nfor a value-taker and it eats the next token, which is the app spec, and the\ncommand exits with no app specified. The user sees that immediately. Mistake a\nvalue-taker for a boolean and its value is left lying in argv to be picked up as\nthe app spec, and the server cheerfully starts serving something nobody asked\nfor. Both are bugs. Only one of them is quiet.
python manage.py runserver does not run. It stops and says why, and points at\nthe command that works.
This is the only refusal in the Python support that blocks something people\ndemonstrably want, so it is worth defending. Every other entrypoint here hands\nyou an app object, which is a thing the bridge can serve. runserver binds the\nsocket itself. Given Pyodide's socket, that means it would start, print its\nbanner, and answer nothing, which is the failure mode described at the top of\nthis post.
The rest of manage.py is untouched. migrate, makemigrations, shell and\ncreatesuperuser all run normally, because none of them is a socket.
python -m http.server is the neatest case, because it shows what the bridge\nmakes 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\nanswer. The value of -m http.server is that it is the directory listing you\nknow, the mimetypes table you know, the Range and If-Modified-Since\nhandling you know, and the 404 you know. A lookalike is worth much less than the\nreal one.
So the handler stays and the socket goes. BaseHTTPRequestHandler does all of\nits I/O through self.rfile and self.wfile, which\nStreamRequestHandler.setup() builds from self.connection by calling\nmakefile(). It never touches the socket directly. So a socket, as far as that\nclass 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\nthe work, and collect the raw response bytes out of out. The same guest Node\nserver carries them that carries Flask's.
Duck typing gets used to defend some questionable things. This is the case it\nwas invented for.
\nNeither of these was designed. Both are consequences of the constraints, noticed\nafterwards, which is usually a sign the layering is right.
\nThere is an exact moment when the filesystem is consistent. A served app\nthat writes a file, an upload or a SQLite commit, needs those writes mirrored\nback into the editor. On a normal server there is no clean moment to do that,\nbecause another thread is always mid-write. Here the handler has returned and\nthere are no threads, so the end of a request is a point where \"everything the\napp has written\" is a complete and correct answer. Persistence happens there,\nafter the response bytes are already out, and costs nothing on a request that\nwrote nothing.
\n--reload works, without a watcher thread or a subprocess. Real reloaders\nneed both: something to poll the filesystem, and a process to kill and respawn.\nNeither exists here and neither is needed. The virtual filesystem already pushes\nchange notifications, because that is how Vite's dev server sees your edits. And\nthere is no server process to restart, because your app is an object imported\ninto the bridge's process, so a reload re-imports the module and rebinds one\nname. A failed re-import puts the previous modules back and the old app keeps\nserving, which matters because a syntax error in a file you just saved is the\nnormal case rather than the exceptional one.
The Python web frameworks here are shipped as experimental templates. That\nis the project's own word for them, it is what the README says, and this post is\nnot the place to quietly upgrade it. Vivari's CPython core, pip and the REPL\nare stable. Flask, FastAPI and Django sit above them and are not.
The limits worth knowing before you try it:
\nrunserver is refused, as described above.url_for(), reverse() and\nrequest.url_for() stay inside the preview. A hardcoded /about escapes it.psycopg2 still has no\nwheel. Streamlit still stops on watchdog. This bridge is about serving an\napp you can already import.What is not caveated: a real Flask app, a real FastAPI app with real Starlette\nrouting, and a real Django app served through real gunicorn argv handling, all\nanswering real HTTP requests in a browser tab with no server anywhere and no\nsocket underneath.
\nEvery one of these posts has ended in the same place from a different direction.\nThe synchronous bridge works because Atomics.wait is\na real blocking primitive and the whole system was built to respect it. Node's\nreal lib/ works because Node already had a\nseam and we cut along it.
WSGI and ASGI are that same seam, and Python drew it years before any of this\nexisted, with none of it in mind. The frameworks were already written against an\ninterface that says nothing about sockets. All that was missing was something\nstanding on the other side of it.
\nThe next post is about a different Python problem entirely: why the first\npython command in a session costs nearly two seconds, why the second one used\nto as well, and what PEP 552 has to do with fixing it. There is more detail on\neverything above in the Python docs.
Vivari is an open-source, MIT-licensed WebContainer: no commercial licence, no\nper-seat fee, self-host every asset. The code is on\nGitHub and the\nStudio runs in your browser.
", "url": "https://vivari.run/blog/python-web-servers-without-sockets", "title": "Flask, Django and FastAPI answering real requests, with no socket underneath", "summary": "Pyodide gave us CPython in the browser. It did not give us a socket, and a Python web server is mostly socket. Here is the bridge that runs WSGI and ASGI apps anyway, and the Starlette bug that took the longest to find.", "date_modified": "2026-08-03T00:00:00.000Z", "tags": [ "Teardown", "Python", "Runtime" ] }, { "id": "https://vivari.run/blog/nextjs-rsc-in-a-tab", "content_html": "For most of this project's life, our notes said Next.js was out of reach. The\nreasoning looked solid: Next compiles with SWC, SWC is native Rust, there is no\nnative code in a browser tab, therefore no Next.js. A hard wall, filed away.
\nThat verdict was wrong, and it was wrong in the most ordinary way: we had\ndecided something was impossible and then stopped rechecking it.
\nnext dev --webpack now boots inside a browser tab, compiles an App Router\npage, renders React Server Components, and answers GET / → 200 with real HTML.\nNo server. The kernel, the filesystem, the process model, the dev server and the\nReact render all live in one tab.
Getting there was mostly unremarkable engineering, plus one problem that has no\ncorrect solution.
\n\nThree things had to be true at once, and all three already were:
\nNext 16 kept the Wasm SWC fallback. @next/swc-wasm-nodejs still exists,\nbecause Next still has to run in environments without a native binding. Next's\nown loadBindings prefers it when process.versions.webcontainer is set,\nwhich our runtime now reports, because that is exactly what we are.
webpack is still selectable. Turbopack is native Rust with no Wasm build, so\nit genuinely is unavailable. But --webpack remains a supported flag, and\nwebpack is JavaScript.
npm skips the native optional dependencies. On arch wasm32, the\n@next/swc-<platform> optionalDeps do not install, so the Wasm build is not\nmerely preferred, it is the only binding present.
So the wall was three assumptions that had each expired. Worth remembering next\ntime something gets filed as impossible.
\nThe rest of the work was the usual: vm.runInNewContext had to make the sandbox\nthe real global, so that globalThis.__RSC_MANIFEST = ... assignments in\nNext's generated manifest files actually land on the context object; without\nthat the client-reference manifest never loads. child_process.fork needed a\ngenuine IPC channel, because next dev forks its dev server and gates startup\non process.send existing. pathToFileURL had to resolve relative to absolute\nlike Node does. A handful of modules had to exist: dns/promises, stream/web,\nan inspector stub, module.findSourceMap, and the complete Console method\nsurface that @edge-runtime/primitives binds.
All generic. None of it Next-specific. Then there was the interesting one.
\nThe App Router's internals rely on AsyncLocalStorage. Its workStore and\nworkUnitAsyncStorage carry per-request context, and React's server rendering\nreads them from deep inside component code. If getStore() returns undefined\nat the wrong moment, you get:
Expected workStore to be initialized
In real Node, AsyncLocalStorage works because V8 exposes a PromiseHook.\nThe engine tells async_hooks when a promise is created, resolved, and\ncontinued, so the context can follow execution across a native await. Our\nruntime delegates to the host's async_hooks through the internalBinding seam\nwhen one exists, which is exact.
A browser has no PromiseHook. There is no way to observe a native await. You\ncannot know that this continuation belongs to that async context, because the\nengine never tells you.
This is worth sitting with, because it is a genuinely different class of problem\nfrom everything else in this series. Every other gap was work: read Node's\nsource, implement the binding, be precise. This one is a capability the platform\ndoes not have and cannot be made to have.
\nWhat we could do was stop trying to solve the general problem. A dev preview\nhandles one request at a time. That is a much weaker requirement than a\nproduction server, and within it the context can be tracked well enough to be\ndeterministic, not merely usually correct.
\nThree rules, each of which exists because a specific thing broke.
\nRule 1: a thenable-returning run(store, cb) holds its store until the\npromise 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\nlive nested scope. The \"never back to undefined\" clause is the one that took\nreal debugging. A streaming RSC render returns its promise early, as soon as\nthe stream is created, while React carries on rendering components detached\nacross native awaits. Zeroing the store when that early promise settles throws\nExpected workStore to be initialized in code that is still running. Restoring\na defined parent store is safe and keeps nested scopes correct; restoring\nundefined is not.
Rule 2: a plain, non-thenable return does not restore at all.
\nNext's renderToFlightStream returns a stream synchronously and does the actual\nrendering later, across raw awaits, with no promise for us to observe. If the\nstore is popped when run() returns, all of that detached work runs with no\ncontext. Leaving the store current keeps getStore() correct until the next\nrun() overwrites it.
This rule is, straightforwardly, a leak. In a general-purpose implementation it\nwould be wrong. Under one-request-at-a-time it is the behaviour that makes the\ndetached render work, and the next run() cleans up after it.
Rule 3: propagate a per-hop snapshot of every live store through the\nscheduling primitives React uses.
\nSpecifically Promise.prototype.then, queueMicrotask, setImmediate and\nsetTimeout. React's scheduler hops through these constantly, and each hop is a\nplace context would otherwise be lost. Snapshotting at schedule time and\nrestoring 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\nmatters: after the runtime's own timer globals are in place, and before any\nframework code loads, so React captures the wrapped primitives rather than the\noriginals. When the host provides real async_hooks, none of this is active.
A context bug that only appears under specific interleavings is the worst kind\nto claim you have fixed. \"It worked when I tried it\" is not evidence when the\nmechanism is inherently timing-sensitive.
\nSo the polyfill is tested by forcing it. VV_NO_HOST_ALS=1 disables the host\nasync_hooks delegation even where it is available, which means the headless\ntest suite exercises the browser path on a machine where the real one exists.\nThat gives two things: an oracle, and the ability to run the comparison under\nload.
The specific case that matters is the RSC refresh render: the App Router's\n\"on save\" re-render, the request with RSC: 1 that the HMR flow issues. That is\nthe path that threw workStore in the studio, so it is the path that has to be\ngreen.
The results we hold it to: GET / returns 200; the refresh render returns 200\nwith zero invariant errors across repeats; and the output is byte-identical\nto the host async_hooks path, under heavy-I/O perturbation, which is the\nwhole point. Byte-identical against a known-correct implementation is a much\nstronger claim than \"no errors observed\", and it is the only reason we are\ncomfortable describing the behaviour as deterministic rather than lucky.
One more detail that is easy to get wrong: Next resolves the Wasm SWC by\ndownloading it into its own cache on first compile. That is its intended\nbehaviour in Wasm environments and real Node does the same thing. The template's\npostinstall seeds that cache from the already-installed package so the first\ncompile is offline, with Next's own on-demand download left in place as the\nfallback.
Next.js is shipped as a stable template, in TypeScript and\nJavaScript, and the caveats are real:
\n--webpack is the path.AsyncLocalStorage polyfill targets a dev preview. It is correct for\none request at a time. It is not a general-purpose implementation and we would\nnot present it as one.What is not caveated: this is real Next.js from npm, real webpack, real SWC,\nreal React Server Components, rendering real HTML, with no server involved\nanywhere. You can open the Studio and pick the Next.js template right now.
\nEvery post in this series has landed in the same place, from a different\ndirection.
\nThe synchronous bridge works because\nAtomics.wait is a real blocking primitive and we built the entire system\naround respecting it. Node's real lib/\nworks because Node already had a seam and we cut along it.\nnpm, yarn and pnpm work because\nthe layers underneath implemented real specifications instead of the subset our\ndemos needed.
AsyncLocalStorage is the exception that proves the rule. There is no seam to\ncut, no specification to implement completely, no primitive to respect. V8's\nPromiseHook simply is not there. So the only honest move was to narrow the\nproblem until it was solvable, be explicit about the boundary, and test against\nthe real implementation rather than against our own expectations.
Sometimes the interesting engineering is admitting exactly how much of the\nproblem you actually solved.
\nVivari is an open-source, MIT-licensed WebContainer: no commercial licence, no\nper-seat fee, self-host every asset. The code is on\nGitHub and the\nStudio runs in your browser.
", "url": "https://vivari.run/blog/nextjs-rsc-in-a-tab", "title": "Next.js 16 renders React Server Components in a browser tab, and the AsyncLocalStorage trap", "summary": "We had written Next.js off as a hard native wall. That verdict was wrong. Getting RSC rendering in-browser came down to one primitive the platform cannot provide.", "date_modified": "2026-07-27T00:00:00.000Z", "tags": [ "Teardown", "Runtime", "Node.js" ] }, { "id": "https://vivari.run/blog/databases-and-the-http-parser", "content_html": "Two shorter pieces this time, connected by a theme:\nrunning Node's real source keeps paying\nout in places you did not plan for, and WebAssembly turns out to cover a lot of\nwhat \"you need a native binary for that\" used to mean.
\n\nNode's lib/http does not parse HTTP. It delegates to\ninternalBinding('http_parser'), which in real Node is llhttp, a C parser\ncompiled into the binary.
We had written a pure-JavaScript HTTP/1.1 parser to fill that binding. It\nworked, in the sense that ordinary requests went in and ordinary responses came\nout. It also had the failure profile every hand-written protocol parser has: the\ncommon path is fine and the edges are a long tail of things you have not thought\nabout yet. Trailers. HEAD responses, which have Content-Length but no body.\n204, which has neither. Chunked encoding with extensions. Pipelining. Upgrade\nand CONNECT hand-off, where the parser has to stop parsing mid-stream and hand\nthe raw socket over.
The right answer is to run the same parser Node runs.
\nWe did not build a toolchain to do it. Standing up wasi-sdk and clang just\nto recompile llhttp would produce an artifact essentially identical to one that\nalready ships publicly. undici bundles a prebuilt llhttp.wasm from the same\nupstream project, under the same MIT licence. So a vendoring script pins the\nundici version and regenerates a binding module with the binary base64-embedded,\nabout 54 KB. No fetch at runtime, no build dependency.
Two details made it interesting.
\nIt has to compile synchronously. The binding is constructed at process\nbootstrap, inside the\nsynchronous world everything else lives in, so\nthe module is built with new WebAssembly.Module() rather than the async\ncompile. That is allowed on a worker thread, which is where guest processes\nrun. On the main thread there is a 4 KB size cap on synchronous compilation, and\na 54 KB module throws, which turns out to be a convenient way to detect the\nenvironment. Exceeding the cap is precisely what trips the pure-JS fallback, so\nthe JS parser stays in the tree as the main-thread path rather than as dead\ncode. VV_HTTP_PARSER=js|wasm forces either side, with wasm failing loudly\ninstead of falling back, so tests can assert which one they exercised.
The bridge has to be numerically exact. llhttp reports progress through span\ncallbacks: on_url, on_status, on_header_field, on_header_value,\non_body, on_headers_complete, on_message_complete. Node's\nlib/_http_common.js does not consume those; it expects a specific set of\nnumeric kOn* slots. The binding mirrors what Node's own node_http_parser.cc\ndoes: drive llhttp's callbacks, fold them onto the exact kOn* contract, for\nboth requests and responses. allMethods follows llhttp's method enum, so\nallMethods[llhttp_get_method()] round-trips the way callers assume.
When the Wasm backend is live it advertises process.versions.llhttp, exactly\nas real Node does. Twenty offline checks guard it in CI, plus an extended HTTP\ncase covering HEAD, 204, chunked requests and responses, trailers and\nkeep-alive, run against both backends, because a fallback nobody tests is a\nfallback that does not work.
You can watch it parse. The server below binds a port inside this tab and then\nfetches from itself:
\n\"No native database\" is the limitation every in-browser runtime lists, and the\ndocumentation usually stops at suggesting workarounds.
\nIt is worth asking why the limitation exists. The blocker is not SQL. It is\nthat database clients are native addons, and there is no compiler in the tab. So\nthe question becomes: what do you need in order for a Wasm-compiled engine to\nwork, and do we already have it?
\nThe answer was yes, and it had nothing to do with databases. A Wasm SQL engine\nneeds a real fs to read its data files, a working url module, and the host's\nWebAssembly, all of which exist because of decisions made for other reasons.\nSo this was less a feature than a discovery.
SQLite via sql.js. SQLite compiled to Wasm. initSqlJs() finds its .wasm\nnext to itself with locateFile: (f) => require.resolve('sql.js/dist/' + f),\nwhich resolves over the virtual filesystem like any other module path.
PostgreSQL via PGlite. This is real PostgreSQL, currently 18, compiled to\nWasm. About 16 MB of pglite.wasm and pglite.data, read out of\nnode_modules through the virtual filesystem: the package resolves them from\n__filename, builds a new URL('./pglite.wasm', ...), and calls\nfs.readFile. Every step of that is ordinary Node behaviour, which is the whole\npoint.
One deliberate choice: we use PGlite's CommonJS build. The ESM build relies\non top-level await, and in-VM only the entry module can block on TLA. Choosing\nCJS avoids the problem entirely.
\nAnd one we deliberately did not ship. libSQL is not available as an in-VM\ntemplate, and the reason is worth stating rather than leaving as a gap in a\ntable. @libsql/client in local mode is a native N-API addon with no wasm32\nbuild. @libsql/client/web works, but only talks to a remote Turso server,\nwhich is a network client, not a database in the tab. Neither is\nself-contained, so neither belongs in a list of things that run with no server.\nsql.js remains the local SQLite path.
Both engines were confirmed end-to-end in plain Node first, against the same\nfs, url and WebAssembly primitives the runtime exposes, before either was\nwired into a template. Both are then gated by network spikes in CI that install\nthe dependency, bind a port, and assert that the API reports the right engine\nversion and returns seeded rows, with a longer budget for PGlite, whose install\nand first-boot Wasm compile are genuinely heavy.
Both of these landed for the same reason, and it is not cleverness.
\nThe HTTP parser worked because Node had already defined the seam\n(internalBinding('http_parser')) and someone had already compiled the C to\nWasm. The databases worked because the runtime implemented fs and url\nproperly rather than implementing the subset our own demos needed.
Neither was planned. Both fell out of building the layer underneath correctly\nand then discovering what it supported. That is a much better position to be in\nthan the alternative, and it is most of the argument for\nthe architecture these posts\nkeep coming back to.
", "url": "https://vivari.run/blog/databases-and-the-http-parser", "title": "llhttp in Wasm, and a real Postgres in the tab", "summary": "Two smaller teardowns. Replacing a hand-written HTTP parser with the same llhttp Node ships, and running PostgreSQL 18 with no server and no native addon.", "date_modified": "2026-07-20T00:00:00.000Z", "tags": [ "Teardown", "WebAssembly", "Runtime" ] }, { "id": "https://vivari.run/blog/three-ways-to-isolate-a-preview", "content_html": "When an in-browser IDE runs your dev server and shows you the result, the\nresult has to be served from somewhere. The easy answer is the origin you\nalready have: put the preview at /preview/5173/ on the IDE's own domain, let\nthe Service Worker route by path, ship it.
That is what we did, and it is a security problem.
\nSame origin means the same cookie jar, the same localStorage, the same\nIndexedDB, the same OPFS, the same Cache Storage, the same Service Worker scope.\nPreview code, which includes every npm package the project installed and\nanything an AI assistant just generated, sits inside the IDE's origin. It can\nread the editor's session state, corrupt its persistence, and call its\nsame-origin APIs. Previews are not isolated from the IDE, and they are not\nisolated from each other.
Fixing this properly took three attempts, and each one ran into a different\npiece of web platform trivia.
\n\nThe default, and the one to move away from.
\nhttps://ide.example.com/preview/5173/
The Service Worker intercepts requests under /preview/<port>/, strips the\nprefix, and relays them to the kernel, which it can find directly because it\nis same-origin with the tab holding it.
Zero extra infrastructure, and it works. But beyond the storage problem, path\nrouting quietly breaks things that a real server would get right:
\n| Keyed on origin | Breaks under shared-origin path routing |
|---|---|
Cookie jar (session, CSRF, SameSite) | frontend and backend cookies collide at / |
| localStorage / IndexedDB / OPFS / Cache | services share one store, state bleeds |
CORS and fetch credentials | cross-service calls look same-origin, wrongly |
| Service Worker scope | the app's own SW registrations collide |
| Absolute paths | router basename, /asset.png and <base> all break |
That last row is the one users actually report. Any app that assumes it is\nserved from / needs a prefix hack somewhere: in the SW, in the URL rewriter,\nor in the app's own config.
Move previews to a different origin entirely and the browser's same-origin\npolicy does the work for you. The kernel still lives in the IDE tab, so the\npreview's Service Worker reaches it through a hidden bridge iframe and a\nMessagePort.
Here the hosting platform pushes back. A Cloudflare Pages project only gets\n<project>.pages.dev, and you cannot mint preview.myproject.pages.dev. A\nsecond origin means a second Pages project.
Which sounds fine, and introduces the first real trap.
\npages.dev is on the Public Suffix List. That makes myproject.pages.dev\nand myproject-preview.pages.dev different sites, not merely different\norigins. As an isolation boundary that is stronger than you asked for: cookies\ncannot be shared even deliberately.
It also breaks popping a preview out into its own tab, in a way that cannot be\nworked around.
\nChrome storage-partitions cross-site contexts. The kernel is reached through a\nbridge iframe living in the editor tab; for a standalone preview tab to use that\nbridge's Service Worker registration and MessagePort, both have to be in the\nsame storage partition. Cross-site, they are not. And requestStorageAccess()\nun-partitions cookies, not Service Worker registrations, so the \"connect\nthis tab to its project\" gate can never actually bridge the two partitions. The\ngate appears, you grant it, and nothing changes.
Two subdomains of one registrable domain fix it. Serve the IDE at\nide.example.com and previews at preview.example.com, both CNAMEd to their\nPages projects, and the two are same-site: no partition wall exists, so the\npopped-out tab shares the bridge's Service Worker and reaches the kernel with no\ngate at all. Storage is still origin-scoped, so preview code still cannot touch\nIDE storage.
| Deploy | Same-site? | Partitioned? | Pop-out |
|---|---|---|---|
Two *.pages.dev projects | No, PSL cuts pages.dev | Yes | Gate appears, cannot be granted |
| Two subdomains of one domain | Yes | No | Connects immediately, no gate |
StackBlitz (stackblitz.com / webcontainer.io) | No, different domains | Yes | Gate, accepted deliberately |
The residual leak with same-site subdomains is domain-wide cookies: anything set\nwith Domain=example.com is visible to both. So do not set domain-wide cookies\non the IDE. For trusted first-party code this is the right trade. For untrusted\ncode at scale you want the cross-site boundary and you accept the gate, which\nis exactly the choice StackBlitz made, and it is a reasonable one for their\nthreat model, not an oversight.
There is one important caveat: you have to open the editor at\nide.example.com. Loading it via the raw .pages.dev hostname reintroduces\ncross-site and the gate comes back.
Mode B isolates previews from the IDE, but every preview still shares one origin\nwith every other preview, and the port is still in the path. Mode C gives each\nin-VM port its own origin:
\nhttps://k3f9a2xh--5173-vv.example.com/
The port moves into the hostname, so each preview gets genuine\nlocalhost:<port> semantics, with its own cookies, its own storage and its own\nCORS behaviour, and previews are isolated from each other as well as from the IDE.\nEverything on the \"breaks under path routing\" list above stops being a problem,\nand the prefix hacks come out of the codebase.
This is the model StackBlitz uses, and their URLs decode neatly:
\nhttps://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\nbite.
\nCloudflare Pages cannot do wildcard custom domains. They are exact hostnames\nonly. So the wildcard origin has to be a Worker bound to a route, serving the\nstatic Service Worker runtime and the bridge document. It runs no kernel and no\nIDE; it is pure static hosting for an origin that has to exist per port.
\nThe wildcard must be a prefix, so the tag must be a suffix. Cloudflare\nroutes only allow * at the start of a hostname. vv-*.example.com is an\ninfix wildcard and is rejected. That is why the marker is a suffix and the route\nreads *-vv.example.com/*, which has the pleasant side effect of being narrow:\nit matches Vivari preview hosts and nothing else on the zone. Anything else that\nreaches the Worker is passed straight through untouched.
Free TLS covers exactly one label. Cloudflare's Universal SSL issues a\ncertificate for the apex plus a single-level wildcard: *.example.com matches\nabc.example.com but not abc.def.example.com. So a scheme like\n*.preview.example.com is two levels deep, is not covered, and produces a TLS\nerror rather than a helpful message. Paid Advanced Certificate Manager fixes it;\nstaying free means keeping preview hostnames one level under the apex and\npacking the port into that single label, hence <token>--<port>-vv, all in one\nlabel.
Each preview response is then stamped with COOP: same-origin,\nCOEP: credentialless and CORP: cross-origin, so the IDE (which is\nrequire-corp) can embed the bridge iframe, and the Service Worker is allowed\nto claim root scope.
One thing worth being honest about, because it applies to every client-side\ncontainer including this one.
\nA preview URL is not a network address. It is a capability ticket that only\nworks inside the browser holding a kernel-connected Service Worker. The\nService Worker is a per-origin proxy running in your browser, and its live\nlink to the kernel is a MessagePort held in its memory.
The consequences are observable on StackBlitz and we inherit all of them:
\nwindow.opener channel to re-handshake.postMessage does\nnot cross the network.None of that is fixable within the no-server model, because the thing serving\nthe preview genuinely is not a server. A persistent, shareable preview URL\nrequires a real backend, which is a different product decision, not a bug to\nfile.
\n| A. same-origin | B. shared preview origin | C. wildcard per port | |
|---|---|---|---|
| Extra infrastructure | none | one more Pages project | custom domain + wildcard DNS + Worker |
| Port encoded in | path | path | hostname |
| Isolates IDE from preview | no | yes | yes |
| Isolates previews from each other | no | no | yes |
| Real per-port semantics | no | no | yes |
The modes are a deploy-time choice rather than a runtime toggle, which keeps the\ncore simple. Start at A if you are running your own trusted code and want zero\ninfrastructure. Move to B with same-site subdomains as soon as anyone else's\ncode runs in your previews. Go to C when previews need to be isolated from each\nother, or when apps genuinely need to believe they are on their own host.
\nThe deployment guide has the full\nsetup for each.
", "url": "https://vivari.run/blog/three-ways-to-isolate-a-preview", "title": "Three ways to isolate a preview, and the Cloudflare wildcard trick", "summary": "Serving a preview from the same origin as the IDE hands preview code your cookies, your storage and your OPFS. Fixing it runs into the Public Suffix List, storage partitioning and a TLS wildcard rule.", "date_modified": "2026-07-14T00:00:00.000Z", "tags": [ "Teardown", "Deployment", "Browser platform" ] }, { "id": "https://vivari.run/blog/real-package-managers-in-the-browser", "content_html": "Once you are running Node's real lib/ in a\ntab, the interesting question stops being \"can we reimplement npm?\" and becomes\n\"why would we?\". The package managers are just Node programs. If the runtime\nunderneath them is honest, the real CLIs should run unmodified.
They do. npm, yarn, pnpm and corepack in Vivari are the actual published\nreleases, vendored and executed as-is. But \"should run\" and \"runs\" are separated\nby every Node API each tool happens to touch, and the four of them touch almost\ndisjoint sets. Each one, in turn, walked into a different corner of the runtime\nand found the wall.
The retired approach was a Turbo-style installer that resolved a lockfile and\nwrote node_modules itself. It was fine for a demo and wrong for a product: it\nwas not npm, so it did not behave like npm, and every gap between the two was a\nsupport burden. The shipped studio boots the real thing instead.
Delivering a real CLI to a tab is a packaging problem. Each package manager is\ninstalled at a pinned version on the build host, its file tree is walked, and\nthe whole thing is written into one archive that ships as a static asset under\npackages/studio/public/vendor/. The archive is a deliberately boring custom\nformat 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\nbecause we control both ends and would rather not meet tar's long-path and\nGNU-extension edge cases, and npm's @npmcli/* paths are long enough to hit them.\nAnd the gzipped output is named *-pack.bin, not *.gz, on purpose:
\n\nStatic servers (Vite's sirv, many CDNs) treat a
\n.gzfile as\nTRANSFER-encoded and serve it withContent-Encoding: gzip, so the browser\ntransparently decompresses it before our fetch sees it, and our own gunzip\nthen 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\nDecompressionStream, and writes the tree into the virtual filesystem at\n/usr/lib/node_modules/npm in one batched transfer. A three-line shim lands on\nPATH at /bin/npm.js and does nothing but require the real\nbin/npm-cli.js. npm is loaded eagerly because almost every project needs it;\nyarn, pnpm and corepack are registered as lazy loaders and only fetched the\nfirst time you actually spawn them, so the sizes below are costs you opt into.
| Tool | Version | Delivered | Files |
|---|---|---|---|
| npm | 10.9.2 | ~2.8 MB gz | ~2400 |
| yarn (classic) | 1.22.22 | ~1.2 MB gz | 11 |
| pnpm | 9.15.9 | ~3.7 MB gz | ~898 |
| corepack | 0.35.0 | ~0.12 MB gz | 54 |
None of that is the hard part. The hard part is that a real CLI calls real Node.
\nnpm booted first, and getting npm -v to print 10.9.2 and exit 0 closed\nthree gaps that a reimplementation would never have surfaced, because they are\nabout being Node, not about installing packages. process had to be a genuine\nEventEmitter (npm's proc-log attaches listeners to it). A dynamic import()\ninside a CommonJS module had to route through our loader (npm does\nawait import('chalk')). And stdout.write(cb), process.exitCode and a single\n'exit' event all had to behave the way npm's exit-handler assumes. Fixing those\nwas less \"supporting npm\" and more \"finishing Node\".
Then there is the thing every in-browser runtime has to answer for: native\naddons. There is no compiler in a tab, and a .node binary could not be loaded\nif there were, because we run Wasm. But real npm runs a package's\ninstall/rebuild lifecycle script, which for a native package is\nnode-gyp rebuild, and a non-zero exit there aborts the entire install. So\nnode-gyp is stubbed to a non-fatal no-op:
\n\nTo keep installs working we make node-gyp a non-fatal no-op: the build is\nskipped and the script \"succeeds\". This mirrors how browser WebContainers\nhandle native deps: the package's JS fallback (or its wasm32-wasi build,\nauto-selected via optionalDependencies) is what actually loads at runtime.
\n
The rest of npm's needs are environmental. Registry requests go through a\nfetcher that strips the non-safelisted headers a browser would otherwise\npreflight and reject; downloads run through an async fetch op so npm's parallel\ntarball fetches are actually parallel; large writes bypass the shared buffer\npool; and npm_config_audit, npm_config_fund and the update-notifier are\nswitched off, with the cache pointed at an OPFS-backed directory so it survives\na reload.
Yarn classic is trivial to deliver (a bin/yarn.js entry and a ~5 MB\nwebpack cli.js, eleven files total) and instructive to run. It exercises a\nset of Node internals npm simply never reached, and lighting it up filled five\nmore compatibility gaps, all fixed down in packages/runtime/ where they help\nevery program and not just yarn.
The memorable one is graceful-fs, which yarn bundles through fs-extra.\ngraceful-fs patches fs by subclassing fs.WriteStream with\nfs$WriteStream.apply(this, arguments), the old prototypal-inheritance move,\nwhich throws against a modern class. Alongside it: process.memoryUsage()\n(yarn's reporter tracks peak memory), and internal/fs/dir for fs.opendir,\nwhich yarn trips indirectly because thenify-all runs promisifyAll(fs) over\nevery method it can find. A package manager that reflects over the whole fs\nmodule is an excellent conformance test you did not have to write.
pnpm was the one we expected to be hardest, and it was, because it uses the\nfeatures the others avoid. It drives real worker_threads for fetch and\nextract. It builds a symlinked node_modules: a content-addressable store\nplus symlinks into it, which means the virtual filesystem has to implement\nsymlink, readlink and lstat as first-class operations rather than\napproximations. The store's packages are shared via hard links, so the VFS also\ngrew a real link(2). What it does not get is reflink/copy-on-write, so the\nprebuilt *.node reflink addons, which only exist for macOS and Windows, are\ndropped 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.\nnpm makes them POSIX symlinks to the real .js; pnpm writes a #!/bin/sh\ncmd-shim that exec node \"$basedir/../vite/bin/vite.js\" \"$@\". Our loader cannot\nrun a shell script, so without help it hands that shell wrapper to the JS\ncompiler and gets SyntaxError: missing ) after argument list the first time\nyou run a pnpm-installed binary. The fix is a small, unit-tested unwrapper that\nparses the target .js out of the shell shim before runMain execs it. The\nonly genuinely missing runtime primitive was util.types.isBoxedPrimitive,\nwhich pnpm's JSON path uses; it went in with the rest of the boxed-primitive and\ntyped-array predicates.
corepack is the odd one out, because it is not a package manager at all. It is a\nversion manager: it reads a project's packageManager field, downloads that\nexact yarn or pnpm release, verifies it, and execs it. So it gets only a\n/bin/corepack.js shim and deliberately leaves the direct npm/yarn/pnpm\nshims alone: those stay the defaults, and corepack is the extra \"run the\nproject-pinned version\" path.
Its download-then-extract-then-exec pipeline surfaced five more gaps, again\nfixed generically: require('module').runMain, which corepack uses to exec the\ndownloaded manager in-process; Readable.fromWeb, so it can stream the tarball\nout of the global fetch() response body; WHATWG stream readers whose\nread()/cancel() promises properly ref the event loop, so a download does not\nrace the loop to exit; and crypto.Hash extending stream.Writable, so the\nidiomatic stream.pipe(createHash(algo)) works and the sha512 integrity check\npasses. The one thing our crypto layer cannot do is corepack's registry ECDSA\nsignature check (there is no crypto.verify), so the shell sets\nCOREPACK_INTEGRITY_KEYS=0, which is corepack's own supported escape hatch. The\ntarball's sha512 integrity is still checked.
None of these four required code that knows anything about installing packages.\nnpm needed process to be a real EventEmitter; yarn needed graceful-fs to\nbe able to subclass fs.WriteStream; pnpm needed symlinks and hard links to be\nreal filesystem operations; corepack needed WHATWG streams to ref the loop.\nEvery one of those fixes lives in the runtime, not in a shim, so it is there for\nthe next program too, which is exactly why\nthe next thing to run took less work than this did.
That is the whole bet behind running Node's real source:\nyou do not implement the tools, you implement the platform, and then the tools\nrun because they were always just programs. The argument is spelled out in more\ndetail in the architecture docs.
", "url": "https://vivari.run/blog/real-package-managers-in-the-browser", "title": "Real npm, yarn and pnpm in the browser, and how each one broke the runtime", "summary": "Not reimplementations. The actual npm, yarn, pnpm and corepack CLIs, vendored and run in a tab. Each one leaned on a different corner of Node, and fixing what it broke improved the whole runtime.", "date_modified": "2026-07-06T00:00:00.000Z", "tags": [ "Teardown", "Runtime", "Node.js" ] }, { "id": "https://vivari.run/blog/nodes-real-lib-in-the-browser", "content_html": "There are two ways to give a browser a Node-compatible runtime, and for a long\ntime we were confidently building the wrong one.
\nPath A is the obvious one: hand-write the core modules. Implement fs on\ntop of your virtual filesystem, implement path as string manipulation,\nimplement events as a small emitter, and keep going. It feels productive\nimmediately. path takes an afternoon. events takes a morning. fs takes a\nweek and mostly works.
Then you reach stream, and progress stops.
stream is not a big module because Node's authors were verbose. It is big\nbecause backpressure is genuinely hard, and because fifteen years of packages\nhave come to depend on the exact observable behaviour of that difficulty.
You can write something called Readable in a day. Making it emit 'readable'\nat the right moments, respect highWaterMark, handle a pipe target that\nreturns false from write, unpipe cleanly on error, support both flowing and\npaused modes, implement readableEnded versus readableFinished, and behave\ncorrectly when a subclass calls the constructor without new: that is not a\nday. And when you get one of those wrong, you do not get a clean error. You get\na dev server that hangs at 40% of a build, in a package four levels deep in\nsomeone's dependency tree.
http is worse, because it is a protocol parser plus a connection agent plus a\nstream implementation. crypto is worse still, because it is an ABI over\nOpenSSL. zlib needs a compression codec.
We had a runtime that could run a small Express app and could not run anything\nreal, with a queue of modules ahead of us that each represented months of work\nand would still be, at the end of all that effort, an imitation.
\nStackBlitz's WebContainer had clearly solved this. So we did the obvious thing\nand read their bundle, a ~2.1 MB file called builtins.2896b7f3.js.
The finding reframed the entire project:
\nThey do not hand-write Node's core modules. They ship Node's actual lib/\nJavaScript.
The evidence is not subtle once you look. The bundle exports an object with\nroughly 300 keys, and those keys are not a curated public API. They are Node's\ninternal module tree. Alongside fs, http, stream, crypto, zlib, net,\ntls and worker_threads sit internal/streams/readable, _http_agent,\ninternal/crypto/*, and internal/bootstrap/realm. Every module is wrapped in\na function taking (exports, require, module, process, internalBinding, primordials).
internalBinding and primordials are internal-only Node machinery. You do not\nend up with those identifiers by writing a compatibility layer. You end up with\nthem by shipping Node's source.
Once you see it, the architecture of real Node becomes the architecture of the\nsolution.
\nNode is two layers. On top is lib/*.js, tens of thousands of lines of\nJavaScript implementing streams, HTTP, crypto, the module loader, everything a\npackage 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\nthe shape of what comes back. That is a seam, and a seam is something you can\ncut along.
So: keep Node's JavaScript layer verbatim, and replace the C++ layer underneath\nwith your own implementation. When lib/fs.js calls internalBinding('fs'), it\ngets an object backed by a Rust/Wasm virtual filesystem and a\nsynchronous shared-memory bridge instead of libuv.
The economics are what make this decisive. internal/bootstrap/realm lists the\nbindings 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\nabove the line is Node's own code, already correct, already battle-tested\nagainst the entire npm ecosystem. All the remaining work is below the line.
\nThat is the whole trade. Path A means writing hundreds of modules and getting\nthem approximately right. Path B means writing twenty-five bindings and getting\nthem exactly right, because Node's internal callers are unforgiving about\nshapes. Harder in a smaller place.
\nHere is the result. Every module below is Node's own source, unmodified,\nexecuting in this page:
\nThe uncomfortable question when you decide to throw away months of work is how\nmuch of the rest goes with it. In this case, almost none, and understanding why\nis the most useful part of the story.
\nThe realisation was that our existing fs-client.js, the thing user code called\nto reach the virtual filesystem, was already an internalBinding('fs') in\neverything but name. It took a syscall opcode and arguments, packed them into\nshared memory, parked the thread, and returned bytes or an errno. That is\nprecisely the contract Node's C++ fs binding fulfils.
The same held everywhere. The Rust virtual filesystem is what internalBinding('fs')\nneeds to sit on. The PID table and process supervisor are what process_wrap\nand spawn_sync need. The virtual network is what tcp_wrap needs. The\nAtomics 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\nbinding line, the part that had been genuinely hard to build, was the part\nworth keeping. Path A had not been wasted either: writing the hand-rolled\nbuiltins is how we learned what the binding contract actually needed to be.
\nBeing honest about the other side of the ledger:
\nThe internal ABI is undocumented and unstable. You are writing against\nNode's private contract. Nobody upstream owes you compatibility, and pinning to\na Node version is not optional.
\nFailures are opaque. When a binding returns a subtly wrong shape, the error\nsurfaces somewhere in internal/streams/* with a stack trace full of Node\ninternals and no mention of your code. Debugging means reading Node's source,\nwhich is a genuine skill investment.
Delivery gets heavier. Node's lib/ is a lot of JavaScript to ship into a\ntab, which pushes you into lazy loading and compression decisions you would\nrather not think about.
Against that: http, stream and crypto work, correctly, for real packages,\ntoday. That trade is not close.
Compatibility claims are cheap. The honest test of whether you have a Node\nruntime is not whether hello world prints. It is whether software written by\npeople who assumed a real Node install runs unmodified.
The hardest such software is the package managers. npm, yarn and pnpm are large,\nold, gnarly programs that touch every corner of the runtime and were absolutely\nnot written with charity toward reimplementations. Getting them to run is the\nsubject of the next post, and\neach one broke the runtime in a different, instructive way.
", "url": "https://vivari.run/blog/nodes-real-lib-in-the-browser", "title": "Running Node's real lib/ in a browser tab", "summary": "We spent months hand-writing Node's core modules, then took apart a 2.1 MB StackBlitz bundle and threw the approach away. Here is what we found and why we pivoted.", "date_modified": "2026-06-25T00:00:00.000Z", "tags": [ "Teardown", "Runtime", "Node.js" ] }, { "id": "https://vivari.run/blog/blocking-in-a-browser", "content_html": "Every browser-based Node runtime runs into the same wall on day one, and it is\nnot the filesystem, the module resolver, or the process model. It is one line of\ncode:
\nconst config = fs.readFileSync(\"/app/package.json\", \"utf8\");
That call has to return bytes. Not a promise, not a callback: bytes, on the\nnext line. And reading those bytes means asking something else for them, which\nin a browser means waiting. Browsers are built on exactly one promise to the\nuser: nothing blocks. So the very first thing Node requires is the one thing the\nplatform refuses to do.
\nThere is precisely one exception, and this post is about building on top of it.
\n\nThe obvious dodge is to give up on synchronous I/O: rewrite the runtime around\nfs.promises, tell users to await everything, and move on. It does not work,\nfor a reason that has nothing to do with taste.
Synchronous I/O is not a convenience in Node; it is load-bearing. require()\nis synchronous all the way down: resolving a specifier means statSync on a\ndozen candidate paths, then readFileSync on the winner, then compiling and\nexecuting it, before the calling module's next statement runs. execSync blocks\na parent until its child exits. zlib.gunzipSync, child_process.spawnSync,\ncrypto.randomBytes in its sync form. The whole ecosystem sits on this.
You cannot make require() async without breaking every CommonJS package ever\npublished, which is most of npm. And you certainly cannot ship the real npm\nCLI, which is what we actually wanted to do. So the synchronous surface is not\nnegotiable. Something has to genuinely block.
Atomics.wait on a workerThe main thread may not block. A Web Worker may.
\n// 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\nis not a busy-loop and not a trick with XMLHttpRequest; the thread is actually\nparked, and it resumes when another thread calls Atomics.notify on the same\nword. Browsers allow it off the main thread precisely because a blocked worker\ncannot freeze anyone's tab.
That single primitive is the whole foundation. Run user code on a worker, give\nthat worker a SharedArrayBuffer, and a synchronous call can become: write a\nrequest into shared memory, park, let another thread do the async work, get\nnotified, read the response out. From inside user code, readFileSync returned\nbytes. 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\ntimed with performance.now() so you can see what a blocking syscall costs\ninside a browser tab:
SharedArrayBuffer was restricted after Spectre, and getting it back requires\nthe page to prove it is not sharing a browsing context group with anything it\ndoes not trust. Concretely, every page that hosts the runtime must be served\nwith:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Miss either header and SharedArrayBuffer is simply undefined. There is no\ndegraded mode to fall back to; the runtime does not start.
This propagates further than it first appears. require-corp means every\nsubresource on the page must opt in to being embedded, so a third-party image\nwithout a Cross-Origin-Resource-Policy header stops loading. An iframe is only\ncross-origin isolated if its embedder is too, which is why the page you are\nreading carries the headers as well: the live example above is an iframe, and it\nwould not have SharedArrayBuffer otherwise.
It is worth being blunt about this cost, because it is the part people discover\nlate. Adopting a browser Node runtime is not just an npm install; it is a\ndecision about your document's headers, and therefore about every third-party\nscript, font, and pixel on the page.
\nEvery client (the kernel and each process) gets one SharedArrayBuffer, laid\nout 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\nerror case carries a UTF-8 errno like ENOENT so that Node's own error\nconstruction upstack behaves normally. The request frame itself is\nself-describing ([flags:u32][fieldCount:u32]([len:u32][bytes])*) with\nscalars 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\nconstant has caused more bugs than anything else in the system, because it is\ninvisible until a payload crosses it, and payloads cross it constantly:
\nwriteLarge\npath that skips the shared buffer entirely and transfers an ArrayBuffer\ninstead. That becomes necessary the moment you try to write something like\nyarn's 5 MB bundled cli.js into the filesystem.If there is one lesson here, it is that a fixed-size shared window is not a\ndetail of the transport. It is a constraint that reaches up through every layer\nabove it, and every subsystem eventually has to answer for how it handles a\npayload larger than the window.
\nBlocking is only safe if the thread you blocked is not the one that has to\nanswer you. So the work is split:
\nMessagePort\ndoorbell.Some syscalls are deferred rather than serviced immediately: accept,\nspawn and blocking fetch leave the caller parked until the awaited event\nactually arrives. That is not a workaround, it is the point: it is how\nblocking accept() and execSync() get their semantics. A parked worker\ncosts nothing while it waits.
None of the above is exotic on its own. Atomics.wait is a documented API and\nSharedArrayBuffer has shipped for years. What is interesting is how much falls\nout of taking the one available blocking primitive seriously and building the\nentire system to respect it: real require(), real execSync, real child\nprocesses, and, because the synchronous surface is honest, the ability to run\nNode'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\na browser tab, and why hand-writing\nstream and http was never going to work.
Vivari is MIT-licensed and the code is on\nGitHub.
", "url": "https://vivari.run/blog/blocking-in-a-browser", "title": "The one browser API that makes a Node runtime possible", "summary": "Node's API is synchronous and browsers refuse to block. Everything Vivari does rests on the single exception to that rule, and on a 1 MiB window.", "date_modified": "2026-06-15T00:00:00.000Z", "tags": [ "Teardown", "Runtime", "Browser platform" ] } ] }