How to Use and Tips for nvm - Node Version Manager

The Issue

What makes you feel "fear" when working with Node.js? For me, it's maintaining an old Node.js/JavaScript codebase, meaning a project that was written a long time ago and is using a very outdated version of Node that can barely run.

It's not hard to understand, and I'm sure many readers have similar feelings. There are plenty of reasons for this, such as outdated syntax, disorganized code, libraries no longer supported, or even the lack of documentation... Imagine a library you've never used before suddenly has no trace of documentation – how would you proceed? Not to mention, when you encounter issues with an "archived" library, there's no one left to ask.

But in life, we can't avoid such situations forever; maintenance is inevitable. My computer is currently running Node 18, a "modern" version, but I need to run an "app" that requires Node < 8. What should I do? Uninstall, reinstall, uninstall again, reinstall... Is this the process I have to go through every time I want to use a different Node version? Of course not. I'm sure many of you have heard of nvm – Node Version Manager, which makes it easy to switch between different Node.js versions with just a few simple commands.

In fact, nvm is not the only tool that can do this; there are many tools to manage Node.js versions, such as fnm and asdf. However, it's a matter of personal preference, and I'm using nvm. Therefore, today, I'd like to share some ways and tricks to use it effectively.

What Is NVM?

NVM (Node Version Manager) is a tool that helps you manage different versions of Node.js on your computer. It allows you to easily install, switch between, and manage various Node.js versions on the same system. This is especially useful when working on different projects that require different Node.js versions.

Installing nvm is straightforward, and it supports all three major platforms: Mac, Linux, and Windows. For example, I'm using a Mac and I use Homebrew for installation:

$ brew install nvm

Also, please note that you need to add these two configuration lines to ~/.profile or ~/.zshrc if you're using zsh:

    export NVM_DIR="$HOME/.nvm"
    [ -s "$HOMEBREW_PREFIX/opt/nvm/nvm.sh" ] && \. "$HOMEBREW_PREFIX/opt/nvm/nvm.sh" # This loads nvm
    [ -s "$HOMEBREW_PREFIX/opt/nvm/etc/bash_completion.d/nvm" ] && \. "$HOMEBREW_PREFIX/opt/nvm/etc/bash_completion.d/nvm" # This loads nvm bash_completion

Or, if you're on Linux:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.4/install.sh | bash

For Windows, it's a bit different; you can download and install it from nvm-windows.

How to Use and Tips

The concept of using nvm is quite simple: "install version -> switch version -> run."

# Download version 18
$ nvm install 18

# List installed versions
$ nvm ls
       v16.18.1
->     v18.17.1

# Select version 16
$ nvm use 16

# Run your code
$ node index.js

Once you select version 16, this Terminal session will be using Node 16, allowing you to start Node/JavaScript applications with the chosen version.

When you're done with your session, like closing the Terminal, Node will revert to the default version. If you want to use Node 16 again, you just need to run nvm use 16. However, this can be inconvenient and time-consuming, so to check which version nvm is currently using as the default:

$ nvm alias default
default -> 18 (-> v18.17.1)

In this case, it's set to use version 18 as the default. If you want to switch to version 16, you can do this:

$ nvm alias default 16
$ nvm alias default
default -> 16 (-> v16.18.1)

However, I have about a dozen projects, each requiring a different Node version. How can I remember or at least communicate to others which version to use? It's simple; create an .nvmrc file in the project's root directory. For example:

$ echo "16" > .nvmrc

This command creates an .nvmrc file containing the number 16. .nvmrc serves as nvm's configuration file, letting everyone know which Node version is recommended for this project. Then, just run:

$ nvm use

Nvm will immediately switch to version 16.

Well, that's interesting, but it's still a hassle to manually type the use command every time you open a project, right? Ah... yeah... there's a way to automate that as well. We'll add a command to automatically detect and use nvm in the background.

For example, I'm using zsh, so I open ~/.zshrc and add this line at the end:

$ vi ~/.zshrc

autoload -U add-zsh-hook

load-nvmrc() {
  local nvmrc_path
  nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version
    nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
      nvm use
    fi
  elif [ -n "$(PWD=$OLDPWD nvm_find_nvmrc)" ] && [ "$(nvm version)" != "$(nvm version default)" ]; then
    echo "Reverting to nvm default version"
    nvm use default
  fi
}

add-zsh-hook chpwd load-nvmrc
load-nvmrc

Save it and update the configuration:

$ source ~/.zshrc

If you're not using zsh, you can explore other methods at Deeper Shell Integration.

Now, try closing and reopening VSCode and opening a terminal in-app to see if Node automatically switches to the version specified in .nvmrc.

Finally, a note about debugging: if you're used to debugging with breakpoints, your text editor or IDE might not know which Node version you want to use for debugging. Depending on the tool you're using, there may be a way to configure the Node version somewhere, but for VSCode, I don't currently see such an option. Therefore, the simplest solution is to set the default Node version with the alias command, restart VSCode, and you're good to go.