@codeenthusiast09/create-express-app 1.0.0

package/templates/boilerplate/src/common/utils/response-helper.ts

@@ -0,0 +1,140 @@
+import { Response } from 'express';
+import {
+  ApiSuccessResponse,
+  ApiFailResponse,
+  ApiErrorResponse,
+  ErrorDetail,
+} from '@/types/response.types';
+import { config } from '@/config';
+
+/**
+ * Response Helper
+ *
+ * Provides consistent, type-safe JSON responses across the API.
+ */
+export class ResponseHelper {
+  /**
+   * Success Response (2xx)
+   */
+  static success<T>(res: Response, data: T, message = 'Success', statusCode = 200): Response {
+    const response = {
+      success: true,
+      data,
+      message,
+      timestamp: new Date().toISOString(),
+    } satisfies ApiSuccessResponse<T>;
+    return res.status(statusCode).json(response);
+  }
+
+  /**
+   * Client Error Response (4xx)
+   * Use for validation errors, not found, unauthorized, etc.
+   */
+  static fail(
+    res: Response,
+    code: string,
+    message: string,
+    statusCode = 400,
+    details?: ErrorDetail[],
+  ): Response {
+    const response = {
+      success: false,
+      error: {
+        code,
+        message,
+        details,
+      },
+      timestamp: new Date().toISOString(),
+    } satisfies ApiFailResponse;
+    return res.status(statusCode).json(response);
+  }
+
+  /**
+   * Server Error Response (5xx)
+   * Use for unexpected server errors
+   */
+  static error(
+    res: Response,
+    code: string,
+    message: string,
+    statusCode = 500,
+    error?: Error,
+  ): Response {
+    const response = {
+      success: false,
+      error: {
+        code,
+        message,
+        // Only include stack trace in development
+        stack: config.nodeEnv === 'development' ? error?.stack : undefined,
+      },
+      timestamp: new Date().toISOString(),
+    } satisfies ApiErrorResponse;
+    return res.status(statusCode).json(response);
+  }
+
+  // ========== Convenience Methods ==========
+
+  /**
+   * 201 Created
+   */
+  static created<T>(res: Response, data: T, message = 'Resource created') {
+    return ResponseHelper.success(res, data, message, 201);
+  }
+
+  /**
+   * 204 No Content
+   */
+  static noContent(res: Response) {
+    return res.status(204).send();
+  }
+
+  /**
+   * 400 Bad Request (with validation errors)
+   */
+  static badRequest(res: Response, message: string, details?: ErrorDetail[]) {
+    return ResponseHelper.fail(res, 'BAD_REQUEST', message, 400, details);
+  }
+
+  /**
+   * 401 Unauthorized
+   */
+  static unauthorized(res: Response, message = 'Authentication required') {
+    return ResponseHelper.fail(res, 'UNAUTHORIZED', message, 401);
+  }
+
+  /**
+   * 403 Forbidden
+   */
+  static forbidden(res: Response, message = 'Access denied') {
+    return ResponseHelper.fail(res, 'FORBIDDEN', message, 403);
+  }
+
+  /**
+   * 404 Not Found
+   */
+  static notFound(res: Response, message = 'Resource not found') {
+    return ResponseHelper.fail(res, 'NOT_FOUND', message, 404);
+  }
+
+  /**
+   * 409 Conflict
+   */
+  static conflict(res: Response, message: string) {
+    return ResponseHelper.fail(res, 'CONFLICT', message, 409);
+  }
+
+  /**
+   * 422 Unprocessable Entity (validation errors)
+   */
+  static validationError(res: Response, details: ErrorDetail[]) {
+    return ResponseHelper.fail(res, 'VALIDATION_ERROR', 'Validation failed', 422, details);
+  }
+
+  /**
+   * 500 Internal Server Error
+   */
+  static internalError(res: Response, message = 'Internal server error', error?: Error) {
+    return ResponseHelper.error(res, 'INTERNAL_SERVER_ERROR', message, 500, error);
+  }
+}

package/templates/boilerplate/src/config/env.ts

@@ -0,0 +1,24 @@
+import dotenv from 'dotenv';
+import path from 'path';
+
+/**
+ * Load environment variables from .env file
+ *
+ * This MUST be imported before any other config files
+ * to ensure environment variables are available.
+ */
+
+// Load .env from project root
+dotenv.config({ path: path.resolve(__dirname, '../../.env') });
+
+// Validate required environment variables
+const requiredEnvVars = ['DATABASE_URL', 'JWT_SECRET'];
+
+for (const envVar of requiredEnvVars) {
+  if (!process.env[envVar]) {
+    throw new Error(`Missing required environment variable: ${envVar}`);
+  }
+}
+
+// Export nothing - this file is just for side effects
+export {};

