Se tem algo mais chato do que problemas causados pela versão errada do Node, ainda não me apresentaram. (Se ao menos tivesse como automatizar isso, né?)

Na hora que eu finalmente lembro de fazer um node -v, me sinto o burro do Shrek.

Agora... imagina abrir um projeto de 2020 que exige Node 12 e, segundos depois, mudar para outro com Node 20, e tudo funcionar normalmente sem digitar um único comando.

Para nunca mais passar por esses perrengues, fui atrás de uma solução... e descobri.

Em resumo, para ativar automaticamente a versão correta do Node, use o NVM e crie um arquivo .nvmrc na raiz com a versão desejada. Depois, adicione uma função no seu terminal (Bash ou ZSH) que detecta esse arquivo e executa nvm use automaticamente.

É uma mão na roda para garantir que todo mundo do time use a mesma versão, e evitar o clássico "na minha máquina funciona".

O benefício disso é que você pode trabalhar em vários projetos, cada um com sua versão diferente de Node, e alternar entre elas de forma automática.

Para começar, você precisa entender um pouco sobre o Node Version Manager (NVM) .

O que é e como usar o Node Version Manager (NVM)

O nome já entrega: Node Version Manager é um gerenciador de versões do Node.

Ele permite gerenciar as diferentes versões instaladas no seu computador através da linha de comando. Com ele, você consegue:

• Instalar versões

• Desinstalar versões

• Mudar a versão ativa

• Ver a versão ativa

• Listar as versões instaladas

• Criar apelidos (alias) para versões

• Definir a versão padrão

Para instalar o NVM:

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

# ou 

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

Agora veja alguns comandos básicos para entender como ele funciona.

Instalar versão do Node com NVM

Muito simples.

nvm install 12     # instala a versão 12.22.12
nvm install 14.7.0 # instala a versão exata 14.7.0
nvm install node   # instala a versão mais recente do Node

A palavra node sempre aponta para a versão mais recente disponível.

Desinstalar versão do Node com NVM

Só muda a palavra do meio do comando:

nvm uninstall 12.22.12

Ativar uma versão do Node com NVM

Use (literalmente):

nvm use 12       # ativa a versão 12 que estiver instalada
nvm use 12.22.12 # ativa a versão exata 12.22.12
nvm use node     # ativa a versão mais recente

Esse é o comando que será executado automaticamente após fazer essa automação (mais informações em breve).

Descobrir versão atual do Node com NVM

"Atual" em inglês é current.

$ nvm current  
v20.16.0

$ node -v 
v20.16.0

Por questões particulares (preguiça), prefiro node -v, pois traz o mesmo resultado e é mais fácil de digitar.

Listar versões do Node instaladas com NVM

É bem parecido com o comando para listar pastas e arquivos na linha de comando.

Se você está acostumado com isso, já usou o comando ls.

Então para listar versões do Node:

$ nvm ls

      v12.22.12
       v18.17.0
