Express TypeScript Starter

Um projeto starter para aplicações web usando Express.js e TypeScript, configurado com as melhores práticas de desenvolvimento, testes e estrutura de projeto.

🚀 Funcionalidades

• ✅ Express.js 5.1+ - Framework web rápido e minimalista
• ✅ TypeScript - Tipagem estática para JavaScript
• ✅ Sistema de Decorators - Controllers e rotas com decorators customizados
• ✅ Reflect Metadata - Metadados para decorators e injeção de dependência
• ✅ Jest - Framework de testes com cobertura de código
• ✅ CORS configurado - Middleware para Cross-Origin Resource Sharing
• ✅ Variáveis de ambiente - Configuração com dotenv
• ✅ Health Check - Endpoint para verificação de saúde da aplicação
• ✅ 404 Handler - Middleware para rotas não encontradas
• ✅ Build otimizado - Compilação TypeScript para produção

📁 Estrutura do Projeto

express-typescript-starter/
├── src/
│   ├── server.ts                          # Arquivo principal do servidor
│   ├── config/
│   │   └── config.ts                      # Configurações da aplicação
│   ├── controllers/
│   │   └── main.ts                        # Controller principal com decorators
│   ├── decorators/
│   │   ├── controller.ts                  # Decorator para controllers
│   │   └── routes.ts                      # Decorator para rotas
│   ├── lib/
│   │   └── routes.ts                      # Tipos para sistema de rotas
│   ├── modules/
│   │   └── routes.ts                      # Lógica de definição de rotas
│   └── middleware/
│       ├── cors-handler.middleware.ts     # Middleware de CORS
│       └── not-found-route.middleware.ts  # Middleware 404
├── test/
│   └── integration/
│       └── server.integration.test.ts     # Testes de integração
├── build/                                 # Arquivos compilados (gerados)
├── coverage/                              # Relatórios de cobertura de testes
├── jest.config.ts                         # Configuração do Jest
├── tsconfig.json                          # Configuração do TypeScript
├── tsconfig.build.json                    # Configuração de build
└── package.json                           # Dependências e scripts

🛠️ Pré-requisitos

• Node.js 18+
• npm ou yarn

⚡ Instalação e Execução

1. Clone o repositório

git clone https://github.com/zYasuo/express-typescript-starter.git
cd express-typescript-starter

2. Instale as dependências

npm install

3. Configure as variáveis de ambiente

Crie um arquivo .env na raiz do projeto:

NODE_ENV=development
SERVER_HOSTNAME=localhost
SERVER_PORT=3001

4. Execute em modo de desenvolvimento

npm run dev

O servidor estará rodando em http://localhost:3001

5. Build para produção

npm run build

Os arquivos compilados estarão na pasta build/

🧪 Testes

Executar todos os testes

npm test

Executar testes com watch mode

npm run test:watch

Ver relatório de cobertura

Após executar os testes, abra o arquivo coverage/lcov-report/index.html no navegador.

📋 Scripts Disponíveis

Script	Descrição
npm test	Executa todos os testes com cobertura
npm run build	Compila o projeto TypeScript para JavaScript
npm start	Inicia o servidor em produção (após build)

🌐 Endpoints

Health Check

POST /healthcheck

Resposta:

{
    "hello": "world",
    "message": "Server is running"
}

404 - Rota não encontrada

Qualquer rota não definida retornará:

{
    "message": "Not Found",
    "path": "/rota-inexistente",
    "status": 404
}

⚙️ Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
NODE_ENV	Ambiente de execução	-
SERVER_HOSTNAME	Hostname do servidor	localhost
SERVER_PORT	Porta do servidor	3001

Middleware Configurado

• CORS: Permite requisições de diferentes origens
• Body Parser: Parse de JSON e URL-encoded
• 404 Handler: Tratamento de rotas não encontradas

🔧 Desenvolvimento

Sistema de Decorators

O projeto utiliza um sistema de decorators personalizado para definir controllers e rotas de forma declarativa:

Controllers

Use o decorator @Controller() para definir um controller:

import { Controller } from "../decorators/controller";

@Controller("/api") // Base path opcional
class ApiController {
    // métodos do controller
}

Rotas

Use o decorator @Routes() para definir rotas:

import { Routes } from "../decorators/routes";
import { Request, Response, NextFunction } from "express";

@Controller()
class MainController {
    @Routes("post", "/healthcheck")
    getHealthCheck(req: Request, res: Response, next: NextFunction) {
        res.status(200).json({
            hello: "world",
            message: "Server is running"
        });
    }
}

Registrando Controllers

No arquivo server.ts, registre os controllers usando DefineRoutes:

import MainController from "./controllers/main";
import { DefineRoutes } from "./modules/routes";

// Registra todos os controllers
DefineRoutes([MainController], app);

Adicionando novas rotas

1. Crie um novo controller em src/controllers/
2. Use os decorators @Controller() e @Routes()
3. Registre o controller no array de DefineRoutes em server.ts

Adicionando novos middlewares

1. Crie um novo arquivo em src/middleware/
2. Implemente o middleware seguindo o padrão do projeto
3. Importe e use no server.ts ou como parâmetro no decorator @Routes()

Configurações adicionais

Edite o arquivo src/config/config.ts para adicionar novas configurações.

📝 Estrutura de Testes

O projeto usa Jest para testes com a seguinte estrutura:

• Testes de Integração: test/integration/
• Configuração: jest.config.ts
• Cobertura: Relatórios gerados na pasta coverage/

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

👨‍💻 Autor

Danilo Aguiar

• GitHub: @zYasuo

---

⭐ Se este projeto te ajudou, considere dar uma estrela no repositório!