@yoms/create-monorepo 1.1.0 → 2.0.0

package/dist/index.js

@@ -6,7 +6,9 @@ import { cac } from "cac";
 // src/commands/create.ts
 import path7 from "path";
 import ora from "ora";
+import chalk from "chalk";
 import { execa as execa2 } from "execa";
+import enquirer4 from "enquirer";
 
 // src/utils/file-ops.ts
 import fs from "fs-extra";
@@ -74,6 +76,15 @@ var logger = {
 
 // src/utils/package-manager.ts
 import { execa } from "execa";
+async function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent;
+  if (userAgent) {
+    if (userAgent.includes("pnpm")) return "pnpm";
+    if (userAgent.includes("yarn")) return "yarn";
+    if (userAgent.includes("bun")) return "bun";
+  }
+  return "pnpm";
+}
 async function installDependencies(cwd, pm) {
   await execa(pm, ["install"], { cwd, stdio: "inherit" });
 }
@@ -187,13 +198,24 @@ async function promptBackendConfig() {
     });
     includeSwagger = swagger;
   }
+  let includeAuth = false;
+  if (backendType === "web") {
+    const { auth } = await enquirer2.prompt({
+      type: "confirm",
+      name: "auth",
+      message: "Include JWT authentication?",
+      initial: false
+    });
+    includeAuth = auth;
+  }
   return {
     type: backendType,
     framework,
     database: database === "none" ? void 0 : database,
     includeRedis,
     includeSmtp,
-    includeSwagger
+    includeSwagger,
+    includeAuth
   };
 }
 
