Dicas para gerenciar múltiplas versões do Node.js com nvm

1. Introdução ao nvm e seus benefícios

O Node Version Manager (nvm) é uma ferramenta essencial para desenvolvedores que trabalham com múltiplos projetos Node.js. Imagine cenários comuns: você mantém um sistema legado que exige Node.js 12, um projeto moderno que usa recursos do Node 20, e um cliente que pede testes específicos na versão 16. Sem o nvm, gerenciar essas versões seria um pesadelo de instalações manuais, conflitos de dependências e permissões quebradas.

Os principais benefícios do nvm incluem:

  • Isolamento completo: cada projeto pode usar sua própria versão do Node.js sem interferências
  • Troca instantânea: alterne entre versões com um único comando
  • Instalação simplificada: baixe e configure qualquer versão do Node.js em segundos
  • Gerenciamento de pacotes globais: evite conflitos reinstalando automaticamente pacotes entre versões

2. Instalação e configuração inicial do nvm

No Linux/macOS

A instalação é feita via curl ou wget:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Ou com wget:

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

No Windows

Para Windows, utilize o nvm-windows (projeto separado):

# Baixe o instalador em:
# https://github.com/coreybutler/nvm-windows/releases
# Execute nvm-setup.exe e siga o assistente

Configuração do shell

Após a instalação, adicione estas linhas ao seu arquivo de shell (~/.bashrc, ~/.zshrc ou ~/.profile):

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # Carrega o nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # Ativa autocompletar

Recarregue o shell:

source ~/.bashrc

Verifique a instalação:

nvm --version
# Saída esperada: 0.39.7

3. Gerenciamento de versões: instalação e listagem

Instalando versões específicas

# Instalar versão exata
nvm install 18.17.0

# Instalar a versão LTS mais recente
nvm install --lts

# Instalar a versão estável mais recente
nvm install node

Listando versões disponíveis

# Todas as versões disponíveis remotamente
nvm ls-remote

# Apenas versões LTS
nvm ls-remote --lts

# Filtrar por versão específica (ex: versões 16.x)
nvm ls-remote | grep -i "v16"

Listando versões instaladas localmente

nvm ls
# Saída exemplo:
# ->     v16.20.2
#        v18.17.0
#        v20.11.0
# default -> 20.11.0

4. Alternância entre versões do Node.js

Usando uma versão específica

# Ativar versão 16.20.0
nvm use 16.20.0

# Ativar versão LTS
nvm use --lts

# Verificar versão ativa
node --version

Definindo uma versão padrão

# Definir versão 20.11.0 como padrão
nvm alias default 20.11.0

# Toda nova sessão de terminal usará esta versão

Executando comandos com versão temporária

# Executar app.js com Node 14.21.0 sem alterar a versão ativa
nvm run 14.21.0 app.js

# Executar com argumentos
nvm exec 16.20.0 node --experimental-modules app.mjs

5. Gerenciamento de pacotes globais entre versões

Problemas comuns

Ao trocar de versão, pacotes instalados globalmente (como npm, yarn, typescript) podem não estar disponíveis. Isso ocorre porque cada versão do Node.js tem seu próprio diretório de pacotes globais.

Reinstalação automática

# Antes de trocar para uma nova versão
nvm install 18.17.0 --reinstall-packages-from=16.20.0

# Ou, se já instalou a versão
nvm use 18.17.0
nvm reinstall-packages 16.20.0

Boas práticas

Sempre que possível, prefira:

# Usar npx para executar pacotes sem instalá-los globalmente
npx create-react-app my-app

# Instalar ferramentas de desenvolvimento como dependências locais
npm install --save-dev typescript eslint prettier

6. Automação e integração com projetos

Arquivo .nvmrc

Crie um arquivo .nvmrc na raiz do projeto:

# .nvmrc
20.11.0

Ou com versão parcial:

# .nvmrc
16

Para usar automaticamente:

nvm use
# Lê a versão do arquivo .nvmrc

Script de shell para automação

Adicione ao seu ~/.bashrc ou ~/.zshrc:

# Carrega automaticamente a versão do Node ao entrar em um diretório
autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path="$(pwd)/.nvmrc"
  if [[ -f "$nvmrc_path" ]]; then
    nvm use
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

Integração com npm scripts

No package.json:

{
  "scripts": {
    "preinstall": "nvm use",
    "test": "nvm use && node --experimental-vm-modules node_modules/.bin/jest"
  }
}

7. Solução de problemas comuns e dicas avançadas

Erros de permissão

Se encontrar erros de permissão ao instalar pacotes globais:

# Nunca use sudo com npm! Em vez disso, corrija o nvm
nvm use 18.17.0
# Se o erro persistir, reinstale o nvm
nvm uninstall 18.17.0
nvm install 18.17.0

Removendo versões antigas

# Listar versões instaladas
nvm ls

# Remover versão específica
nvm uninstall 12.22.12

# Remover versões não utilizadas (cuidado!)
nvm prune

Dicas de desempenho

# Limpar cache do npm para a versão ativa
npm cache clean --force

# Verificar espaço ocupado pelas versões
du -sh ~/.nvm/versions/node/*

# Remover versões que não são mais necessárias
nvm uninstall 14.21.0

Verificando caminhos corretos

# Verificar qual Node.js está sendo usado
which node
# Deve apontar para ~/.nvm/versions/node/v20.11.0/bin/node

# Se apontar para /usr/local/bin, algo está errado
# Verifique se o nvm está carregado corretamente

Migrando entre sistemas

# Exportar lista de versões instaladas
nvm ls --no-colors > ~/nvm-versions.txt

# No novo sistema, instalar todas as versões
cat ~/nvm-versions.txt | while read v; do
  if [[ $v != *"->"* ]] && [[ $v != *"default"* ]]; then
    nvm install $v
  fi
done

Conclusão

O nvm é uma ferramenta indispensável para qualquer desenvolvedor Node.js profissional. Com as técnicas apresentadas neste artigo, você pode gerenciar múltiplas versões do Node.js com eficiência, evitando conflitos e mantendo a produtividade. Lembre-se sempre de usar arquivos .nvmrc para documentar a versão necessária de cada projeto e automatizar a alternância entre versões.

Referências