NVM and .nvmrc Management Guide

A comprehensive guide for managing Node.js versions across projects using nvm and .nvmrc files.

What is nvm?

Node Version Manager (nvm) allows you to install and switch between multiple Node.js versions on the same machine. This is essential for:

Working on projects that require different Node versions
Testing applications across Node.js versions
Avoiding "works on my machine" issues in teams

What is .nvmrc?

.nvmrc is a simple text file that specifies which Node.js version a project should use. When placed in a project root, it allows automatic version switching.

Installation

macOS/Linux

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash
# Restart terminal or run: source ~/.bashrc

Windows

Use nvm-windows

Basic nvm Commands

# List available Node versions
nvm ls-remote

# List installed versions
nvm list

# Install latest LTS
nvm install --lts

# Install specific version
nvm install 22.17.0

# Use specific version
nvm use 22.17.0

# Set default version
nvm alias default 22.17.0

# Uninstall version
nvm uninstall 20.0.0

Working with .nvmrc

Creating .nvmrc

# In your project directory
echo "22.17.0" > .nvmrc

# Or use current version
node --version > .nvmrc

Using .nvmrc

# Switch to version specified in .nvmrc
nvm use

# Install version specified in .nvmrc
nvm install

Automatic Version Switching

Add this to your shell profile (~/.zshrc, ~/.bashrc):

# Auto-switch Node version when entering directory with .nvmrc
autoload -U add-zsh-hook
load-nvmrc() {
  if [[ -f .nvmrc && -r .nvmrc ]]; then
    nvm use
  fi
}
add-zsh-hook chpwd load-nvmrc

For bash users:

# Add to ~/.bashrc
cdnvm() {
    command cd "$@"
    nvm_path=$(nvm_find_up .nvmrc | tr -d '\n')
    if [[ ! $nvm_path = *[^[:space:]]* ]]; then
        declare default_version;
        default_version=$(nvm version default);
        if [[ $default_version == "N/A" ]]; then
            nvm install node;
            default_version=$(nvm version default);
        fi
        if [[ $(nvm current) != "$default_version" ]]; then
            nvm use default;
        fi
    elif [[ -s $nvm_path/.nvmrc && -r $nvm_path/.nvmrc ]]; then
        declare nvm_version
        nvm_version=$(<"$nvm_path"/.nvmrc)
        declare locally_resolved_nvm_version
        locally_resolved_nvm_version=$(nvm ls --no-colors "$nvm_version" | tail -1 | tr -d '\->*' | tr -d '[:space:]')
        if [[ "$locally_resolved_nvm_version" == "N/A" ]]; then
            nvm install "$nvm_version";
        elif [[ $(nvm current) != "$locally_resolved_nvm_version" ]]; then
            nvm use "$nvm_version";
        fi
    fi
}
alias cd='cdnvm'

Best Practices

Project Setup

Always include .nvmrc in your project root
Specify exact versions (not ranges like >=18)
Use LTS versions for production projects
Add to version control (commit .nvmrc)

Team Collaboration

# package.json engines field
{
  "engines": {
    "node": ">=22.17.0",
    "npm": ">=10.9.0"
  }
}

Documentation

Include setup instructions in your README:

## Getting Started

1. Install the correct Node version:
   ```bash
   nvm install
   nvm use

Install dependencies:
```
npm install
```


## Common Scenarios

### Starting a New Project
```bash
# 1. Install latest LTS
nvm install --lts
nvm use --lts

# 2. Create .nvmrc
node --version > .nvmrc

# 3. Initialize project
npm init -y

Joining an Existing Project

# 1. Clone repository
git clone <repo-url>
cd <project>

# 2. Install and use specified Node version
nvm install
nvm use

# 3. Install dependencies
npm install

Managing Multiple Projects

# Project A (Node 18)
cd project-a
nvm use  # Automatically switches to 18.x

# Project B (Node 22)
cd project-b
nvm use  # Automatically switches to 22.x

Troubleshooting

"nvm: command not found"

# Add to your shell profile
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

"node: command not found" after nvm install

# Set a default version
nvm alias default node
# Or specific version
nvm alias default 22.17.0

Package manager not found after version switch

# Each Node version has separate global packages
# Reinstall global packages for each version
npm install -g pnpm yarn

.nvmrc not working

# Check file contents
cat .nvmrc

# Ensure no extra whitespace
echo "22.17.0" > .nvmrc

# Make sure auto-switching is set up
# (see "Automatic Version Switching" section)

Advanced Tips

List Global Packages by Version

# See what's installed globally for current version
npm list -g --depth=0

# Reinstall globals when switching versions
npm install -g pnpm yarn typescript

Migrate Packages Between Versions

# From old version
nvm use 20.0.0
npm list -g --depth=0 --json > packages.json

# To new version
nvm use 22.17.0
# Parse packages.json and reinstall as needed

Version-Specific Commands

# Run command with specific Node version
nvm exec 18.0.0 node script.js

# Run in subshell with different version
nvm run 20.0.0 --version

Integration with CI/CD

GitHub Actions

- name: Use Node.js from .nvmrc
  uses: actions/setup-node@v4
  with:
    node-version-file: '.nvmrc'
    cache: 'npm'

Docker

# Read version from .nvmrc
FROM node:$(cat .nvmrc)-alpine
WORKDIR /app
COPY . .
RUN npm install

Summary

nvm manages multiple Node.js versions
.nvmrc specifies project Node version
Automatic switching eliminates manual version management
Team consistency through version control and documentation
CI/CD integration ensures deployment consistency

This setup eliminates "works on my machine" issues and ensures all team members use consistent Node.js versions across projects.

davehague/NVM-management.md