@@ -230,6 +252,7 @@ async function promptFrontendConfig() {
 
 // src/generators/monorepo.generator.ts
 import path2 from "path";
+import { fileURLToPath } from "url";
 
 // src/generators/base.generator.ts
 var BaseGenerator = class {
@@ -254,11 +277,19 @@ var BaseGenerator = class {
 };
 
 // src/generators/monorepo.generator.ts
+var __dirname = path2.dirname(fileURLToPath(import.meta.url));
+var getPackageRoot = () => {
+  const dirname = __dirname;
+  return path2.resolve(dirname, "..");
+};
 var MonorepoGenerator = class extends BaseGenerator {
   async generate(config) {
     await ensureDir(this.options.projectDir);
     await this.createRootFiles(config);
     await this.createPackagesDirectory();
+    if (config.includeDocker) {
+      await this.createDockerCompose(config);
+    }
   }
   async createRootFiles(config) {
     const workspaceContent = `packages:
@@ -393,11 +424,34 @@ ${config.includeBackend ? "\u2502   \u251C\u2500\u2500 api/         # Backend AP
   async createPackagesDirectory() {
     await ensureDir(path2.join(this.options.projectDir, "packages"));
   }
+  async createDockerCompose(config) {
+    const packageRoot = getPackageRoot();
+    const templatePath = path2.join(packageRoot, "templates", "docker-compose.yml");
+    const template = await readFile(templatePath);
+    const hasPostgres = config.backend?.database === "postgres";
+    const hasMongodb = config.backend?.database === "mongodb";
+    const hasRedis = config.backend?.includeRedis || false;
+    const hasSmtp = config.backend?.includeSmtp || false;
+    let content = template.split("\n").filter((line) => {
+      if (line.includes("__IF_POSTGRES__")) return hasPostgres;
+      if (line.includes("__IF_MONGODB__")) return hasMongodb;
+      if (line.includes("__IF_REDIS__")) return hasRedis;
+      if (line.includes("__IF_SMTP__")) return hasSmtp;
+      return true;
+    }).map((line) => {
+      return line.replace(/__IF_POSTGRES__/g, "").replace(/__IF_MONGODB__/g, "").replace(/__IF_REDIS__/g, "").replace(/__IF_SMTP__/g, "");
+    }).join("\n");
+    const tokens = this.getTokens();
+    for (const [token, value] of Object.entries(tokens)) {
+      content = content.replace(new RegExp(token, "g"), value);
+    }
+    await writeFile(path2.join(this.options.projectDir, "docker-compose.yml"), content);
+  }
 };
 
 // src/generators/backend.generator.ts
 import path4 from "path";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/utils/template-merger.ts
 import fs2 from "fs-extra";
@@ -459,9 +513,9 @@ async function mergeEnvFile(baseDir, additionsPath) {
 }
 
 // src/generators/backend.generator.ts
-var __dirname = path4.dirname(fileURLToPath(import.meta.url));
-var getPackageRoot = () => {
-  const dirname = __dirname;
+var __dirname2 = path4.dirname(fileURLToPath2(import.meta.url));
+var getPackageRoot2 = () => {
+  const dirname = __dirname2;
   return path4.resolve(dirname, "..");
 };
 var BackendGenerator = class extends BaseGenerator {
@@ -479,7 +533,7 @@ var BackendGenerator = class extends BaseGenerator {
       __HAS_REDIS__: String(this.config.includeRedis),
       __HAS_SMTP__: String(this.config.includeSmtp)
     });
-    const packageRoot = getPackageRoot();
+    const packageRoot = getPackageRoot2();
     let templatePath;
     if (this.config.type === "web") {
       templatePath = path4.join(packageRoot, "templates", `backend-${this.config.framework}`, "base");
@@ -507,16 +561,20 @@ var BackendGenerator = class extends BaseGenerator {
         const swaggerFeaturePath = path4.join(featuresPath, "swagger");
         await mergeFeature(backendDir, swaggerFeaturePath, tokens);
       }
+      if (this.config.includeAuth) {
+        const authFeaturePath = path4.join(featuresPath, "jwt-auth");
+        await mergeFeature(backendDir, authFeaturePath, tokens);
+      }
     }
   }
 };
 
 // src/generators/frontend.generator.ts
 import path5 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
-var getPackageRoot2 = () => {
-  const dirname = __dirname2;
+import { fileURLToPath as fileURLToPath3 } from "url";
+var __dirname3 = path5.dirname(fileURLToPath3(import.meta.url));
+var getPackageRoot3 = () => {
+  const dirname = __dirname3;
   return path5.resolve(dirname, "..");
 };
 var FrontendGenerator = class extends BaseGenerator {
@@ -531,7 +589,7 @@ var FrontendGenerator = class extends BaseGenerator {
     const tokens = this.getTokens({
       __API_URL__: this.config.apiUrl
     });
-    const packageRoot = getPackageRoot2();
+    const packageRoot = getPackageRoot3();
     const templatePath = path5.join(packageRoot, "templates", "frontend-nextjs", "base");
     await copyDirRecursive(templatePath, frontendDir, tokens);
   }
@@ -539,10 +597,10 @@ var FrontendGenerator = class extends BaseGenerator {
 
 // src/generators/shared.generator.ts
 import path6 from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
-var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
-var getPackageRoot3 = () => {
-  const dirname = __dirname3;
+import { fileURLToPath as fileURLToPath4 } from "url";
+var __dirname4 = path6.dirname(fileURLToPath4(import.meta.url));
+var getPackageRoot4 = () => {
+  const dirname = __dirname4;
   return path6.resolve(dirname, "..");
 };
 var SharedGenerator = class extends BaseGenerator {
@@ -550,57 +608,151 @@ var SharedGenerator = class extends BaseGenerator {
     const sharedDir = path6.join(this.options.projectDir, "packages", "shared");
     await ensureDir(sharedDir);
     const tokens = this.getTokens();
-    const packageRoot = getPackageRoot3();
+    const packageRoot = getPackageRoot4();
     const templatePath = path6.join(packageRoot, "templates", "shared", "base");
     await copyDirRecursive(templatePath, sharedDir, tokens);
   }
 };
 
 // src/commands/create.ts
-async function createMonorepo(targetDir) {
+function showPreview(config) {
   console.log("");
-  logger.info("Welcome to create-monorepo!");
+  console.log(chalk.bold("\u{1F4E6} Project Preview:"));
   console.log("");
-  const projectName = await promptProjectName(targetDir ? path7.basename(targetDir) : void 0);
-  const projectDir = path7.resolve(process.cwd(), targetDir || projectName);
-  if (!await isDirEmpty(projectDir)) {
-    logger.error(`Directory "${projectDir}" is not empty. Please choose an empty directory.`);
-    process.exit(1);
+  console.log(chalk.cyan(`${config.projectName}/`));
+  console.log(chalk.gray("\u251C\u2500\u2500 packages/"));
+  if (config.includeBackend && config.backend) {
+    const features = [];
+    if (config.backend.database) features.push(config.backend.database.toUpperCase());
+    if (config.backend.includeRedis) features.push("Redis");
+    if (config.backend.includeSmtp) features.push("SMTP");
+    if (config.backend.includeSwagger) features.push("Swagger");
+    if (config.backend.includeAuth) features.push("JWT Auth");
+    const featureStr = features.length > 0 ? chalk.gray(` (${features.join(", ")})`) : "";
+    console.log(chalk.gray(`\u2502   \u251C\u2500\u2500 api/`) + chalk.yellow(` ${config.backend.framework}`) + featureStr);
   }
-  const packageManager = await promptPackageManager();
-  const includeBackend = await promptIncludeBackend();
-  const includeFrontend = await promptIncludeFrontend();
-  if (!includeBackend && !includeFrontend) {
-    logger.error("You must include at least one package (backend or frontend).");
-    process.exit(1);
+  if (config.includeFrontend && config.frontend) {
+    const features = [];
+    if (config.frontend.includeShadcn) features.push("shadcn/ui");
+    const featureStr = features.length > 0 ? chalk.gray(` (${features.join(", ")})`) : "";
+    console.log(chalk.gray(`\u2502   \u251C\u2500\u2500 web/`) + chalk.yellow(` Next.js 15`) + featureStr);
   }
-  const config = {
-    projectName,
-    packageManager,
-    includeBackend,
-    includeFrontend
-  };
-  if (includeBackend) {
-    console.log("");
-    logger.info("Configure backend package:");
-    config.backend = await promptBackendConfig();
+  if (config.includeBackend && config.includeFrontend) {
+    console.log(chalk.gray(`\u2502   \u2514\u2500\u2500 shared/`) + chalk.yellow(` Zod schemas + types`));
   }
-  if (includeFrontend) {
-    console.log("");
-    logger.info("Configure frontend package:");
-    config.frontend = await promptFrontendConfig();
+  console.log(chalk.gray("\u251C\u2500\u2500 pnpm-workspace.yaml"));
+  console.log(chalk.gray("\u251C\u2500\u2500 package.json"));
+  if (config.includeDocker) {
+    console.log(chalk.gray("\u251C\u2500\u2500 docker-compose.yml") + chalk.yellow(" \u26A1"));
   }
+  console.log(chalk.gray("\u2514\u2500\u2500 ..."));
+  console.log("");
+}
+async function confirmPreview() {
+  const { confirm } = await enquirer4.prompt({
+    type: "confirm",
+    name: "confirm",
+    message: "Does this look good?",
+    initial: true
+  });
+  return confirm;
+}
+async function createMonorepo(targetDir, options = {}) {
   console.log("");
-  logger.info("Generating project...");
+  logger.info("Welcome to create-monorepo!");
+  console.log("");
+  const isInteractive = !options.yes && process.stdin.isTTY;
   try {
+    const projectName = isInteractive ? await promptProjectName(targetDir ? path7.basename(targetDir) : void 0) : targetDir ? path7.basename(targetDir) : "my-monorepo";
+    const projectDir = path7.resolve(process.cwd(), targetDir || projectName);
+    if (!await isDirEmpty(projectDir)) {
+      throw new Error(`Directory "${projectDir}" is not empty. Please choose an empty directory.`);
+    }
+    let packageManager;
+    if (options.pm) {
+      packageManager = options.pm;
+    } else if (isInteractive) {
+      packageManager = await promptPackageManager();
+    } else {
+      packageManager = await detectPackageManager();
+    }
+    let includeBackend;
+    let includeFrontend;
+    if (options.yes) {
+      includeBackend = options.backend !== void 0 || options.database !== void 0;
+      includeFrontend = options.frontend === true;
+      if (!includeBackend && !includeFrontend) {
+        includeBackend = true;
+        includeFrontend = true;
+      }
+    } else if (isInteractive) {
+      includeBackend = await promptIncludeBackend();
+      includeFrontend = await promptIncludeFrontend();
+    } else {
+      includeBackend = true;
+      includeFrontend = true;
+    }
+    if (!includeBackend && !includeFrontend) {
+      throw new Error("You must include at least one package (backend or frontend).");
+    }
+    const config = {
+      projectName,
+      packageManager,
+      includeBackend,
+      includeFrontend,
+      includeDocker: options.docker
+    };
+    if (includeBackend) {
+      if (options.yes || !isInteractive) {
+        config.backend = {
+          type: "web",
+          framework: options.backend || "hono",
+          database: options.database,
+          includeRedis: options.redis || false,
+          includeSmtp: options.smtp || false,
+          includeSwagger: options.swagger || false,
+          includeAuth: options.auth || false
+        };
+      } else {
+        console.log("");
+        logger.info("Configure backend package:");
+        config.backend = await promptBackendConfig();
+      }
+    }
+    if (includeFrontend) {
+      if (options.yes || !isInteractive) {
+        config.frontend = {
+          framework: "nextjs",
+          includeShadcn: options.shadcn || false,
+          apiUrl: "http://localhost:3001"
+        };
+      } else {
+        console.log("");
+        logger.info("Configure frontend package:");
+        config.frontend = await promptFrontendConfig();
+      }
+    }
+    if (isInteractive) {
+      showPreview(config);
+      const confirmed = await confirmPreview();
+      if (!confirmed) {
+        console.log("");
+        logger.info("Cancelled. No files were created.");
+        return;
+      }
+    }
+    console.log("");
+    logger.info("Generating project...");
+    console.log("");
+    const spinner = ora();
+    spinner.start("Creating monorepo structure...");
     const monorepoGenerator = new MonorepoGenerator({
       projectName,
       projectDir,
       packageManager
     });
-    const spinner = ora("Creating monorepo structure...").start();
     await monorepoGenerator.generate(config);
-    spinner.succeed("Monorepo structure created");
+    spinner.succeed(chalk.green("Monorepo structure created"));
     if (includeBackend && includeFrontend) {
       spinner.start("Generating shared package...");
       const sharedGenerator = new SharedGenerator({
@@ -609,7 +761,7 @@ async function createMonorepo(targetDir) {
         packageManager
       });
       await sharedGenerator.generate();
-      spinner.succeed("Shared package generated");
+      spinner.succeed(chalk.green("Shared package generated"));
     }
     if (includeBackend && config.backend) {
       spinner.start("Generating backend package...");
@@ -620,7 +772,7 @@ async function createMonorepo(targetDir) {
         config: config.backend
       });
       await backendGenerator.generate();
-      spinner.succeed("Backend package generated");
+      spinner.succeed(chalk.green(`Backend package generated (${config.backend.framework})`));
     }
     if (includeFrontend && config.frontend) {
       spinner.start("Generating frontend package...");
@@ -631,34 +783,61 @@ async function createMonorepo(targetDir) {
         config: config.frontend
       });
       await frontendGenerator.generate();
-      spinner.succeed("Frontend package generated");
+      spinner.succeed(chalk.green("Frontend package generated (Next.js 15)"));
+    }
+    if (!options.skipInstall) {
+      spinner.start(`Installing dependencies with ${packageManager}...`);
+      spinner.text = `Installing dependencies... ${chalk.gray("(this may take a minute)")}`;
+      await installDependencies(projectDir, packageManager);
+      spinner.succeed(chalk.green("Dependencies installed"));
+    } else {
+      logger.info(chalk.yellow("\u26A0 Skipped dependency installation"));
+    }
+    if (!options.skipGit) {
+      spinner.start("Initializing git repository...");
+      await execa2("git", ["init"], { cwd: projectDir });
+      await execa2("git", ["add", "."], { cwd: projectDir });
+      await execa2("git", ["commit", "-m", "Initial commit from create-monorepo"], { cwd: projectDir });
+      spinner.succeed(chalk.green("Git repository initialized"));
+    } else {
+      logger.info(chalk.yellow("\u26A0 Skipped git initialization"));
     }
-    spinner.start("Installing dependencies...");
-    await installDependencies(projectDir, packageManager);
-    spinner.succeed("Dependencies installed");
-    spinner.start("Initializing git repository...");
-    await execa2("git", ["init"], { cwd: projectDir });
-    await execa2("git", ["add", "."], { cwd: projectDir });
-    await execa2("git", ["commit", "-m", "Initial commit from create-monorepo"], { cwd: projectDir });
-    spinner.succeed("Git repository initialized");
     console.log("");
-    logger.success(`Project "${projectName}" created successfully!`);
+    logger.success(`${chalk.bold('\u2728 Project "')}${chalk.bold.cyan(projectName)}${chalk.bold('" created successfully!')}`);
     console.log("");
-    logger.info("Next steps:");
-    console.log(`  cd ${targetDir || projectName}`);
-    console.log(`  ${packageManager} dev`);
+    logger.info(chalk.bold("Next steps:"));
+    console.log(chalk.gray("  $ ") + chalk.cyan(`cd ${targetDir || projectName}`));
+    if (options.skipInstall) {
+      console.log(chalk.gray("  $ ") + chalk.cyan(`${packageManager} install`));
+    }
+    console.log(chalk.gray("  $ ") + chalk.cyan(`${packageManager} dev`));
     console.log("");
+    if (config.includeDocker) {
+      logger.info(chalk.bold("\u{1F433} Docker Compose:"));
+      console.log(chalk.gray("  $ ") + chalk.cyan("docker-compose up -d"));
+      console.log("");
+    }
   } catch (error) {
-    logger.error(`Failed to create project: ${error instanceof Error ? error.message : String(error)}`);
+    console.log("");
+    if (error instanceof Error) {
+      logger.error(chalk.red(`\u2716 ${error.message}`));
+      if (error.stack && process.env.DEBUG) {
+        console.log("");
+        console.log(chalk.gray(error.stack));
+      }
+    } else {
+      logger.error(chalk.red(`\u2716 Failed to create project: ${String(error)}`));
+    }
+    console.log("");
     process.exit(1);
   }
 }
 
 // src/index.ts
 var cli = cac("create-monorepo");
-cli.command("[dir]", "Create a brand new monorepo project").action(async (dir) => {
-  await createMonorepo(dir);
+cli.command("[dir]", "Create a new monorepo project").option("--backend <framework>", "Backend framework (hono)").option("--database <db>", "Database (postgres, mongodb, none)").option("--redis", "Include Redis cache").option("--smtp", "Include SMTP email").option("--swagger", "Include Swagger docs").option("--auth", "Include JWT authentication").option("--frontend", "Include Next.js frontend").option("--shadcn", "Include shadcn/ui components").option("--pm <manager>", "Package manager (pnpm, npm, yarn, bun)").option("--docker", "Include Docker Compose setup").option("--skip-install", "Skip dependency installation").option("--skip-git", "Skip git initialization").option("-y, --yes", "Skip all prompts and use defaults").action(async (dir, options) => {
+  await createMonorepo(dir, options);
 });
 cli.help();
-cli.version("0.1.0");
+cli.version("1.2.0");
 cli.parse();

package/package.json

@@ -1,24 +1,11 @@
 {
   "name": "@yoms/create-monorepo",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "CLI tool to scaffold monorepo projects from templates",
   "type": "module",
   "bin": {
     "create-monorepo": "./dist/index.js"
   },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "build": "tsup src/index.ts --format esm --clean",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "test:generate": "tsx scripts/test-generate.ts",
-    "test:validate": "tsx scripts/validate-templates.ts",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "release": "pnpm build && changeset publish",
-    "prepublishOnly": "pnpm build && pnpm typecheck"
-  },
   "keywords": [
     "monorepo",
     "template",
@@ -66,9 +53,25 @@
     "prettier": "^3.4.2",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup src/index.ts --format esm --clean",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run tests/e2e",
+    "test:generate": "tsx scripts/test-generate.ts",
+    "test:validate": "tsx scripts/validate-templates.ts",
+    "changeset": "changeset",
+    "version": "changeset version && pnpm install --lockfile-only",
+    "release": "pnpm build && changeset publish"
   }
-}
+}

package/templates/backend-hono/base/AGENT.md

@@ -0,0 +1,326 @@
+# AGENT.md - Backend API
+
+This file provides guidance to AI agents (Claude, Cursor, etc.) when working with this backend API.
+
+## Project Overview
+
+This is a Hono-based backend API in a monorepo workspace. It's designed for high performance, full type safety, and production-ready patterns.
+
+## Tech Stack
+
+- **Framework**: Hono (lightweight, fast, type-safe)
+- **Language**: TypeScript with strict mode
+- **Runtime**: Node.js (compatible with Bun, Deno, Cloudflare Workers)
+- **Validation**: Zod schemas
+- **Logger**: Winston with structured logging
+- **Build Tool**: tsup (fast ESM bundler)
+- **Testing**: Vitest with coverage
+
+## Development Commands
+
+```bash
+# Development
+pnpm dev              # Start with hot reload
+pnpm build            # Build for production
+pnpm start            # Run production build
+pnpm test             # Run tests
+pnpm test:watch       # Watch mode
+pnpm test:coverage    # Coverage report
+pnpm typecheck        # Type checking
+```
+
+## Project Structure
+
+```
+src/
+├── config/           # Configuration (env, logger, db)
+├── lib/              # Utilities and helpers
+│   ├── errors.ts     # Custom error classes
+│   └── response.ts   # Response helpers
+├── middleware/       # Hono middleware
+│   ├── cors.middleware.ts
+│   ├── error.middleware.ts
+│   ├── logger.middleware.ts
+│   └── rate-limit.middleware.ts
+├── routes/           # API route handlers
+│   └── health.route.ts
+├── services/         # Business logic (if database enabled)
+├── types/            # TypeScript types
+└── index.ts          # App entry point
+```
+
+## Architecture Patterns
+
+### Error Handling
+
+Use custom error classes for consistent error responses:
+
+```typescript
+import { NotFoundError, BadRequestError } from '../lib/errors.js';
+
+// Throw custom errors - they're automatically handled
+throw new NotFoundError('User not found');
+throw new BadRequestError('Invalid email format');
+```
+
+Available errors:
+- `BadRequestError` (400)
+- `UnauthorizedError` (401)
+- `ForbiddenError` (403)
+- `NotFoundError` (404)
+- `ConflictError` (409)
+- `ValidationError` (422)
+- `TooManyRequestsError` (429)
+- `InternalServerError` (500)
+
+### Response Helpers
+
+Use standardized response helpers:
+
+```typescript
+import { success, created, noContent, paginated } from '../lib/response.js';
+
+// Success response (200)
+return success(c, { id: '123', name: 'John' });
+
+// Created response (201)
+return created(c, newUser);
+
+// No content (204)
+return noContent(c);
+
+// Paginated response
+return paginated(c, users, page, limit, total);
+```
+
+### Route Structure
+
+Follow this pattern for new routes:
+
+```typescript
+import { Hono } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+import { success } from '../lib/response.js';
+import { CreateItemSchema } from '@__PROJECT_NAME__/shared';
+
+const items = new Hono();
+
+// List items with pagination
+items.get('/', zValidator('query', paginationSchema), async (c) => {
+  const { page, limit } = c.req.valid('query');
+  const result = await ItemService.getAll(page, limit);
+  return paginated(c, result.items, page, limit, result.total);
+});
+
+// Get by ID
+items.get('/:id', async (c) => {
+  const id = c.req.param('id');
+  const item = await ItemService.getById(id);
+  return success(c, item);
+});
+
+// Create
+items.post('/', zValidator('json', CreateItemSchema), async (c) => {
+  const data = c.req.valid('json');
+  const item = await ItemService.create(data);
+  return created(c, item);
+});
+
+export { items };
+```
+
+### Service Layer Pattern
+
+Create services for business logic:
+
+```typescript
+import { prisma } from '../config/database.js';
+import { NotFoundError, ConflictError } from '../lib/errors.js';
+
+export class ItemService {
+  static async getAll(page = 1, limit = 10) {
+    const skip = (page - 1) * limit;
+    const [items, total] = await Promise.all([
+      prisma.item.findMany({ skip, take: limit }),
+      prisma.item.count(),
+    ]);
+    return { items, total, page, limit };
+  }
+
+  static async getById(id: string) {
+    const item = await prisma.item.findUnique({ where: { id } });
+    if (!item) throw new NotFoundError(`Item ${id} not found`);
+    return item;
+  }
+
+  static async create(data: CreateItem) {
+    // Check for duplicates
+    const existing = await prisma.item.findUnique({ where: { name: data.name } });
+    if (existing) throw new ConflictError('Item already exists');
+
+    return prisma.item.create({ data });
+  }
+}
+```
+
+### Environment Variables
+
+All env vars are validated with Zod in `src/config/env.ts`. Add new variables:
+
+```typescript
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(3001),
+  // Add your vars here
+  NEW_VAR: z.string().min(1),
+});
+```
+
+### Rate Limiting
+
+Apply rate limiting to routes:
+
+```typescript
+import { rateLimits } from '../middleware/rate-limit.middleware.js';
+
+// Use preset limits
+app.use('/api/*', rateLimits.standard); // 100 req/min
+
+// Custom limit
+app.use('/auth/login', rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5,
+  message: 'Too many login attempts',
+}));
+```
+
+### Testing
+
+Write tests for all routes and services:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { Hono } from 'hono';
+import { items } from '../items.route.js';
+
+describe('Items Route', () => {
+  const app = new Hono();
+  app.route('/items', items);
+
+  it('should list items', async () => {
+    const res = await app.request('/items?page=1&limit=10');
+    expect(res.status).toBe(200);
+
+    const json = await res.json();
+    expect(json.success).toBe(true);
+    expect(json.data).toBeInstanceOf(Array);
+    expect(json.pagination).toBeDefined();
+  });
+});
+```
+
+## Database (if enabled)
+
+### Prisma Commands
+
+```bash
+pnpm prisma:generate   # Generate Prisma client
+pnpm prisma:migrate    # Create and run migrations
+pnpm prisma:studio     # Open Prisma Studio UI
+pnpm prisma:push       # Push schema to database
+```
+
+### Creating Migrations
+
+```bash
+# After editing schema.prisma
+pnpm prisma:migrate
+# Enter migration name when prompted
+```
+
+## Type Sharing
+
+Import shared types from the shared package:
+
+```typescript
+import { User, CreateUser, UpdateUser } from '@__PROJECT_NAME__/shared';
+import { UserSchema } from '@__PROJECT_NAME__/shared';
+
+// Use schemas for validation
+const result = UserSchema.parse(data);
+
+// Use types for type safety
+const user: User = await getUser(id);
+```
+
+## Best Practices
+
+### DO:
+- ✅ Use custom error classes, not raw `throw new Error()`
+- ✅ Use response helpers for all routes
+- ✅ Validate all input with Zod schemas
+- ✅ Put business logic in services, not routes
+- ✅ Write tests for new features
+- ✅ Use type-safe imports from shared package
+- ✅ Log important operations with structured logging
+- ✅ Handle async operations properly with try/catch
+
+### DON'T:
+- ❌ Don't return raw `c.json()` - use response helpers
+- ❌ Don't put business logic in routes - use services
+- ❌ Don't use `any` type - maintain type safety
+- ❌ Don't skip validation - always validate input
+- ❌ Don't commit `.env` files - use `.env.example`
+- ❌ Don't use blocking operations in async handlers
+- ❌ Don't modify shared types here - edit in `packages/shared`
+
+## Common Tasks
+
+### Adding a New Route
+
+1. Create route file in `src/routes/`
+2. Create service in `src/services/` (if needed)
+3. Add validation schemas in `packages/shared/src/schemas/`
+4. Register route in `src/index.ts`
+5. Write tests in `src/routes/__tests__/`
+
+### Adding Middleware
+
+1. Create in `src/middleware/`
+2. Export middleware function
+3. Apply in `src/index.ts` with `app.use()`
+
+### Adding Environment Variables
+
+1. Add to `.env.example`
+2. Add to `src/config/env.ts` schema
+3. Use via `env.YOUR_VAR`
+
+## Debugging
+
+```typescript
+// Use structured logging
+import { logger } from './config/logger.js';
+
+logger.info('User logged in', { userId: user.id });
+logger.warn('Rate limit approaching', { ip, count });
+logger.error('Database error', { error, query });
+```
+
+## Performance Tips
+
+- Use database indexes for frequently queried fields
+- Use pagination for list endpoints
+- Cache expensive operations with Redis (if enabled)
+- Use `prisma.$transaction()` for multiple related operations
+- Profile with `pnpm test:coverage` to find slow tests
+
+## Security Checklist
+
+- [ ] All inputs are validated with Zod
+- [ ] Rate limiting is applied to auth endpoints
+- [ ] Sensitive data is not logged
+- [ ] Database queries use parameterized queries (Prisma does this)
+- [ ] CORS is configured correctly
+- [ ] Environment variables are validated on startup
+- [ ] Error messages don't leak sensitive info in production

