Skip to main content

​
nodeup

nodeup is a Rust-based Node.js version manager with rustup-like commands and deterministic runtime selection.

​
Why use nodeup

  • Manage multiple Node.js runtimes with a single CLI.
  • Resolve runtime precedence consistently across default, override, and explicit execution.
  • Use stable human and JSON output modes for both operators and automation.

​
Core capabilities

  • Toolchain lifecycle: toolchain list|install|uninstall|link
  • Runtime selection: default, override set|unset|list, show active-runtime
  • Runtime-aware execution: run, which
  • Self-management: self update|uninstall|upgrade-data
  • Shell completion generation: completions <shell> [command]

​
Install

Tag contract:
  • nodeup@v<semver>
Package manager:
  • macOS/Linux: brew install delinoio/tap/nodeup
  • Homebrew installs prebuilt archives on macOS Intel, macOS Apple Silicon, Linux amd64, and Linux arm64
cargo-binstall: 
cargo binstall nodeup --no-confirm
GitHub Actions: 
- uses: taiki-e/install-action@v2
  with:
    tool: cargo-binstall
- run: cargo binstall nodeup --no-confirm
nodeup toolchain install supports macOS, Linux, and Windows x64/arm64 hosts.

​
Common workflows

Set a global default runtime: 
nodeup default lts
Install and run with an explicit runtime: 
nodeup toolchain install 24.0.0
nodeup run --install 24.0.0 node -v
Use a project directory override: 
nodeup override set lts --path /path/to/project

​
Runtime resolution precedence

  1. Explicit runtime selector in command invocation (run, which --runtime)
  2. Directory override selector (override set)
  3. Global default selector (default)

​
packageManager support (yarn / pnpm)

nodeup reads the nearest package.json from the current directory upward and applies strict packageManager handling for yarn and pnpm.
  • Supported format: <manager>@<exact-semver>
  • Supported managers: yarn, pnpm
  • When present, manager mismatch fails with conflict.
  • Malformed values fail with invalid-input.
  • Corepack is not used; nodeup runs the selected runtime’s npm exec.
Mapping behavior:
  • pnpm@x.y.z -> pnpm@x.y.z
  • yarn@1.x.y -> yarn@1.x.y
  • yarn@2+ -> @yarnpkg/cli-dist@x.y.z
When packageManager is missing:
  • direct bin/yarn or bin/pnpm is preferred if available
  • otherwise nodeup falls back to npm exec defaults:
    • yarn -> @yarnpkg/cli-dist
    • pnpm -> pnpm

​
Output and logging behavior

  • --output human|json is available for management commands.
  • Human mode uses pretty tracing logs by default.
  • JSON mode writes machine payloads to stdout and keeps logs off by default unless explicitly enabled.
  • Handled failures use an actionable message shape: <cause>. Hint: <next action>.
  • completions always writes raw completion scripts to stdout, even when --output json is set.
Human output color control:
  • --color auto|always|never controls ANSI styling for --output human output.
  • NODEUP_COLOR=auto|always|never controls the same behavior via environment.
  • Precedence is --color > NODEUP_COLOR > NO_COLOR > auto.
  • auto enables color only when each output stream is attached to a terminal.
  • --output json and completions output are always emitted without ANSI styling.

​
Shell completions

Supported shells:
  • bash
  • zsh
  • fish
  • powershell
  • elvish
Command scope behavior:
  • nodeup completions <shell> generates completion output for all top-level commands.
  • nodeup completions <shell> <command> only accepts top-level command scopes (toolchain, default, show, update, check, override, which, run, self, completions).
  • Invalid shell or scope values fail with invalid-input.

​
Reliability and validation

nodeup is validated with both unit tests and end-to-end CLI integration tests to keep command behavior predictable for operators and automation. Coverage highlights:
  • Command-family coverage for toolchain, default, show, update, check, override, which, run, self, and completions.
  • Deterministic JSON failure envelopes on stderr (kind, message, exit_code) with stdout reserved for machine output.
  • Selector precedence checks across explicit selectors, directory overrides, and global defaults.
  • Alias dispatch checks for node, npm, npx, yarn, and pnpm execution paths.
To run project validation from repository root: 
cargo test -p nodeup