@yoms/create-monorepo 2.0.0 → 4.0.0

package/README.md

@@ -33,8 +33,10 @@ npm create @yoms/monorepo my-project
 
 ## Quick Start
 
+### Interactive Mode (Default)
+
 ```bash
-# Create a new project
+# Create a new project with interactive prompts
 npx @yoms/create-monorepo my-project
 
 # Navigate to project
@@ -51,6 +53,49 @@ pnpm dev
 # - Frontend: http://localhost:3000
 ```
 
+### Non-Interactive Mode with CLI Flags
+
+```bash
+# Create a project with all features using CLI flags
+npx @yoms/create-monorepo my-project \
+  --backend hono \
+  --database postgres \
+  --redis \
+  --smtp \
+  --swagger \
+  --auth \
+  --frontend \
+  --shadcn \
+  --docker \
+  --pm pnpm
+
+# Quick start with defaults (skips all prompts)
+npx @yoms/create-monorepo my-project --yes
+```
+
+## CLI Options
+
+```bash
+npx @yoms/create-monorepo [dir] [options]
+
+Options:
+  --backend <framework>    Backend framework (hono)
+  --database <db>          Database (postgres, mongodb, none)
+  --redis                  Include Redis cache
+  --smtp                   Include SMTP email
+  --swagger                Include Swagger docs
+  --auth                   Include JWT authentication
+  --frontend               Include Next.js frontend
+  --shadcn                 Include shadcn/ui components
+  --pm <manager>           Package manager (pnpm, npm, yarn, bun)
+  --docker                 Include Docker Compose setup
+  --skip-install           Skip dependency installation
+  --skip-git               Skip git initialization
+  -y, --yes                Skip all prompts and use defaults
+  -h, --help               Display help
+  -v, --version            Display version
+```
+
 ## What You Get
 
 ### Backend Options
@@ -60,8 +105,12 @@ pnpm dev
 - **Caching**: Redis with ready-to-use cache service
 - **Email**: SMTP with Nodemailer
 - **Docs**: Swagger/OpenAPI with Scalar UI
+- **Authentication**: JWT with refresh tokens (optional)
 - **Logging**: Winston with structured logging
 - **Validation**: Zod schemas
+- **Error Handling**: Custom error classes and response helpers
+- **Rate Limiting**: Memory-based rate limiter with presets
+- **Testing**: Vitest with example tests
 - **Type Safety**: Full TypeScript with strict mode
 
 ### Frontend
@@ -85,12 +134,14 @@ my-project/
 │   ├── api/                  # Backend API
 │   │   ├── src/
 │   │   │   ├── routes/       # API routes
-│   │   │   ├── middleware/   # Express/Hono middleware
+│   │   │   ├── middleware/   # Hono middleware
 │   │   │   ├── services/     # Business logic
 │   │   │   ├── config/       # Configuration (env, logger, db)
+│   │   │   ├── lib/          # Utilities (jwt, errors, response)
 │   │   │   └── types/        # TypeScript types
-│   │   ├── prisma/           # Database schema
-│   │   └── Dockerfile        # Production container
+│   │   ├── prisma/           # Database schema (if database selected)
+│   │   ├── Dockerfile        # Production container
+│   │   └── vitest.config.ts  # Test configuration
 │   │
 │   ├── web/                  # Next.js frontend
 │   │   ├── app/              # App router pages
@@ -102,6 +153,7 @@ my-project/
 │           ├── schemas/      # Zod schemas
 │           └── types.ts      # Common types
 │
+├── docker-compose.yml        # Docker services (if --docker)
 ├── pnpm-workspace.yaml       # Workspace configuration
 └── tsconfig.base.json        # Shared TypeScript config
 ```
@@ -157,6 +209,35 @@ SMTP_HOST=smtp.gmail.com
 SMTP_PORT=587
 SMTP_USER=...
 SMTP_PASS=...
+
+# JWT (if --auth selected)
+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
+```
+
+## Docker Compose
+
+When using the `--docker` flag, a `docker-compose.yml` file is generated with the following services based on your configuration:
+
+- **PostgreSQL**: If `--database postgres` is selected
+- **MongoDB**: If `--database mongodb` is selected
+- **Redis**: If `--redis` is selected
+- **MailHog**: If `--smtp` is selected (SMTP testing server with web UI)
+
+```bash
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+
+# View MailHog web UI (if SMTP selected)
+open http://localhost:8025
 ```
 
 ## Available Scripts
