Posted about 3 years ago. Visible to the public. Repeats.

Documenting your Rails project's Node.js version in .nvmrc

Not all versions of Node.js are compatible with each other. Also npm packages may require a minimum or maximum version of Node.js. We use nvm on our development PCs so we can operate multiple versions of Node.js in parallel.

To make sure that all developers use a compatible version of Node.js, your Rails project should declare the required Node.js in a file called .nvmrc.

When a .nvmrc exists, developers can cd in your project directory and activate the project's node version with

nvm use

There are some hacks Archive to automatically activate a Node version as you cd into a directory, but I didn't test them. Note that these hacks might clash with rbenv which also aliases your cd to activate the correct Ruby version from .ruby-version.

Picking the right Node version

We avoid declaring Node versions with minor and patch versions. Instead we prefer declaring LTS release lines Archive in our .nvmrc.

To use the latest release of Node 16 LTS your .nvmrc should be:


To use the latest release of Node 14 LTS your .nvmrc should be:


New LTS releases are assigned line names ("argon", "carbon" etc.) as they become active. The current list of LTS releases and their line names can be viewed on the Node.js release page Archive .


If you are using unmanaged Node.js with capistrano-opscomplete Archive your .nvmrc must contain a specific node version, not an LTS alias.

Testing compatibility

In general, a recent Rails projects should use the currently active LTS version of LTS.

If you are unsure about compatibility, these two commands should work:

yarn rake assets:precompile
Growing Rails Applications in Practice
Check out our new e-book:
Learn to structure large Ruby on Rails codebases with the tools you already know and love.

Owner of this card:

Henning Koch
Last edit:
7 months ago
by Henning Koch
About this deck:
We are makandra and do test-driven, agile Ruby on Rails software development.
License for source code
Posted by Henning Koch to makandra dev
This website uses short-lived cookies to improve usability.
Accept or learn more