package/templates/boilerplate/src/config/index.ts

@@ -0,0 +1,92 @@
+import './env';
+import { z } from 'zod';
+
+/**
+ * Configuration Schema
+ *
+ * This defines what environment variables we need and validates them.
+ * If validation fails, the app won't start and will show you what's wrong.
+ */
+const configSchema = z.object({
+  // Application settings
+  nodeEnv: z.enum(['development', 'production', 'test']).default('development'),
+  port: z.number().int().positive().default(3000),
+
+  // Database
+  database: z.object({
+    url: z.string().min(1, 'DATABASE_URL is required'),
+  }),
+
+  // JWT Authentication
+  jwt: z.object({
+    secret: z.string().min(32, 'JWT_SECRET must be at least 32 characters for security'),
+    expiresIn: z.string().default('7d'),
+  }),
+
+  // CORS Configuration
+  cors: z.object({
+    origin: z.string().or(z.array(z.string())).default('*'),
+    credentials: z.boolean().default(true),
+  }),
+
+  // Logging
+  logging: z.object({
+    level: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
+  }),
+});
+
+/**
+ * Parse and Validate Configuration
+ *
+ * This reads from process.env, validates it, and returns a type-safe config object.
+ */
+const parseConfig = () => {
+  const rawConfig = {
+    nodeEnv: process.env.NODE_ENV || 'development',
+    port: parseInt(process.env.PORT || '3000', 10),
+    database: {
+      url: process.env.DATABASE_URL || '',
+    },
+    jwt: {
+      secret: process.env.JWT_SECRET || '',
+      expiresIn: process.env.JWT_EXPIRES_IN || '7d',
+    },
+    cors: {
+      origin: process.env.CORS_ORIGIN || '*',
+      credentials: process.env.CORS_CREDENTIALS === 'true',
+    },
+    logging: {
+      level: (process.env.LOG_LEVEL || 'info') as 'info',
+    },
+  };
+
+  try {
+    return configSchema.parse(rawConfig);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error('❌ Invalid environment variables:');
+      error.errors.forEach((err) => {
+        console.error(`  - ${err.path.join('.')}: ${err.message}`);
+      });
+      process.exit(1);
+    }
+    throw error;
+  }
+};
+
+/**
+ * Validated Configuration
+ *
+ * Import this anywhere in your app to access config.
+ * TypeScript knows the exact shape and will autocomplete!
+ *
+ * Usage:
+ *   import { config } from '@/config';
+ *   const port = config.port; // TypeScript knows this is a number
+ */
+export const config = parseConfig();
+
+/**
+ * Configuration Type
+ */
+export type Config = z.infer<typeof configSchema>;

package/templates/boilerplate/src/database/drizzle.connection.ts

@@ -0,0 +1,50 @@
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+import { config } from '@/config';
+import { logger } from '@/common/utils/logger';
+
+/**
+ * PostgreSQL Connection (Drizzle)
+ */
+
+// Create connection pool
+const pool = new Pool({
+  connectionString: config.database.url,
+  max: 10,
+  min: 2,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 5000,
+});
+
+// Initialize Drizzle
+export const db = drizzle(pool);
+
+export const connectDatabase = async (): Promise<void> => {
+  try {
+    // Test connection
+    await pool.query('SELECT NOW()');
+    logger.info('󰪩 PostgreSQL connected successfully (Drizzle)');
+  } catch (error) {
+    logger.error('󱙀  PostgreSQL connection error:', error);
+    process.exit(1);
+  }
+};
+
+export const disconnectDatabase = async (): Promise<void> => {
+  try {
+    await pool.end();
+    logger.info('󱙀 PostgreSQL disconnected');
+  } catch (error) {
+    logger.error('󱙀 Error disconnecting from PostgreSQL:', error);
+  }
+};
+
+// Graceful shutdown
+const gracefulShutdown = async (signal: string) => {
+  logger.info(`${signal} received. Closing PostgreSQL connection...`);
+  await disconnectDatabase();
+  process.exit(0);
+};
+
+process.on('SIGINT', () => void gracefulShutdown('SIGINT'));
+process.on('SIGTERM', () => void gracefulShutdown('SIGTERM'));

package/templates/boilerplate/src/database/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Database Connection Export
+ *
+ * This file exports the database connection based on your choice.
+ * The CLI will automatically update this file during project generation.
+ *
+ * Available options:
+ * - MongoDB with Mongoose
+ * - PostgreSQL with Prisma
+ * - PostgreSQL with Drizzle
+ */
+
+// Default: Mongoose (MongoDB)
+export * from './mongoose.connection';
+
+// Uncomment for Prisma (PostgreSQL)
+// export * from './prisma.connection';
+
+// Uncomment for Drizzle (PostgreSQL)
+// export * from './drizzle.connection';

