Visão geral

O Koala Nest é um facilitador para criar APIs NestJS com arquitetura DDD. Em vez de depender de uma biblioteca opaca, a CLI copia módulos prontos para dentro do projeto — abordagem semelhante ao shadcn/ui. O código gerado fica no seu repositório, pronto para leitura, adaptação e manutenção.

Core (sempre instalado)

Ao rodar kl-nest new, a CLI instala automaticamente:

• validação de variáveis de ambiente com Zod;
• TypeORM com PostgreSQL e scripts de migration;
• documentação OpenAPI em /doc via Scalar;
• filtro global de erros (Zod, TypeORM e exceções HTTP);
• bases reutilizáveis para controllers, handlers, validators e repositórios;
• sistema de mapeamento entre entidades, requests e responses;
• @koalarx/utils — delay, CPF/CNPJ, strings, datas e arrays.

Funcionalidades opcionais

Escolha no kl-nest new ou adicione depois com kl-nest add:

OAuth2 e cron jobs instalam cache em memória automaticamente quando Redis não foi selecionado (sem ioredis).

Templates

No template CRUD, auth, cache e jobs são incluídos automaticamente para demonstrar o fluxo completo. Apenas health check permanece opcional na criação (ou via kl-nest add health).

Estrutura de pastas

Projetos gerados seguem esta organização:

src/
├── application/   # casos de uso, validadores, mapeamentos
├── core/          # utilitários, env, ferramentas compartilhadas
├── domain/        # entidades, DTOs, contratos de repositório
├── host/          # controllers, módulos Nest, filtros, OpenAPI
├── infra/         # banco de dados, repositórios, serviços externos
└── test/          # testes unitários

Próximos passos

• Guia de instalação — kl-nest new e kl-nest add
• Arquitetura DDD — camadas e responsabilidades
• Estrutura do projeto — bootstrap e módulos Nest
• Fluxo CRUD Person — exemplo ponta a ponta (template CRUD)
• Health check — monitoramento com Terminus
• Cache (Redis) — cache distribuído
• Cron e Event Jobs — jobs em background