feat(vpx): run TypeScript scripts with the vendored oxc-node

[fengmk2]

Summary

vpx <file> runs a script file directly with the project's managed Node.js and the oxc-node loader:

vpx ./scripts/seed.ts --dry-run

TypeScript syntax that Node.js cannot strip (enums, namespaces, parameter properties, legacy decorators, JSX), tsconfig paths, .js → .ts imports, TypeScript dependencies, and ESM/CJS interop work without a tsx or ts-node dependency. Package-binary execution through the global vpx (vpx eslint .) is unchanged. Inside package.json scripts, vpx <pkg> now runs only binaries installed in node_modules/.bin.

Design and findings: rfcs/vpx-script-execution.md.

Changes

• Vendored oxc-node. The Rust source is cloned by sync-remote, like Rolldown, and compiled into the native binding unpatched. It is pinned to ce22828, a main commit after v0.1.7 whose fixes are not released yet; upgrade-deps moves the pin to the first stable tag that contains it. The binding links it with default-features = false, so oxc-node registers no NAPI exports and no global allocator of its own, and with yarn_pnp, to match the oxc_resolver feature the workspace enables, and packages/cli/binding/src/oxc_node.rs forwards what the loader uses under an oxcNode namespace (createResolve, load, OxcTransformer, setTsconfigPath, setTransformDeps, transformsDep). Its module_exports hook runs init_tracing and detect_runtime_syntax, so OXC_LOG works and using stays native on Node.js 24+. patch-oxc-node.ts only points oxc-node's oxc dependency at the workspace version, so the binding links one oxc: oxc-node's main asks for 0.155.0 and builds unchanged with the workspace's 0.154.0, which Rolldown pins. The preload calls setTransformDeps('typescript'), so TypeScript under node_modules is transformed and other dependencies run as published. The release binding grows by about 130 KB (0.3%).

• Loader. vpx <file> runs node --require dist/script-preload.cjs --import dist/script-register.js <file>. Node.js 22.22.3+, 24.11.1+, and 26 use the in-thread module.registerHooks() (the releases tsx also switches at); older 22.x and 24.11.0 use module.register(), which takes longer to start; its hooks thread requires the binding as CommonJS, which saves 5–13 ms there. Runtime helpers are emitted under a private module name, vite-plus:oxc-node, and resolved from @oxc-project/runtime, a vite-plus dependency, so helper imports from other oxc-node copies keep their own resolution; CommonJS output require()s them through a Module._resolveFilename wrapper, so a pnpm project or a script outside any project finds them too.

• CLI. Script detection in the global vpx (Rust) and a new project-local vpx bin, so package.json scripts work without the global CLI. Both implementations decide from one shared table of cases. A missing script is an error, never a package download, with or without --package. An explicit path to a file that is not executable, or to a directory without a package.json, is a vpx error instead of a vp dlx failure. vpx -v/--version prints the Vite+ version. --tsconfig <path> selects the tsconfig, passed to oxc-node's setTsconfigPath(). After -e/--eval, -p/-pe/--print, --run, or --test, the remaining arguments are code arguments, a package script's arguments, or test files and globs, never a script to check, and Node.js options also match with _ for - (--redirect_warnings), as Node.js accepts. Script mode selects the Node.js that vp node selects, including a system-first Node.js found on PATH, and passes Node.js the loader's real path, so --preserve-symlinks works with a pnpm-installed vite-plus.

• One process on Unix. Like the global vpx, the project-local bin replaces itself with the script's Node.js through process.execve(), so the PID its caller holds, every signal sent to it (kill -INT, SIGUSR1 for the inspector), and the exit status belong to the script, and no second Node.js process (about 50 MB) stays alive while the script runs. The new process starts as a spawned child would: default SIGPIPE and SIGXFSZ dispositions and blocking stdio, which process.execve() otherwise leaves non-blocking (process.execve() passes non-blocking stdio to the new program nodejs/node#66824). When a tool fork()s the bin, it keeps spawning, relays the IPC channel to the script in both directions, as tsx does, and exits with the script's code whichever side closes the channel first; the global vpx passes the channel on through exec. On Windows the bin always spawns, and only a fork() of the bin file carries a channel, not a .cmd shim.

