Managing Node.js versions with asdf

asdf is a runtime version manager that allows you to install multiple programming languages. Its main advantage over the others is that it has a plugin system that will enable it to support various languages, including Ruby, Elixir and Python.

Installation on macOS (Zsh)

1. Make sure Homebrew is installed

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install asdf

brew install asdf

3. Configure Shell

Add these two lines to your .zshrc file.

Load asdf into your current shell session.

. /opt/homebrew/opt/asdf/libexec/asdf.sh

Set default asdf behaviour to mimic nvm/fnm.

export ASDF_NODEJS_LEGACY_FILE_DYNAMIC_STRATEGY=latest_installed

3. Install Node.js

Add node to asdf’s plugin list.

asdf plugin add nodejs

4. Install Node.js

asdf install nodejs latest:22

(At the time of writing, 22 is the LTS)

Configuration

To set it globally

asdf set -u nodejs latest:22

(Where 22 is the same version installed)

To list all installed Node.js versions, use this command.

asdf list nodejs

To set it locally

Either create a .tools-versions file in your project directory.

nodejs 22.15.1

Or set it to read it from the .nvmrc file.

Create a .asdfrc file in your $HOME directory with

legacy_version_file = yes

Useful features

asdf can automatically install global npm packages when a Node.js version is installed.

To do it, create .default-npm-packages in your $HOME directory and write one package per line in it.

Example:

npm
autocannon
firebase-tools
@anthropic-ai/claude-code
@openai/codex

Additional Commands

List installed Node.js versions

asdf list nodejs

Verify current version

asdf current nodejs

For a complete guide, refer to the asdf Getting Started Guide.