80

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?

wisew
  • 2,672
  • 3
  • 23
  • 30

7 Answers7

49

.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 (macOS, Linux)
  • 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)
  • nodeenv Virtual environment for Node.js & integrator with virtualenv (macOS, Linux, Windows)
  • 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-rust A cross-platform node version manager that doesn't suck (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)
  • rtx Polyglot switcher compatible with asdf plugins, built in Rust. (macOS, Linux)
  • setup-node (configuration) Set up your GitHub Actions workflow with a specific version of node.js
  • tea tea is the next-generation, cross-platform package manager from the creator of brew. (macOS, Linux)

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!

Note: nvm does not support reading a .node-version file.

I documented usage and some supported features here: https://github.com/shadowspawn/node-version-usage

shadowspawn
  • 3,039
  • 22
  • 26
47

There are a few 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
  • nvs - Node Version Switcher

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.

unional
  • 14,651
  • 5
  • 32
  • 56
Leonid Beschastny
  • 50,364
  • 10
  • 118
  • 122
  • 2
    [ndenv](https://github.com/riywo/ndenv) also uses `.node-version` file. – paulodiovani Jul 27 '16 at 13:55
  • 4
    I recommend `nodenv` - it also works like `rbenv` and `pyenv` so you can carry over your knowledge. – Ben Creasy Aug 05 '17 at 23:22
  • Well, the answer might be shorter if explained what does not support `.node-version` file then! All "node version managers" known seem to support it. From what I understand, one could safely assume they can rename their `.nvmrc` file to `.node-version` safely, which would cover more "node version managers". - WELL it seems I misunderstood that answer and `nvm` doesn't support `.node-version`, see https://stackoverflow.com/a/29545541/2391795 – Vadorequest Dec 03 '20 at 13:46
  • [nodeenv](https://github.com/ekalinin/nodeenv)—a node virtual env manager—also uses the file: https://github.com/ekalinin/nodeenv/blob/0f9e2e2d85240d263016347802453ffec5d64727/nodeenv.py#L138-L140 (note the double "ee" in its name, this is different from [nodenv](https://github.com/nodenv/nodenv) linked in the answer, which has a single "e"). – nishanthshanmugham Nov 27 '22 at 16:18
  • 1
    There are lots of version managers now that support `.node-version`. I added a more up to date list in separate answer. – shadowspawn May 20 '23 at 03:44
43

(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.

Community
  • 1
  • 1
LJHarb
  • 32,486
  • 2
  • 32
  • 38
  • How do you get changing a directory to switch to the .nvmrc just like rvm does? – justingordon Oct 31 '15 at 22:32
  • You don't, not automatically. `nvm` isn't intrusive like `rvm` is. You could certainly overwrite your builtin `cd` to run `nvm use`, but how often are you cding around as opposed to using multiple shell tabs? – LJHarb Nov 01 '15 at 23:40
  • 5
    It's nice to not have to remember to set your node version when you cd into a project. Nothing worse than killing hours trying to figure out why your app suddenly doesn't work when all this time you forgot to change your node version to the version the app your working on is known to run on. This lack of support for auto switching has me contemplating switching from nvm to avn. – Catfish Jan 19 '16 at 21:53
  • 4
    "auto switching" is intrusive and slow. If you'd like to use it, you can overwrite `cd` yourself, or you can use nvm via avn which does that for you. – LJHarb Jan 21 '16 at 05:40
  • Is there any link to the discussion where auto switching was rejected? Would be interested to learn more about this decision. – Meekohi Jul 22 '19 at 15:37
  • @LJHarb auto switching is not intrusive and slow, there are tools that don't get it right, but it's certainly possible to do it right, take a look into the multiple runtime version manager, `asdf`. – goetz Jul 24 '20 at 23:52
  • 1
    @goetzc I've used asdf; hijacking `cd` always introduces a slowdown, and using always-pathed shims introduces a slowdown when invoking the tool itself. There's no "right" way to do it that avoids these tradeoffs. – LJHarb Jul 26 '20 at 19:59
  • 3
    @LJHarb Could you please clarify whether `nvm` supports `.node-version` file? Or does it only support `.nvmrc`? (the accepted answer is confusing me, and your answer isn't straight-to-the-point) – Vadorequest Dec 03 '20 at 13:49
  • 3
    @Vadorequest nvm only supports `.nvmrc`. – LJHarb Dec 04 '20 at 22:52
  • rtx supports autoswitching (though technically not on "cd"—that's the wrong place to put it) and thanks to being written in rust the performance impact is negligible. You're not going to notice <5ms of overhead. – Jeff Dickey May 08 '23 at 18:16
6

asdf with asdf-nodejs supports .node-version with

legacy_version_file = yes

added to ~/.asdfrc

Evmorov
  • 1,134
  • 22
  • 28
5

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

Wil Moore III
  • 6,968
  • 3
  • 36
  • 49
3

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.

Nodeski
  • 31
  • 2
3

fnm also supports .node-version https://github.com/fisherman/fnm/

for f in .fnmrc .nvmrc .node-version
aristidesfl
  • 1,310
  • 10
  • 15