Context

Sometimes you need to install a Node.js version that is not available in the official ASDF plugin (because node-build lacks the definition or the version was never added). This guide explains how to manually add a custom node-build definition so ASDF can install any Node.js version — including legacy or unreleased ones.

1. Check if ASDF supports the version

asdf list-all nodejs | grep 20.18

If your version does not appear (e.g., 20.18.1), proceed with the manual definition. The all builds are in "https://nodejs.org/dist/.

---

2. Locate the node-build directory used by ASDF

Run:

find ~/.asdf/plugins/nodejs -type d -name "node-build"

This returns the path where node-build definitions are stored. Example output:

/Users/<user>/.asdf/plugins/nodejs/.node-build/share/node-build

Copy that path — you’ll use it next.

---

3. Create a custom definition file

Navigate to the node-build folder:

cd <PASTE_THE_PATH_HERE>/share/node-build

Create a new file named after the version you want:

nano 20.18.1

---

📌 NOTE for Apple Silicon (ARM) users

If you're on Apple Silicon (arm64), you must use the ARM tarball:

install_package "node-v20.18.1-darwin-arm64" "https://nodejs.org/dist/v20.18.1/node-v20.18.1-darwin-arm64.tar.xz#sha256=SKIP"

If you're on Intel, replace with:

install_package "node-v20.18.1-darwin-x64" "https://nodejs.org/dist/v20.18.1/node-v20.18.1-darwin-x64.tar.xz#sha256=SKIP"

---

4. Save and exit

Nano:

CTRL + O → ENTER → CTRL + X

---

5. Install the custom version with ASDF

asdf install nodejs 20.18.1

If the definition is correct, ASDF will download the binary from nodejs.org and install it normally.

---

🧪 6. Verify

node -v

Output:

v20.18.1

🎉 Done!

You have successfully installed a Node.js version that ASDF didn't officially support.