Pin and verify project runtimes

Projects often require specific Node.js, Python, Ruby, or other runtime versions. One global Node works until the day you maintain two projects that disagree, and upgrading for one breaks the other.

The fix has two halves: a version manager that can hold several runtimes side by side (nvm, mise, and similar tools), and a version file committed to each project. The file gives tools and teammates one visible requirement instead of tribal knowledge.

Declare the version in the repo

With nvm the file is .nvmrc:

echo "22.17.0" > .nvmrc
nvm use
# Found '/Users/flavio/dev/api-server/.nvmrc' with version <22.17.0>
# Now using node v22.17.0 (npm v10.9.2)

Other managers read their own files — mise and asdf use .tool-versions — but the principle is identical: the requirement lives in the repository, next to the code that needs it.

Record the version mechanism in the project README too. “Run nvm use before installing” is one line, and it saves every new contributor the same confused half hour.

Prove what the shell resolves

Declaring a version is not the same as running it. After activating your chosen version manager, verify resolution:

node --version
# v22.17.0
command -v node
# /Users/flavio/.nvm/versions/node/v22.17.0/bin/node
type -a node
# node is /Users/flavio/.nvm/versions/node/v22.17.0/bin/node
# node is /opt/homebrew/bin/node

command -v shows the winner. type -a exposes shadowed installations — every node on the PATH, in order. That second line in the output is a Homebrew Node waiting to take over in any shell where the version manager didn’t run.

That is the realistic failure: node --version prints the right number in your terminal, but a script, cron job, or editor launches a shell without the manager’s setup, silently gets the Homebrew Node, and installs native modules against the wrong version. When dependency builds fail mysteriously, run command -v node in the failing context first.

Last piece of advice: avoid a global upgrade that silently changes every project at once. Bump versions per project, through the version file, in a commit that can be reviewed and reverted.