package/templates/boilerplate/src/database/mongoose.connection.ts

@@ -0,0 +1,56 @@
+import mongoose from 'mongoose';
+import { config } from '@/config';
+import { logger } from '@/common/utils/logger';
+
+/**
+ * MongoDB Connection (Mongoose)
+ */
+
+export const connectDatabase = async (): Promise<void> => {
+  try {
+    const options: mongoose.ConnectOptions = {
+      maxPoolSize: 10,
+      minPoolSize: 2,
+      serverSelectionTimeoutMS: 5000,
+      socketTimeoutMS: 45000,
+    };
+
+    await mongoose.connect(config.database.url, options);
+    logger.info('󰆼 MongoDB connected successfully');
+  } catch (error) {
+    logger.error('󱙀 MongoDB connection error:', error);
+    process.exit(1);
+  }
+};
+
+export const disconnectDatabase = async (): Promise<void> => {
+  try {
+    await mongoose.disconnect();
+    logger.info('󰆼 MongoDB disconnected');
+  } catch (error) {
+    logger.error('󱙀 Error disconnecting from MongoDB:', error);
+  }
+};
+
+// Connection event listeners
+mongoose.connection.on('connected', () => {
+  logger.info('󰪩 Mongoose connected to MongoDB');
+});
+
+mongoose.connection.on('disconnected', () => {
+  logger.warn('󱙀 Mongoose disconnected from MongoDB');
+});
+
+mongoose.connection.on('error', (error) => {
+  logger.error('󱙀 MongoDB connection error:', error);
+});
+
+// Graceful shutdown
+const gracefulShutdown = async (signal: string) => {
+  logger.info(`󰆼 ${signal} received. Closing MongoDB connection...`);
+  await disconnectDatabase();
+  process.exit(0);
+};
+
+process.on('SIGINT', () => void gracefulShutdown('SIGINT'));
+process.on('SIGTERM', () => void gracefulShutdown('SIGTERM'));

package/templates/boilerplate/src/database/prisma.connection.ts

@@ -0,0 +1,50 @@
+import { PrismaClient } from '@prisma/client';
+import { logger } from '@/common/utils/logger';
+import { config } from '@/config';
+
+/**
+ * PostgreSQL Connection (Prisma)
+ */
+
+// Singleton pattern to prevent multiple instances
+const globalForPrisma = global as unknown as { prisma: PrismaClient };
+
+export const prisma =
+  globalForPrisma.prisma ||
+  new PrismaClient({
+    log: config.nodeEnv === 'development' ? ['query', 'error', 'warn'] : ['error'],
+    errorFormat: config.nodeEnv === 'development' ? 'pretty' : 'minimal',
+  });
+
+if (config.nodeEnv !== 'production') {
+  globalForPrisma.prisma = prisma;
+}
+
+export const connectDatabase = async (): Promise<void> => {
+  try {
+    await prisma.$connect();
+    logger.info('󰪩 PostgreSQL connected successfully (Prisma)');
+  } catch (error) {
+    logger.error('󱙀 PostgreSQL connection error:', error);
+    process.exit(1);
+  }
+};
+
+export const disconnectDatabase = async (): Promise<void> => {
+  try {
+    await prisma.$disconnect();
+    logger.info('󱙀 PostgreSQL disconnected');
+  } catch (error) {
+    logger.error('󱙀 Error disconnecting from PostgreSQL:', error);
+  }
+};
+
+// Graceful shutdown
+const gracefulShutdown = async (signal: string) => {
+  logger.info(`${signal} received. Closing PostgreSQL connection...`);
+  await disconnectDatabase();
+  process.exit(0);
+};
+
+process.on('SIGINT', () => void gracefulShutdown('SIGINT'));
+process.on('SIGTERM', () => void gracefulShutdown('SIGTERM'));

package/templates/boilerplate/src/server.ts

