/node-version-usage

Document current usage of .node-version file

MIT LicenseMIT

.node-version File Usage

Q: Is .node-version read by multiple Node.js version managers?
A: Yes.

Q: Does .node-version have a defined common or standard file format?
A: No.

Q: So what compatibility is there across individual products?
A: Good question! Read on...

Supporting Products

Version managers for Node.js which read a .node-version file 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)
  • dev dev is built on pkgx, a single, standalone binary that can run anything (macOS, Linux)
  • direnv unclutter your .profile. (macOS, Linux)
  • fnm 🚀 Fast and simple Node.js version manager, built in Rust. (macOS, Linux, Windows)
  • mise Polyglot switcher compatible with asdf plugins, built in Rust. (macOS, Linux)
  • 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)
  • setup-node (configuration) Set up your GitHub Actions workflow with a specific version of node.js
  • vfox The Multiple SDK Version Manager

Other products which read .node-version include:

  • bitrise The CI/CD Platform built for Mobile DevOps
  • 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
  • Pulumi Deployments Automate, Secure, and Manage Everything You Run in the Cloud
  • ReadyMage Magento 2 and PWA managed auto-scalable infrastructure hosting service.
  • render A Cloud for the New Decade
  • Spaceship Minimalistic, powerful and extremely customizable Zsh prompt
  • starship ☄🌌️ The minimal, blazing-fast, and infinitely customizable prompt for any shell!
  • Vercel Conformance Conformance provides tools that run automated checks on your code for product critical issues, such as performance, security, and code health.
  • VMware Tanzu The Tanzu Node.js Buildpack supports several popular configurations for Node.js apps.

(Note: nvm does not support reading a .node-version file. See #4 for more.)

Suggested Compatible Format

If you are creating the file, a format with full compatibility across current tests is:

  • single line with unix line ending
  • three part numeric version e.g. 14.5.0

A leading 'v' is widely supported, so this will work with most implementations:

$ node --version
v20.12.0
$ node --version > .node-version

If you are reading the file in a new implementation, I suggest you also support optional leading v and any line ending. Allowing a leading v is common and gives nice symmetry with node --version. Allowing any line ending makes it easier for users and especially Windows users to create a file compatible with your product.

Compatibility Testing

Utility simple leading v partial Unix EOL No EOL Win EOL Notes
20.5.0 v20.5.0 20.5
asdf ✅ ✅ ❌ ✅ ✅ ❌
avn ✅ ✅ ✅ ✅ ✅ ✅ 👻 #11
chnode ✅ ✅ ✅ ✅ ✅ ✅
dev ✅ ✅ ✅ ✅ ✅ ✅
direnv ✅ ✅ ✅ ✅ ✅ ❌
fnm ✅ ✅ ✅ ✅ ✅ ✅
mise ✅ ✅ ✅ ✅ ✅ ✅
n ✅ ✅ ✅ ✅ ✅ ✅
nodeenv ✅ ❌ ❌ ✅ ✅ ✅
nenv ✅ 🧩 #8 🧩 #8 ✅ ✅ ✅
nodenv ✅ ✅ 🧩 #1 ✅ ✅ ✅
nodist ✅ ✅ ✅ ✅ ✅ ✅
nve ✅ ✅ ✅ ✅ ✅ ✅
nvm-rust ✅ ✅ ✅ ✅ ✅ ✅
nvm.fish ✅ ✅ ✅ ✅ ✅ ❌
nvs ✅ ✅ ✅ ✅ ✅ ✅
setup-node ✅ ✅ ✅ ✅ ✅ ✅
vfox ✅ ✅ ✅ ✅ ✅ ✅

The columns show whether the utility supports a file containing:

  • simple: three part numeric version, like 20.5.0
  • leading v: numeric version with a leading v, like v20.5.0
  • partial: numeric version with less than three parts, like 20.5
  • EOL: end of line characters used in file, Unix \n or Windows \r\n or none

References

For interest, here are discussion about similar .ruby-version file format. The commonly supported format is a simple version, with many products adding fuzzy matching. (Ruby is likely the inspiration for some of the .node-version usage, especially nodenv which uses rbenv syntax.)

A discussion about a possible standard format for .node-version was started in 2016 initially covering desirable (new) features and then more focus on existing usage, but did not reach consensus.

StackOverflow: What uses / respects the .node-version file?