• Package binaries in package.json scripts. Package managers and vp run put node_modules/.bin first on PATH, so scripts run the project-local bin. It never hands off to the global vpx, so two copies on PATH cannot spawn each other. The nearest binary in node_modules/.bin runs directly, as the global vpx runs it, exec'd in place on Unix, so it needs no package.json above the cwd and installs nothing first. A native binary, or a script whose #! interpreter is one, execs directly; anything else goes through /bin/sh, which reports a file it cannot run as a terminal does. pkg@version, --package, or --shell-mode run with the package's own vp dlx. On Windows, a .cmd binary runs through cmd.exe, so Ctrl+C there can end with the "Terminate batch job (Y/N)?" prompt, which the global vpx avoids by running the .ps1 sibling in a terminal. A tool found only in global packages or on PATH is no longer found there, and a binary that is not installed fails with a hint instead of a download:

  error: vpx: 'eslint' is not installed in node_modules
  note: Add it to devDependencies, or run `vp dlx eslint` to download and run it.
  

• Toolchain. vp toolchain reports oxc-node with its version and revision.

• Deps. @oxc-project/runtime follows Rolldown's pin. upgrade-deps.ts bumps the oxc-node pin to new stable tags, but only to a tag that contains the pinned commit, so a pin to an unreleased fix is not dropped.

Upstream

17 issues found while vendoring were filed upstream and fixed: oxc-project/oxc-node#794 to oxc-project/oxc-node#798 in v0.1.5, oxc-project/oxc-node#804 to oxc-project/oxc-node#806 and oxc-project/oxc-node#808 to oxc-project/oxc-node#811 in v0.1.6, and in v0.1.7 oxc-project/oxc-node#807 (a napi feature, so an embedder links it without its exports), oxc-project/oxc-node#820 (CommonJS transformed twice on the registerHooks() path), oxc-project/oxc-node#821 (an option to transform TypeScript dependencies alone), oxc-project/oxc-node#827 (extra file reads added by the #820 fix), and oxc-project/oxc-node#828 (extensionless ES modules). The vendored patch, once 30 hunks, is gone.

12 more were found later, most of them in end-to-end testing against tsx 4.23 on macOS, Linux, and Windows, and all are fixed on oxc-node main and synced here: oxc-project/oxc-node#835 (paths for a file outside every tsconfig include), oxc-project/oxc-node#837 (file names with # or % ran the wrong file), oxc-project/oxc-node#839 (no line and column in errors), oxc-project/oxc-node#840 (.js resolved before .ts), oxc-project/oxc-node#841 (data: URL imports), oxc-project/oxc-node#842 (ERR_REQUIRE_ASYNC_MODULE), oxc-project/oxc-node#843 (invalid UTF-8), oxc-project/oxc-node#844 (an unreadable tsconfig skipped silently), oxc-project/oxc-node#845 (--preserve-symlinks, and OXC_LOG on stdout), oxc-project/oxc-node#846 (a byte order mark before a shebang), oxc-project/oxc-node#856 (# in an import specifier), and oxc-project/oxc-node#862 (a parent URL ending in /, the working directory Node.js resolves the entry point and --import against, resolved as a file, so an extensionless --import ./setup was not found and scripts failed with the working directory at /). Two oxc transformer issues from the same testing are open: oxc-project/oxc#27741 (accessor fields are not lowered) and oxc-project/oxc#27742 (legacy decorator order differs from tsc). The final round also found nodejs/node#66824 (process.execve() passes non-blocking stdio to the new program), worked around in the local bin. Because vpx sets the dependency mode, OXC_TRANSFORM_ALL has no effect under it.

script-preload.ts mirrors the oxc-project/oxc-node#820 fix in upstream's register.mjs: it returns a null source for CommonJS only when oxc-node produced none, so source from another hook is kept. That fix added two file reads per CommonJS-package file with ES module syntax, which the oxc-project/oxc-node#827 fix removed. It also mirrors the oxc-project/oxc-node#842 change, which sets ERR_REQUIRE_ASYNC_MODULE on the binding's error for require() of an ES module with top-level await.

An extensionless shebang script runs as JavaScript, as before; TypeScript in it is not supported, because the name does not tell which it is. With the oxc-project/oxc-node#828 fix, its syntax decides whether it is an ES module in a package without "type", as in Node.js.

Following upstream, a .cts file with import/export fails with one error that suggests renaming it to .mts, as Node.js also rejects it. Without --tsconfig, TS_NODE_PROJECT and OXC_TSCONFIG_PATH apply, as they do for oxnode.

Performance

Compared with tsx 4.23.15 on an Apple M4 Pro (macOS 26.6). Each vpx is compared with the tsx setup it replaces:

• Global vpx execs Node.js in place, so it is one process, like node --import tsx. Its times include the Rust shim's startup, Node.js resolution, and the loader lookup, which take 5–10 ms.
• Project-local vpx is what package.json scripts run. It starts its own Node.js before it execs the script, which adds 23–30 ms, against the 32–42 ms the tsx CLI's parent process adds.

