Node Version Manager (nvm) migration guide

Flox is an environment and package manager that allows you to install software from an extensive catalog into individual environments, each of which usually corresponds to a software project. Flox gives you the opportunity to simplify the development workflow used by your team, consolidating various functions into a single command: flox activate.

Just like nvm, Flox allows you to install and activate different versions of Node.js, enabling you to switch versions as project requirements dictate. Unlike nvm, however, Flox also allows you to install just about any software you need, including databases and packages from language ecosystems like Python, Rust, Go, Java, Ruby, and others.

Why you might want to use Flox instead of nvm

nvm does exactly what it purports to do: it manages Node.js versions simply and effectively. Point notwithstanding, it's also one more dependency that you don't have to worry about if you're using Flox. Consider whether one of the following cases applies to you, or to your team:

You work on a team with members who have diverse skill sets, and you want to have a single entrypoint for development, regardless of language ecosystem. No matter what languages and technologies your team is comfortable with, they can use the same Flox commands to spin up their local dev environments. For example, instead of asking a Java developer who uses a Linux machine to install nvm in order to get the right node version for your project, you can offer a better solution. That developer can use the same Flox commands they use to activate their own projects to activate the dev environment for your node project, which you develop on your Mac.
You want a tool that allows you to manage Node.js versions as well as other dependencies. Having a single-use tool like nvm is fine, but what if you could install node, PostgreSQL, nginx, etc. with a single command? Flox lets you do just that. It also allows you to configure and run services, the latter of which you can do simply by adding the --start-services argument to flox activate.
You need to use node-gyp to compile native add-on modules for Node.js, and you want to be sure you have the right version of Python, Make, GCC, Clang, and other dependencies. As a Flox user, you can be certain you'll install versions of these dependencies that are compatible with the node version in your environment. This is all thanks to Nix Packages, which is the underlying software repository on which the Flox Catalog is based.
You need to manage versions of other JavaScript runtimes, like Bun or Deno. While nvm is, as the name denotes, used for managing Node.js versions, that's all it does. You can use Flox to install node, but you can also use it to install different JavaScript runtimes, including Bun and Deno.

Install Flox

Download and install Flox as described in our installation instructions.

Create a Flox environment in your existing project and install Node.js

Navigate to your project's directory and run flox init, and then search for the version of Node.js that is currently included in your .nvmrc, or in the "engines" property of your package.json. (Note that node is listed as nodejs and variants thereof in the Flox Catalog.)

➜  node-project git:(main) ✗ flox search nodejs
nodejs       Event-driven I/O framework for the V8 JavaScript engine
nodejs_14    Event-driven I/O framework for the V8 JavaScript engine
nodejs_16    Event-driven I/O framework for the V8 JavaScript engine
nodejs_18    Event-driven I/O framework for the V8 JavaScript engine
nodejs_19    Event-driven I/O framework for the V8 JavaScript engine
nodejs_20    Event-driven I/O framework for the V8 JavaScript engine
nodejs_21    Event-driven I/O framework for the V8 JavaScript engine
nodejs_22    Event-driven I/O framework for the V8 JavaScript engine
nodejs_23    Event-driven I/O framework for the V8 JavaScript engine
nodejs-10_x  Event-driven I/O framework for the V8 JavaScript engine

Showing 10 of 67 results. Use `flox search nodejs --all` to see the full list.

Use 'flox show <package>' to see available versions

There is a lot of software in the Flox Catalog, so you should have no trouble finding the node version you need. We recommend that you install one of the nodejs packages with a numerical suffix (e.g., nodejs_18 or nodejs_22), rather than nodejs, which is the latest stable version of node from the perspective of the Nix Packages maintainers. The nodejs package may not get a new version until all the other Nix packages that depend on that specific Node.js version have been updated for compatibility, which could be a long while after an official Node.js release.

At any rate, for this project, perhaps you decide to install Node.js v20.18.1.

➜  node-project git:(main) ✗ flox install nodejs_20
✅ 'nodejs_20' installed to environment 'node-project'

Verify the Node.js version

Now that you've installed node, you activate the Flox environment to verify that it has the the version you expect.

➜  node-project git:(main) ✗ flox activate
✅ You are now using the environment 'node-project'.
To stop using this environment, type 'exit'

...
flox [node-project] ➜  node-project git:(main) ✗ node -v
v20.18.1

Add Node.js and associated dependencies to a package group (optional)

If you need an older version of node in your environment, we recommend that you specify a package group in your manifest to ensure that you can still install the latest versions of other software in your environment. (For more on the manifest and on package groups, read our reference guide.)

You can run flox edit to open up the manifest for the environment.

...
[install]
nodejs_20 = { pkg-path = "nodejs_20", pkg-group = "node-toolchain" }
...

Install other dependencies using Flox (optional)

Assuming your project is like most Node.js applications, you probably have dependencies other than node to install. In this case, maybe you need PostgreSQL and nginx. Fortunately, you can install both using Flox, in the same way in which you installed node.

flox [node-project] ➜  node-project git:(main) ✗ flox install postgresql nginx
✅ 'postgresql' installed to environment 'node-project'
✅ 'nginx' installed to environment 'node-project'

Now you have everything you need to develop locally, and you didn't have to figure out how to install nginx and PostgreSQL individually.

Update the Node.js version

If you want to install a different node version, you can always update your environment to include the version you need. For example, let's say you're upgrading your project to Node.js v22. The best way to get the correct Flox Catalog version name for your desired version is to run flox show <package>:

flox [node-project] ➜  node-project git:(main) ✗ flox show nodejs_22
nodejs_22 - Event-driven I/O framework for the V8 JavaScript engine
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]
    [email protected]

Once you know what's available, you can run flox edit to open up the manifest for the environment. You can then set your desired node version directly in the manifest, and then save your changes. Note that you'll need to prepend nodejs- to whatever Node.js version number you intend to set in the manifest. This is required because of how those versions are stored in the Nix Packages collection.

(If you omit the specific version, you will get the latest version of nodejs_22 that's compatible with everything in your environment. If you have a pkg-group set but no specific version, you'll get the latest version that's compatible with the rest of the software in the package group.)

...
[install]
nodejs_22 = { pkg-path = "nodejs_22", pkg-group = "node-toolchain", version = "nodejs-22.10.0" }
...

Update the README in your project

At this point, you can replace any nvm-related instructions in your README with corresponding instructions for using Flox. In particular, instead of running nvm use to pick up the Node.js version from the .nvmrc, you can just run flox activate. This will install all the dependencies in your Flox environment, not just node.

Now that you're managing your project's Node.js version using Flox, you can git rm .nvmrc and commit the result. You're free to repeat the process in other project directories before following the instructions for uninstalling nvm as listed in the nvm README.