Automating Node.js Versions for Seamless Development

Managing Node.js versions across different projects can be a headache. One project needs Node 14, another needs 16, and the latest one uses 20. Forgetting to switch versions can lead to weird compilation errors and wasted time.

In this post, we'll explore how to automate this process using nvm (Node Version Manager) and some simple scripts, ensuring your environment is always correct.

What is NVM?

NVM (Node Version Manager) is the industry standard for managing multiple Node.js versions on a single machine. It allows you to install and switch between different versions with simple commands.

Normally, you would use it like this:

1. List installed versions: nvm ls
2. Install a specific version: nvm install 16
3. Switch to a specific version: nvm use 16
4. Set a default version: nvm alias default 20

While nvm use 16 is easy enough to type, doing it every time you switch projects is tedious and error-prone. That's where automation comes in.

1. Pinning the Version with .nvmrc

The first step is to explicitly declare which Node version your project needs. We do this with a .nvmrc file in the root of your project.

16

This simple file tells nvm exactly which version to use. You can simply run nvm use in your terminal, and it will pick up this version automatically.

2. Enforcing Constraints with package.json

To ensure that tools like npm or yarn warn you if you're using the wrong version, you should add an engines block to your package.json.

"engines": {
    "node": "16.x",
    "npm": ">=8.0.0"
}

While this doesn't switch the version for you, it acts as a safeguard against using incompatible runtimes.

3. Automating the Start Command

Why remember to run nvm use before starting your server? We can automate this by wrapping our start command in a shell script.

Create a script called start-dev.sh (you can download the bash script below):

#!/bin/bash

# Load nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Use the Node version specified in .nvmrc
nvm use

# Run the Angular dev server
ng serve "$@"

Then, add a custom script to your package.json:

"scripts": {
    "devstart": "./start-dev.sh"
}

Now, when you run npm run devstart, the script will automatically ensuring the correct Node version is active before launching your Angular application.

4. The "Magic" Auto-Switch for Mac Users

For an even smoother experience, you can configure your shell to automatically switch Node versions whenever you cd into a directory containing an .nvmrc file.

We have a setup script, setup-nvm-auto-switch.sh (available for download below), that configures your Zsh profile (~/.zshrc) to handle this.

The script adds a hook that checks for an .nvmrc file every time you change directories:

autoload-nvmrc() {
  if [[ -f .nvmrc && -r .nvmrc ]]; then
    nvm use
  elif [[ $(nvm version) != $(nvm version default) ]]; then
    echo "Reverting to nvm default version"
    nvm use default
  fi
}
add-zsh-hook chpwd autoload-nvmrc

Once you run this setup script once, your terminal becomes context-aware, automatically switching to Node 16 when you enter the project and reverting to your default version when you leave.