What uses / respects the .node-version file?
node.jsNvmnode.js Problem Overview
I've searched Stack Overflow and GitHub (for both node and nvm) for an answer, but to no avail.
In some repos (like GitHub's Atom text editor, for instance), I've come across a .node-version
file. It seems to be analogous to the .ruby-version
standard file that works with any Ruby version manager to set the current version of Ruby correctly for the project.
But as far as I can tell from its documentation, nvm (Node Version Manager) only respects a .nvmrc
file - it mentions nothing about a more general .node-version
file. And there's no mention of .node-version
in node's documentation (and I wouldn't expect there to be, since it doesn't ship with a version manager out of the box). I'm not aware of any other node version manager in heavy use.
So my question is, what is .node-version
? What tools actually use it? Is it just an alias for .nvmrc
, or am I missing something here?
node.js Solutions
Solution 1 - node.js
There are at least two version managers for node.js, respecting .node-version
file:
- avn - Automatic Node Version Switching
- nodenv - Yet another version managers
- asdf - Extendable version manager with support for Ruby, Node.js, Elixir, Erlang & more, provided you configure it accordingly
There may be some other version managers, but I'm not aware of them.
I don't know which particular version manager Atom uses. nodenv
have more stars on github, but avn
looks more mature and better maintained for me, not to mention its compatibility with both n and nvm.
Solution 2 - node.js
(disclosure: I maintain http://nvm.sh)
The most-used version managers for node are without a doubt nvm
, nave
, and n
.
nvm
is for modifying individual shell sessions to use the version you want.
nave
is for launching subshells with the version you want loaded.
n
is for switching a single system-wide version of node.
nvm
uses a .nvmrc
file, which like .ruby-version
, contains the version-ish string X you'd normally couple with nvm use X
or nvm install X
. nvm use
or nvm install
by itself will locate the .nvmrc
file, as will simply sourcing nvm
upon opening a new shell.
It appears nave
supports a .naverc
file, but I'm not too familiar with its usage.
n
doesn't appear to support any such config, but as it's system-wide, it doesn't really make as much sense to do so.
avn
supports .node-version
and attempts to provide automatic version switching by hooking into cd
, after nvm
decided that was too invasive a behavior to include.
Solution 3 - node.js
.node-version
is a file read by various tools on an individual basis for specifying the target node version. Version managers which use/respect it include (in alphabetical order):
- asdf-nodejs Node.js plugin for asdf version manager. (macOS, Linux)
- avn Automatic Version Switching for Node. (macOS, Linux)
- chnode Changes shell's current Node.js version by updating $PATH
- direnv unclutter your .profile. (macOS, Linux)
- fnm Fast and simple Node.js version manager, built in Rust. (macOS, Linux, Windows)
- n Interactively Manage Your Node.js Versions. (macOS, Linux)
- nenv Groom your app’s Node environment with nenv (macOS, Linux)
- nodenv Manage multiple NodeJS versions. (macOS, Linux)
- nodist Natural node.js and npm version manager for windows. (Windows)
- nve Run any command on specific Node.js versions (macOS, Linux, Windows)
- nvm.fish Node.js version manager lovingly made for Fish. (macOS, Linux)
- nvs Node Version Switcher - A cross-platform tool for switching between versions and forks of Node.js. (macOS, Linux, Windows)
Other products which test for .node-version include:
- Cloudflare Pages Build fast sites. In record time.
- Hostman Hosting platform that deploys your web applications
- netlify Instantly build and deploy your sites to our global network from Git.
- paketo Your app, in your favorite language, ready to run in the cloud
- preferred-node-version Get the preferred Node.js version of a project or user
- render A Cloud for the New Decade
- starship ☄️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!
I documented usage and some supported features here: https://github.com/shadowspawn/node-version-usage
Solution 4 - node.js
Direnv supports both .node-version
and .nvmrc
files. Direnv is all I use for loading project-specific versions of Node.js.
https://github.com/direnv/direnv/wiki/node#load-nodejs-version-from-a-node-version-or-nvmrc-file
Solution 5 - node.js
Solution 6 - node.js
fnm also supports .node-version https://github.com/fisherman/fnm/
for f in .fnmrc .nvmrc .node-version
Solution 7 - node.js
Using nvm use
or nvm install
with no version, nvm will crawl up the file tree looking for a version within a .nvmrc
file, usually landing at stable
in ~/.nvmrc
.
Here is a rough 6-line git patch that will look for a local .node-version
file if no .nvmrc
file is found:
~/.nvm/nvm.sh, ≈line 280
1 file changed, 8 insertions(+), 2 deletions(-)
# Obtain nvm version from rc file
nvm_rc_version() {
local NVMRC_PATH
NVMRC_PATH="$(nvm_find_nvmrc)"
if [ ! -e "${NVMRC_PATH}" ]; then
- nvm_err "No .nvmrc file found"
- return 1
+ local LOCAL_NODE_VERSION_DOTFILE_PATH
+ LOCAL_NODE_VERSION_DOTFILE_PATH="${PWD}/.node-version"
+ if [ -e "${LOCAL_NODE_VERSION_DOTFILE_PATH}" ]; then
+ NVMRC_PATH="${LOCAL_NODE_VERSION_DOTFILE_PATH}"
+ else
+ nvm_err "No .nvmrc file found"
+ return 1
+ fi
No cd-hooking, no extra packages to install, just (what I find to be) a sensible default.