Noções Básicas de Configuração de Projeto

9 exemplos para você começar com a Configuração de Projeto - 7 básicos e 2 intermediários.

Pré-requisitos

• Node.js 24.18.0 e npm 10+.
• TypeScript 5.6+: npm init -y && npm install -D typescript@5.6 tsx @types/node.
• Git inicializado: git init && git add . && git commit -m "init".

Exemplos Básicos

1. Layout Padrão de Serviço de API

Separe código fonte, testes e configuração na raiz do repositório para clareza.

billing-api/
  src/
    server.ts
    routes/
    services/
  test/
    health.test.ts
  package.json
  tsconfig.json
  Dockerfile
  .gitignore

• src/ contém o TypeScript em tempo de execução; test/ espelha as pastas de domínio.
• Arquivos de configuração ficam na raiz para que as ferramentas os descubram sem flags adicionais.
• Um deploy por repositório, a menos que você adote um layout explícito de monorepo.

Relacionado: Scaffolding de APIs - inicialize a partir de templates

2. Scripts package.json para Desenvolvimento e Produção

Conecte os comandos diários que todos os contribuidores e jobs de CI executam.

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc -p tsconfig.build.json",
    "start": "node dist/server.js",
    "test": "node --import tsx --test",
    "typecheck": "tsc --noEmit"
  }
}

• dev para iteração local; start executa o código compilado em produção.
• typecheck falha rapidamente sem emitir arquivos.
• Scripts são o contrato - documente-os no README.

3. Configuração TypeScript Dividida

Use configurações separadas para saída de build vs. verificação de tipo do editor/CI.

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noEmit": true,
    "rootDir": ".",
    "types": ["node"]
  },
  "include": ["src", "test"]
}

// tsconfig.build.json
{
  "extends": "./tsconfig.json",
  "compilerOptions": { "noEmit": false, "outDir": "dist", "rootDir": "src" },
  "include": ["src"]
}

• NodeNext corresponde à resolução ESM do Node 24.
• A configuração de build exclui testes do dist/ de produção.

4. Arquivos de Ambiente e Gitignore

Mantenha segredos fora do git; documente as variáveis necessárias.

# .gitignore
node_modules/
dist/
.env
.env.local
coverage/

# .env.example (commitado)
PORT=3000
DATABASE_URL=postgres://localhost:5432/billing
LOG_LEVEL=info

• Commite .env.example, nunca .env.
• Carregue e valide as variáveis de ambiente na inicialização (esquema Zod em uma etapa posterior de fortalecimento do serviço).

5. Dockerfile Mínimo

Build em múltiplos estágios: instale, compile, execute imagem de runtime slim.

FROM node:24.18.0-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:24.18.0-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/server.js"]

• Fixe o patch do Node em FROM para corresponder a engines.
• Copie o lockfile antes do código fonte para o cache de camadas do Docker.

6. Ponto de Entrada de Verificação de Integridade (Health Check)

Todo serviço expõe uma rota de liveness desde o primeiro dia.

// src/server.ts
import express from "express";
 
const app = express();
 
app.get("/health", (_req, res) => {
  res.json({ status: "ok" });
});
 
const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => console.log(`listening on ${port}`));

• /health é amigável para balanceadores de carga e orquestradores.
• Mantenha-o livre de chamadas de banco de dados para liveness básica (readiness pode ser separada).

7. Bloco de Onboarding do README

Novos membros da equipe executam três comandos e obtêm um teste verde.

## Quick start
npm ci
cp .env.example .env
npm run dev
 
## Checks
npm run typecheck
npm test

• README é parte da configuração do projeto - não um pensamento posterior.
• Combine os comandos com os scripts do package.json exatamente.

Exemplos Intermediários

8. Pastas de Teste Colocadas vs. Separadas

Escolha uma convenção por repositório e a aplique.

# Opção A: test/ no nível superior (mostrado acima)
test/routes/health.test.ts

# Opção B: Colocado
src/routes/health.test.ts

• test/ no nível superior mantém dist/ limpo sem regras de exclusão adicionais.
• Testes colocados ficam ao lado dos módulos - bom para domínios com muitas unidades.
• Nunca misture os dois padrões em um único serviço.

Relacionado: Noções Básicas de Teste - pirâmide para APIs

9. Monorepo vs. Repositório de Serviço Único

Comece com serviço único; divida quando as fronteiras estiverem claras.

• Monorepos prematuros taxam cada PR com sobrecarga de coordenação.
• Extraia código compartilhado quando o terceiro serviço copiar o mesmo módulo.

Relacionado: Monorepo Multi-Serviço - regras de fronteira

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.