@@ -165,11 +246,16 @@ SMTP_PASS=...
 # Development
 pnpm dev              # Start all packages in dev mode
 pnpm --filter api dev # Start only backend
+pnpm --filter web dev # Start only frontend
 
 # Building
 pnpm build            # Build all packages
 pnpm typecheck        # Type-check all packages
 
+# Testing
+pnpm --filter api test        # Run backend tests
+pnpm --filter api test:watch  # Run tests in watch mode
+
 # Database (if Prisma is selected)
 pnpm --filter api prisma:generate  # Generate Prisma client
 pnpm --filter api prisma:migrate   # Run migrations
@@ -180,6 +266,48 @@ pnpm lint             # Lint all packages
 pnpm format           # Format with Prettier
 ```
 
+## Authentication (JWT)
+
+When using the `--auth` flag, JWT authentication is set up with the following features:
+
+- **Access tokens**: Short-lived (15 minutes default)
+- **Refresh tokens**: Long-lived (7 days default)
+- **Password hashing**: bcryptjs with salt rounds
+- **Protected routes**: Auth middleware for route protection
+
+### Example Usage
+
+```typescript
+// Register a new user
+POST /auth/register
+{
+  "email": "user@example.com",
+  "password": "securepassword",
+  "name": "John Doe"
+}
+
+// Login
+POST /auth/login
+{
+  "email": "user@example.com",
+  "password": "securepassword"
+}
+
+// Refresh access token
+POST /auth/refresh
+{
+  "refreshToken": "..."
+}
+
+// Protected route example
+import { authMiddleware } from './middleware/auth.middleware';
+
+app.get('/protected', authMiddleware, (c) => {
+  const { userId, email } = c.get('jwtPayload');
+  return c.json({ userId, email });
+});
+```
+
 ## Requirements
 
 - Node.js >= 18

package/dist/index.js

@@ -199,11 +199,11 @@ async function promptBackendConfig() {
     includeSwagger = swagger;
   }
   let includeAuth = false;
-  if (backendType === "web") {
+  if (backendType === "web" && database !== "none") {
     const { auth } = await enquirer2.prompt({
       type: "confirm",
       name: "auth",
-      message: "Include JWT authentication?",
+      message: "Include authentication? (better-auth \u2014 email/password + sessions)",
       initial: false
     });
     includeAuth = auth;
@@ -265,6 +265,7 @@ var BaseGenerator = class {
       __PROJECT_NAME__: this.options.projectName,
       __PACKAGE_SCOPE__: `@${this.options.projectName}`,
       __DATABASE_PROVIDER__: "none",
+      __PRISMA_PROVIDER__: "postgresql",
       __HAS_REDIS__: "false",
       __HAS_SMTP__: "false",
       __API_PORT__: "3001",
@@ -357,6 +358,113 @@ tmp/
 `;
     await writeFile(path2.join(this.options.projectDir, ".gitignore"), gitignoreContent);
     const tokens = this.getTokens();
