Como configurar ambiente Node.js: guia passo a passo

Montar um ambiente de desenvolvimento Node.js funcional é o primeiro passo para criar aplicações back-end, APIs e ferramentas modernas. Este guia cobre desde a instalação do Node.js e do gerenciador de pacotes npm até a configuração de variáveis de ambiente e a escolha de um editor de código.

Passo 1: Instalar o Node.js e o npm

O Node.js é o runtime que executa JavaScript no servidor. O npm (Node Package Manager) acompanha a instalação padrão e gerencia as bibliotecas do projeto.

Acesse o site oficial [nodejs.org](https://nodejs.org). Para a maioria dos usuários, a versão LTS (Long Term Support) é a recomendada por ser mais estável. Baixe o instalador do seu sistema operacional (Windows, macOS ou Linux).

No Windows, execute o arquivo .msi e siga o assistente, mantendo as opções padrão. No macOS, use o instalador .pkg ou, se preferir, o Homebrew com o comando brew install node. No Linux (Ubuntu/Debian), utilize:

• sudo apt update
• sudo apt install nodejs npm

Erro comum: instalar a versão Current (mais recente) em projetos de produção. Ela pode conter funcionalidades experimentais e causar incompatibilidade. Prefira sempre a LTS se não precisar de recursos de ponta.

Passo 2: Verificar a instalação

Abra o terminal (Prompt de Comando no Windows, Terminal no macOS/Linux) e digite:

• node -v, deve retornar algo como v18.17.0
• npm -v, retorna a versão do npm, por exemplo 9.6.7

Se aparecer um erro de comando não encontrado, a instalação pode não ter sido concluída ou o PATH não foi configurado. No Windows, reinicie o terminal ou o computador. No Linux, verifique se o pacote foi instalado corretamente.

Passo 3: Escolher um editor de código

Embora qualquer editor de texto funcione, um bom editor com suporte a JavaScript acelera o desenvolvimento. O Visual Studio Code (VS Code) é o mais popular por ser gratuito, ter integração com terminal e extensões específicas para Node.js.

Baixe o VS Code em [code.visualstudio.com](https://code.visualstudio.com). Instale e, na aba de extensões (Ctrl+Shift+X), procure por:

• ESLint, para identificar erros de sintaxe
• Prettier, para formatar o código automaticamente
• Node.js Modules Intellisense, para autocomplete de módulos

Dica: configure o VS Code para abrir diretamente na pasta do projeto. Use o menu 'File > Open Folder' e selecione a pasta onde o código será salvo.

Passo 4: Criar o primeiro projeto Node.js

Crie uma pasta para o projeto: mkdir meu-projeto cd meu-projeto

Inicialize o projeto com: npm init -y

A flag -y aceita todas as configurações padrão. Será gerado o arquivo package.json, que contém metadados do projeto (nome, versão, scripts, dependências).

Para instalar um pacote, use: npm install express

O Express será baixado para a pasta node_modules e registrado como dependência no package.json.

Erro comum: esquecer de criar o arquivo .gitignore antes de versionar. Adicione a pasta node_modules ao .gitignore para não enviar milhares de arquivos desnecessários ao repositório.

Passo 5: Configurar variáveis de ambiente

Variáveis de ambiente guardam informações sensíveis como chaves de API, senhas de banco de dados e portas. A forma mais comum é usar um arquivo .env.

Instale o pacote dotenv: npm install dotenv

Crie um arquivo .env na raiz do projeto: PORT=3000 DB_HOST=localhost DB_USER=root DB_PASS=minha-senha

No arquivo principal (por exemplo index.js), carregue as variáveis: require('dotenv').config();

const port = process.env.PORT || 3000; console.log(Servidor rodando na porta ${port});

Dica: nunca compartilhe o arquivo .env no GitHub. Adicione .env ao .gitignore. Crie um arquivo .env.example com as mesmas variáveis, mas sem valores reais, para orientar outros desenvolvedores.

Passo 6: Testar o ambiente com um servidor simples

Crie um arquivo index.js: const express = require('express'); const app = express(); const port = process.env.PORT || 3000;

app.get('/', (req, res) => { res.send('Olá, Node.js!'); });

app.listen(port, () => { console.log(Servidor rodando em http://localhost:${port}); });

No terminal, execute: node index.js

Abra o navegador em http://localhost:3000. Se aparecer 'Olá, Node.js!', o ambiente está configurado corretamente.

Checklist do que foi feito

• [ ] Node.js e npm instalados (versão LTS)
• [ ] Instalação verificada com node -v e npm -v
• [ ] Editor de código configurado (VS Code com extensões)
• [ ] Projeto inicializado com npm init -y
• [ ] Dependência instalada (Express)
• [ ] Arquivo .env criado e protegido no .gitignore
• [ ] Servidor de teste rodando e respondendo

Perguntas frequentes (FAQ)

Preciso instalar o Node.js separadamente para cada projeto?

Não. O Node.js é instalado uma vez no sistema. Cada projeto usa a mesma instalação do runtime, mas as dependências (pacotes npm) são isoladas por projeto na pasta node_modules.

Qual a diferença entre npm e npx?

O npm instala e gerencia pacotes. O npx executa pacotes sem instalá-los globalmente. Por exemplo, npx create-react-app meu-app baixa e executa o pacote sem deixá-lo instalado no sistema.

Como atualizar o Node.js?

No site oficial, baixe a nova versão LTS e reinstale. No Linux, use sudo apt upgrade nodejs. No macOS com Homebrew, brew upgrade node. Sempre verifique a compatibilidade com os projetos existentes.

O que fazer se o comando 'node' não for reconhecido?

No Windows, verifique se o Node.js foi adicionado ao PATH durante a instalação (opção padrão). Reinicie o terminal ou o computador. No Linux, confirme se o pacote foi instalado com which node.

É obrigatório usar o Express?

Não. O Express é um framework web popular, mas você pode usar outros como Fastify, Koa ou até o módulo nativo http do Node.js. O processo de configuração do ambiente é o mesmo.

Como desinstalar um pacote npm?

Use npm uninstall <nome-do-pacote> no terminal. O comando remove o pacote da pasta node_modules e atualiza o package.json automaticamente.