Skip to content

nodeup.mdx

Latest commit

 

History

History
150 lines (101 loc) · 4.64 KB

nodeup.mdx

File metadata and controls

150 lines (101 loc) · 4.64 KB

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, and Linux amd64
  • Linux arm64 is not yet published for the Homebrew package

Windows direct install:

  • ./scripts/install/nodeup.ps1 -Version latest -Method direct

Script installer:

./scripts/install/nodeup.sh --version latest --method package-manager
./scripts/install/nodeup.ps1 -Version latest -Method direct

Direct installers verify Sigstore bundle sidecars (*.sigstore.json) and only support bundle-enabled releases.

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

Related pages