Manage Node.js versions with OMG

Install Node.js in pure Rust without external subprocesses, verify official SHA-256 digests, switch project versions with .node-version or .nvmrc, and diagnose PATH conflicts.

OMG maintainers · Updated · Source-reviewed guide

Pure Rust Node.js installation without external processes

Unlike shell wrappers that spawn curl, tar, and xz subprocesses, OMG manages Node.js entirely in compiled Rust (`src/runtimes/node.rs`). It queries the official index at `nodejs.org/dist/index.json`, downloads release archives directly over HTTPS, and parses `SHASUMS256.txt` to verify the archive hash in memory before extraction.

Extraction is handled by OMG’s pure-Rust `.tar.xz` streaming unpacker (`extract_tar_xz`) into an isolated temporary directory. Once the regular file at `bin/node` is verified, the installation is published atomically to `~/.local/share/omg/versions/node/<version>`.

Install Node.js releases and aliases

omg use node lts
omg use node lts/iron
omg use node 22
omg list node
omg which node

OMG resolves aliases deterministically: `lts` maps to the current active LTS release from `index.json`, `lts/<codename>` (e.g. `lts/iron` or `lts/jod`) maps to that named release, and partial version numbers like `20` or `20.1` resolve to the newest matching release.

Published OMG releases target Linux x86_64 and Apple Silicon macOS. On Windows, run OMG inside WSL; Intel macOS and Linux ARM64 are not published release targets.

Project version pin resolution order

When you enter a project directory, OMG’s compiled shell hook (`src/hooks/mod.rs`) walks upward through the directory tree. The nearest directory with a Node.js pin wins. Within one directory, it checks these sources in order:

  1. Explicit `.node-version` file in the project directory or any parent directory.

  2. Legacy `.nvmrc` file (reused directly without configuration translation).

  3. Multi-runtime `.tool-versions` file (asdf and mise compatibility).

  4. `package.json` engines (`engines.node`) or Volta pin (`volta.node`).

Verify active Node.js and npm path in your shell

omg which node
which -a node
node --version
npm --version

Runtime ownership vs package management

OMG manages the Node.js executable and the `npm` and `npx` binaries bundled with that release. It activates them by symlinking the selected version to `~/.local/share/omg/versions/node/current/bin` and prepending that directory to your PATH.

OMG does not intercept or wrap `npm install` or `pnpm install`. Dependency resolution, `node_modules`, and lockfiles (`package-lock.json`, `pnpm-lock.yaml`) remain strictly under the control of their respective package managers.

Diagnosing PATH precedence and conflicting shims

A previously activated nvm, system installation, or another version manager can appear earlier in PATH. Review the shell profile and enable only the manager intended for this project. Keep the old installation until the new workflow works.

OMG is approaching beta. These instructions are reviewed against the linked source documentation, not a claim of execution on every supported platform. Consult the runtime handbook for verification, storage, and version-file details.

Inspect shell runtime resolution

omg which node
which -a node
which -a npm

Sources and verification

Commands and behavior are based on the references below. Source review is not a claim that every workflow has been executed on every supported platform.

Read as Markdown