.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
• 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)
• setup-node (configuration) Set up your GitHub Actions workflow with a specific version of node.js

Other products which read .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!

Suggested Compatible Format

If you are creating the file, the 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
v10.15.3
$ 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

References

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

• https://gist.github.com/fnichol/1912050

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.

• https://github.com/nodejs/version-management/issues/13

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

• https://stackoverflow.com/questions/27425852/what-uses-respects-the-node-version-file