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
1. Install direnv
macOS:
brew install direnv
Ubuntu/Debian:
sudo apt install direnv
2. 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:
3. Set Up Your Project with .envrc
Navigate to the root of your Node.js project:
This tells direnv
to look for a .nvmrc
file and load the specified Node version.
Now authorize direnv
to load the .envrc
:
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:
Bonus: Combine .env
and .nvmrc
in .envrc
Want to load environment variables too? Update your .envrc
:
Or declare environment variables directly:
Git Best Practices
-
✅ Commit:
.nvmrc
and.envrc
-
❌ Ignore:
.env
(if it contains secrets)
Update your .gitignore
:
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.