Skip to main content

node (shim)

In shim mode, the node command is the NVM for Windows' Zig-built node.exe shim, not the Node.js binary. It dynamically resolves which version of Node.js to run, verifies the real node.exe, applies a thin security wrapper, and launches the real node.exe.

Switch modes with nvm use shim / nvm use link. Background: Operating Modes.

What the shim does​

  1. Parse shim-only flags (below); strip them before forwarding.
  2. Resolve Node.js version (active preference, detection files, --nvm-use, aliases).
  3. Optionally auto-install a missing version when configured.
  4. Verify shim self-integrity when launched from the data-root .shim directory.
  5. Verify the resolved node.exe (verify-cache / Authenticode) before spawn.
  6. CreateProcessW the real Node.js with remaining arguments.

Shim flags​

These flags are consumed by the shim and are not passed to Node.js. They may appear anywhere on the command line.

FlagPurpose
--nvm-use <version>Run this invocation with a specific Node.js version (one-shot; does not change the default).
--nvm-use=<version>Same as --nvm-use <version>.
--nvm-whichPrint how the version was resolved (source, requested, effective, resolved path), then continue.
--nvm-shim-versionPrint the shim executable version and exit.
node --version
node --nvm-which --version
node --nvm-use 22 script.js
node --nvm-use=22 script.js
node --nvm-shim-version

Example --nvm-which line:

nvm version resolution: source=system_default requested=24.16.0 effective=24.16.0 resolved=24.16.0 node=C:\Users\...\node.exe

Version resolution​

Without --nvm-use, the shim uses project detect files when auto_use is on, then the default version. A range such as engines.node >=8.9 does not switch to the newest installed Node.js when the default already satisfies the range. See Version resolution.

--nvm-which prints the source of that decision. --nvm-use is only a one-shot override. There is no --nvm-use-which flag.

Detection and auto-install are configurable (auto_detect, auto_use, auto_install, auto_install_prompt). See Basic Configuration.

Integrity checks​

CheckWhenBehavior
Shim self-checkInvoked from {DataRoot}/.shim/node.exeByte-compare against the program-root canonical shim. Mismatch → shim integrity check failed, exit 1.
node.exe trustBefore every spawnPrefer signed verify-cache hit (~1–2 ms). Cache miss/invalid → full Authenticode, then PE FileVersion vs folder. Authenticode failure → NVM4301. FileVersion mismatch → NVM4314. Certified version firewall → NVM4411.

If the verify-cache public key or entries are missing, the shim falls back to full Authenticode (slower, still secure). nvm doctor reports verify-cache health.

Latency​

The shim adds roughly 1–3 ms of resolution work. Windows still pays CreateProcessW twice (shim, then Node). Typical total overhead is ~25–35 ms versus link mode. Details: Operating Modes.