package/templates/backend-hono/features/jwt-auth/env-additions.txt

@@ -0,0 +1,5 @@
+# JWT Configuration
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+JWT_EXPIRES_IN=15m
+JWT_REFRESH_SECRET=your-super-secret-refresh-key-change-this-in-production
+JWT_REFRESH_EXPIRES_IN=7d

package/templates/backend-hono/features/jwt-auth/package-additions.json

@@ -0,0 +1,10 @@
+{
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2",
+    "bcryptjs": "^2.4.3"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.7",
+    "@types/bcryptjs": "^2.4.6"
+  }
+}

package/templates/backend-hono/features/jwt-auth/src/config/env-additions.ts

@@ -0,0 +1,16 @@
+// Add these to your env schema validation
+
+import { z } from 'zod';
+
+export const jwtEnvSchema = z.object({
+  JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 characters'),
+  JWT_EXPIRES_IN: z.string().default('15m'),
+  JWT_REFRESH_SECRET: z.string().min(32, 'JWT_REFRESH_SECRET must be at least 32 characters'),
+  JWT_REFRESH_EXPIRES_IN: z.string().default('7d'),
+});
+
+// Merge this with your existing env schema:
+// const envSchema = z.object({
+//   ...existingFields,
+//   ...jwtEnvSchema.shape,
+// });

