Using nodes installed outside of nodenv

Nodenv users typically install their node versions using node-build (via its nodenv-install plugin). Indeed, for Homebrew users, node-build is installed by default with the nodenv formula. However, it's quite common to want to use nodenv to switch to a node that is installed outside of nodenv's managed versions. Thankfully, nodenv allows switching to any version that exists within $(nodenv root)/versions, including symlinks!

Scenario: runtime from Homebrew (or other package manager)

Node-build supports quite a few "non-standard" nodes—graalvm, jxcore, etc. But perhaps you have stumbled on a new node runtime that isn't supported within node-build yet. A good example of this is deno, also by the original node creator: Ryan Dahl. (Deno can be installed by homebrew, though how you install the runtime isn't important.)

1. Install the runtime

   In this example, we'll install deno using Homebrew (or Linuxbrew!). The deno formula already links into your PATH, but we'll unlink it here to show that this approach works with keg-only formulae as well.

   $ brew install deno
   [/snip...]
   $ brew unlink deno
   

2. Symlink the runtime into nodenv versions

   $ cd $(nodenv root)/versions
   $ ln -s $(brew --prefix deno) deno
   

   (Substitute $(brew --prefix deno) with any other path that points to the runtime you'd like to use.)

3. Active the runtime as desired

   $ nodenv shell deno
   $ nodenv version
   deno => 0.40.0 (set by NODENV_VERSION environment variable)
   

   (The deno symlink within nodenv points to homebrew's symlink within $(brew --prefix)/opt which itself points to a particular version within the Cellar, hence the final link destination is "0.40.0".)

Scenario: vendored runtime

Perhaps your project vendors its node runtime directly within the project itself. In order to ensure that all node (and related bins, like npm) use the vendored node, add a symlink to the vendored node from $(nodenv root)/versions.

1. Symlink the vendored node

   Let's assume our project lives at ~/code/my-org/project and that the vendored node lives within said project under vendor/node/current. (It's common for vendored runtimes to be named by their version and to have a current symlink which allows dual-booting the app on both "current" and "next" runtimes.)

   cd $(nodenv root)/versions
   ln -s ~/code/my-org/project/vendor/node/current my-org-project
   

   ("my-org-project" will be the name of the node as recognized by nodenv. Use whatever you like.)

   Now nodenv versions should include "my-org-project" in its output.

2. Activate the vendored node within the project

   cd ~/code/my-org/project
   nodenv local my-org-project
   

   (You probably do not want to version this .node-version file, as the version will likely not exist on your teammates systems. If your project already has a .node-version file in the repo, you may wish to use nodenv shell my-org-project to override it using the NODENV_VERSION environment variable—which takes precedence over the local file.

3. Party! 🎉

   Now all node invocations within your project will use the vendored node runtime!

   $ nodenv local
   my-org-project
   $ nodenv version
   my-org-project => current (set by /Users/username/code/my-org/project/.node-version)