Awesome
.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 use .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!
- typescript-action Create a TypeScript Action with tests, linting, workflow, publishing, and versioning
- 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 | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: | :x: | |
avn | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :ghost: #11 |
chnode | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
dev | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
direnv | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | |
fnm | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
mise | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
n | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
nodeenv | :white_check_mark: | :white_check_mark: | :x: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
nenv | :white_check_mark: | 🧩 #8 | 🧩 #8 | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
nodenv | :white_check_mark: | :white_check_mark: | 🧩 #1 | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
nodist | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
nve | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
nvm-rust | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
nvm.fish | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | |
nvs | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
setup-node | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | |
vfox | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |
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 leadingv
, likev20.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?