+    const pm = this.options.packageManager;
+    const hasBackend = config.includeBackend;
+    const hasFrontend = config.includeFrontend;
+    const hasShared = hasBackend && hasFrontend;
+    const db = config.backend?.database;
+    const hasAuth = config.backend?.includeAuth;
+    const hasRedis = config.backend?.includeRedis;
+    const claudeMdContent = `# CLAUDE.md \u2014 ${tokens.__PROJECT_NAME__}
+
+This file provides guidance to Claude Code when working in this monorepo.
+
+## Project Overview
+
+**${tokens.__PROJECT_NAME__}** is a TypeScript monorepo generated with create-monorepo.
+
+Packages:
+${hasBackend ? `- \`packages/api/\` \u2014 Hono backend API (port ${tokens.__API_PORT__})
+` : ""}${hasFrontend ? `- \`packages/web/\` \u2014 Next.js frontend (port ${tokens.__WEB_PORT__})
+` : ""}${hasShared ? `- \`packages/shared/\` \u2014 Shared Zod schemas and TypeScript types
+` : ""}
+## Stack
+
+${hasBackend ? `- **Backend**: Hono, TypeScript, Zod${db ? `, Prisma (${db})` : ""}${hasAuth ? ", better-auth" : ""}${hasRedis ? ", Redis" : ""}
+` : ""}${hasFrontend ? `- **Frontend**: Next.js 15 App Router, TanStack Query, Tailwind CSS, shadcn/ui${hasAuth ? ", better-auth client" : ""}
+` : ""}${hasShared ? `- **Shared**: Zod schemas, inferred TypeScript types
+` : ""}- **Package Manager**: ${pm}
+- **Monorepo**: pnpm workspaces
+
+## Development Commands
+
+\`\`\`bash
+# Run everything
+${pm} dev                         # Start all packages in parallel
+
+# Individual packages
+${pm} --filter api dev            # Backend only
+${pm} --filter web dev            # Frontend only
+
+# Build
+${pm} build                       # Build all packages
+${pm} --filter shared build       # Build shared first if types changed
+
+# Quality
+${pm} typecheck                   # Type-check all packages
+${pm} lint                        # Lint all packages
+${pm} format                      # Format all packages
+\`\`\`
+
+## Package Dependency
+
+\`\`\`
+${hasShared ? `packages/shared  \u2190  packages/api
+                  \u2190  packages/web` : hasBackend ? "packages/api" : "packages/web"}
+\`\`\`
+
+${hasShared ? `> Always build \`packages/shared\` first after schema changes: \`${pm} --filter shared build\`
+` : ""}${db ? `
+## Database
+
+- **Provider**: ${db === "postgres" ? "PostgreSQL" : "MongoDB"} via Prisma
+- Schema: \`packages/api/prisma/schema.prisma\`
+
+\`\`\`bash
+${pm} --filter api prisma:generate   # Regenerate Prisma client
+${pm} --filter api prisma:migrate    # Run migrations
+${pm} --filter api prisma:studio     # Open Prisma Studio
+\`\`\`
+` : ""}${hasAuth ? `
+## Authentication
+
+Powered by [better-auth](https://better-auth.com).
+
+- Sessions stored in database, sent as HTTP-only cookies
+- Auth routes handled at \`/api/auth/**\` on the backend
+- Frontend uses \`lib/auth-client.ts\` \u2014 no manual token management
+- Required env vars: \`BETTER_AUTH_SECRET\`, \`BETTER_AUTH_URL\`
+
+See \`packages/api/CLAUDE.md\` for protecting routes.
+See \`packages/web/CLAUDE.md\` for frontend usage.
+` : ""}
+## Environment Setup
+
+\`\`\`bash
+cp packages/api/.env.example packages/api/.env
+${hasFrontend ? `cp packages/web/.env.example packages/web/.env
+` : ""}\`\`\`
+
+Edit the \`.env\` files before running \`${pm} dev\`.
+
+## Key Files
+
+${hasBackend ? `- \`packages/api/src/index.ts\` \u2014 Hono app entry point
+- \`packages/api/src/lib/errors.ts\` \u2014 Custom error classes
+- \`packages/api/src/lib/response.ts\` \u2014 Response helpers
+` : ""}${hasFrontend ? `- \`packages/web/services/api/client.ts\` \u2014 HTTP client
+- \`packages/web/services/api/endpoints.ts\` \u2014 API endpoint constants
+- \`packages/web/lib/auth-client.ts\` \u2014 better-auth client
+` : ""}${hasShared ? `- \`packages/shared/src/index.ts\` \u2014 All shared type exports
+` : ""}
+## Per-Package Guidance
+
+Each package has its own \`CLAUDE.md\` with detailed patterns:
+${hasBackend ? `- \`packages/api/CLAUDE.md\` \u2014 routes, services, middleware, error handling
+` : ""}${hasFrontend ? `- \`packages/web/CLAUDE.md\` \u2014 services, hooks, auth, components
+` : ""}${hasShared ? `- \`packages/shared/CLAUDE.md\` \u2014 adding schemas and types
+` : ""}`;
+    await writeFile(path2.join(this.options.projectDir, "CLAUDE.md"), claudeMdContent);
     const readmeContent = `# ${tokens.__PROJECT_NAME__}
 
 Generated with create-monorepo.
