nave

library3.5.6jsnpmunverified

Nave (Node Virtual Environments) is a command-line tool designed for managing multiple Node.js versions and their associated global npm package installations. It operates by spawning isolated subshells, allowing users to switch Node.js versions and their global npm environments on a per-session or per-project basis without permanently altering system-wide shell configurations like `.bashrc` or `.profile`. As of version 3.5.6, Nave functions primarily as a Bash script, differentiating it from Node.js-based version managers. Its installation can be achieved by simply downloading the `nave.sh` script or via a global npm installation, which essentially symlinks the script. The project's release cadence is irregular, reflecting maintainer-driven updates rather than a fixed schedule. A key advantage is its lightweight nature and reliance on standard shell features for environment isolation.

devops

npm install nave

github ↗package ↗

INSTALL

IMPORT

SIG · NAVE

nave

devopsjavascriptv3.5.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

This quickstart demonstrates the installation of the Nave shell script, listing remote Node.js versions, installing and switching to a specific version within a temporary subshell, installing a global npm package, and managing named Node.js environments. Note that these are shell commands, not JavaScript code, executed in the context of Node.js development.

# Install nave by downloading the script (recommended for initial setup) curl https://raw.githubusercontent.com/isaacs/nave/main/nave.sh > /usr/local/bin/nave chmod 0755 /usr/local/bin/nave # List available remote Node.js versions nave ls-remote # Install a specific Node.js version and automatically switch to a subshell using it nave use 18.17.1 # Verify the active Node.js and npm versions within the subshell node -v npm -v # Install a global npm package within this specific Node.js environment npm install -g yarn # Exit the nave subshell to revert to the previous Node.js environment exit # Install an LTS version under a named environment nave use my-project-env lts/hydrogen # Enter the named environment later nave use my-project-env # List locally installed Nave environments and versions nave ls

nave --version

Debug

Known issues

gotchaNave primarily operates by spawning a new subshell for each `nave use <version>` command. This means that changes to the Node.js version and global npm packages are scoped only to that subshell. Exiting the subshell (e.g., with `exit` or `^D`) will revert your environment to its state before `nave use` was called.

fix

Always remember that `nave use` creates a temporary environment. For persistent changes across all your terminal sessions, consider using `nave usemain <version>`, or for project-specific auto-switching, configure a `.naverc` file and use `nave auto`.

affects: >=3.0.0

gotchaAlthough Nave can be installed via `npm install -g nave`, it is fundamentally a Bash shell script, not a Node.js library. Users accustomed to typical Node.js package interactions might find its shell-based nature and command-line interface distinct.

fix

Understand that Nave's operations are command-line based shell functions. Its internal workings and troubleshooting are often related to shell environments (PATH, permissions, subshells) rather than Node.js module resolution or JavaScript execution.

affects: >=3.0.0

gotchaTo establish a specific Node.js version as the 'main' system-wide version (i.e., modifying `/usr/local/bin` to point to a Nave-managed Node.js), you must explicitly use the `nave usemain <version>` command. Regular `nave use <version>` only affects the current subshell.

fix

If you intend for a Node.js version to be your default across all new terminal sessions, use `nave usemain <version>`. Be aware that this command may require `sudo` privileges depending on your system's `/usr/local` permissions.

affects: >=3.0.0

gotchaNave focuses exclusively on managing Node.js runtime versions and their associated global npm packages. It does not manage local project `node_modules` dependencies or `package.json` configurations. These aspects are handled by standard tools like `npm` or `yarn` within the activated Nave environment.

fix

Continue using `npm install` or `yarn install` within your project directories after switching to a desired Node.js version with Nave to manage project-specific dependencies.

affects: >=3.0.0

Errors

Common errors & fixes

nave: command not found

The `nave.sh` script is not located in a directory listed in your system's PATH environment variable, or it does not have execute permissions.

fix

Ensure the `nave.sh` file (e.g., downloaded to `/usr/local/bin/nave`) has execute permissions (`chmod 0755 /usr/local/bin/nave`) and that its containing directory is included in your shell's PATH. If installed via npm, verify `npm bin -g` is in your PATH.

Node.js version is not X.Y.Z outside of the nave shell

The `nave use <version>` command only creates a temporary subshell environment. When you `exit` that subshell, your terminal reverts to the Node.js version that was active before `nave use` was called.

fix

If you want a Node.js version to be the default for all new terminal sessions, use `nave usemain <version>`. For project-specific, persistent environment switching, configure a `.naverc` file and use `nave auto`.

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/npm'

When attempting to install global npm packages within a `nave` environment, `npm` is trying to write to a system-owned directory (`/usr/local`) where your current user lacks write permissions.

fix

This often means the `npm` prefix within the Nave environment is incorrectly configured. Ensure `npm config get prefix` inside the `nave` subshell points to a user-owned directory within your Nave installation (e.g., `~/.nave/node/<version>/`). If not, you might need to reinstall the Node version via Nave, or manually configure the npm prefix using `npm config set prefix ~/.nave/node/$(nave get version)/lib/node_modules` (adjust path as necessary).

Upgrade

Version history

3.5.6latest on npm

Audit

Dependencies

bashrequiredNave is a Bash shell script and requires a Bash-compatible shell environment to execute its commands.

curloptionalUsed for the recommended method of initially installing the `nave.sh` script by downloading it from GitHub.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/isaacs/nave ↗

packagehttps://www.npmjs.com/package/nave ↗