Koala Nest

Facilitador para criar APIs NestJS com arquitetura DDD, focado em manutenção, escalabilidade e liberdade para evoluir o código no seu próprio repositório.

Em vez de depender de uma biblioteca opaca, a CLI copia módulos prontos para dentro do projeto — abordagem semelhante ao shadcn/ui. Você recebe código que pode ler, adaptar e manter sem amarras futuras.

Documentação: nest.koalarx.com (PT e EN)

Novidades: CHANGELOG.md · Patch notes (docs)

O que está disponível hoje

| Recurso | Status | | --- | --- | | Comando new (API ou Worker) | Disponível | | Módulo core (DDD, TypeORM, validação Zod) | Disponível | | Template Padrão (estrutura limpa) | Disponível | | Template Exemplo de CRUD (Person) — só API | Disponível | | Autenticação JWT, OAuth2 e API Key | Disponível via new e add | | Cache Redis, health, cron, events, queue | Disponível via new e add | | Contexto AI (Cursor / GitHub Copilot) | Disponível via new (prompt) e add ai-context | | Comando add (funcionalidades avulsas) | Disponível |

Instalação e uso

O pacote @koalarx/nest expõe o comando kl-nest. Você pode usá-lo de três formas:

Instalação global (recomendado)

Instale uma vez e use kl-nest em qualquer pasta:

npm install -g @koalarx/nest
# ou: bun install -g @koalarx/nest
# ou: pnpm add -g @koalarx/nest

kl-nest new
kl-nest --help

Sem instalar (bunx / npx)

Execute a versão publicada diretamente, sem instalação global:

bunx @koalarx/nest new
npx @koalarx/nest new

Útil para testar uma versão específica ou usar a CLI pontualmente:

bunx @koalarx/nest@latest new
npx @koalarx/nest@latest new

CLI

Comandos

| Comando | Descrição | | --- | --- | | kl-nest new | Cria um novo projeto (fluxo interativo) | | kl-nest add | Adiciona funcionalidades a um projeto existente | | kl-nest version | Exibe a versão da CLI | | kl-nest help | Lista comandos disponíveis |

kl-nest new
kl-nest new my-worker -y --type worker --features queue
kl-nest add cache
kl-nest add auth jwt health
kl-nest add auth api-key
kl-nest add queue
kl-nest add ai-context cursor github
kl-nest version
kl-nest --help

# equivalente sem instalação global:
bunx @koalarx/nest new
npx @koalarx/nest new

O comando new pergunta:

• tipo de aplicação (API ou Worker);
• nome do projeto;
• gerenciador de pacotes (bun, npm ou pnpm — Bun recomendado);
• template (Padrão ou Exemplo de CRUD — CRUD só na API);
• autenticação (JWT, OAuth2, API Key aditiva, ou nenhuma) e features (cache, health, cron, events, queue — health/auth só na API);
• contexto AI (Cursor, GitHub Copilot, ambos ou nenhum). Com -y o contexto AI não é gerado.

O comando add instala funcionalidades em um projeto Koala Nest já existente (detecta o que já está presente e pula duplicatas):

• auth jwt / auth oauth2 / auth api-key — autenticação (API; api-key exige JWT e/ou OAuth2)
• cache — cache Redis (com exemplos no template CRUD)
• health — endpoint GET /health (API)
• cron / events — jobs internos (JobsModule / host/jobs)
• queue — handlers de fila (QueueBase; sem JobsModule)
• ai-context cursor / github — contexto para vibecoding

cd meu-projeto
kl-nest add cache
kl-nest add auth jwt health --verbose
kl-nest add auth api-key --api-key-internal-subnet
kl-nest add cron events
kl-nest add queue
kl-nest add ai-context cursor

Detalhes: Guia de instalação · Contexto AI

Templates

Padrão — estrutura DDD pronta para começar do zero, sem código de exemplo de domínio.

Exemplo de CRUD — inclui um módulo completo de Person (entidades, repositório, handlers, controllers e mapeamentos) para servir de referência.

Estrutura gerada

Projetos criados 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

Módulo core

Ao criar um projeto, o módulo core instala e configura:

• validação de variáveis de ambiente com Zod (PORT, NODE_ENV, DATABASE_URL);
• TypeORM com PostgreSQL e scripts de migration;
• documentação OpenAPI em /doc via Scalar;
• filtro global de erros;
• bases reutilizáveis para controllers, handlers, validators e repositórios;
• sistema de mapeamento entre entidades, requests e responses.

Variáveis de ambiente

Crie um .env na raiz do projeto gerado:

PORT=3000
NODE_ENV=develop
DATABASE_URL=postgresql://user:password@localhost:5432/my_api

Scripts úteis no projeto gerado

bun run start:dev          # sobe a API (aplica migrations pendentes no boot)
bun run migration:generate # gera migration a partir das entidades
bun run migration:run      # aplica migrations pendentes (CI / ops)
bun run migration:revert   # reverte a última migration

Detalhes: Migrations · Patch notes

Documentação

Site completo: nest.koalarx.com — guias de instalação, arquitetura DDD, autenticação, cache, jobs, fluxo CRUD e patch notes (português e inglês).

Histórico resumido de mudanças: CHANGELOG.md.

Índices para agentes de IA

• PT: https://nest.koalarx.com/llms.txt (alias: /llm.txt)
• EN: https://nest.koalarx.com/llms-en.txt (alias: /llm-en.txt)

Repositório (desenvolvimento)

Para contribuir ou testar alterações locais da CLI:

git clone <url-do-repositorio>
cd koala-nest
bun install
bun run build
bun kl-nest new

O script bun kl-nest no package.json compila o projeto e executa a CLI a partir de dist/cli/index.js.

koala-nest/
├── libs/
│   ├── cli/          # código-fonte da CLI (kl-nest)
│   ├── doc/          # markdown da documentação + site Angular
│   └── koala-nest/   # templates copiados para projetos gerados
├── scripts/          # build da CLI, docs e templates
└── dist/             # saída do build (cli + koala-nest + package.json)

Scripts de desenvolvimento

bun run build              # build completo (CLI + templates + dist/package.json)
bun run build:cli          # apenas a CLI
bun run build:koala-nest   # apenas os templates
bun run build:docs         # site de documentação
bun test                   # testes do monorepo (CLI, lib, docs)