@tndhuy/create-app 1.0.0 → 1.2.2

package/dist/cli.js

@@ -26,6 +26,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // src/cli.ts
 var import_prompts = require("@clack/prompts");
 var import_path3 = require("path");
+var import_promises3 = require("fs/promises");
+var import_execa = require("execa");
 
 // src/scaffold.ts
 var import_promises2 = require("fs/promises");
@@ -38,6 +40,7 @@ function toPascalCase(kebab) {
 function buildReplacements(serviceName) {
   return [
     ["nestjs-backend-template", serviceName],
+    ["{{SERVICE_NAME_KEBAB}}", serviceName],
     ["NestjsBackendTemplate", toPascalCase(serviceName)]
   ];
 }
@@ -156,18 +159,48 @@ 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}}}`;
+          if (content2.includes(startTag)) {
+            if (flag) {
+              return 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");
+              return 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);
@@ -185,8 +218,8 @@ async function replaceFileContents(dir, replacements) {
 async function renamePathsWithPlaceholders(dir, replacements) {
   const allPaths = await collectPaths(dir);
   allPaths.sort((a, b) => {
-    const depthA = a.split("/").length;
-    const depthB = b.split("/").length;
+    const depthA = a.split(import_path2.sep).length;
+    const depthB = b.split(import_path2.sep).length;
     return depthB - depthA;
   });
   for (const oldPath of allPaths) {
@@ -214,17 +247,52 @@ 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) {
+          delete pkg.dependencies["@prisma/adapter-pg"];
+          delete pkg.dependencies["pg"];
+          delete pkg.dependencies["@types/pg"];
+          pkg.dependencies["@prisma/client"] = PRISMA_MONGO_COMPAT;
+        }
+        if (pkg.devDependencies) {
+          pkg.devDependencies["prisma"] = PRISMA_MONGO_COMPAT;
+        }
+      } else {
+        if (pkg.dependencies) {
+          delete pkg.dependencies["@prisma/client"];
+          delete pkg.dependencies["@prisma/adapter-pg"];
+          delete pkg.dependencies["pg"];
+          delete pkg.dependencies["@types/pg"];
+          pkg.dependencies["mongoose"] = "^8.0.0";
+          pkg.dependencies["@nestjs/mongoose"] = "^11.0.0";
+        }
+        if (pkg.devDependencies) {
+          delete pkg.devDependencies["prisma"];
+        }
+      }
+    } else {
       if (pkg.dependencies) {
-        delete pkg.dependencies["@prisma/client"];
-        delete pkg.dependencies["@prisma/adapter-pg"];
-        delete pkg.dependencies["pg"];
-        delete pkg.dependencies["@types/pg"];
-        pkg.dependencies["mongoose"] = "^8.0.0";
-        pkg.dependencies["@nestjs/mongoose"] = "^11.0.0";
+        pkg.dependencies["@prisma/client"] = PRISMA_LATEST;
+        pkg.dependencies["@prisma/adapter-pg"] = PRISMA_LATEST;
       }
       if (pkg.devDependencies) {
-        delete pkg.devDependencies["prisma"];
+        pkg.devDependencies["prisma"] = PRISMA_LATEST;
       }
     }
     if (options.modules.includes("kafka")) {
@@ -263,7 +331,8 @@ async function pathExists(p) {
 async function safeDeleteFile(destDir, filePath) {
   const resolved = (0, import_path2.resolve)(filePath);
   const resolvedDestDir = (0, import_path2.resolve)(destDir);
-  if (!resolved.startsWith(resolvedDestDir + "/") && resolved !== resolvedDestDir) {
+  const prefix = resolvedDestDir.endsWith(import_path2.sep) ? resolvedDestDir : resolvedDestDir + import_path2.sep;
+  if (!resolved.startsWith(prefix) && resolved !== resolvedDestDir) {
     throw new Error(`Security: path '${filePath}' is outside destDir '${destDir}'`);
   }
   try {
@@ -274,7 +343,8 @@ async function safeDeleteFile(destDir, filePath) {
 async function safeDeleteDir(destDir, dirPath) {
   const resolved = (0, import_path2.resolve)(dirPath);
   const resolvedDestDir = (0, import_path2.resolve)(destDir);
-  if (!resolved.startsWith(resolvedDestDir + "/") && resolved !== resolvedDestDir) {
+  const prefix = resolvedDestDir.endsWith(import_path2.sep) ? resolvedDestDir : resolvedDestDir + import_path2.sep;
+  if (!resolved.startsWith(prefix) && resolved !== resolvedDestDir) {
     throw new Error(`Security: path '${dirPath}' is outside destDir '${destDir}'`);
   }
   try {
@@ -367,8 +437,31 @@ 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
   ]);
+  const pinoConfigPath = (0, import_path2.join)(destDir, "src", "shared", "logger", "pino.config.ts");
+  if (await pathExists(pinoConfigPath)) {
+    await removeMatchingLines(pinoConfigPath, [
+      // Remove OTel imports
+      /^import\s*\{[^}]*trace[^}]*\}\s*from\s*['"]@opentelemetry\/api['"];\n?/m,
+      // Remove mixin block (more robust regex for multiline)
+      /^\s*mixin\(\)\s*\{[\s\S]*?\n\s*\},\n/m
+    ]);
+  }
+  const redisServicePath = (0, import_path2.join)(destDir, "src", "infrastructure", "cache", "redis.service.ts");
+  if (await pathExists(redisServicePath)) {
+    await removeMatchingLines(redisServicePath, [
+      /^import\s*\{[^}]*trace[^}]*\}\s*from\s*['"]@opentelemetry\/api['"];\n?/m,
+      // Remove tracing spans from methods
+      /^\s*const\s+span\s*=\s*trace\.getTracer[\s\S]*?span\.end\(\);\n/gm,
+      // Fallback: remove any remaining span.end() or span related lines
+      /^\s*span\.end\(\);\n/gm,
+      /^\s*const\s+span\s*=\s*trace\.getTracer.*\n/gm
+    ]);
+  }
+  await safeDeleteFile(destDir, (0, import_path2.join)(destDir, "prometheus.yml"));
 }
 async function addKafka(destDir, serviceName) {
   await generateKafkaModule(destDir, serviceName);
@@ -402,8 +495,8 @@ $1`
           /(imports:\s*\[[^\]]*?)(\s*\])/s,
           (match, arrayContent, closing) => {
             const trimmed = arrayContent.trimEnd();
-            const sep = trimmed.endsWith(",") ? "" : ",";
-            return `${trimmed}${sep}
+            const sep2 = trimmed.endsWith(",") ? "" : ",";
+            return `${trimmed}${sep2}
     KafkaModule,${closing}`;
           }
         );
@@ -425,13 +518,50 @@ $1`
   }
 }
 async function scaffold(options) {
-  const templateDir = (0, import_path2.join)(__dirname, "..", "templates", options.db);
-  const { destDir, serviceName, modules } = options;
+  const templateName = options.orm === "prisma" ? "postgres" : options.db;
+  const templateDir = (0, import_path2.join)(__dirname, "..", "templates", templateName);
+  const { destDir, serviceName, modules, dryRun } = options;
+  if (dryRun) {
+    console.log(`
+  [Dry Run] Would copy template from ${templateName} to ${destDir}`);
+    console.log(`  [Dry Run] Would replace placeholders for: ${serviceName}`);
+    console.log(`  [Dry Run] Would apply modules: ${modules.join(", ") || "none"}
+`);
+    return;
+  }
   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") {
+    const schemaPath = (0, import_path2.join)(destDir, "prisma", "schema.prisma");
+    if (await pathExists(schemaPath)) {
+      try {
+        let content = await (0, import_promises2.readFile)(schemaPath, "utf-8");
+        content = content.replace(/provider\s*=\s*["']postgresql["']/g, 'provider = "mongodb"');
+        content = content.replace(
+          /id\s+String\s+@id/g,
+          'id String @id @default(auto()) @map("_id") @db.ObjectId'
+        );
+        await (0, import_promises2.writeFile)(schemaPath, content, "utf-8");
+      } catch (err) {
+        console.warn("Warning: Could not update schema.prisma for MongoDB:", err);
+      }
+    }
+    const envPath = (0, import_path2.join)(destDir, ".env.example");
+    if (await pathExists(envPath)) {
+      try {
+        let content = await (0, import_promises2.readFile)(envPath, "utf-8");
+        content = content.replace(
+          /DATABASE_URL=postgresql:\/\/.*/g,
+          'DATABASE_URL="mongodb+srv://user:password@cluster.mongodb.net/myDatabase?retryWrites=true&w=majority"'
+        );
+        await (0, import_promises2.writeFile)(envPath, content, "utf-8");
+      } catch {
+      }
+    }
+  }
   if (!modules.includes("redis")) {
     await removeRedis(destDir);
   }
@@ -451,81 +581,224 @@ function guardCancel(value) {
   }
   return value;
 }
+async function directoryExists(p) {
+  try {
+    await (0, import_promises3.stat)(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function main() {
-  (0, import_prompts.intro)("create-app -- NestJS DDD scaffolder");
-  const argName = process.argv[2];
-  let serviceName;
-  if (argName && !validateServiceName(argName)) {
-    serviceName = argName;
-    console.log(`  Service name : ${serviceName} (from arguments)`);
-  } else {
-    serviceName = guardCancel(
-      await (0, import_prompts.text)({
-        message: "Service name (kebab-case)",
-        placeholder: "my-service",
-        validate: (v) => validateServiceName(v)
-      })
-    );
-  }
-  const db = guardCancel(
-    await (0, import_prompts.select)({
-      message: "Select database",
-      options: [
-        { value: "postgres", label: "PostgreSQL", hint: "default" },
-        { value: "mongo", label: "MongoDB" }
-      ]
-    })
-  );
-  const modules = guardCancel(
-    await (0, import_prompts.multiselect)({
-      message: "Optional modules (space to toggle, enter to confirm)",
-      options: [
-        { value: "redis", label: "Redis", hint: "caching + circuit breaker" },
-        { value: "otel", label: "OpenTelemetry", hint: "traces + metrics" },
-        { value: "kafka", label: "Kafka", hint: "message broker boilerplate" }
-      ],
-      required: false
-    })
-  );
-  const selectedModules = modules.length > 0 ? modules.join(", ") : "none";
-  console.log("");
-  console.log(`  Service name : ${serviceName}`);
-  console.log(`  Database     : ${db}`);
-  console.log(`  Modules      : ${selectedModules}`);
-  console.log("");
-  const proceed = guardCancel(
-    await (0, import_prompts.confirm)({
-      message: "Scaffold project with these settings?",
-      initialValue: true
-    })
-  );
-  if (!proceed) {
-    (0, import_prompts.cancel)("Scaffolding cancelled.");
-    process.exit(0);
+  const args = process.argv.slice(2);
+  const dryRun = args.includes("--dry-run");
+  const positionalName = args.find((a) => !a.startsWith("--"));
+  (0, import_prompts.intro)("create-app -- NestJS DDD scaffolder" + (dryRun ? " [DRY RUN]" : ""));
+  const config = {
+    serviceName: "",
+    db: "postgres",
+    orm: "mongoose",
+    modules: []
+  };
+  if (positionalName && !validateServiceName(positionalName)) {
+    config.serviceName = positionalName;
+    (0, import_prompts.note)(`Using service name: ${config.serviceName} (from arguments)`, "Info");
   }
-  const destDir = (0, import_path3.join)(process.cwd(), serviceName);
+  let step = config.serviceName ? 1 : 0;
+  const totalSteps = 4;
+  while (step < totalSteps) {
+    switch (step) {
+      case 0: {
+        const res = guardCancel(
+          await (0, import_prompts.text)({
+            message: "Service name (kebab-case)",
+            placeholder: "my-service",
+            validate: (v) => validateServiceName(v)
+          })
+        );
+        config.serviceName = res;
+        step++;
+        break;
+      }
+      case 1: {
+        const res = guardCancel(
+          await (0, import_prompts.select)({
+            message: "Select database",
+            options: [
+              { value: "postgres", label: "PostgreSQL", hint: "using Prisma" },
+              { value: "mongo", label: "MongoDB", hint: "choice of Mongoose or Prisma" },
+              { value: "_back", label: "Go Back", hint: "return to service name" }
+            ]
+          })
+        );
+        if (res === "_back") {
+          step--;
+        } else {
+          config.db = res;
+          if (res === "mongo") {
+            config.orm = guardCancel(
+              await (0, import_prompts.select)({
+                message: "Select MongoDB ORM",
+                options: [
+                  { value: "mongoose", label: "Mongoose", hint: "default for NestJS" },
+                  { value: "prisma", label: "Prisma", hint: "v6 compatible mode" }
+                ]
+              })
+            );
+          } else {
+            config.orm = "prisma";
+          }
+          step++;
+        }
+        break;
+      }
+      case 2: {
+        const res = guardCancel(
+          await (0, import_prompts.multiselect)({
+            message: "Optional modules (space to toggle, enter to confirm)",
+            options: [
+              { value: "redis", label: "Redis", hint: "caching + circuit breaker" },
+              { value: "otel", label: "OpenTelemetry", hint: "traces + metrics" },
+              { value: "kafka", label: "Kafka", hint: "message broker boilerplate" },
+              { value: "_back", label: "Go Back", hint: "return to database selection" }
+            ],
+            required: false
+          })
+        );
+        if (res.includes("_back")) {
+          step--;
+        } else {
+          config.modules = res;
+          step++;
+        }
+        break;
+      }
+      case 3: {
+        const selectedModules = config.modules.length > 0 ? config.modules.join(", ") : "none";
+        (0, import_prompts.note)(
+          `Service name : ${config.serviceName}
+Database     : ${config.db}
+ORM          : ${config.orm}
+Modules      : ${selectedModules}`,
+          "Confirm Project Summary"
+        );
+        const res = guardCancel(
+          await (0, import_prompts.select)({
+            message: "Scaffold project with these settings?",
+            options: [
+              { value: "confirm", label: "Yes, scaffold project" },
+              { value: "back", label: "No, let me change something", hint: "go back" },
+              { value: "cancel", label: "Cancel", hint: "exit" }
+            ]
+          })
+        );
+        if (res === "confirm") {
+          const destDir2 = (0, import_path3.join)(process.cwd(), config.serviceName);
+          if (await directoryExists(destDir2) && !dryRun) {
+            const overwrite = guardCancel(
+              await (0, import_prompts.select)({
+                message: `Directory "${config.serviceName}" already exists.`,
+                options: [
+                  { value: "overwrite", label: "Overwrite", hint: "danger: deletes existing directory" },
+                  { value: "back", label: "Change service name", hint: "go back to step 1" },
+                  { value: "cancel", label: "Exit", hint: "cancel" }
+                ]
+              })
+            );
+            if (overwrite === "overwrite") {
+              const confirmDelete = guardCancel(await (0, import_prompts.confirm)({ message: "Are you absolutely sure?", initialValue: false }));
+              if (confirmDelete) {
+                const s2 = (0, import_prompts.spinner)();
+                s2.start("Cleaning up existing directory...");
+                await (0, import_promises3.rm)(destDir2, { recursive: true, force: true });
+                s2.stop("Directory cleaned.");
+                step++;
+              }
+            } else if (overwrite === "back") {
+              step = 0;
+            } else {
+              (0, import_prompts.cancel)("Operation cancelled.");
+              process.exit(0);
+            }
+          } else {
+            step++;
+          }
+        } else if (res === "back") {
+          step--;
+        } else {
+          (0, import_prompts.cancel)("Scaffolding cancelled.");
+          process.exit(0);
+        }
+        break;
+      }
+    }
+  }
+  const destDir = (0, import_path3.join)(process.cwd(), config.serviceName);
   const s = (0, import_prompts.spinner)();
   s.start("Scaffolding project...");
   try {
     await scaffold({
-      serviceName,
-      db,
-      modules,
-      destDir
+      serviceName: config.serviceName,
+      db: config.db,
+      orm: config.orm,
+      modules: config.modules,
+      destDir,
+      dryRun
     });
     s.stop("Project scaffolded!");
   } catch (err) {
     s.stop("Scaffolding failed.");
     throw err;
   }
+  if (!dryRun) {
+    const initGit = guardCancel(await (0, import_prompts.confirm)({ message: "Initialize git repository?", initialValue: true }));
+    if (initGit) {
+      const gs = (0, import_prompts.spinner)();
+      gs.start("Initializing git...");
+      try {
+        await (0, import_execa.execa)("git", ["init"], { cwd: destDir });
+        await (0, import_execa.execa)("git", ["add", "."], { cwd: destDir });
+        await (0, import_execa.execa)("git", ["commit", "-m", "chore: initial commit from template"], { cwd: destDir });
+        gs.stop("Git initialized with initial commit.");
+      } catch (err) {
+        gs.stop("Git initialization failed (check if git is installed).");
+      }
+    }
+    const installDeps = guardCancel(await (0, import_prompts.confirm)({ message: "Install dependencies now?", initialValue: true }));
+    if (installDeps) {
+      const pkgManager = guardCancel(await (0, import_prompts.select)({
+        message: "Select package manager",
+        options: [
+          { value: "pnpm", label: "pnpm", hint: "recommended" },
+          { value: "npm", label: "npm" },
+          { value: "yarn", label: "yarn" }
+        ]
+      }));
+      const is = (0, import_prompts.spinner)();
+      is.start(`Installing dependencies using ${pkgManager}...`);
+      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:
 
-  cd ${serviceName}
-  npm install
-  cp .env.example .env
-  npm run start:dev
-`
+  cd ${config.serviceName}
+${dryRun ? "" : "  npm run start:dev\n"}`
   );
 }
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tndhuy/create-app",
-  "version": "1.0.0",
+  "version": "1.2.2",
   "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/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/main.ts

@@ -87,7 +87,11 @@ async function bootstrap() {
   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/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/package.json

@@ -4,10 +4,7 @@
   "description": "",
   "author": "",
   "private": true,
-  "license": "UNLICENSED",
-  "workspaces": [
-    "packages/*"
-  ],
+  "license": "MIT",
   "scripts": {
     "build": "nest build",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
@@ -63,7 +60,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/prisma/schema.prisma

@@ -4,6 +4,7 @@ generator client {
 
 datasource db {
   provider = "postgresql"
+  url      = env("DATABASE_URL")
 }
 
 model Item {

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/main.ts

@@ -87,7 +87,11 @@ async function bootstrap() {
   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);