package/templates/backend-hono/features/jwt-auth/src/lib/jwt.ts

@@ -0,0 +1,75 @@
+import jwt from 'jsonwebtoken';
+import { env } from '../config/env.js';
+import { UnauthorizedError } from '../lib/errors.js';
+
+export interface JwtPayload {
+  userId: string;
+  email: string;
+  type: 'access' | 'refresh';
+}
+
+export interface TokenPair {
+  accessToken: string;
+  refreshToken: string;
+}
+
+/**
+ * Generate access and refresh tokens for a user
+ */
+export function generateTokens(userId: string, email: string): TokenPair {
+  const accessToken = jwt.sign(
+    { userId, email, type: 'access' } as JwtPayload,
+    env.JWT_SECRET,
+    { expiresIn: env.JWT_EXPIRES_IN }
+  );
+
+  const refreshToken = jwt.sign(
+    { userId, email, type: 'refresh' } as JwtPayload,
+    env.JWT_REFRESH_SECRET,
+    { expiresIn: env.JWT_REFRESH_EXPIRES_IN }
+  );
+
+  return { accessToken, refreshToken };
+}
+
+/**
+ * Verify and decode an access token
+ */
+export function verifyAccessToken(token: string): JwtPayload {
+  try {
+    const decoded = jwt.verify(token, env.JWT_SECRET) as JwtPayload;
+    if (decoded.type !== 'access') {
+      throw new UnauthorizedError('Invalid token type');
+    }
+    return decoded;
+  } catch (error) {
+    if (error instanceof jwt.TokenExpiredError) {
+      throw new UnauthorizedError('Token expired');
+    }
+    if (error instanceof jwt.JsonWebTokenError) {
+      throw new UnauthorizedError('Invalid token');
+    }
+    throw error;
+  }
+}
+
+/**
+ * Verify and decode a refresh token
+ */
+export function verifyRefreshToken(token: string): JwtPayload {
+  try {
+    const decoded = jwt.verify(token, env.JWT_REFRESH_SECRET) as JwtPayload;
+    if (decoded.type !== 'refresh') {
+      throw new UnauthorizedError('Invalid token type');
+    }
+    return decoded;
+  } catch (error) {
+    if (error instanceof jwt.TokenExpiredError) {
+      throw new UnauthorizedError('Refresh token expired');
+    }
+    if (error instanceof jwt.JsonWebTokenError) {
+      throw new UnauthorizedError('Invalid refresh token');
+    }
+    throw error;
+  }
+}

