ADR 0009: Use cjs-module-lexer for CommonJS named exports
- Status: accepted (2026-10-21)
- Context: When an ES module imports a CommonJS module, Node exposes the named exports that
cjs-module-lexer detects in the source. import { useState } from 'react' works because
the lexer follows React’s module.exports = require(...) re-exports. Whatever that lexer
returns is the specification. A re-implementation tested against the real lexer on 1,500
package files matched only 55% of them exactly. Its heuristics (unsafe getters, star-export
bindings, last-reexport-wins, object literal rules) are what make Node’s behavior.
- Decision: Use
cjs-module-lexer itself as a runtime dependency of @clientvm/kernel,
pinned to 2.1.0, the version bundled with Node 24.11. The kernel uses it when serving a
CommonJS file as an ES facade.
- Justification: It is Node’s own component (MIT, no dependencies, about 30 kB). Using it
gives exact fidelity, and any other choice would be an approximation of it.
- Consequences:
- The package’s ESM build is WebAssembly, initialized synchronously on first use in the
kernel worker.
- Bump the pin together with the Node target (ADR 0001).
- The ESM side uses our own lexer. It matches
es-module-lexer exactly on the 793-file
corpus and also returns the import-clause details the rewriter needs.
Edit this page on GitHub ↗Markdown