ADR 0006: Run ES modules natively, served by the instance service worker
-
Status: accepted (2026-10-21)
-
Context: Node packages ship as CommonJS, ESM, or both. Transforming ESM into an internal CommonJS format needs a full JavaScript parser, and it can only approximate live bindings, cycles, and top-level await.
-
Decision: Processes load ES modules with the browser’s native
import()from/__clientvm/fs/<absolute path>on the instance origin. The instance service worker forwards these requests to the kernel. The kernel:- resolves specifiers using Node’s ESM algorithm (
exports/imports, conditionsimport/node/default), with no extension guessing for relative imports; - rewrites them with a small TS lexer;
- serves CommonJS files as ES facades whose named exports are detected lexically, as Node does with cjs-module-lexer;
- serves builtins (
node:fs) as facades over the process’s builtin modules.
import.meta.urlis afile:URL. A probe confirmed that cycles and top-level await work. - resolves specifiers using Node’s ESM algorithm (
-
Consequences:
- Real ESM semantics: live bindings, cycles, top-level await, correct evaluation order.
require()of an ES module is not supported (native import is async), matching Node before 22.12; Node 24 allows it, so this is documented as a gap.- Loading an ESM graph costs one SW → kernel round trip per module. Measure on Vite.
- The kernel transforms modules for all processes in one thread. Measure, and cache per (path, mtime) if needed.