Noções Básicas de Onboarding

10 exemplos para configuração do primeiro dia: Node LTS, gerenciador de pacotes, Docker, Postgres/Redis local - para que um novo membro da equipe execute a API antes do almoço.

Pré-requisitos

Clone o repositório da equipe e confirme o contrato da stack antes de instalar as dependências.

git clone git@github.com:your-org/your-api.git
cd your-api
node -v   # espere v24.18.0
cat package.json | grep '"engines"'

Stack alvo para esta seção:

{
  "engines": { "node": "24.18.0", "npm": ">=10.0.0" },
  "packageManager": "npm@10.8.0"
}

Ferramentas: Node.js 24.18.0 (Active LTS), TypeScript 5.6+, Fastify 5 ou Nest 11 por ADR de serviço.

Exemplos Básicos

1. Node 24 LTS com fnm ou nvm

# Exemplo fnm
fnm install 24.18.0
fnm use 24.18.0
node -v   # v24.18.0
npm -v    # 10.x

# .nvmrc
24.18.0

• Corrija a versão do Node antes de npm ci - Node incorreto causa erros de ABI de módulo nativo
• engines em package.json deve corresponder a .nvmrc

Relacionado: Instalação e Gerenciamento de Versão

2. Instalar Dependências com npm ci

npm ci

• Use npm ci, não npm install, em um clone novo para corresponder exatamente à CI
• Se a equipe usa pnpm, execute corepack enable && pnpm install --frozen-lockfile em vez disso
• Uma política de lockfile por repositório - veja Noções Básicas de Gerenciadores de Pacotes

3. Variáveis de Ambiente

cp .env.example .env

# .env.example (commitado)
NODE_ENV=development
PORT=3000
DATABASE_URL=postgres://app:app@localhost:5432/app_dev
REDIS_URL=redis://localhost:6379
LOG_LEVEL=debug

• Nunca comite .env com segredos reais
• Segredos de produção vêm da injeção da plataforma, não de arquivos

Relacionado: Noções Básicas de Configuração

4. Docker Compose para Postgres e Redis

# docker-compose.yml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app_dev
    ports: ["5432:5432"]
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]

docker compose up -d
npm run db:migrate

• Armazenamentos de dados locais correspondem à topologia de produção (SQL + Redis) mesmo que a produção seja RDS/ElastiCache gerenciado
• Documente que docker compose down -v apaga os dados - avise os novos contratados

5. Iniciar a API e Verificar Saúde

npm run dev
curl -sf http://localhost:3000/health | jq .
curl -sf http://localhost:3000/ready | jq .

• Caminho verde: ambos retornam 200 antes de atribuir trabalho de feature
• Se ready falhar, verifique DATABASE_URL e os logs do container Postgres

Relacionado: Noções Básicas de CLI para Node

6. Executar o Conjunto de Testes

npm test
npm run typecheck
npm run lint

• Os mesmos três comandos que a CI executa - aprenda-os no primeiro dia
• Corrija falhas localmente antes de abrir o primeiro PR

7. Checklist do CONTRIBUTING.md

Todo repositório deve documentar:

## Quick start
1. fnm use / nvm use
2. npm ci
3. cp .env.example .env
4. docker compose up -d && npm run db:migrate
5. npm run dev
6. npm test

• O buddy aponta o CONTRIBUTING.md para o novo contratado nos primeiros 30 minutos
• A confusão no primeiro dia se torna um PR de documentação até o quinto dia

Exemplos Intermediários

8. Bootstrap de Monorepo

cd your-monorepo
npm ci                    # root instala workspaces
npm run build --workspaces --if-present
cd services/orders-api
npm run dev

• package.json raiz define workspaces
• O novo contratado trabalha em um serviço primeiro, não no monorepo inteiro no primeiro dia

Relacionado: Workspaces & Monorepos

9. Configuração de IDE e Debugger

// .vscode/launch.json (excerto)
{
  "type": "node",
  "request": "launch",
  "name": "Debug API",
  "runtimeArgs": ["--import", "tsx"],
  "args": ["src/server.ts"]
}

• Comite a configuração de lançamento compartilhada do VS Code/Cursor
• Depuração com breakpoints é melhor que console.log para aprender o fluxo assíncrono

10. Designação de Buddy no Primeiro Dia

## Novo contratado: Alex - início em 2026-07-09
Buddy: Jordan (backend, 2 anos)
Dia 1: Configuração da máquina + saúde verde + tour pelo codebase Nível 1
Dia 2: Pequeno PR de documentação (corrigir caminho do README)
Dias 3-5: Primeiro PR de feature com pareamento

• Buddy nomeado - não "pergunte no Slack"
• Veja Melhores Práticas de Equipe e Onboarding

FAQs

Relacionados

• Caminho Frontend → Node - curva de aprendizado da primeira semana
• Matriz de Habilidades - expectativas de nivelamento
• Melhores Práticas de Equipe e Onboarding - resumo de 25 itens

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.