package/templates/backend-hono/features/jwt-auth/src/middleware/auth.middleware.ts

@@ -0,0 +1,50 @@
+import type { Context, Next } from 'hono';
+import { verifyAccessToken } from '../lib/jwt.js';
+import { UnauthorizedError } from '../lib/errors.js';
+
+/**
+ * Middleware to authenticate requests using JWT
+ * Extracts and verifies the JWT token from the Authorization header
+ * and attaches the decoded payload to c.get('jwtPayload')
+ */
+export async function authMiddleware(c: Context, next: Next): Promise<void> {
+  const authHeader = c.req.header('Authorization');
+
+  if (!authHeader) {
+    throw new UnauthorizedError('No authorization header');
+  }
+
+  const [type, token] = authHeader.split(' ');
+
+  if (type !== 'Bearer' || !token) {
+    throw new UnauthorizedError('Invalid authorization header format');
+  }
+
+  const payload = verifyAccessToken(token);
+  c.set('jwtPayload', payload);
+
+  await next();
+}
+
+/**
+ * Optional authentication middleware
+ * Similar to authMiddleware but doesn't throw if no token is present
+ * Use this for routes that work for both authenticated and unauthenticated users
+ */
+export async function optionalAuthMiddleware(c: Context, next: Next): Promise<void> {
+  const authHeader = c.req.header('Authorization');
+
+  if (authHeader) {
+    try {
+      const [type, token] = authHeader.split(' ');
+      if (type === 'Bearer' && token) {
+        const payload = verifyAccessToken(token);
+        c.set('jwtPayload', payload);
+      }
+    } catch {
+      // Silently ignore invalid tokens for optional auth
+    }
+  }
+
+  await next();
+}

