DEV Community

Matías Denda
Matías Denda

Posted on

Automatic Node.js Version Switching Across Projects

#go #node #cli #devtools

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):

  1. .nvmrc - Standard nvm configuration file
  2. .node-version - Alternative version file format
  3. package.json - Reads engines.node field
  4. 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:

  1. Detects the required Node.js version
  2. Checks which version manager you have installed
  3. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Force reinstall detected version 

autonode --force
Enter fullscreen mode Exit fullscreen mode

Update AutoNode itself 

  autonode update
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Quick test: 

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

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!

Top comments (0)