bug: vite-plus@0.2.1 crashes on Node < 20.12 with "node:util has no export named styleText" before engine check

[l246804]

Describe the bug

Running vpr <script> in a project pinned to a Node.js version that does not yet have util.styleText (added in Node 20.12 / 22) crashes at module load time, before any of vp's own engine-compatibility checks can run:

file:///~/.vite-plus/0.2.1/node_modules/.pnpm/vite-plus@0.2.1_vite@8.0.16/node_modules/vite-plus/dist/terminal-uTv0ZaMr.js:2
import { styleText } from "node:util";
         ^^^^^^^^^
SyntaxError: The requested module 'node:util' does not provide an export named 'styleText'
    at ModuleJob._instantiate (internal/modules/esm/module_job.js:98:21)
    at async ModuleJob.run (internal/modules/esm/module_job.js:143:5)
    at async Loader.import (internal/modules/esm/loader.js:165:24)
    at async Object.loadESM (internal/process/esm_loader.js:68:5)

Source:

// vite-plus/dist/terminal-uTv0ZaMr.js
import { styleText } from "node:util";

styleText was added in Node 20.12 and only stabilized in v22, so any project whose .node-version resolves to Node 14 / 16 / 18.x < 20.12 will hit this SyntaxError during ESM instantiation of the terminal helper — i.e. before vp's own "Node.js X is incompatible with Vite+ CLI" message has a chance to fire, and before the script-runner soft-fallback work tracked in #1875 (PR #1865 / #1874) can take effect.

This makes vpr completely unusable in older repos even as a thin script forwarder, which is exactly the use case #1875 was supposed to preserve.

Suggested fix

Either:

1. Avoid the static import { styleText } from "node:util" in any module that can be loaded before the engine check (in particular terminal-*.js, which the CLI bootstrap pulls in eagerly). A small pc-style fallback or a dynamic import gated on process.versions.node >= 20.12 would let the runner reach the vpr soft-fallback path; or
2. Build the CLI bootstrap chunk with a downlevel target so static imports don't reference Node-22-only named exports.

Reproduction

Any project with a .node-version pinning Node ≤ 20.11 (reproduced on 14.15.0). Steps:

1. In a directory with .node-version containing 14.15.0 (or use vp env use 14.15.0).
2. vpr dev (or any vpr <script> — fails before reaching the script).

Result: the SyntaxError above. Expected: the soft-fallback behavior from #1875, or at minimum the previous "Node.js X is incompatible with Vite+ CLI" diagnostic.

Steps to reproduce

echo 14.15.0 > .node-version
vpr dev

System Info

$ vp env current
VITE+ - The Unified Toolchain for the Web

Environment:
  Version       14.15.0
  Source        .node-version
  Source Path   /home/<me>/<project>/.node-version
  Project Root  /home/<me>/<project>

Tool Paths:
  node  ~/.vite-plus/js_runtime/node/14.15.0/bin/node
  npm   ~/.vite-plus/js_runtime/node/14.15.0/bin/npm
  npx   ~/.vite-plus/js_runtime/node/14.15.0/bin/npx

$ vp --version
VITE+ - The Unified Toolchain for the Web
vp v0.2.1

Local vite-plus:
  vite-plus  Not found

Environment:
  Package manager  npm latest
  Node.js          v14.15.0 (.node-version)

Used Package Manager

npm

Related

• vpr should not hard-fail on incompatible Node version — fall back like @antfu/ni #1875 — vpr should soft-fallback on incompatible Node versions. This issue is what blocks that fallback from ever being reached on 0.2.1, because the failure happens during ESM instantiation of terminal-uTv0ZaMr.js, prior to any version-guard logic.

Validations

• Read the Contributing Guidelines.
• Checked existing issues; vpr should not hard-fail on incompatible Node version — fall back like @antfu/ni #1875 is related but distinct (engine guard vs. unconditional node:util named import).
• This is a Vite+ issue (the offending import lives in the published vite-plus package).
• Reproduction is minimal (any low-Node project + vpr <script>).

[fengmk2]

https://github.com/voidzero-dev/vite-plus/blob/main/packages/cli/package.json#L439 We have currently raised the minimum supported node version to 20.19.0.

[l246804]

I understand bumping engines to ^20.19.0 — Vite+ core needn't support Node 14. But I'd like to suggest another angle: when vpr detects an unsupported Node version, degrade to pure passthrough — load no Vite+ JS at all, and have the Rust layer directly fork the project's own package manager to run the script. Scoped to vpr only.

Why this matters

Many enterprise projects are still pinned to older Node and can't be upgraded short-term due to process and compatibility constraints. The value of vpr as a script runner (#1875) is one muscle memory across every repo; if low-Node repos force a fallback to nr / npm run, that universality is lost.

Sketch

Version check in the Rust trampoline (no Node module loader involved):

Node version >= engines.min
  yes → existing vite-plus CLI path
  no  → reuse existing package-manager detection,
        exec npm/pnpm/yarn run <script>, forward exit code

Benefits

• No Vite+ JS is loaded on low Node — styleText-style errors disappear
• The Rust trampoline is Node-version-agnostic
• Small diff; reuses the package-manager detection from vpr should not hard-fail on incompatible Node version — fall back like @antfu/ni #1875
• Actually delivers the soft-fallback promised in vpr should not hard-fail on incompatible Node version — fall back like @antfu/ni #1875
• Scoped to vpr — vp dev / vp build etc. keep the engines guard

[fengmk2]

Good suggestion. Are you willing to try to implement it?
One relatively challenging thing is how to continuously ensure that the vpr command will not be compromised by subsequent new features. It is necessary to consider adding continuous validation test cases.

[l246804]

Thanks! Unfortunately I'm not proficient in Rust and don't feel confident delivering a production-quality patch — it'd be safer for someone more familiar with the codebase to take it on, but I'm happy to help with testing and drafting validation cases.

[l246804]

Adding to the shim scope: on low Node, vp i (project install) breaks the same way as vpr, and worse — it leaves devEngines.packageManager = npm@11.17.0 in package.json and routes every npm call to an npm version incompatible with the active Node (npm 11 needs Node ≥20.17; under Node 14 it throws Cannot find module 'node:path'). So not only is vp i unusable on low Node, it also breaks manual npm i / npm run dev afterward.

Filed as a separate, independently-reproducible bug: #1916. The passthrough/shim idea here should cover both vpr and vp i — at minimum, on unsupported Node, forward to the Node-bundled package manager instead of loading Vite+ JS or pinning an incompatible npm.