->     v20.16.0
default -> teste-alias (-> N/A)
iojs -> N/A (default)
unstable -> N/A (default)
node -> stable (-> v20.16.0) (default)
stable -> 20.16 (-> v20.16.0) (default)
lts/* -> lts/jod (-> N/A)
lts/argon -> v4.9.1 (-> N/A)
lts/boron -> v6.17.1 (-> N/A)
lts/carbon -> v8.17.0 (-> N/A)
lts/dubnium -> v10.24.1 (-> N/A)
lts/erbium -> v12.22.12
lts/fermium -> v14.21.3 (-> N/A)
lts/gallium -> v16.20.2 (-> N/A)
lts/hydrogen -> v18.20.8 (-> N/A)
lts/iron -> v20.19.0 (-> N/A)
lts/jod -> v22.14.0 (-> N/A)

As versões do topo são as que você instalou. A seta aponta para a versão ativa.

Logo depois você algumas versões com um nome do lado esquerdo, esse é o alias.

Veja agora como usar o alias a seu favor.

Criar alias para uma versão do Node com NVM

Alias, apelido, nickname... como quiser.

Criar um alias facilita na hora de ativar uma versão, porque você pode usar um nome em vez de lembrar da versão completa.

Uma dica é colocar em cada versão o nome do projeto que a utiliza:

nvm alias tictactimer 12.22.12
nvm alias todolist 20.16.0

Então para ativar essas versões, basta digitar:

nvm use tictactimer
nvm use todolist

Se quiser remover algum alias:

nvm unalias tictactimer
nvm unalias todolist

Se você definir um alias chamado default para alguma versão, ela terá poderes mágicos. Isso significa que essa será a versão selecionada ao abrir um terminal.

nvm alias default 12.22.12
nvm alias default tictactimer

Se quiser sempre abrir o terminal na versão mais recente, basta digitar:

nvm alias default node

Com esses comandos você já consegue trabalhar tranquilamente com o NVM. Eu, por exemplo, nunca usei nenhum comando além desses.

O ponto chave desse artigo é: quando tudo estiver pronto, o comando nvm use <version> será executado automaticamente. Mas antes, o terminal precisa saber qual é a versão correta. E essa informação fica no arquivo .nvmrc.

O que é o arquivo .nvmrc e como ele funciona

O terminal irá procurar por ele sempre que você mudar de pasta ou abrir um projeto no VS Code.

Já que estamos falando de linha de comando, veja como criar esse arquivo pelo terminal.

Para começar acesse a raiz do projeto e digite:

echo 20.16.0 > .nvmrc

Esse comando escreve o conteúdo 20.16.0 dentro do arquivo .nvmrc.

Veja o resultado:

1. Criei o arquivo e escrevi o conteúdo lá dentro

2. Listei os arquivos e pastas

3. Encontrei o arquivo .nvmrc criado

4. Executei um comando para ver o conteúdo do um arquivo

5. E o conteúdo aparece no terminal

Estamos quase lá.

Agora você já tem o NVM para trocar a versão do Node, e o projeto já está configurado através do arquivo .nvmrc.

Agora falta o principal: automatizar.

Como ativar automaticamente a versão do Node

Quem vai fazer a automação é uma função.

E você precisa inseri-la no arquivo de configuração do seu terminal Shell. Os dois tipos mais usados de Shell são Bash e ZSH.

Veja como descobrir qual é o seu.

Descubra o seu Shell

Basta digitar um comando inexistente (como comando-errado), e ver o que aparece no começo do resultado.

Se você usa o Bash:

nome-do-computador:/ nome-do-usuario$ comando-errado
bash: comando-errado: command not found

Se usa o ZSH:

usuario@nome-do-computador nome-da-pasta % comando-errado
zsh: command not found: comando-errado

De agora em diante, fique atento aos comandos relativos ao seu Shell.

Abra o arquivo de configuração do Shell

Use o comando abaixo:

code ~/.bashrc # Bash
code ~/.zshrc # ZSH

Aqui você precisa escrever a função.

Crie a função que ativa automaticamente a versão do Node

Ao final do arquivo escreva essa função (ela vale para os dois Shells):

autoload_nvmrc() {
  local nvmrc_path
  nvmrc_path=$(nvm_find_nvmrc)

  if [ -n "$nvmrc_path" ]; then
    local desired_version
    desired_version=$(cat "$nvmrc_path")

    if [ -z "$desired_version" ]; then
      echo "⚠️  Arquivo .nvmrc está vazio ou mal formatado."
      return
    fi

    local resolved_version
    resolved_version=$(nvm version "$desired_version")

    if [ "$resolved_version" = "N/A" ]; then
      echo "📦 Versão \"$desired_version\" não está instalada. Instalando..."
      nvm install "$desired_version" || {
        echo "❌ Falha ao instalar Node $desired_version"
        return 1
      }
    fi

    if [ "$(nvm current)" != "$resolved_version" ]; then
      echo "🔁 Alternando para Node $resolved_version"
      nvm use "$desired_version" || {
        echo "❌ Falha ao alternar para Node $desired_version"
        return 1
      }
    else
      echo "✅ Já usando Node $resolved_version"
    fi
  fi
}

Veja o que essa função faz:

1. Define uma função chamada autoload_nvmrc

2. Localiza o caminho do arquivo .nvmrc e salva na variável nvmrc_path

3. Lê o conteúdo do arquivo e salva na variável desired_version. Esse conteúdo é exatamente a versão do Node daquele projeto

4. Se a versão não estiver instalada, tenta instalar com nvm install <version>

5. Agora, após garantir que a versão correta está instalada, verifica se é ela que está ativa. Se não for, dispara o nvm use <version> para ativá-la (eu te disse que esse momento chegaria)

6. Se a função correta já está ativa, apenas finaliza a função

Com exceção do passo 1, todos os outros podem gerar algum erro. Mas a função já está preparada para lidar com isso parar a execução nesse caso. Nesse caso, nada de ruim acontece, apenas a automação não funciona.

Agora que a função está criada, você precisa informar quando quer dispará-la.

Execute a função

No Bash, adicione esse trecho logo após a função:

cd() {
  builtin cd "$@" && autoload_nvmrc
}

autoload_nvmrc # roda ao abrir o shell

A função cd substitui o comando cd default. Mas não se preocupe, porque esse código executa o que esse comando faz originalmente e depois dispara o autoload_nvmrc. Assim a verificação da versão do Node acontece a cada mudança de pasta.

E a última linha faz o mesmo, porém para cada vez que você abre um novo projeto no VS Code.

No ZSH, você também precisa adicionar um trecho de código após a função autoload_nvmrc:

autoload -U add-zsh-hook
add-zsh-hook chpwd autoload_nvmrc
autoload_nvmrc # executa ao abrir terminal também

Recarregue o terminal

Quase lá.

Após esses passos, você precisa recarregar o terminal para as alterações serem válidas.

E isso é muito simples:

source ~/.bashrc  # se você usa Bash
source ~/.zshrc   # se você usa ZSH

Pronto, agora a versão correta do Node será ativada sempre que mudar de pasta ou abrir um novo projeto. Mas não se esqueça que isso só funciona se o projeto tiver o arquivo .nvmrc na raiz.

Callback

Você pode ativar automaticamente a versão do Node do projeto que você está trabalhando.

Quem ativa as versões para você é uma função que usa o Node Version Manager (NVM).

Essa função localiza o arquivo .nvmrc na raiz do projeto e usa o conteúdo dele para saber qual é a versão correta.

Você deve inserir essa função dentro do arquivo de configuração do seu Shell, seja ele Bash ou ZSH.

Por fim, recarregue o terminal para que a função entre em ação.

Tão legal quanto automatizar uma tarefa da vida com programação, é automatizar uma tarefa da própria programação.

E por isso aprender a fazer essa tarefa, e também ensinar aqui no blog, é tão gratificante.

Espero que isso te ajude de alguma forma.

Rolou alguma dúvida? Deixa aqui embaixo nos comentários.

Obrigado pela sua leitura 😬