Manage Node.js versions using asdf

When working with several projects at a time, you may need different versions of the programming language in which you are writing. This leads to uninstalling and reinstalling the correct version of each language, which wastes plenty of time.

Fortunately, switching between different versions can be easy with version managers like Node Version Manager, rbenv for Ruby, or pyenv for Python.

These are a great help, but now you need to manage and install multiple tools for your multi-language project, which can be cumbersome. Instead, you can use asdf to manage multiple runtime versions, managing all of the language versions that you’re using with a single CLI tool.

Asdf is an extendible version manager that supports multiple languages like Ruby, Node.js, Elixir, Erlang, Python, and more, all at once. You can switch between versions of languages both globally and on a per-directory basis.

In this article, we will learn everything you need to work with asdf and Node, including how to set up and update asdf in your local machine, and install, update, and remove the Node plugin.

Getting started

To begin using asdf, we need to install some dependencies like coreutils, curl, and git. Asdf uses these dependencies to install different languages.

Execute the following commands to install asdf:

 
brew install coreutils curl git  # on macOS with Homebrew

sudo apt install curl git        # on Linux

Asdf documentation recommends cloning from the git repo, like so:

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.8.1

To install asdf, add it to your shell. You can check out other installation methods in the documentation. I’ll be using the “Bash & Homebrew (macOS)” method.

Add asdf.sh to your ~/.bash_profile with the following:

echo -e "\\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.bash_profile

Then, set up bash completion:

echo -e "\\n. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash" >> ~/.bash_profile

You can see your ~/.bash_profile like so:

cat ~/.bash_profile

Asdf also supports Zsh and Fish shells.

Now, close the terminal, and start a new terminal. Let’s make sure asdf is installed by typing asdf in the command line.

Installing the Node.js plugin

In asdf, each language is supported by a plugin. They have hundreds of plugins, but if you don’t see what you need, you can also create your own.

Plugins don’t just include languages; asdf also supports databases.

Plugins are installed with the following command:

asdf plugin add <name> 

Before installing the Node plugin, we first have to install GnuPG to verify the authenticity of the package. There are different requirements for every plugin, which you can find on each plugin’s GitHub repo.

For Mac, we can install GnuPG via Homebrew:

brew install gpg

After installing GnuPG, install the Node plugin by running the following:

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

Once installed, you can see a list of installed plugins like so:

asdf plugin list

Installing a programming language version

Asdf lists all available versions of each programming language; as of writing this article, there are a total of 604 versions of Node we can install.

You can view a list of Node versions with the following:

asdf list all nodejs | wc -l   # prints 604

To install a specific version of Node, run:

asdf install nodejs 14.17.6

If you come across some errors while installing a version of Node, try this command:

asdf reshim nodejs

You may get an error here about reshim . Without running the reshim command, the npm package will not be available in your path:

Unknown command: `asdf reshim nodejs 14.17.6`
/usr/local/Cellar/asdf/0.8.1_1/libexec/bin/asdf: line 82: /Users/<your-username>/.asdf/lib/commands/command-help.bash: No such file or directory

You can see which versions you have installed by running the following:

asdf list all nodejs

To install the latest version of Node, run:

asdf install nodejs latest

We can also install the latest Node version that begins with a given string:

# asdf install <name> latest:<version>
asdf install nodejs latest:16

Setting a version

Programming language versions can be set on three levels: global, in the current shell, or locally.

Global

You can set a default global version of Node so that it will persist in any new shell. This will add or update a line in the .tool-versions file under the Home directory.

To set a global or default version of Node, run:

# asdf global <name> <version> [<version>...]
asdf global nodejs 14.17.6
asdf global nodejs latest

Now, you can verify the current version of asdf with asdf current command. In my case, it’s showing the latest Node version of 16.9.0:

(base) ➜  ~ asdf current
nodejs          16.9.0          /Users/<username>/.tool-versions

If you don’t have a version listed for a tool execution, this will return an error. With this command, we can see the tool and version resolution, or the absence of it, from the current directory.

Global defaults are managed in $HOME/.tool-versions. You can see its contents by running the following:

cat $HOME/.tool-versions

I have set the global Node version to the latest, which I can verify by running:

(base) ➜  ~ node -v
v16.9.0 

Shell

If you want to use the Node version only in the current shell, run the following:

# asdf shell <name> <version> [<version>...]
asdf shell nodejs 14.17.6
asdf shell nodejs latest

This version of Node will only run in the current shell session, so when you close the session, this version will not be available.

Under the hood, shell sets the version to an environment variable named ASDF_${LANG}_VERSION for the current shell session only:

ASDF_NODEJS_VERSION=14.17.6 node --version

Local

You can also run a specific version of Node based on a single project by setting up the version locally:

asdf local <name> <version> [<version>...]
asdf local nodejs 14.17.6
asdf local nodejs latest

local writes the version to $PWD/.tool-versions.

You can verify the Node version for local and shell environments by running node -v.

To set up a local version based on a single project, first install the version you want to use with asdf install nodejs and run asdf local nodejs . This will create a .tool-versions file with the Node version you chose.

Uninstall a version

To uninstall a version, use this command:

# asdf uninstall <name> <version>
asdf uninstall nodejs 14.17.6
asdf uninstall nodejs latest

Legacy support

Adopting a new version manager can take time within teams, which is why asdf lets you fallback to legacy version files. You can still use your preferred version manager like nvm, if you’d like.

To enable legacy support, just add a .asdfrc file to the home directory ($HOME/.asdfrc) and add the following configuration setting:

legacy_version_file = yes  # .asdfrc file

By setting legacy version files to yes, asdf will be able to read other version manager files like .nvmrc, .node-versions or .ruby-versions.

Updating plugins

At some point, you may need to update the plugins. You can do it by running this command:

asdf plugin update --all

Up until this point, we have relied on asdf to manage multiple development environments. To keep up with the asdf version, run the following command:

asdf update       # via git
brew upgrade asdf # via homebrew

If you want to uninstall asdf, you can follow along with the docs.

Conclusion

Asdf is a great tool for polyglot programmers. It enables a concern-free installation and easy switching between multiple language versions, saving time for what really matters – Don’t forget to read the Ballad of asdf!

Now, you can install as many languages as you want to work with. Instead of using many different package managers, you can give asdf a try to rule them all.

What about you? Do you use asdf? How has your experience been with it?