Automatic Node.js Version Switching Across Projects

Matías Denda — Fri, 07 Nov 2025 21:21:15 +0000

The Challenge

Modern JavaScript development often involves working on multiple projects simultaneously. Each project may require a different Node.js version:

Legacy project: Node 14
Production app: Node 18 LTS
New experimental project: Node 20

Manually switching versions between projects adds friction to your workflow. You need to remember which version each project uses and run the appropriate commands when switching contexts.

What is AutoNode?

AutoNode is a CLI tool that automatically detects and switches to the correct Node.js version when you navigate between projects. It works seamlessly with your existing version manager (nvm, nvs, or Volta).

Key features:

🔍 Automatic version detection from multiple sources
⚡ Zero runtime dependencies (single native binary)
🔄 Works with your existing version manager
🌍 Cross-platform (macOS, Linux, Windows)
📦 Under 6MB with everything included

How It Works

Version Detection

AutoNode reads version requirements from multiple sources (in priority order):

.nvmrc - Standard nvm configuration file
.node-version - Alternative version file format
package.json - Reads engines.node field
Dockerfile - Parses FROM node:X declarations

This multi-source approach ensures compatibility with different project conventions.

Shell Integration

When you cd into a project directory, AutoNode:

Detects the required Node.js version
Checks which version manager you have installed
Switches to the appropriate version automatically

The integration works through a shell hook similar to other developer tools like direnv or starship.

Installation

One-line install:

  curl -fsSL https://raw.githubusercontent.com/matutetandil/autonode/main/install.sh | bash

The installer will:

Detect your platform and architecture
Download the appropriate binary
Install to a standard location
Configure shell integration for bash/zsh/fish

Manual Commands

You can also use AutoNode manually:

Check detected version without switching

autonode --check

Force reinstall detected version

autonode --force

Update AutoNode itself

  autonode update

Real-World Use Cases

Development Teams

Ensure all team members use consistent Node.js versions across projects without manual intervention.

CI/CD Pipelines

Automatically use the correct Node version in build scripts without hardcoding version numbers.

Monorepo Management

Different packages in a monorepo can specify different Node requirements, and AutoNode handles transitions seamlessly.

Docker Development

Parse Node versions directly from Dockerfiles to match your local environment with production.

Compatibility

Operating Systems:

macOS (Intel & Apple Silicon)
Linux (AMD64 & ARM64)
Windows (AMD64)

Version Managers:

nvm (Node Version Manager)
nvs (Node Version Switcher)
Volta

Shells:

bash
zsh
fish

Roadmap

Planned improvements:

Additional version manager support (fnm, asdf)
Configuration file for custom behavior
Shell completion scripts
Package manager distribution (Homebrew, apt)
Pre-commit hooks integration
CI/CD action/workflow templates

Contributing

AutoNode is open source and welcomes contributions. Whether it's:

Bug reports and fixes
New version detector implementations
Version manager integrations
Documentation improvements
Feature requests

Check out the https://github.com/matutetandil/autonode to get involved.

Try It Out

Installation:

curl -fsSL https://raw.githubusercontent.com/matutetandil/autonode/main/install.sh | bash

Quick test:

  mkdir test-project && cd test-project
  echo "18.17.0" > .nvmrc
  # AutoNode switches automatically
  node --version

Feedback Wanted:

I'm actively looking for feedback on:

Does it work reliably with your setup?
Any edge cases in version detection?
Performance in large monorepos?
Installation experience on different platforms?

Feel free to open an issue or start a discussion on GitHub!

Resources

GitHub Repository: https://github.com/matutetandil/autonode
Documentation: Full setup and usage guide in the README
Installation Script: Direct download and shell integration
Releases: Pre-built binaries for all platforms

AutoNode aims to simplify Node.js version management across projects. If you find it useful or have suggestions, I'd love to hear from you!

Forem: Matías Denda