Guia para Configuração Independente de Versões do Node.js por Projeto usando ServBay (macOS)

O ServBay é um ambiente local de desenvolvimento web poderoso, pensado especialmente para desenvolvedores. Ele oferece uma solução integrada com diversas linguagens de programação, bancos de dados e servidores web, incluindo o Node.js. Um dos principais benefícios do ServBay é seu suporte nativo e gerenciável a múltiplas versões do Node.js. Com um simples arquivo de configuração, você pode especificar facilmente a versão do Node.js necessária para cada projeto sem depender de gerenciadores externos como NVM, fnm ou containers Docker—simplificando o fluxo de trabalho e evitando poluição do ambiente global e conflitos de versão.

Neste artigo, mostraremos em detalhes como utilizar o arquivo .servbay.config do ServBay para obter controle de versão do Node.js a nível de projeto.

Por que utilizar o .servbay.config do ServBay para gerenciar versões do Node.js?

Os métodos tradicionais para gerenciar versões do Node.js—como o uso do NVM ou instalações manuais—podem apresentar inconvenientes:

• Poluição e conflitos globais: Alternar a versão global ou instalar o Node.js de forma global pode provocar conflitos de dependência entre projetos diferentes.
• Tempo de instalação e compilação: Instalar uma versão nova ou alternar entre diferentes arquiteturas (x86_64 e arm64, por exemplo) pode exigir recompilações demoradas.
• Sobrecarga de containers Docker: Para necessidades simples de versões específicas do Node.js, rodar um container completo é um exagero.

O ServBay soluciona isso ao pré-instalar várias versões populares do Node.js (atualmente suportando v12 até v23, podendo verificar e gerenciar as versões pelo menu "Pacotes" do aplicativo ServBay) e através do arquivo .servbay.config, oferece um caminho elegante:

• Troca instantânea: As versões já estão instaladas, a alternância entre elas é praticamente imediata.
• Isolamento por projeto: A configuração só afeta o diretório do projeto correspondente, garantindo isolamento real de versões.
• Sem poluição global: Não altera o ambiente do sistema, mantendo seu macOS limpo.
• Integração com outros recursos do ServBay: Totalmente integrado ao ambiente do ServBay, funcionando junto com outros pacotes gerenciados como PHP, bancos de dados, servidores web, etc.

Pré-requisitos

Antes de começar, certifique-se de que:

1. O ServBay está instalado e em funcionamento no seu macOS.
2. No aplicativo ServBay, na seção "Pacotes" (Packages), você já ativou a versão do Node.js que deseja usar no seu projeto.
3. Você possui um diretório de projeto para o qual quer definir uma versão específica do Node.js.

Princípio de Funcionamento

O ServBay monitora o diretório corrente sempre que você usa o terminal integrado. Ao navegar para um diretório via comando cd, ele procura (no diretório atual e em todos os diretórios acima) um arquivo chamado .servbay.config. Assim que encontrar (dando preferência ao mais próximo do diretório atual), o ServBay lê as definições do arquivo e ajusta dinamicamente as variáveis de ambiente da sessão do terminal, como o PATH, apontando para a versão do Node.js definida no .servbay.config.

Esse mecanismo garante que, em sessões de terminal abertas dentro de diferentes diretórios de projeto, cada uma carregue e utilize automaticamente a versão específica do Node.js definida para aquele ambiente—sem necessidade de comutação manual.

Passos para Configuração

Configurar a versão independente do Node.js por projeto é muito simples e envolve apenas dois passos:

Passo 1: Criar e editar o arquivo .servbay.config

No diretório raiz do seu projeto (geralmente onde está o package.json), crie um novo arquivo chamado .servbay.config.

Abra este arquivo em seu editor de texto favorito e adicione o seguinte conteúdo:

# Especifica a versão principal do Node.js a ser usada no projeto
# O ServBay seleciona automaticamente a última versão já instalada desse major version
NODE_VERSION=20

# Opcional: Configuração de repositório de pacotes npm/pnpm/yarn para acelerar instalações
# Para usuários na China continental, recomenda-se um mirror local
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Opcional: Diretório de cache do npm ou pnpm
# Recomenda-se utilizar o diretório temporário do ServBay para evitar ocupar espaço ou poluir pastas do usuário
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Explicação das configurações:

• NODE_VERSION: Obrigatório. Define o número da versão principal (major) do Node.js exigido pelo projeto. Por exemplo, NODE_VERSION=20 utilizará automaticamente a versão mais recente do Node.js 20.x instalada no ServBay. Certifique-se de que ServBay tenha a versão correspondente instalada.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: Opcional. Define mirrors para os repositórios do Yarn ou npm—útil para acelerar instalações, especialmente em locais com restrições de rede.
• NPM_CONFIG_CACHE: Opcional. Define o diretório de cache do npm (ou pnpm). Direcionar o cache para /Applications/ServBay/tmp/npm/cache ajuda a manter o controle e evita espalhar arquivos pelo sistema.

Salve e feche o arquivo .servbay.config.

Passo 2: Validar a versão no Terminal ServBay

