Blog Set up per-project Node versions painlessly
Set up per-project Node versions painlessly
TL;DR Use a Node version manager and commit a version file to each project. The manager reads it and switches to the right Node version when you enter the directory, so every project runs on the version it was built for, and new contributors get it automatically.
Switching between projects that expect different Node versions is a quiet source of wasted time: an install fails, a build breaks, a bug appears, and it takes a while to realise you are just on the wrong Node. A version manager plus a committed version file fixes it for good. Here is the setup.
Use a version manager
Install a Node version manager, the tool that lets you install and switch between multiple Node versions on one machine. With it, you can have several versions side by side and pick which one a shell uses.
That alone solves the manual case: you can switch versions on demand. The real win is making the switch automatic.
Commit a version file
Add a small file to each project that names the Node version it expects, and commit it to the repo:
# .nvmrc
20
Now the project itself declares its Node version, in version control, where everyone sees it.
Let it switch automatically
Configure your version manager to read that file when you enter a directory. From then on, changing into a project's folder switches you to the right Node version without a thought. Move to another project, and it switches again.
You stop tracking versions in your head. The directory you are in decides the Node version, which is exactly right, because the project knows what it needs and you do not have to.
Why the committed file matters
The version file is not just for you. Because it is in the repo, every contributor who uses the same manager gets the correct version automatically when they clone and enter the project. That removes one of the most common works-on-my-machine problems: someone building against a Node version the project was never tested on.
The payoff
This is a small setup that pays off every day you work across more than one project. Each project runs on the version it was built for, switching is automatic, and new people get it for free. The class of bugs that come from silently being on the wrong Node just disappears, which is a lot of value for committing one tiny file and installing one tool.
FAQ
Why do I need different Node versions per project?
Projects are built and tested against a specific Node version, and running one on the wrong version causes subtle bugs and install failures. Older projects may need an older Node; newer ones need current features. A version manager lets each project use what it expects.
How does automatic switching work?
You commit a version file to the project that names the Node version. A version manager reads that file when you enter the directory and switches to the matching version, so you do not have to remember or set it by hand each time.
What should new contributors do?
Install the same version manager and let it read the committed version file. When they clone the project and enter the directory, they get the correct Node version automatically, which removes a whole class of works-on-my-machine problems.