package/templates/backend-hono/features/jwt-auth/src/routes/auth.route.ts

@@ -0,0 +1,157 @@
+import { Hono } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+import { z } from 'zod';
+import bcrypt from 'bcryptjs';
+import { generateTokens, verifyRefreshToken } from '../lib/jwt.js';
+import { success, created } from '../lib/response.js';
+import { UnauthorizedError, ConflictError } from '../lib/errors.js';
+
+// NOTE: This is a basic example. In a real application, you would:
+// 1. Store users in a database
+// 2. Store refresh tokens in a database or Redis for invalidation
+// 3. Add email verification
+// 4. Add password reset functionality
+// 5. Add rate limiting on auth endpoints
+// 6. Add account lockout after failed attempts
+
+const auth = new Hono();
+
+// Validation schemas
+const registerSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+  name: z.string().min(1),
+});
+
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string(),
+});
+
+const refreshSchema = z.object({
+  refreshToken: z.string(),
+});
+
+// In-memory user store (replace with database in production)
+interface User {
+  id: string;
+  email: string;
+  password: string;
+  name: string;
+  createdAt: Date;
+}
+
+const users: Map<string, User> = new Map();
+
+/**
+ * POST /auth/register
+ * Register a new user
+ */
+auth.post('/register', zValidator('json', registerSchema), async (c) => {
+  const { email, password, name } = c.req.valid('json');
+
+  // Check if user already exists
+  const existingUser = Array.from(users.values()).find((u) => u.email === email);
+  if (existingUser) {
+    throw new ConflictError('User with this email already exists');
+  }
+
+  // Hash password
+  const hashedPassword = await bcrypt.hash(password, 10);
+
+  // Create user
+  const userId = crypto.randomUUID();
+  const user: User = {
+    id: userId,
+    email,
+    password: hashedPassword,
+    name,
+    createdAt: new Date(),
+  };
+
+  users.set(userId, user);
+
+  // Generate tokens
+  const tokens = generateTokens(userId, email);
+
+  return created(c, {
+    user: {
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      createdAt: user.createdAt,
+    },
+    ...tokens,
+  });
+});
+
+/**
+ * POST /auth/login
+ * Login with email and password
+ */
+auth.post('/login', zValidator('json', loginSchema), async (c) => {
+  const { email, password } = c.req.valid('json');
+
+  // Find user
+  const user = Array.from(users.values()).find((u) => u.email === email);
+  if (!user) {
+    throw new UnauthorizedError('Invalid email or password');
+  }
+
+  // Verify password
+  const isValidPassword = await bcrypt.compare(password, user.password);
+  if (!isValidPassword) {
+    throw new UnauthorizedError('Invalid email or password');
+  }
+
+  // Generate tokens
+  const tokens = generateTokens(user.id, user.email);
+
+  return success(c, {
+    user: {
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      createdAt: user.createdAt,
+    },
+    ...tokens,
+  });
+});
+
+/**
+ * POST /auth/refresh
+ * Refresh access token using refresh token
+ */
+auth.post('/refresh', zValidator('json', refreshSchema), async (c) => {
+  const { refreshToken } = c.req.valid('json');
+
+  // Verify refresh token
+  const payload = verifyRefreshToken(refreshToken);
+
+  // Get user
+  const user = users.get(payload.userId);
+  if (!user) {
+    throw new UnauthorizedError('User not found');
+  }
+
+  // Generate new tokens
+  const tokens = generateTokens(user.id, user.email);
+
+  return success(c, tokens);
+});
+
+/**
+ * POST /auth/logout
+ * Logout (client should discard tokens)
+ * In a real app, you would invalidate the refresh token in the database
+ */
+auth.post('/logout', async (c) => {
+  // In a real application, you would:
+  // 1. Get refresh token from request
+  // 2. Delete it from database/Redis
+  // 3. Optionally blacklist the access token until it expires
+
+  return success(c, { message: 'Logged out successfully' });
+});
+
+export default auth;