1. Abra a interface principal do aplicativo ServBay.

2. Clique no botão “Terminal” para iniciar o terminal integrado do ServBay.

3. No terminal, use cd para navegar até o diretório do seu projeto.

   cd /Applications/ServBay/www/seu-nome-do-projeto

   (Substitua /Applications/ServBay/www/seu-nome-do-projeto pelo caminho real do seu projeto)

4. Execute o comando node -v para verificar qual versão do Node.js está ativa.

   node -v

   O retorno deve exibir a versão que você definiu no arquivo .servbay.config (por exemplo, v20.x.x).

5. Também é possível rodar npm -v (ou pnpm -v, yarn -v) para conferir se o gerenciador de pacotes está associado corretamente à versão do Node.js ativa.

Pronto! Agora, dentro do diretório do seu projeto, qualquer comando Node.js ou npm/pnpm/yarn será executado utilizando a versão de Node.js e variáveis definidas em .servbay.config.

Exemplo Prático

Veja como .servbay.config permite alternar automaticamente a versão do Node.js ao alternar entre diferentes projetos:

Imagine que você tenha dois projetos: project-a (Node.js v18) e project-b (Node.js v20).

1. Crie os diretórios dos projetos e os arquivos de configuração:

   # Crie diretórios de exemplo dentro do www do ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Para project-a, crie .servbay.config com Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Para project-b, crie .servbay.config com Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Valide a alternância de versões no terminal ServBay:

   Abra o terminal do ServBay e execute:

   # Entre no diretório project-a
   cd /Applications/ServBay/www/project-a
   # Verifique a versão do Node.js
   node -v
   # Esperado: v18.x.x
   
   # Entre no diretório project-b
   cd ../project-b
   # Verifique a versão do Node.js
   node -v
   # Esperado: v20.x.x
   
   # Volte ao project-a
   cd ../project-a
   # Verifique novamente
   node -v
   # Esperado: v18.x.x

Como demonstrado, o ServBay aplica automaticamente o valor de NODE_VERSION do .servbay.config correspondente ao diretório corrente, alternando as versões do Node.js sem esforço manual.

A imagem abaixo ilustra a mudança automática de versão do Node.js ao alternar entre diferentes diretórios de projeto, baseada no .servbay.config (imagem meramente ilustrativa; a interface real pode variar):

Observações Importantes

• O arquivo .servbay.config deve estar presente no diretório do projeto ou em um diretório pai. O ServBay fará uma busca ascendente e usará o primeiro arquivo encontrado (mais próximo do diretório atual).
• Garanta que você está utilizando o terminal integrado do ServBay ou um terminal externo corretamente configurado com as variáveis de ambiente do ServBay.
• O valor de NODE_VERSION deve corresponder a uma versão de Node.js que está instalada e ativada no aplicativo ServBay. Se a versão não estiver disponível, o ServBay pode reverter para o padrão ou não encontrar o comando Node.js.
• As configurações do .servbay.config afetam apenas a sessão atual do terminal e subprocessos, sem impacto no ambiente global do sistema ou em processos fora do ambiente do ServBay.

Perguntas Frequentes (FAQ)

P: O que acontece se meu projeto não possui um arquivo .servbay.config?

R: Caso o ServBay não encontre o .servbay.config no diretório atual nem em diretórios superiores, ele usará as configurações globais padrão, geralmente a versão de Node.js marcada como "padrão" no ServBay.

P: Como descubro quais versões do Node.js o ServBay suporta?

R: Abra o aplicativo ServBay e navegue até o menu “Pacotes” (Packages) na barra lateral esquerda. Lá você verá todas as versões do Node.js disponíveis—basta marcar ou desmarcar para ativar/desativar versões específicas.

P: A configuração do .servbay.config afeta meu sistema inteiro?

R: Não. As configurações do .servbay.config são temporárias e aplicadas somente à sessão daquele terminal ou a processos filhos dentro do ambiente do ServBay. Isso não altera variáveis globais do sistema, nem afeta processos fora do ServBay. Esse é um dos mecanismos chave para o isolamento do ambiente por projeto.

P: Além do NODE_VERSION, posso configurar outros parâmetros no .servbay.config?

R: Sim! O .servbay.config é um mecanismo genérico do ServBay para definir variáveis de ambiente no nível do projeto. Além de parâmetros relacionados ao Node.js, você pode inserir outras variáveis que serão carregadas para o ambiente daquele projeto. Os itens suportados podem variar conforme novas versões do ServBay, mas a definição de variáveis de ambiente é o principal propósito.

Resumo

Ao adotar o arquivo .servbay.config do ServBay, você consegue especificar e gerenciar versões independentes do Node.js para cada projeto local de maneira fácil e eficiente. Essa abordagem, mais leve e prática do que gerenciadores de versão tradicionais ou containers, se encaixa perfeitamente ao ambiente integrado do ServBay e contribui para um fluxo de trabalho colaborativo, limpo e estável. Experimente utilizar o .servbay.config em seus projetos e aproveite toda a conveniência trazida pelo ServBay!