Checklist de configuração inicial de projeto Node.js: passo a passo

Montar um projeto Node.js do zero parece simples, mas pular etapas gera retrabalho. Este checklist cobre do ambiente ao erro que ninguém avisa.

1. Ambiente e inicialização

• Node e npm instalados, Rode node -v e npm -v no terminal. Se faltar, baixe do site oficial (nodejs.org).
• `npm init`, Cria o package.json. Use npm init -y para o padrão ou responda as perguntas manualmente.
• Pasta do projeto, Crie uma pasta limpa com mkdir meu-projeto && cd meu-projeto.
• Arquivo de entrada, Crie index.js ou app.js com um console.log('ok') de teste.

2. Dependências e organização

• `node_modules` no .gitignore, Adicione node_modules/ e .env no .gitignore antes do primeiro commit. Esquecer isso é o erro mais comum.
• Variáveis de ambiente, Instale dotenv com npm install dotenv. Crie .env com chaves como PORT=3000 e carregue no código com require('dotenv').config().
• Scripts no package.json, Configure ao menos "start": "node index.js" e "dev": "nodemon index.js" (se usar nodemon).

3. Qualidade e padronização

• ESLint, Instale como dev: npm install eslint --save-dev. Rode npx eslint --init e escolha estilo (Airbnb, Standard, etc.).
• EditorConfig, Crie .editorconfig na raiz para manter indentação e encoding consistentes entre editores.
• Teste rápido, Execute npm start e veja se o servidor sobe sem erros. Se deu console.log, veja a mensagem no terminal.

O erro que ninguém avisa

O erro clássico: commitar node_modules e .env para o repositório. Sem .gitignore, o repositório fica pesado e expõe senhas. Configure o .gitignore antes de qualquer git add. Depois de commitar, remova com git rm -r --cached node_modules.

FAQ

Preciso instalar o Node globalmente?

Sim, o Node precisa estar instalado no sistema. Use o instalador do site oficial ou um gerenciador de versões como nvm para trocar entre versões.

Qual a diferença entre npm init e npm init -y?

npm init faz perguntas interativas (nome, versão, descrição). npm init -y aceita os valores padrão e gera o package.json mais rápido.

Devo usar npm ou yarn?

Ambos funcionam. npm já vem com Node e é suficiente para a maioria dos projetos. Yarn pode ser mais rápido em instalações grandes. Escolha o que sua equipe já usa.

O que colocar no .env?

Informações sensíveis e de ambiente: chaves de API, senhas de banco, porta do servidor, URLs de serviços externos. Nunca commite esse arquivo.

Preciso de um linter desde o início?

Sim. ESLint pega erros de sintaxe e padroniza o código antes que vire bagunça. Configure no início para evitar refatoração depois.

Como testar se o setup está correto?

Rode npm start e veja se o servidor sobe sem erros. Se usou console.log, confira a mensagem no terminal. Depois, faça uma requisição HTTP básica (se for um servidor) com curl ou navegador.