▲reactivite
/packages/docs/courses/cli/skillpool/promaster/contact
all docs

$ npm view @ubuligan/nodevm

CLI

@ubuligan/nodevm

Per-project Node.js version switching scoped to the current terminal session. Reads .nvmrc and swaps versions without touching the global install.

npm versiondownloads
npm github
$ npm install @ubuligan/nodevm

Per-project Node.js versions, scoped to your terminal session.

Pin a version to a project once. From then on, every terminal you open inside that project uses it — and nowhere else on the machine changes. Close the terminal and your own Node is back.

It replaces doing this by hand in every shell:

export PATH="/c/nodes/nodejs14:$PATH"
hash -r

Install#

npm install -g @ubuligan/nodevm
nodevm setup          # once per machine, per shell

Then open a new terminal.

nodevm itself needs Node 18.17.0 or newer. That is a genuine chicken-and-egg: a JavaScript CLI needs a modern Node to run, while existing to rescue you from old ones. If your only Node is older, nodevm tells you so and names the minimum — it does not fail with a cryptic engines error. Once installed, it manages any version, Node 14 included.

setup prints exactly what it changed and is fully reversible with nodevm setup --undo.

Use it#

cd my-legacy-app
nodevm install 14 --pin    # installs Node 14 and writes .nvmrc

cd ..                      # your own Node
cd my-legacy-app           # Node 14, automatically

That is the whole workflow. No command to run per terminal, no PATH editing.

nodevm ls-remote           # ~12 rows: newest of each LTS line + current
nodevm ls-remote --all     # every published release
nodevm install             # interactive picker
nodevm ls                  # what is installed here (never uses the network)
nodevm current             # what is active, and why
nodevm which               # path to the node that would run
nodevm use 20              # activate in THIS terminal only
nodevm use --unpin         # remove this project's pin
nodevm uninstall 14

Already have Node folders?#

Register them instead of downloading again. nodevm never modifies, moves, or deletes them.

nodevm link "C:\nodes\nodejs14"
nodevm link "C:\nodes\nodejs14" --remove   # removes only the registration

How pinning works#

The pin lives in .nvmrc — one line, committed to your repo. It is the same file nvm, fnm, nodenv and Volta read, so a project you pin works for teammates using those tools, and a project they pinned works here with no changes.

When .nvmrc is absent, nodevm also reads .node-version, then package.json engines.node (treated as a range: the newest installed version that satisfies it wins). nodevm use --unpin deletes only the .nvmrc nodevm wrote — never the other two, which it never created.

The innermost pin wins, so a package inside a monorepo can differ from its parent.

How it works#

A child process cannot change its parent shell's PATH, so nodevm setup installs a small shell hook. On every directory change the hook is pure shell: it walks up for the nearest pin file and compares a path:mtime:size fingerprint. If nothing changed — the usual case — it spawns no process at all. Only when the pin actually changes does it call nodevm, which prints the PATH change as shell code for the hook to eval.

Nothing is written to disk when you switch. The active version lives in three environment variables in that one session, which is why closing the terminal needs no cleanup, and why two terminals in two differently pinned projects run different versions at the same time.

Deactivation removes exactly the directory that was added, by string match — never a pattern strip. A PATH entry you set by hand survives untouched.

Safety#

  • Downloads come only from https://nodejs.org/dist (or a mirror you set with NODEVM_MIRROR).
  • Every archive is checked against the official SHASUMS256.txt before extraction. A mismatch installs nothing.
  • Extraction happens in a temp directory and is promoted with one atomic rename, so an interrupted install can never leave a half-version that ls reports as installed.
  • Everything lives under ~/.nodevm. No administrator rights, ever. Nothing outside that directory is touched except the one consented setup change to your shell config.
  • Concurrent installs of the same version take a lock: the second waits, then succeeds. Locks left by a crashed process expire.

Not verified: GPG signatures on SHASUMS256.txt. Checksums are verified over HTTPS; signature verification would need a crypto dependency and a key-distribution story. This is a deliberate, documented gap, not an oversight.

Platform notes#

Windows, macOS and Linux, on x64 and arm64. Git Bash, PowerShell, cmd.exe, bash, zsh and fish.

No native build for your machine? Some old versions publish none — Node 14 has no Apple Silicon build, for instance. nodevm checks the release index before downloading and either offers the x64 build under Rosetta (--rosetta to pre-answer) or names the oldest version that does have a native build. It never silently substitutes an emulated build, and never fails with a mid-download 404.

cmd.exe limitation. cmd.exe raises no directory-change event, so nodevm intercepts cd with a doskey macro. Those macros do not expand inside batch files, so a cd in a .bat does not trigger automatic switching. Interactive cd does. nodevm use <version> works everywhere, batch files included. nodevm setup states this when you install it.

Uninstall#

nodevm setup --undo
npm uninstall -g @ubuligan/nodevm
rm -rf ~/.nodevm

Your machine's original Node behaviour returns, with no leftover files or config.

Scripting#

Every command that reports data supports --json with a stable documented shape. Data goes to stdout; errors, warnings, progress and all interactive UI go to stderr, so nodevm ls | grep 20 works. Exit codes: 0 success, 2 usage, 3 version not found, 4 no build for this platform, 5 checksum mismatch, 6 network unavailable, 7 store error, 8 Node too old to run nodevm.

--json and --silent both force non-interactive mode: nodevm never waits for input that cannot arrive.

License#

MIT

  • home
  • packages
  • skillpool
  • docs
  • cli
▲reactivite

// The fastest way to scaffold production-ready React apps. Built by developers, for developers.

$ npm create reactivite@latest

resources/

  • └─ documentation
  • └─ packages
  • └─ cli
  • └─ courses
  • └─ markdown
  • └─ diff
  • └─ run
  • └─ radio
  • └─ tv
  • └─ games
  • └─ about
  • └─ contact

community/

  • └─ github

© 2026 reactivite — all rights reserved