According to davidwalsh.name, a single line in a file called .nvmrc can save every developer on a project from "works on my machine" chaos. The file is plain text, lives in the repo root, and tells nvm which Node version to use.
That is the entire feature. The reason it matters is that Node moves fast, and most "weird" bugs in a fresh checkout are actually version mismatches.
What happened
- .nvmrc is a single-line text file containing a Node version string.
- Running nvm use reads the file and switches to the listed version automatically.
- It works with nvm install to install the version if it is not already present.
- It belongs in the root of every project that uses nvm.
- It is a one-time setup that prevents weeks of version drift bugs.
Why this is worth doing
Node.js has a habit of breaking things between major versions. Dependencies that worked on one major version may not on the next. A team that does not pin a version will end up with contributors spread across multiple active versions, and a stream of issues that look like flaky tests but are really version mismatches.
.nvmrc solves this with a one-line file in the repo. The contents are just the version string, for example the example given in the original post which is "v16". Any contributor can run nvm use and the right version downloads and activates. Nvm install then runs the project's install steps against that version, so the lockfile and the runtime are aligned.
How to set it up
Open the project root. Create a file called .nvmrc with no extension. Add the version you want to standardize on, following the format shown in the reference. Commit it. That is the entire setup. The next time a new contributor clones the repo and runs nvm use, they will land on the right version.
Pair .nvmrc with an engines field in package.json if you publish packages. That gives npm itself a chance to complain when the wrong version is in use. The two together cover both human contributors and CI.
What it means for you
If you are a Tip Tipa reader who works on Android, web, or anything that touches Node tooling, this is a free five-minute improvement. Add .nvmrc to every repo you maintain. Add it to the repos you contribute to, even if you have to send a PR. The cost is trivial and the upside is months of "but it works for me" cleanup that never happens.
The same pattern works for any version manager. Ruby has .ruby-version, Python has .python-version, and Go has go.mod's directive. The idea is the same: pin the runtime so the team starts from the same place every time.
A worked example
Say you inherit a repo that "sometimes fails to build" on a teammate's machine. You check the repo and there is no .nvmrc. The README says "use Node 18" but the lockfile is built against a slightly different patch. You run node -v and you are on a much newer major. You drop a one-line .nvmrc with the version the lockfile was built against, commit, and push. The next person who clones the repo runs nvm use, gets the right version, and the build works. That is the end of the flaky-build thread.
The principle scales. Pin everything you can: the Node version with .nvmrc, the package manager with corepack, the formatter with a config file in the repo. Each pin removes a class of "why does it look different on my machine" surprises.
Bottom line
A single line in .nvmrc is the cheapest insurance you can buy against version drift. Add it to every repo and commit it today.
Key takeaways
- .nvmrc is a one-line file in the repo root that pins the Node version.
- It works with nvm use and nvm install to align every contributor.
- It eliminates the most common class of "works on my machine" bugs.
- The setup takes under a minute and pays off forever.
Frequently asked questions
What goes inside .nvmrc?
A version string, such as the "v16" example from the reference. Nvm reads it on nvm use.
Does this work without nvm?
No, nvm reads .nvmrc. Other version managers use their own files, like .ruby-version for rbenv.
Should I also pin the version in package.json?
Yes. The engines field in package.json is a good second line of defense, especially for published packages.
Does .nvmrc affect CI?
Only if your CI uses nvm. Most CI providers have their own Node version settings, which should match what is in .nvmrc.