package/templates/docker-compose.yml

@@ -0,0 +1,70 @@
+version: '3.8'
+
+services:
+__IF_POSTGRES__  postgres:
+__IF_POSTGRES__    image: postgres:16-alpine
+__IF_POSTGRES__    container_name: __PROJECT_NAME__-postgres
+__IF_POSTGRES__    environment:
+__IF_POSTGRES__      POSTGRES_USER: postgres
+__IF_POSTGRES__      POSTGRES_PASSWORD: postgres
+__IF_POSTGRES__      POSTGRES_DB: __PROJECT_NAME__
+__IF_POSTGRES__    ports:
+__IF_POSTGRES__      - '5432:5432'
+__IF_POSTGRES__    volumes:
+__IF_POSTGRES__      - postgres_data:/var/lib/postgresql/data
+__IF_POSTGRES__    healthcheck:
+__IF_POSTGRES__      test: ['CMD-SHELL', 'pg_isready -U postgres']
+__IF_POSTGRES__      interval: 10s
+__IF_POSTGRES__      timeout: 5s
+__IF_POSTGRES__      retries: 5
+__IF_POSTGRES__
+__IF_MONGODB__  mongodb:
+__IF_MONGODB__    image: mongo:7-jammy
+__IF_MONGODB__    container_name: __PROJECT_NAME__-mongodb
+__IF_MONGODB__    environment:
+__IF_MONGODB__      MONGO_INITDB_ROOT_USERNAME: root
+__IF_MONGODB__      MONGO_INITDB_ROOT_PASSWORD: password
+__IF_MONGODB__      MONGO_INITDB_DATABASE: __PROJECT_NAME__
+__IF_MONGODB__    ports:
+__IF_MONGODB__      - '27017:27017'
+__IF_MONGODB__    volumes:
+__IF_MONGODB__      - mongodb_data:/data/db
+__IF_MONGODB__    healthcheck:
+__IF_MONGODB__      test: echo 'db.runCommand("ping").ok' | mongosh localhost:27017/__PROJECT_NAME__ --quiet
+__IF_MONGODB__      interval: 10s
+__IF_MONGODB__      timeout: 5s
+__IF_MONGODB__      retries: 5
+__IF_MONGODB__
+__IF_REDIS__  redis:
+__IF_REDIS__    image: redis:7-alpine
+__IF_REDIS__    container_name: __PROJECT_NAME__-redis
+__IF_REDIS__    ports:
+__IF_REDIS__      - '6379:6379'
+__IF_REDIS__    volumes:
+__IF_REDIS__      - redis_data:/data
+__IF_REDIS__    healthcheck:
+__IF_REDIS__      test: ['CMD', 'redis-cli', 'ping']
+__IF_REDIS__      interval: 10s
+__IF_REDIS__      timeout: 5s
+__IF_REDIS__      retries: 5
+__IF_REDIS__
+__IF_SMTP__  mailhog:
+__IF_SMTP__    image: mailhog/mailhog:latest
+__IF_SMTP__    container_name: __PROJECT_NAME__-mailhog
+__IF_SMTP__    ports:
+__IF_SMTP__      - '1025:1025'  # SMTP
+__IF_SMTP__      - '8025:8025'  # Web UI
+__IF_SMTP__    healthcheck:
+__IF_SMTP__      test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:8025']
+__IF_SMTP__      interval: 10s
+__IF_SMTP__      timeout: 5s
+__IF_SMTP__      retries: 5
+
+volumes:
+__IF_POSTGRES__  postgres_data:
+__IF_MONGODB__  mongodb_data:
+__IF_REDIS__  redis_data:
+
+networks:
+  default:
+    name: __PROJECT_NAME__-network