How to read it: the percentage is how much less (−) or more (+) time vpx takes than tsx. 🟢 vpx is faster, 🔴 vpx is slower, ⚪ within ±3%, about the run-to-run noise.

Scenarios: hello is 1 file with erasable syntax only; esm-app is 301 modules in an ES module package, and cjs-app the same modules in a package without type; large-cjs and large-esm are one 1.8 MB file, as CommonJS and as ESM.

Global vpx against node --import tsx

Scenario	Node.js	global vpx	tsx, warm cache	vpx vs warm	tsx, no cache	vpx vs no cache
hello	22.18	51 ms	68 ms	🟢 −25%	75 ms	🟢 −33%
hello	24.12	34 ms	46 ms	🟢 −26%	63 ms	🟢 −46%
hello	26.5	37 ms	38 ms	🟢 −4%	61 ms	🟢 −39%
esm-app	22.18	94 ms	124 ms	🟢 −24%	141 ms	🟢 −34%
esm-app	24.12	75 ms	94 ms	🟢 −20%	217 ms	🟢 −65%
esm-app	26.5	77 ms	92 ms	🟢 −16%	216 ms	🟢 −64%
cjs-app	22.18	94 ms	143 ms	🟢 −34%	289 ms	🟢 −67%
cjs-app	24.12	75 ms	116 ms	🟢 −36%	261 ms	🟢 −71%
cjs-app	26.5	77 ms	113 ms	🟢 −32%	257 ms	🟢 −70%
large-cjs	22.18	121 ms	122 ms	⚪ −1%	229 ms	🟢 −47%
large-cjs	24.12	100 ms	90 ms	🔴 +11%	273 ms	🟢 −64%
large-cjs	26.5	93 ms	76 ms	🔴 +21%	258 ms	🟢 −64%
large-esm	22.18	103 ms	107 ms	🟢 −4%	200 ms	🟢 −49%
large-esm	24.12	84 ms	75 ms	🔴 +12%	177 ms	🟢 −53%
large-esm	26.5	86 ms	69 ms	🔴 +24%	173 ms	🟢 −50%

Project-local vpx in package.json scripts against the tsx CLI

Scenario	Node.js	local vpx	tsx CLI, warm cache	vpx vs warm	tsx CLI, no cache	vpx vs no cache
hello	22.18	66 ms	103 ms	🟢 −35%	110 ms	🟢 −40%
hello	24.12	52 ms	83 ms	🟢 −37%	96 ms	🟢 −46%
hello	26.5	57 ms	72 ms	🟢 −22%	94 ms	🟢 −40%
esm-app	22.18	113 ms	165 ms	🟢 −31%	177 ms	🟢 −36%
esm-app	24.12	93 ms	134 ms	🟢 −30%	250 ms	🟢 −63%
esm-app	26.5	98 ms	134 ms	🟢 −27%	249 ms	🟢 −61%
cjs-app	22.18	112 ms	184 ms	🟢 −39%	327 ms	🟢 −66%
cjs-app	24.12	93 ms	155 ms	🟢 −40%	296 ms	🟢 −69%
cjs-app	26.5	99 ms	155 ms	🟢 −36%	291 ms	🟢 −66%
large-cjs	22.18	139 ms	155 ms	🟢 −11%	265 ms	🟢 −48%
large-cjs	24.12	118 ms	122 ms	⚪ −3%	305 ms	🟢 −61%
large-cjs	26.5	113 ms	111 ms	⚪ +2%	294 ms	🟢 −61%
large-esm	22.18	122 ms	139 ms	🟢 −12%	232 ms	🟢 −47%
large-esm	24.12	103 ms	108 ms	🟢 −5%	210 ms	🟢 −51%
large-esm	26.5	107 ms	104 ms	⚪ +3%	206 ms	🟢 −48%

• 🟢 Against tsx with a warm cache, on hello, esm-app, and cjs-app, the global vpx takes 4–36% less time and the local vpx 22–40% less, on every Node.js version.
• 🟢 Against tsx without its cache, vpx takes 33–71% less time in every scenario.
• 🔴 tsx's disk cache wins only for the 1.8 MB files through the global vpx on 24.12 and 26.5, by 11–24% (9–17 ms), because vpx transforms them on every run. Against the tsx CLI, the local vpx is 5–12% faster or level. A transform cache stays a nice-to-have.
• Against plain node type stripping, on the erasable hello file, the global vpx is 23% faster on 24.12 and 26.5 (34–37 against 44–48 ms) and 3 ms slower on 22.18 (51 against 48 ms), where the shim's 10 ms outweighs the loader's 7 ms lead.
• Exec in place leaves script startup where spawning the script left it, within 2 ms in every scenario; what it saves is the second Node.js process.
• Running an installed binary takes about 25 ms through the local vpx, 4 ms less than spawning it, against 9 ms through the global one.

