Overview

What Koala Nest is and how it fits into NestJS projects with DDD.

Koala Nest is a facilitator for building NestJS APIs with DDD architecture. Instead of relying on an opaque library, the CLI copies ready-made modules into your project — an approach similar to shadcn/ui. The generated code lives in your repository, ready to read, adapt, and maintain.

Core (always installed)

When you run kl-nest new, the CLI asks for API or Worker, then installs:

  • environment variable validation with Zod;
  • TypeORM with PostgreSQL, migrations applied on boot (runMigrations), and CLI scripts;
  • reusable bases for handlers, validators, and repositories (and controllers on API);
  • mapping system between entities, requests, and responses;
  • @koalarx/utils — import '@koalarx/utils/prototypes' on boot; delay, CPF/CNPJ, strings, dates, and arrays.

On API, also: OpenAPI at /doc via Scalar, Helmet/CORS/rate-limit, and a global error filter. On Worker: NestFactory.createApplicationContext (no HTTP port). Details and silent flags: Installation guide.

Optional features

Choose during kl-nest new or add later with kl-nest add:

Feature Command Description
JWT/OAuth2 auth kl-nest add auth jwt / oauth2 Global guards, Scalar OAuth
API Key auth kl-nest add auth api-key Additive M2M (requires JWT and/or OAuth2)
Redis cache kl-nest add cache ICacheService + ioredis
Health check kl-nest add health GET /health with Terminus
Cron jobs kl-nest add cron CronJobHandlerBase + JobsModule
Event jobs kl-nest add events EventJob + in-memory handlers
Queue jobs kl-nest add queue QueueBase + IQueueService (implement infra later; no JobsModule)
AI context kl-nest add ai-context cursor|github Vibecoding — AI context

OAuth2 and cron jobs automatically install in-memory cache when Redis was not selected (no ioredis).

Templates

Template Contents
Default Core only — no sample code
CRUD Example Complete Person module with auth, Redis cache, cron and event jobs

In the CRUD template, auth, cache, and jobs are included automatically to demonstrate the full flow. Only health check remains optional during creation (or via kl-nest add health).

Folder structure

Generated projects follow this organization:

text 
src/
├── application/   # use cases, validators, mappings
├── core/          # utilities, env, shared tools
├── domain/        # entities, DTOs, repository contracts
├── host/          # controllers, Nest modules, filters, OpenAPI
├── infra/         # database, repositories, external services
└── test/          # unit tests

What's new

Notable CLI and template changes live in Patch notes (also in the repo CHANGELOG.md).

Next steps