@@ -530,6 +638,7 @@ var BackendGenerator = class extends BaseGenerator {
     const tokens = this.getTokens({
       __BACKEND_FRAMEWORK__: this.config.framework,
       __DATABASE_PROVIDER__: this.config.database || "none",
+      __PRISMA_PROVIDER__: this.config.database === "postgres" ? "postgresql" : this.config.database === "mongodb" ? "mongodb" : "postgresql",
       __HAS_REDIS__: String(this.config.includeRedis),
       __HAS_SMTP__: String(this.config.includeSmtp)
     });
@@ -561,8 +670,8 @@ 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");
+      if (this.config.includeAuth && this.config.database) {
+        const authFeaturePath = path4.join(featuresPath, "better-auth");
         await mergeFeature(backendDir, authFeaturePath, tokens);
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoms/create-monorepo",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "CLI tool to scaffold monorepo projects from templates",
   "type": "module",
   "bin": {

package/templates/backend-hono/base/{AGENT.md → CLAUDE.md}

@@ -1,6 +1,6 @@
-# AGENT.md - Backend API
+# CLAUDE.md — Backend API (`__PACKAGE_SCOPE__/api`)
 
-This file provides guidance to AI agents (Claude, Cursor, etc.) when working with this backend API.
+This file provides guidance to Claude Code when working in this package.
 
 ## Project Overview
 
@@ -315,10 +315,49 @@ logger.error('Database error', { error, query });
 - Use `prisma.$transaction()` for multiple related operations
 - Profile with `pnpm test:coverage` to find slow tests
 
+## Authentication (better-auth)
+
+If auth is enabled, the project uses [better-auth](https://better-auth.com) with cookie-based sessions.
+
+### How it works
+
+- All auth routes are mounted at `/api/auth/**` — handled automatically by better-auth
+- Sessions are stored in the database (Prisma adapter)
+- Cookies are HTTP-only — no manual token management
+
+### Protecting routes
+
+```typescript
+import { requireAuth, optionalAuth } from '../middleware/auth.middleware.js';
+
+// Require a valid session
+app.get('/profile', requireAuth, (c) => {
+  const session = c.get('session'); // { user: User, session: Session }
+  return success(c, session.user);
+});
+
+// Attach session if present, but don't block
+app.get('/feed', optionalAuth, (c) => {
+  const session = c.get('session'); // null if not logged in
+  ...
+});
+```
+
+### Prisma schema
+
+The schema includes `user`, `session`, `account`, and `verification` tables managed by better-auth. Do not modify them manually — run `npx better-auth generate` if you change `src/lib/auth.ts`.
+
+### Auth environment variables
+
+```
+BETTER_AUTH_SECRET=...   # min 32 chars
+BETTER_AUTH_URL=...      # your API URL, e.g. http://localhost:3001
+```
+
 ## Security Checklist
 
 - [ ] All inputs are validated with Zod
-- [ ] Rate limiting is applied to auth endpoints
+- [ ] Rate limiting is applied to sensitive endpoints
 - [ ] Sensitive data is not logged
 - [ ] Database queries use parameterized queries (Prisma does this)
 - [ ] CORS is configured correctly

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

@@ -0,0 +1,4 @@
+
+# Better Auth Configuration
+BETTER_AUTH_SECRET=your-super-secret-key-change-in-production-must-be-32-chars-min
+BETTER_AUTH_URL=http://localhost:__API_PORT__

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

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "better-auth": "^1.2.7"
+  }
+}

package/templates/backend-hono/features/better-auth/prisma/schema.prisma

@@ -0,0 +1,69 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "__PRISMA_PROVIDER__"
+  url      = env("DATABASE_URL")
+}
+
+// Better Auth models — managed by better-auth, do not modify manually.
+// Run `npx better-auth generate` to regenerate if you change auth config.
+
+model user {
+  id            String    @id
+  name          String
+  email         String    @unique
+  emailVerified Boolean
+  image         String?
+  createdAt     DateTime
+  updatedAt     DateTime
+  sessions      session[]
+  accounts      account[]
+
+  @@map("user")
+}
+
+model session {
+  id        String   @id
+  expiresAt DateTime
+  token     String   @unique
+  createdAt DateTime
+  updatedAt DateTime
+  ipAddress String?
+  userAgent String?
+  userId    String
+  user      user     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@map("session")
+}
+
+model account {
+  id                    String    @id
+  accountId             String
+  providerId            String
+  userId                String
+  user                  user      @relation(fields: [userId], references: [id], onDelete: Cascade)
+  accessToken           String?
+  refreshToken          String?
+  idToken               String?
+  accessTokenExpiresAt  DateTime?
+  refreshTokenExpiresAt DateTime?
+  scope                 String?
+  password              String?
+  createdAt             DateTime
+  updatedAt             DateTime
+
+  @@map("account")
+}
+
+model verification {
+  id         String    @id
+  identifier String
+  value      String
+  expiresAt  DateTime
+  createdAt  DateTime?
+  updatedAt  DateTime?
+
+  @@map("verification")
+}

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

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+const authEnvSchema = z.object({
+  BETTER_AUTH_SECRET: z.string().min(32, 'BETTER_AUTH_SECRET must be at least 32 characters'),
+  BETTER_AUTH_URL: z.string().url('BETTER_AUTH_URL must be a valid URL'),
+});
+
+export const authEnv = authEnvSchema.parse(process.env);

package/templates/backend-hono/features/better-auth/src/index.ts

@@ -0,0 +1,53 @@
+import { Hono } from 'hono';
+import { env } from './config/env.js';
+import { logger } from './config/logger.js';
+import { corsMiddleware } from './middleware/cors.middleware.js';
+import { loggerMiddleware } from './middleware/logger.middleware.js';
+import { errorHandler } from './middleware/error.middleware.js';
+import { health } from './routes/health.route.js';
+import { auth } from './lib/auth.js';
+
+const app = new Hono();
+
+// Global middleware
+app.use('*', corsMiddleware);
+app.use('*', loggerMiddleware);
+
+// Better Auth — handles all /api/auth/* routes (sign-in, sign-up, sign-out, session, etc.)
+app.on(['POST', 'GET'], '/api/auth/**', (c) => auth.handler(c.req.raw));
+
+// Routes
+app.route('/health', health);
+
+// Root endpoint
+app.get('/', (c) => {
+  return c.json({
+    success: true,
+    message: 'Welcome to __PROJECT_NAME__ API',
+    version: '0.1.0',
+  });
+});
+
+// Error handling
+app.onError(errorHandler);
+
+// 404 handler
+app.notFound((c) => {
+  return c.json({
+    success: false,
+    error: 'Not found',
+    message: `Route ${c.req.method} ${c.req.url} not found`,
+  }, 404);
+});
+
+// Start server
+const port = env.PORT;
+
+logger.info(`Starting server in ${env.NODE_ENV} mode...`);
+
+export default {
+  port,
+  fetch: app.fetch,
+};
+
+console.log(`Server running on http://localhost:${port}`);

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

@@ -0,0 +1,21 @@
+import { betterAuth } from 'better-auth';
+import { prismaAdapter } from 'better-auth/adapters/prisma';
+import { PrismaClient } from '@prisma/client';
+import { authEnv } from '../config/env-auth.js';
+
+const prisma = new PrismaClient();
+
+export const auth = betterAuth({
+  baseURL: authEnv.BETTER_AUTH_URL,
+  secret: authEnv.BETTER_AUTH_SECRET,
+  database: prismaAdapter(prisma, {
+    provider: '__PRISMA_PROVIDER__',
+  }),
+  emailAndPassword: {
+    enabled: true,
+  },
+  trustedOrigins: [process.env.WEB_URL || 'http://localhost:__WEB_PORT__'],
+});
+
+export type Session = typeof auth.$Infer.Session;
+export type User = typeof auth.$Infer.Session.user;

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

@@ -0,0 +1,38 @@
+import type { Context, Next } from 'hono';
+import { auth } from '../lib/auth.js';
+import { UnauthorizedError } from '../lib/errors.js';
+
+/**
+ * Middleware to require an authenticated session.
+ * Attaches the session to c.get('session') on success.
+ *
+ * Usage:
+ *   app.get('/protected', requireAuth, (c) => {
+ *     const session = c.get('session');
+ *     return c.json({ user: session.user });
+ *   });
+ */
+export async function requireAuth(c: Context, next: Next): Promise<void> {
+  const session = await auth.api.getSession({ headers: c.req.raw.headers });
+
+  if (!session) {
+    throw new UnauthorizedError('Authentication required');
+  }
+
+  c.set('session', session);
+  await next();
+}
+
+/**
+ * Optional auth middleware — attaches session if present, continues either way.
+ * Use for routes that behave differently for authenticated vs. anonymous users.
+ */
+export async function optionalAuth(c: Context, next: Next): Promise<void> {
+  const session = await auth.api.getSession({ headers: c.req.raw.headers });
+
+  if (session) {
+    c.set('session', session);
+  }
+
+  await next();
+}