fix(e2e)!: load TypeScript with e2e's own oxc loader, so pnpm 11+ installs pass - #790

Every new pnpm 11+ user's first pnpm install after pnpm dlx e2e init fails today:

Error: ERR_PNPM_IGNORED_BUILDS
  × installing dependencies
  ╰─▶ Ignored build scripts: esbuild@0.28.2

e2e loaded TypeScript through tsx, tsx depends on esbuild, and esbuild has a postinstall. pnpm 11+ fails on any build script the project has not decided on. The root fix is that nothing e2e installs runs an install script. Replaces the closed #712, which edited pnpm-workspace.yaml instead.

What changed

• tsx is gone from dependencies. e2e loads TypeScript itself with synchronous module.registerHooks hooks (packages/e2e/src/config/esm-hooks.ts), compiles with oxc-transform (config/typescript.ts), and reads tsconfig with get-tsconfig (config/tsconfig.ts). None of the new dependencies has an install script; platform binaries come as optionalDependencies.
• One policy (config/compiled-files.ts): one extension table (lang, format, the extension an import writes) drives what is compiled, its module format, the ./x.js swap, and implied extensions. .ts .mts .tsx .jsx run as ES modules, .cts as CommonJS. A project file compiles with the nearest tsconfig.json; TypeScript in an installed package compiles with defaults.
• Resolution: an import written in a compiled file follows TypeScript (./x.js and ./x to x.ts, a directory's package.json main then index, tsconfig paths/baseUrl for project files); a # import or package export whose target is missing (./x.js, or ./x with no extension) moves to the TypeScript file behind it, also when a lax resolver earlier in the chain returned the missing file. An import written in JavaScript gets plain Node resolution. require() specifiers are read as platform paths (C:\app\helper on Windows; config/specifiers.ts).
• load reads source through nextLoad, so other hooks in the chain still see the file.
• The tsconfig.json is the nearest one, or the referenced project that includes the file when it is solution-style (files: [] + references, as Vite writes). One that cannot be read (an extends package not installed) is skipped with one warning per run (the runner hands the files it warned about to its workers, which warn only about others they reach). tsconfig and file lookups live in a view per module graph (e2e-graph): fresh for each e2e mcp session's graph load, read once otherwise (collecting 50 files parses the extends chain once). Outside a graph, file lookups go to the disk each time, as Node's own resolution does.
• Compiled CommonJS starts with require = globalThis[Symbol.for("e2e.hooked-require.v1")](__filename);, a require the loader registers: the require Node hands a CommonJS module an ES module imported skips resolve hooks before modules: fix sync hook short-circuit in require() in imported CJS nodejs/node#62920 (24.18.0, 26.2.0; not in 22), and on every version once a module.register loader is in the chain (Yarn PnP, tsx in NODE_OPTIONS). Its resolve runs the loader's resolve hook, since require.resolve skips hooks before module: run require.resolve through module.registerHooks() nodejs/node#62028 (24.15.0; not in 22). The statement joins the end of the last directive (found from oxc-parser's parse of the output), so the prologue and every mapped position stay put; with no directive it takes its own first line and the map gains one unmapped line.
• oxc helpers (using on Node 22, legacy decorators) come from e2e's own @oxc-project/runtime: the from "..." / require("...") specifiers oxc reports in helpersUsed are rewritten (oxc 0.152 has no option for it), so a project's own @oxc-project/runtime import is untouched.
• oxc appends export {}; to CommonJS whose only imports were type-only, before any trailing comment; the loader finds it in oxc-parser's parse of the output and blanks it. Not reported upstream yet (crates/oxc_transformer/src/typescript/annotations.rs).
• Syntax oxc passes through and Node cannot run is refused before compiling, with file:line:col and the fix: auto-accessors (no oxc release lowers them), decorators without experimentalDecorators, and import declarations and value export declarations in .cts (export interface/type/declare pass, as tsc allows). The check parses only files whose text could hold them.
• oxc and oxc-parser load on first compile, so --version and --help run without the native binding; without it, a run fails with TYPESCRIPT_COMPILER_UNAVAILABLE (exit 3) naming the @oxc-transform/@oxc-parser bindings for the platform and [BUG] Platform-specific optional dependencies not being included in package-lock.json when reinstalling with node_modules present npm/cli#4828; any other load failure gives its reason.
• Another loader earlier in the chain: a CommonJS load result with no source (Yarn PnP) is read from disk, and an inline source map it left is composed with oxc's (@jridgewell/remapping), so file:line still names the file on disk.
• Workers from source --import config/register.ts, which registers the hooks; it and esm-hooks.ts load under Node's own type stripping, so they stay erasable TypeScript.
• Removed what existed only for tsx: tsxUsesSyncHooks and its version table, the tsx namespace and tsx-namespace URL tagging, the NODE_OPTIONS inspection, and the diagnose hint for tsx's ?namespace= CommonJS dead end. Config and tests now share the runner's module instances; the globalThis slots stay for a project that loads its own copy of e2e.
• A test's source location is read off the stack text, now with at async ... frames (a test file that awaits a helper declaring tests), and only file: URLs are decoded (collect/registry.ts); main throws on a % in a file name and loses the location at a #. util.getCallSites drops async frames and Error.prepareStackTrace gets no call sites while source maps are on, so the text stays the source.
• A type imported without import type that stays in the output (a decorated member's type under emitDecoratorMetadata, a re-exported type) fails at link time as before, but the error now names the importing line and import type.
• Breaking: Node floor is ^22.22.3 || >=24.8.0 for every published package (was >=22.12.0), as an explicit release-range model in internal/node-version.ts. registerHooks does not exist before 22.15, and before 22.22.3 / 24.8.0 a CommonJS file an ES module imported cannot require() an ES module the hooks load (esm: populate separate cache for require(esm) in imported CJS nodejs/node#59679). The CLI refuses older versions naming the ones to upgrade to, and the Bun and Deno runtimes (Bun has no registerHooks; Deno has it but cannot load oxc's addon from a hook); registerLoader refuses them too (NODE_UNSUPPORTED). No async module.register fallback.
• Guards: pnpm check:install-scripts (in pnpm check) walks the installed tree of every published package and names the chain to any preinstall/install/postinstall or binding.gyp (on main: e2e > tsx@4.23.14 > esbuild@0.28.2). A new install CI job runs scripts/install-smoke.ts with pnpm 11 and 12: packs e2e, @e2e-dev/web, @e2e-dev/mobile, installs them into a fresh project, installs again from the lockfile, runs a TypeScript test, and fails on a non-zero exit, ERR_PNPM_IGNORED_BUILDS, or a written pnpm-workspace.yaml (on main: pnpm install exits 1).
• CI pnpm test runs on 22, 24, 26 (check-latest) and the floors 22.22.3 and 24.8.0. Vitest externalizes the workspace packages' dist/ so integration tests load them natively, through e2e's hooks.

flowchart LR
  A["import / require"] --> W{written in a compiled file?}
  W -- no --> N[Node resolution]
  W -- "yes: ./x.js, ./x, ./dir, tsconfig alias" --> P[TypeScript file, from the graph's view]
  W -- "yes: # import / package export" --> X[Node resolution, retried on the x.js to x.ts swap]
  P --> N
  N --> F["format from the extension table; e2e-graph query"]
  X --> F
  F --> L{load hook}
  L -- "TypeScript, JSX" --> O["nextLoad source, oxc-transform, inline source map"]
  L -- "JSON, no type attribute" --> J["nextLoad as json, export default JSON.parse"]
  L -- else --> D[nextLoad]

Parity with tsx

Each row has a test: tests/integration/typescript-loader.test.ts runs the built CLI on a fixture with all of them, in an ESM package and in a package without "type": "module", with --workers 2; tests/unit/esm-hooks.test.ts and tests/unit/typescript.test.ts cover the rules one by one.

Behavior changes, all in docs/reference/config.mdx and the changeset:

• oxc does not turn ESM import statements into require calls, so a .cts file uses import x = require(). TypeScript's verbatimModuleSyntax and Node's own type stripping draw the same line.
• oxc compiles only legacy decorators. Standard decorators without experimentalDecorators, and auto-accessors, are refused with their file:line:col and the fix.
• The CLI runs on Node.js only: bun --bun e2e and deno run npm:e2e exit 2 naming the fix. Bun and Deno still install it, and bunx e2e runs it on Node.js.
• Yarn PnP with a .cts file on Node.js 24.8.0 to 24.11.0: Node rejects the sourceless CommonJS result PnP's loader returns before e2e's hook sees it (fixed in 24.11.1). Documented in docs/reference/cli.mdx.
• Every .ts is an ES module, including one a .cjs file requires; CommonJS TypeScript goes in .cts.
• An import written in a JavaScript file resolves as Node resolves it (tsx also applied TypeScript's extension rules and tsconfig paths there).
• TypeScript in an installed package compiles without the project's tsconfig.json.

Verified

Ran it locally: yes

Fresh user, pnpm 12.6.0. Every published package packed (pnpm pack) and served from a local verdaccio per build (main on 4410, this branch on 4411; e2e and @e2e-dev/* never proxy to npmjs, everything else does), fresh /tmp dirs, fresh store, minimumReleaseAge 0 so a seconds-old local publish is not what pnpm writes a workspace file for, example test against a static site on 4420.

pnpm 12.9.0 on this branch: the same five steps, all exit 0, no pnpm-workspace.yaml.

npm 11.17 (npx e2e init --yes, npm install, npm ci, npx e2e run) and bun 1.4.2 (bunx e2e init --yes, bun install, bun install --frozen-lockfile, bunx e2e run) on this branch: every step exit 0, example test passes.

Node floor. The same three files on each version (hooks.mjs registers pass-through registerHooks, main.mjs imports req.cjs, which requires esm.mjs):

The e2e unit and integration suites pass on 22.22.3, 24.8.0, 24.17.0 (the compiled-CommonJS require path), and 24.19.0; the loader's own tests also on 24.11.0 and 26.3.0; the parity fixture through the built CLI (--workers 2, ESM and CJS scope) also on 26.10.0. On 24.7.0 the CLI stops with e2e requires Node.js 22.22.3 or newer on Node.js 22, or 24.8.0 or newer; this is Node.js 24.7.0. ....

Install smoke. node scripts/install-smoke.ts 11 and ... 12 on this branch: install, frozen install, and the TypeScript test all exit 0. On main, pnpm install exits 1.

Package managers. Every published package packed and served from a local verdaccio on 4411 (e2e and @e2e-dev/* never proxy to npmjs), main is e2e@0.16.0 from npmjs. A fresh /tmp project per row: init --yes through the manager's own runner for npm and pnpm, a copy of that npm-initialized project for the rest; then a TS-heavy fixture (tsconfig paths, a .cts that requires ./plain, a legacy decorator and an enum, JSX, a #shared/* import map naming ./shared/src/* with no extension); install, frozen install, the example test against a static site on 4420, and the fixture. Node 24.19.

Suites. testbed: 71 passed, 1 skipped. Web benchmark tests/: 91 passed. Web benchmark tests-agent/ with CI=1 --strict-cache and no model key: identical per-test verdicts and counters on main and this branch (26 replayed, 2 handed off, 6 missed, 2 model calls refused for the missing key), so the branch moves no replay key. Mobile benchmark left to CI. Every edge case from review has a repro in /tmp/edge-repros and a committed regression test.

Timings. Config load and collect in a fresh process per round (loadConfigModule + resolveConfig + collect from dist), alternating rounds against main, medians.

Config load is 10 to 14 ms faster and CPU about 18% lower (no tsx registration, no esbuild service). Collect is 4 to 5 ms slower: the syntax check parses files whose text could hold a refused construct, and oxc-parser loads on first use.