@@ -0,0 +1,121 @@
+import { config } from './config';
+import express, { Application } from 'express';
+import cors from 'cors';
+import { logger } from './common/utils/logger';
+import { httpLogger } from './common/utils/http-logger';
+import { errorHandler, notFoundHandler } from './common/middleware/error.middleware';
+import { connectDatabase } from './database';
+
+/**
+ * Express Application Setup
+ */
+
+const app: Application = express();
+
+/**
+ * Middleware
+ */
+app.use(
+  cors({
+    origin: config.cors.origin,
+    credentials: config.cors.credentials,
+  }),
+);
+
+app.use(express.json({ limit: '10mb' }));
+app.use(express.urlencoded({ extended: true, limit: '10mb' }));
+app.use(httpLogger);
+
+/**
+ * Health Check Endpoint
+ */
+app.get('/health', (_req, res) => {
+  res.json({
+    status: 'ok',
+    timestamp: new Date().toISOString(),
+    uptime: process.uptime(),
+    environment: config.nodeEnv,
+  });
+});
+
+/**
+ * Root Endpoint
+ */
+app.get('/', (_req, res) => {
+  res.json({
+    message: 'Hello World!',
+    version: '1.0.0',
+  });
+});
+
+/**
+ * API Routes
+ *
+ * Add your routes here:
+ * app.use('/api/users', userRoutes);
+ * app.use('/api/posts', postRoutes);
+ */
+
+/**
+ * Error Handling (must be last)
+ */
+app.use(notFoundHandler);
+app.use(errorHandler);
+
+/**
+ * Start Server
+ */
+const startServer = async (): Promise<void> => {
+  try {
+    await connectDatabase();
+
+    const PORT = config.port;
+    app.listen(PORT, () => {
+      if (config.nodeEnv === 'development') {
+        logger.info(`
+╔════════════════════════════════════════╗
+║   🚀 Server is running!                ║
+║   📍 http://localhost:${PORT}             ║
+║   🌍 Environment: ${config.nodeEnv.padEnd(10)}          ║
+╚════════════════════════════════════════╝
+        `);
+      } else {
+        // Production: Simple, JSON-friendly message
+        logger.info({
+          message: 'Server is running',
+          port: PORT,
+          environment: config.nodeEnv,
+          url: `http://localhost:${PORT}`,
+        });
+      }
+    });
+  } catch (error) {
+    logger.error('Failed to start server:', error);
+    process.exit(1);
+  }
+};
+
+// Graceful shutdown
+const gracefulShutdown = (signal: string) => {
+  logger.info(`${signal} received. Starting graceful shutdown...`);
+  process.exit(0);
+};
+
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+process.on('unhandledRejection', (reason: Error) => {
+  logger.error('Unhandled Promise Rejection:', reason);
+  process.exit(1);
+});
+process.on('uncaughtException', (error: Error) => {
+  logger.error('Uncaught Exception:', error);
+  process.exit(1);
+});
+
+startServer().catch((error) => {
+  logger.error('Failed to start server:', error);
+
+  process.exit(1);
+});
+
+export default app;

package/templates/boilerplate/src/types/express.types.ts

@@ -0,0 +1,29 @@
+import { Request } from 'express';
+
+/**
+ * Authenticated User
+ */
+export interface AuthUser {
+  id: string;
+  email: string;
+  role?: string;
+}
+
+/**
+ * Extend Express Request globally
+ */
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      user?: AuthUser;
+    }
+  }
+}
+
+/**
+ * Type-safe Request with User (for protected routes)
+ */
+export interface AuthenticatedRequest extends Request {
+  user: AuthUser;
+}

package/templates/boilerplate/src/types/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Types Index
+ */
+export * from './express.types';
+export * from './response.types';

package/templates/boilerplate/src/types/response.types.ts

@@ -0,0 +1,54 @@
+/**
+ * Base API Response
+ */
+interface BaseResponse {
+  success: boolean;
+  message?: string;
+  timestamp?: string; // ISO 8601
+}
+
+/**
+ * Successful API Response
+ */
+export interface ApiSuccessResponse<T = unknown> extends BaseResponse {
+  success: true;
+  data: T;
+}
+
+/**
+ * Failed API Response (Client Errors - 4xx)
+ */
+export interface ApiFailResponse extends BaseResponse {
+  success: false;
+  error: {
+    code: string; // e.g., "VALIDATION_ERROR", "NOT_FOUND"
+    message: string;
+    details?: ErrorDetail[]; // For validation errors
+  };
+}
+
+/**
+ * Error API Response (Server Errors - 5xx)
+ */
+export interface ApiErrorResponse extends BaseResponse {
+  success: false;
+  error: {
+    code: string; // e.g., "INTERNAL_SERVER_ERROR"
+    message: string;
+    stack?: string; // Only in development
+  };
+}
+
+/**
+ * Union of all possible responses
+ */
+export type ApiResponse<T = unknown> = ApiSuccessResponse<T> | ApiFailResponse | ApiErrorResponse;
+
+/**
+ * Error detail for validation errors
+ */
+export interface ErrorDetail {
+  field: string;
+  message: string;
+  code?: string; // e.g., "REQUIRED", "INVALID_FORMAT"
+}