🤖 Generated with Claude Code

[github-actions]

✅ Staging deployment successful!

Preview: https://viteplus-staging.void.app/
Commit: 2d68bab

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://feat-vpx-typescript-scripts-viteplus-dev.voidzero-docs.workers.dev (commit 2d68bab)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://252fcc5e-viteplus-dev.voidzero-docs.workers.dev	2d68bab	2026-10-20T09:02:13.482Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://1f5d9d72-viteplus-dev.voidzero-docs.workers.dev	86183c8	2026-10-20T08:31:23.821Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://ca133e94-viteplus-dev.voidzero-docs.workers.dev	b68a3ae	2026-10-20T04:53:21.415Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://b4a67d34-viteplus-dev.voidzero-docs.workers.dev	388d303	2026-10-20T04:42:36.175Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://b629ae3b-viteplus-dev.voidzero-docs.workers.dev	e4cf2d8	2026-10-18T14:36:56.438Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://834b2e34-viteplus-dev.voidzero-docs.workers.dev	aeaeeb0	2026-10-18T12:36:50.393Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://4f6a8b6b-viteplus-dev.voidzero-docs.workers.dev	85296a4	2026-10-18T11:40:41.438Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://a792cf79-viteplus-dev.voidzero-docs.workers.dev	d345fe7	2026-10-18T07:46:24.848Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://d0b69e88-viteplus-dev.voidzero-docs.workers.dev	4581ed2	2026-10-18T07:21:49.252Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://3f23c56a-viteplus-dev.voidzero-docs.workers.dev	43dad7a	2026-10-18T05:55:02.412Z	Visit the dashboard ↗

View all previews: View all previews ↗

[github-actions]

CLI artifact sizes (2d68bab)

Final release artifacts built by the canonical build-upstream and build-windows-cli actions.
The dist rows use the Linux build. The core total excludes .node files to match the release artifact.

Artifact	Format	Base	PR	Change
packages/cli/dist	Directory total	2.11 MiB	2.15 MiB	+39.95 KiB (+1.85%)
packages/core/dist	Directory total	4.08 MiB	4.08 MiB	0 B (0.00%)
Combined package dist	Directory total	6.19 MiB	6.23 MiB	+39.95 KiB (+0.63%)
vp (Linux x64)	Binary	7.21 MiB	7.22 MiB	+12.00 KiB (+0.16%)
vp (Linux x64)	gzip -9	3.34 MiB	3.35 MiB	+7.75 KiB (+0.23%)
NAPI (Linux x64)	Binary	34.79 MiB	35.13 MiB	+341.50 KiB (+0.96%)
NAPI (Linux x64)	gzip -9	13.86 MiB	14.00 MiB	+143.34 KiB (+1.01%)
vp (macOS ARM64)	Binary	4.77 MiB	4.77 MiB	+48 B (+0.00%)
vp (macOS ARM64)	gzip -9	2.86 MiB	2.87 MiB	+7.07 KiB (+0.24%)
NAPI (macOS ARM64)	Binary	41.71 MiB	42.00 MiB	+291.23 KiB (+0.68%)
NAPI (macOS ARM64)	gzip -9	18.02 MiB	18.15 MiB	+138.11 KiB (+0.75%)
vp (Windows x64)	Binary	5.26 MiB	5.27 MiB	+14.50 KiB (+0.27%)
vp (Windows x64)	gzip -9	2.46 MiB	2.47 MiB	+7.02 KiB (+0.28%)
NAPI (Windows x64)	Binary	30.85 MiB	31.19 MiB	+345.50 KiB (+1.09%)
NAPI (Windows x64)	gzip -9	12.56 MiB	12.71 MiB	+157.03 KiB (+1.22%)
Trampoline (Windows x64)	Binary	13.50 KiB	13.50 KiB	0 B (0.00%)
Trampoline (Windows x64)	gzip -9	7.09 KiB	7.09 KiB	0 B (0.00%)
Installer (Windows x64)	Binary	3.64 MiB	3.64 MiB	0 B (0.00%)
Installer (Windows x64)	gzip -9	1.78 MiB	1.78 MiB	0 B (0.00%)

[fengmk2]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: 2d68bab038

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".