@tndhuy/create-app 1.1.4 → 1.2.3

package/dist/cli.js

@@ -40,6 +40,7 @@ function toPascalCase(kebab) {
 function buildReplacements(serviceName) {
   return [
     ["nestjs-backend-template", serviceName],
+    ["{{SERVICE_NAME_KEBAB}}", serviceName],
     ["NestjsBackendTemplate", toPascalCase(serviceName)]
   ];
 }
@@ -158,18 +159,60 @@ async function collectPaths(dir) {
   }
   return results;
 }
-async function replaceFileContents(dir, replacements) {
+async function replaceFileContents(dir, replacements, options) {
   const entries = await (0, import_promises2.readdir)(dir, { withFileTypes: true });
   for (const entry of entries) {
     const fullPath = (0, import_path2.join)(dir, entry.name);
     if (entry.isDirectory()) {
-      await replaceFileContents(fullPath, replacements);
+      await replaceFileContents(fullPath, replacements, options);
     } else {
       const binary = await isBinaryFile(fullPath);
       if (binary) continue;
       try {
         let content = await (0, import_promises2.readFile)(fullPath, "utf-8");
         let modified = false;
+        const isPrisma = options.orm === "prisma";
+        const isMongoose = options.orm === "mongoose";
+        const hasRedis = options.modules.includes("redis");
+        const hasOtel = options.modules.includes("otel");
+        const hasKafka = options.modules.includes("kafka");
+        const isPostgres = options.db === "postgres";
+        const isMongo = options.db === "mongo";
+        const checkBlock = (content2, flag, tag) => {
+          const startTag = `{{#IF_${tag}}}`;
+          const endTag = `{{/IF_${tag}}}`;
+          const startNotTag = `{{#IF_NOT_${tag}}}`;
+          const endNotTag = `{{/IF_NOT_${tag}}}`;
+          if (content2.includes(startTag)) {
+            if (flag) {
+              content2 = content2.replaceAll(startTag, "").replaceAll(endTag, "");
+            } else {
+              const escapedStart = startTag.replace(/\{/g, "\\{").replace(/\}/g, "\\}");
+              const escapedEnd = endTag.replace(/\{/g, "\\{").replace(/\}/g, "\\}");
+              const regex = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}`, "g");
+              content2 = content2.replace(regex, "");
+            }
+          }
+          if (content2.includes(startNotTag)) {
+            if (!flag) {
+              content2 = content2.replaceAll(startNotTag, "").replaceAll(endNotTag, "");
+            } else {
+              const escapedStart = startNotTag.replace(/\{/g, "\\{").replace(/\}/g, "\\}");
+              const escapedEnd = endNotTag.replace(/\{/g, "\\{").replace(/\}/g, "\\}");
+              const regex = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}`, "g");
+              content2 = content2.replace(regex, "");
+            }
+          }
+          return content2;
+        };
+        content = checkBlock(content, isPrisma, "PRISMA");
+        content = checkBlock(content, isMongoose, "MONGOOSE");
+        content = checkBlock(content, hasRedis, "REDIS");
+        content = checkBlock(content, hasOtel, "OTEL");
+        content = checkBlock(content, hasKafka, "KAFKA");
+        content = checkBlock(content, isPostgres, "POSTGRES");
+        content = checkBlock(content, isMongo, "MONGO");
+        modified = content !== await (0, import_promises2.readFile)(fullPath, "utf-8");
         for (const [from, to] of replacements) {
           if (content.includes(from)) {
             content = content.replaceAll(from, to);
@@ -216,8 +259,21 @@ async function patchPackageJson(destDir, options) {
     const raw = await (0, import_promises2.readFile)(pkgPath, "utf-8");
     const pkg = JSON.parse(raw);
     pkg.name = options.serviceName;
+    delete pkg.workspaces;
     const PRISMA_LATEST = "^7.5.0";
     const PRISMA_MONGO_COMPAT = "^6.0.0";
+    if (options.orm === "prisma") {
+      if (!pkg.scripts) pkg.scripts = {};
+      pkg.scripts["db:generate"] = "prisma generate";
+      pkg.scripts["db:push"] = "prisma db push";
+      pkg.scripts["db:pull"] = "prisma db pull";
+      pkg.scripts["db:studio"] = "prisma studio";
+      pkg.scripts["db:format"] = "prisma format";
+      if (options.db === "postgres") {
+        pkg.scripts["db:migrate:dev"] = "prisma migrate dev";
+        pkg.scripts["db:migrate:deploy"] = "prisma migrate deploy";
+      }
+    }
     if (options.db === "mongo") {
       if (options.orm === "prisma") {
         if (pkg.dependencies) {
@@ -393,8 +449,11 @@ async function removeOtel(destDir) {
     // Remove: import otelSdk from './instrumentation';
     /^import\s+\w+\s+from\s+['"][^'"]*instrumentation['"];\n?/m,
     // Remove: otelSdk?.start(); line
-    /^\s*\w+Sdk\?\.start\(\);\n?/m
+    /^\s*\w+Sdk\?\.start\(\);\n?/m,
+    // Remove shutdown logic: void otelSdk?.shutdown()...
+    /^\s*void\s+otelSdk\?\.shutdown\(\)\.catch\(\(\)\s*=>\s*undefined\);\n?/m
   ]);
+  await safeDeleteFile(destDir, (0, import_path2.join)(destDir, "prometheus.yml"));
 }
 async function addKafka(destDir, serviceName) {
   await generateKafkaModule(destDir, serviceName);
@@ -464,7 +523,7 @@ async function scaffold(options) {
   }
   await (0, import_promises2.cp)(templateDir, destDir, { recursive: true });
   const replacements = buildReplacements(serviceName);
-  await replaceFileContents(destDir, replacements);
+  await replaceFileContents(destDir, replacements, options);
   await renamePathsWithPlaceholders(destDir, replacements);
   await patchPackageJson(destDir, options);
   if (options.db === "mongo" && options.orm === "prisma") {
@@ -504,6 +563,10 @@ async function scaffold(options) {
   if (modules.includes("kafka")) {
     await addKafka(destDir, serviceName);
   }
+  const templateGitignore = (0, import_path2.join)(destDir, "gitignore.template");
+  if (await pathExists(templateGitignore)) {
+    await (0, import_promises2.rename)(templateGitignore, (0, import_path2.join)(destDir, ".gitignore"));
+  }
 }
 
 // src/cli.ts
@@ -535,6 +598,7 @@ async function main() {
   };
   if (positionalName && !validateServiceName(positionalName)) {
     config.serviceName = positionalName;
+    (0, import_prompts.note)(`Using service name: ${config.serviceName} (from arguments)`, "Info");
   }
   let step = config.serviceName ? 1 : 0;
   const totalSteps = 4;
@@ -697,8 +761,9 @@ Modules      : ${selectedModules}`,
       }
     }
     const installDeps = guardCancel(await (0, import_prompts.confirm)({ message: "Install dependencies now?", initialValue: true }));
+    let pkgManager = "npm";
     if (installDeps) {
-      const pkgManager = guardCancel(await (0, import_prompts.select)({
+      pkgManager = guardCancel(await (0, import_prompts.select)({
         message: "Select package manager",
         options: [
           { value: "pnpm", label: "pnpm", hint: "recommended" },
@@ -711,17 +776,28 @@ Modules      : ${selectedModules}`,
       try {
         await (0, import_execa.execa)(pkgManager, ["install"], { cwd: destDir, stdio: "inherit" });
         is.stop("Dependencies installed successfully.");
+        if (config.orm === "prisma") {
+          const ps = (0, import_prompts.spinner)();
+          ps.start("Generating Prisma Client...");
+          try {
+            await (0, import_execa.execa)(pkgManager, ["run", "db:generate"], { cwd: destDir });
+            ps.stop("Prisma Client generated successfully.");
+          } catch (err) {
+            ps.stop("Prisma Client generation failed. You may need to run it manually.");
+          }
+        }
       } catch (err) {
         is.stop("Dependency installation failed.");
       }
     }
-  }
-  (0, import_prompts.outro)(
-    `Next steps:
+    (0, import_prompts.outro)(
+      `Next steps:
 
   cd ${config.serviceName}
-${dryRun ? "" : "  npm run start:dev\n"}`
-  );
+${dryRun ? "" : `  ${pkgManager} run start:dev
+`}`
+    );
+  }
 }
 main().catch((err) => {
   (0, import_prompts.cancel)(err instanceof Error ? err.message : String(err));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tndhuy/create-app",
-  "version": "1.1.4",
+  "version": "1.2.3",
   "private": false,
   "bin": {
     "create-app": "dist/cli.js"

package/templates/mongo/README.md

@@ -0,0 +1,128 @@
+# nestjs-backend-template
+
+## Overview
+
+- Production-ready NestJS 11 template with Domain-Driven Design (DDD) architecture — four layers (Domain, Application, Infrastructure, Presenter) with CQRS via `@nestjs/cqrs`
+- Pre-configured infrastructure: Prisma ORM, ioredis with circuit breaker, OpenTelemetry tracing and Prometheus metrics, Scalar API docs at `/docs`
+- Agent-ready: Claude Code (`.claude/`) and Antigravity (`.agent/`) configs pre-wired with codebase context files and GSD skill
+
+## Quick Start
+
+1. **Clone the repository**
+
+   ```bash
+   git clone <repo-url> my-service && cd my-service
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   pnpm install
+   ```
+
+3. **Configure environment**
+
+   ```bash
+   cp .env.example .env
+   ```
+
+   Edit `.env` and set at minimum:
+   - `DATABASE_URL` — MongoDB connection string
+   - `REDIS_URL` — Redis connection string
+
+4. **Start infrastructure**
+
+   ```bash
+   docker compose up -d
+   ```
+
+   Starts MongoDB and Redis locally.
+
+5. **Start the server**
+
+   ```bash
+   pnpm dev
+   ```
+
+   Server starts at http://localhost:3000. API docs available at http://localhost:3000/docs (login: `admin` / `admin`).
+
+## Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm start:dev` | Start in watch mode (development) |
+| `pnpm build` | Compile TypeScript to `dist/` |
+| `pnpm start:prod` | Run compiled build (`dist/src/main`) |
+| `pnpm test` | Run unit tests with Jest |
+| `pnpm test:cov` | Run tests with coverage report |
+| `pnpm test:e2e` | Run end-to-end tests |
+| `pnpm lint` | Run ESLint with auto-fix |
+| `pnpm format` | Run Prettier on `src/` and `test/` |
+| `pnpm db:generate` | Generate Prisma Client from schema |
+| `pnpm db:sync` | Sync Prisma schema to MongoDB (`prisma db push`) |
+| `pnpm db:sync:force` | Force sync schema with destructive changes (`--accept-data-loss`) |
+| `pnpm db:push` | Push schema changes directly to database (no migration files) |
+| `pnpm db:pull` | Pull database schema into `prisma/schema/` |
+| `pnpm db:validate` | Validate Prisma schema and datasource config |
+| `pnpm db:format` | Format Prisma schema files under `prisma/schema/` |
+| `pnpm db:studio` | Open Prisma Studio for data browsing/editing |
+
+## MongoDB Schema Workflow
+
+Prisma migrations are not used for MongoDB in this template.
+
+1. Edit schema files in `prisma/schema/`
+2. Run `pnpm db:format`
+3. Run `pnpm db:validate`
+4. Run `pnpm db:sync` (or `pnpm db:sync:force` when explicitly needed)
+5. Run `pnpm db:generate`
+
+## Environment Variables
+
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `PORT` | No | HTTP server port | `3000` |
+| `NODE_ENV` | No | Environment (`development` / `production`) | `development` |
+| `DATABASE_URL` | Yes | MongoDB connection string | — |
+| `REDIS_URL` | Yes | Redis connection string | — |
+| `API_VERSION` | No | API version for URI prefix | `1` |
+| `APP_NAME` | No | Application name shown in Scalar docs | `NestJS Backend Template` |
+| `APP_DESCRIPTION` | No | API description shown in Scalar docs | `API Documentation` |
+| `REQUEST_TIMEOUT` | No | Request timeout in milliseconds | `30000` |
+| `THROTTLE_TTL` | No | Rate limit window in seconds | `60` |
+| `THROTTLE_LIMIT` | No | Max requests per window | `100` |
+| `DOCS_USER` | No | Basic auth username for `/docs` | `admin` |
+| `DOCS_PASS` | No | Basic auth password for `/docs` | `admin` |
+| `OTEL_ENABLED` | No | Enable OpenTelemetry tracing and metrics | `false` |
+| `OTEL_SERVICE_NAME` | No | Service name reported to OTel collector | `nestjs-backend-template` |
+| `OTEL_PROMETHEUS_PORT` | No | Port for Prometheus metrics scrape endpoint | `9464` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | No | OTLP HTTP endpoint for trace export | `http://localhost:4318` |
+| `LARK_APP_ID` | No | Lark app ID for MCP integration (agent use) | — |
+| `LARK_APP_SECRET` | No | Lark app secret for MCP integration (agent use) | — |
+
+## Architecture
+
+This template follows Domain-Driven Design (DDD) with four layers: Domain, Application, Infrastructure, and Presenter. Each domain module is fully self-contained under `src/<module>/` and communicates through the CQRS bus.
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full guide including layer rules, data flow, and the `ExampleModule` walkthrough.
+
+## Adding a New Module
+
+Each new domain module follows the same DDD structure as `src/example/`. Follow the step-by-step walkthrough in [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md).
+
+## Tech Stack
+
+- **NestJS** 11.0.1 — framework (Express 5 platform)
+- **Prisma** 7.5.0 — MongoDB ORM with schema sync (`db push`)
+- **ioredis** 5.10.1 — Redis client with cockatiel circuit breaker
+- **Pino** / nestjs-pino — structured JSON logging
+- **OpenTelemetry** SDK — distributed tracing (OTLP) and Prometheus metrics
+- **Scalar** (@scalar/nestjs-api-reference) — interactive API docs
+- **class-validator** / **class-transformer** — DTO validation and transformation
+- **@nestjs/cqrs** 11.0.3 — command and query bus
+- **@nestjs/throttler** 6.5.0 — global rate limiting
+- **TypeScript** 5.7.3
+
+## License
+
+UNLICENSED

package/templates/mongo/docker-compose.yml

@@ -1,7 +1,28 @@
 services:
+{{#IF_POSTGRES}}
+  postgres:
+    image: postgres:16-alpine
+    container_name: {{SERVICE_NAME_KEBAB}}-postgres
+    restart: unless-stopped
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: template_db
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user -d template_db"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+{{/IF_POSTGRES}}
+
+{{#IF_MONGO}}
   mongodb:
     image: mongo:latest
-    container_name: nestjs-template-mongodb
+    container_name: {{SERVICE_NAME_KEBAB}}-mongodb
     restart: unless-stopped
     ports:
       - "27017:27017"
@@ -13,11 +34,13 @@ services:
       test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
       interval: 10s
       timeout: 5s
-      retries: 10
+      retries: 5
+{{/IF_MONGO}}
 
+{{#IF_REDIS}}
   redis:
     image: redis:latest
-    container_name: nestjs-template-redis
+    container_name: {{SERVICE_NAME_KEBAB}}-redis
     restart: unless-stopped
     ports:
       - "6379:6379"
@@ -28,8 +51,57 @@ services:
       test: ["CMD", "redis-cli", "ping"]
       interval: 10s
       timeout: 5s
-      retries: 10
+      retries: 5
+{{/IF_REDIS}}
+
+{{#IF_KAFKA}}
+  zookeeper:
+    image: bitnami/zookeeper:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-zookeeper
+    ports:
+      - "2181:2181"
+    environment:
+      - ALLOW_ANONYMOUS_LOGIN=yes
+
+  kafka:
+    image: bitnami/kafka:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-kafka
+    ports:
+      - "9092:9092"
+    environment:
+      - KAFKA_BROKER_ID=1
+      - KAFKA_CFG_ZOOKEEPER_CONNECT=zookeeper:2181
+      - ALLOW_PLAINTEXT_LISTENER=yes
+      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092
+    depends_on:
+      - zookeeper
+{{/IF_KAFKA}}
+
+{{#IF_OTEL}}
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-jaeger
+    ports:
+      - "16686:16686"
+      - "4317:4317"
+      - "4318:4318"
+
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-prometheus
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml
+{{/IF_OTEL}}
 
 volumes:
+{{#IF_POSTGRES}}
+  postgres_data:
+{{/IF_POSTGRES}}
+{{#IF_MONGO}}
   mongodb_data:
+{{/IF_MONGO}}
+{{#IF_REDIS}}
   redis_data:
+{{/IF_REDIS}}

package/templates/mongo/gitignore.template

@@ -0,0 +1,51 @@
+# compiled output
+/dist
+/node_modules
+/build
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# Environment files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# TypeScript incremental compilation
+*.tsbuildinfo
+
+# Claude Code memory files
+**/.claude/
+**/CLAUDE.md
+!/CLAUDE.md

package/templates/mongo/prometheus.yml

@@ -0,0 +1,7 @@
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: 'nestjs-service'
+    static_configs:
+      - targets: ['host.docker.internal:9464']

package/templates/mongo/src/common/interceptors/transform.interceptor.ts

@@ -4,11 +4,22 @@ import { Observable } from 'rxjs';
 import { map } from 'rxjs/operators';
 import { PUBLIC_API_KEY } from '../decorators/public-api.decorator';
 
+export const RAW_RESPONSE_KEY = 'raw_response';
+
 @Injectable()
 export class TransformInterceptor<T> implements NestInterceptor<T, unknown> {
   constructor(private readonly reflector: Reflector) {}
 
   intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const isRaw = this.reflector.getAllAndOverride<boolean>(RAW_RESPONSE_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (isRaw) {
+      return next.handle();
+    }
+
     const isPublic = this.reflector.getAllAndOverride<boolean>(PUBLIC_API_KEY, [
       context.getHandler(),
       context.getClass(),

package/templates/mongo/src/infrastructure/cache/redis.service.ts

@@ -1,9 +1,11 @@
 import { Injectable, OnModuleDestroy, Logger } from '@nestjs/common';
 import Redis from 'ioredis';
 import { circuitBreaker, ConsecutiveBreaker, CircuitBreakerPolicy, handleAll } from 'cockatiel';
+{{#IF_OTEL}}
 import { trace } from '@opentelemetry/api';
 
 const tracer = trace.getTracer('redis-service');
+{{/IF_OTEL}}
 
 @Injectable()
 export class RedisService implements OnModuleDestroy {
@@ -46,6 +48,7 @@ export class RedisService implements OnModuleDestroy {
   }
 
   async get(key: string): Promise<string | null> {
+{{#IF_OTEL}}
     return tracer.startActiveSpan('redis.get', async (span) => {
       try {
         span.setAttribute('db.system', 'redis');
@@ -59,9 +62,14 @@ export class RedisService implements OnModuleDestroy {
         span.end();
       }
     });
+{{/IF_OTEL}}
+{{#IF_NOT_OTEL}}
+    return this.execute((c) => c.get(key));
+{{/IF_NOT_OTEL}}
   }
 
   async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
+{{#IF_OTEL}}
     return tracer.startActiveSpan('redis.set', async (span) => {
       try {
         span.setAttribute('db.system', 'redis');
@@ -84,9 +92,20 @@ export class RedisService implements OnModuleDestroy {
         span.end();
       }
     });
+{{/IF_OTEL}}
+{{#IF_NOT_OTEL}}
+    await this.execute(async (c) => {
+      if (ttlSeconds) {
+        await c.set(key, value, 'EX', ttlSeconds);
+      } else {
+        await c.set(key, value);
+      }
+    });
+{{/IF_NOT_OTEL}}
   }
 
   async del(key: string): Promise<void> {
+{{#IF_OTEL}}
     return tracer.startActiveSpan('redis.del', async (span) => {
       try {
         span.setAttribute('db.system', 'redis');
@@ -100,9 +119,14 @@ export class RedisService implements OnModuleDestroy {
         span.end();
       }
     });
+{{/IF_OTEL}}
+{{#IF_NOT_OTEL}}
+    await this.execute((c) => c.del(key).then(() => undefined));
+{{/IF_NOT_OTEL}}
   }
 
   async expire(key: string, ttlSeconds: number): Promise<void> {
+{{#IF_OTEL}}
     return tracer.startActiveSpan('redis.expire', async (span) => {
       try {
         span.setAttribute('db.system', 'redis');
@@ -117,5 +141,9 @@ export class RedisService implements OnModuleDestroy {
         span.end();
       }
     });
+{{/IF_OTEL}}
+{{#IF_NOT_OTEL}}
+    await this.execute((c) => c.expire(key, ttlSeconds).then(() => undefined));
+{{/IF_NOT_OTEL}}
   }
 }

package/templates/mongo/src/main.ts

@@ -84,10 +84,19 @@ async function bootstrap() {
   const port = parseInt(process.env.PORT ?? '3000', 10);
   const httpServer = await app.listen(port);
 
+  const logger = app.get(Logger);
+  logger.log(`🚀 Application is running on: http://localhost:${port}`);
+  logger.log(`📖 API Documentation (Scalar): http://localhost:${port}/docs`);
+  logger.log(`📄 API Spec (JSON): http://localhost:${port}/docs/json`);
+
   process.on('SIGTERM', () => {
     loggerService.log('SIGTERM signal received: closing HTTP server');
     setTimeout(() => {
-      void otelSdk?.shutdown().catch(() => undefined);
+      if (process.env.OTEL_ENABLED === 'true') {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const otelSdk = require('./instrumentation').default;
+        void otelSdk?.shutdown().catch(() => undefined);
+      }
       httpServer.close(() => {
         loggerService.log('HTTP server closed');
         process.exit(0);

package/templates/mongo/src/shared/logger/pino.config.ts

@@ -1,6 +1,8 @@
 import { join } from 'path';
 import type { Params } from 'nestjs-pino';
+{{#IF_OTEL}}
 import { trace, context, isSpanContextValid } from '@opentelemetry/api';
+{{/IF_OTEL}}
 
 const isDev = process.env.NODE_ENV !== 'production';
 const LOG_DIR = join(process.cwd(), 'logs');
@@ -11,6 +13,7 @@ export const pinoConfig: Params = {
     level: isDev ? 'debug' : 'info',
     // Inject Trace context into every log line
     mixin() {
+{{#IF_OTEL}}
       const activeSpan = trace.getSpan(context.active());
       if (activeSpan) {
         const spanContext = activeSpan.spanContext();
@@ -22,6 +25,7 @@ export const pinoConfig: Params = {
           };
         }
       }
+{{/IF_OTEL}}
       return {};
     },
     // Standardize on X-Request-Id as the primary req.id

package/templates/postgres/README.md

@@ -0,0 +1,76 @@
+# {{SERVICE_NAME_KEBAB}}
+
+Production-ready NestJS 11 backend service based on DDD architecture.
+
+## Architecture Overview
+
+This project follows **Domain-Driven Design (DDD)** principles with four distinct layers:
+
+1.  **Domain:** Core logic, Entities, Value Objects, and Repository interfaces. (No framework dependencies)
+2.  **Application:** Command/Query handlers (CQRS), DTOs, and application services.
+3.  **Infrastructure:** Database implementations (Prisma/Mongoose), Redis cache, and external integrations.
+4.  **Presenter:** Controllers (HTTP/RPC), Interceptors, and Filters.
+
+## Features
+
+- **Pino Logging:** High-performance logging with request context tracking.
+- **Request ID:** Every request is assigned a unique `X-Request-Id` header for traceability.
+- **OpenTelemetry:** Distributed tracing and Prometheus metrics (if enabled).
+- **Circuit Breaker:** Resilience for Redis and external calls using Cockatiel.
+- **API Reference:** Interactive Scalar documentation available at `/docs`.
+
+## Quick Start
+
+### 1. Configure Environment
+
+```bash
+cp .env.example .env
+```
+
+### 2. Infrastructure
+
+Start database and cache using Docker:
+
+```bash
+docker compose up -d
+```
+
+### 3. Database Setup
+
+{{#IF_PRISMA}}
+```bash
+# Generate Prisma Client
+npm run db:generate
+
+# Apply migrations
+npm run db:migrate:deploy
+```
+{{/IF_PRISMA}}
+{{#IF_MONGOOSE}}
+Ensure your `MONGODB_URL` is correct in `.env`.
+{{/IF_MONGOOSE}}
+
+### 4. Running the App
+
+```bash
+# Development
+npm run start:dev
+
+# Production build
+npm run build
+npm run start:prod
+```
+
+## Logging & Observability
+
+- **Console:** Pretty-printed logs in development mode.
+- **Files:** Logs are automatically rotated and stored in the `logs/` directory.
+- **Correlation:** Search for `requestId` in logs to trace all logs for a specific user request.
+
+## Available Scripts
+
+- `npm run build`: Compile the project.
+- `npm run start:dev`: Start in watch mode.
+- `npm run test`: Run unit tests.
+- `npm run test:e2e`: Run end-to-end tests.
+- `npm run lint`: Fix code style issues.

package/templates/postgres/docker-compose.yml

@@ -0,0 +1,107 @@
+services:
+{{#IF_POSTGRES}}
+  postgres:
+    image: postgres:16-alpine
+    container_name: {{SERVICE_NAME_KEBAB}}-postgres
+    restart: unless-stopped
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: template_db
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user -d template_db"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+{{/IF_POSTGRES}}
+
+{{#IF_MONGO}}
+  mongodb:
+    image: mongo:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-mongodb
+    restart: unless-stopped
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_DATABASE: template_db
+    volumes:
+      - mongodb_data:/data/db
+    healthcheck:
+      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+{{/IF_MONGO}}
+
+{{#IF_REDIS}}
+  redis:
+    image: redis:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+{{/IF_REDIS}}
+
+{{#IF_KAFKA}}
+  zookeeper:
+    image: bitnami/zookeeper:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-zookeeper
+    ports:
+      - "2181:2181"
+    environment:
+      - ALLOW_ANONYMOUS_LOGIN=yes
+
+  kafka:
+    image: bitnami/kafka:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-kafka
+    ports:
+      - "9092:9092"
+    environment:
+      - KAFKA_BROKER_ID=1
+      - KAFKA_CFG_ZOOKEEPER_CONNECT=zookeeper:2181
+      - ALLOW_PLAINTEXT_LISTENER=yes
+      - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092
+    depends_on:
+      - zookeeper
+{{/IF_KAFKA}}
+
+{{#IF_OTEL}}
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-jaeger
+    ports:
+      - "16686:16686"
+      - "4317:4317"
+      - "4318:4318"
+
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: {{SERVICE_NAME_KEBAB}}-prometheus
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml
+{{/IF_OTEL}}
+
+volumes:
+{{#IF_POSTGRES}}
+  postgres_data:
+{{/IF_POSTGRES}}
+{{#IF_MONGO}}
+  mongodb_data:
+{{/IF_MONGO}}
+{{#IF_REDIS}}
+  redis_data:
+{{/IF_REDIS}}

package/templates/postgres/gitignore.template

@@ -0,0 +1,51 @@
+# compiled output
+dist/
+node_modules/
+/build
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS
+.DS_Store
+
+# Tests
+/coverage
+/.nyc_output
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# Environment files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# TypeScript incremental compilation
+*.tsbuildinfo
+
+# Do not add .npmrc files with auth tokens
+# packages/create-app/.npmrc is committed intentionally (uses ${NODE_AUTH_TOKEN} placeholder, no literal token)
+.npmrc
+!packages/create-app/.npmrc

package/templates/postgres/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "author": "",
   "private": true,
-  "license": "UNLICENSED",
+  "license": "MIT",
   "workspaces": [
     "packages/*"
   ],
@@ -63,7 +63,6 @@
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/testing": "^11.0.1",
     "@types/express": "^5.0.0",
-    "@types/ioredis": "^5.0.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.10.7",
     "@types/supertest": "^6.0.2",

package/templates/postgres/prometheus.yml

@@ -0,0 +1,7 @@
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: 'nestjs-service'
+    static_configs:
+      - targets: ['host.docker.internal:9464']

package/templates/postgres/src/common/interceptors/transform.interceptor.ts

@@ -4,11 +4,22 @@ import { Observable } from 'rxjs';
 import { map } from 'rxjs/operators';
 import { PUBLIC_API_KEY } from '../decorators/public-api.decorator';
 
+export const RAW_RESPONSE_KEY = 'raw_response';
+
 @Injectable()
 export class TransformInterceptor<T> implements NestInterceptor<T, unknown> {
   constructor(private readonly reflector: Reflector) {}
 
   intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const isRaw = this.reflector.getAllAndOverride<boolean>(RAW_RESPONSE_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (isRaw) {
+      return next.handle();
+    }
+
     const isPublic = this.reflector.getAllAndOverride<boolean>(PUBLIC_API_KEY, [
       context.getHandler(),
       context.getClass(),

package/templates/postgres/src/infrastructure/cache/redis.service.ts

@@ -1,9 +1,11 @@
 import { Injectable, OnModuleDestroy, Logger } from '@nestjs/common';
 import Redis from 'ioredis';
 import { circuitBreaker, ConsecutiveBreaker, CircuitBreakerPolicy, handleAll } from 'cockatiel';
+{{#IF_OTEL}}
 import { trace } from '@opentelemetry/api';
 
 const tracer = trace.getTracer('redis-service');
+{{/IF_OTEL}}
 
 @Injectable()
 export class RedisService implements OnModuleDestroy {
@@ -46,6 +48,7 @@ export class RedisService implements OnModuleDestroy {
   }
 
   async get(key: string): Promise<string | null> {
+{{#IF_OTEL}}
     return tracer.startActiveSpan('redis.get', async (span) => {
       try {
         span.setAttribute('db.system', 'redis');
@@ -59,9 +62,14 @@ export class RedisService implements OnModuleDestroy {
         span.end();
       }
     });
+{{/IF_OTEL}}
+{{#IF_NOT_OTEL}}
+    return this.execute((c) => c.get(key));
+{{/IF_NOT_OTEL}}
   }
 
   async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
+{{#IF_OTEL}}
     return tracer.startActiveSpan('redis.set', async (span) => {
       try {
         span.setAttribute('db.system', 'redis');
@@ -84,9 +92,20 @@ export class RedisService implements OnModuleDestroy {
         span.end();
       }
     });
+{{/IF_OTEL}}
+{{#IF_NOT_OTEL}}
+    await this.execute(async (c) => {
+      if (ttlSeconds) {
+        await c.set(key, value, 'EX', ttlSeconds);
+      } else {
+        await c.set(key, value);
+      }
+    });
+{{/IF_NOT_OTEL}}
   }
 
   async del(key: string): Promise<void> {
+{{#IF_OTEL}}
     return tracer.startActiveSpan('redis.del', async (span) => {
       try {
         span.setAttribute('db.system', 'redis');
@@ -100,9 +119,14 @@ export class RedisService implements OnModuleDestroy {
         span.end();
       }
     });
+{{/IF_OTEL}}
+{{#IF_NOT_OTEL}}
+    await this.execute((c) => c.del(key).then(() => undefined));
+{{/IF_NOT_OTEL}}
   }
 
   async expire(key: string, ttlSeconds: number): Promise<void> {
+{{#IF_OTEL}}
     return tracer.startActiveSpan('redis.expire', async (span) => {
       try {
         span.setAttribute('db.system', 'redis');
@@ -117,5 +141,9 @@ export class RedisService implements OnModuleDestroy {
         span.end();
       }
     });
+{{/IF_OTEL}}
+{{#IF_NOT_OTEL}}
+    await this.execute((c) => c.expire(key, ttlSeconds).then(() => undefined));
+{{/IF_NOT_OTEL}}
   }
 }

package/templates/postgres/src/infrastructure/health/prisma.health-indicator.ts

@@ -10,7 +10,13 @@ export class PrismaHealthIndicator extends HealthIndicator {
 
   async isHealthy(key: string): Promise<HealthIndicatorResult> {
     try {
+{{#IF_POSTGRES}}
       await this.prisma.$queryRaw`SELECT 1`;
+{{/IF_POSTGRES}}
+{{#IF_MONGO}}
+      // Prisma on MongoDB uses $runCommandRaw for ping or simple check
+      await this.prisma.$runCommandRaw({ ping: 1 });
+{{/IF_MONGO}}
       return this.getStatus(key, true);
     } catch (error) {
       throw new HealthCheckError('Database check failed', this.getStatus(key, false));

package/templates/postgres/src/main.ts

@@ -84,10 +84,19 @@ async function bootstrap() {
   const port = parseInt(process.env.PORT ?? '3000', 10);
   const httpServer = await app.listen(port);
 
+  const logger = app.get(Logger);
+  logger.log(`🚀 Application is running on: http://localhost:${port}`);
+  logger.log(`📖 API Documentation (Scalar): http://localhost:${port}/docs`);
+  logger.log(`📄 API Spec (JSON): http://localhost:${port}/docs/json`);
+
   process.on('SIGTERM', () => {
     loggerService.log('SIGTERM signal received: closing HTTP server');
     setTimeout(() => {
-      void otelSdk?.shutdown().catch(() => undefined);
+      if (process.env.OTEL_ENABLED === 'true') {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const otelSdk = require('./instrumentation').default;
+        void otelSdk?.shutdown().catch(() => undefined);
+      }
       httpServer.close(() => {
         loggerService.log('HTTP server closed');
         process.exit(0);

package/templates/postgres/src/shared/logger/pino.config.ts

@@ -1,6 +1,8 @@
 import { join } from 'path';
 import type { Params } from 'nestjs-pino';
+{{#IF_OTEL}}
 import { trace, context, isSpanContextValid } from '@opentelemetry/api';
+{{/IF_OTEL}}
 
 const isDev = process.env.NODE_ENV !== 'production';
 const LOG_DIR = join(process.cwd(), 'logs');
@@ -11,6 +13,7 @@ export const pinoConfig: Params = {
     level: isDev ? 'debug' : 'info',
     // Inject Trace context into every log line
     mixin() {
+{{#IF_OTEL}}
       const activeSpan = trace.getSpan(context.active());
       if (activeSpan) {
         const spanContext = activeSpan.spanContext();
@@ -22,6 +25,7 @@ export const pinoConfig: Params = {
           };
         }
       }
+{{/IF_OTEL}}
       return {};
     },
     // Standardize on X-Request-Id as the primary req.id