What is direnv and How to Use It with nvm for Node.js Version Management

What is direnv?

direnv is a shell extension that automatically loads or unloads environment variables based on the directory you're in. Think of it as dotenv on steroids — it not only loads .env files, but also runs shell scripts, manages Node versions via .nvmrc, and more.

Key Features

• Loads .envrc files automatically when entering a directory

• Supports .nvmrc and .node-version to auto-switch Node.js versions

• Can auto-install Node versions with nvm install

• Works with all major shells (bash, zsh, fish, etc.)

Step-by-Step Setup for direnv + nvm

Install direnv

macOS:

brew install direnv

Ubuntu/Debian:

sudo apt install direnv

Hook direnv into Your Shell

You need to add the following line to your shell's configuration file to enable direnv.

For zsh:

echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

For bash:

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

Then apply the changes:

source ~/.zshrc # or ~/.bashrc

Set Up Your Project with .envrc

Navigate to the root of your Node.js project:

echo 'use_nvm' > .envrc

This tells direnv to look for a .nvmrc file and load the specified Node version.

Now authorize direnv to load the .envrc:

direnv allow

If you have a .nvmrc file (e.g. v20.12.2), direnv will:

• Detect it

• Run nvm install (if the version isn't installed yet)

• Automatically run nvm use when you enter the directory

How use_nvm Works

The use_nvm directive is a built-in direnv helper that does all the heavy lifting. Internally, it functions like this:

use_nvm() {
  export NVM_DIR="$HOME/.nvm"
  source "$NVM_DIR/nvm.sh"
  local node_version=$(<.nvmrc)
  nvm install "$node_version"
  nvm use "$node_version"
}

You can even customise it further by placing a modified version in:

~/.config/direnv/lib/use_nvm.sh

Bonus: Combine .env and .nvmrc in .envrc

Want to load environment variables too? Update your .envrc:

use_nvm dotenv

Or declare environment variables directly:

use_nvm export NODE_ENV=development export API_URL=https://api.example.com

Git Best Practices

• Commit: .nvmrc and .envrc

• Ignore: .env (if it contains secrets)

Update your .gitignore:

# Ignore secret env files 
.env

Conclusion

Using direnv with nvm is a game-changer for managing Node.js versions and environment variables per project. It reduces human error, ensures consistency across teams, and simplifies onboarding and deployment processes.

Need Help Implementing This in Your Team or CI/CD Pipeline?

Whether you're building a startup or managing an enterprise-grade Node.js project, we offer consulting, automation, and environment setup services tailored to your stack.

Contact us today to streamline your workflow and focus on what you do best — building amazing software.