create-express-mongoose-app 1.0.0

package/README.md

@@ -0,0 +1,193 @@
+# create-express-mongo-app
+
+A CLI tool to quickly bootstrap a production-grade Express.js + MongoDB/Mongoose project with TypeScript.
+
+## Features
+
+- 🚀 **Quick Setup** - Create a new project in seconds
+- 📦 **Package Manager Support** - Choose npm, yarn, or pnpm
+- 🔒 **Security First** - Includes Helmet, CORS, rate limiting
+- 📝 **TypeScript** - Strict mode enabled by default
+- 🛡️ **Error Handling** - Centralized error middleware with standardized responses
+- 📊 **Logging** - Winston logger with file rotation
+- ✅ **Validation** - Joi schema validation
+- 🗄️ **Database Ready** - MongoDB/Mongoose with connection retry logic
+- 🏥 **Health Checks** - Built-in /health and /ready endpoints
+
+## Installation
+
+```bash
+npm install -g create-express-mongo-app
+```
+
+Or use npx without installation:
+
+```bash
+npx create-express-mongo-app
+```
+
+## Usage
+
+Run the CLI:
+
+```bash
+create-express-mongo-app
+```
+
+Or with npx:
+
+```bash
+npx create-express-mongo-app
+```
+
+The CLI will ask for:
+
+1. **Project Name** - The name of your project directory
+2. **Package Manager** - Choose between npm, yarn, or pnpm
+
+## What's Included
+
+The generated project includes:
+
+### Core Features
+
+- Express.js server with TypeScript
+- MongoDB/Mongoose integration
+- Centralized error handling
+- API response wrapper class
+- Async error handling
+- Winston logging with file rotation
+- Joi validation framework
+- Security middleware stack (helmet, CORS, rate-limit)
+- Request ID tracking
+- Health check endpoints
+
+### Project Structure
+
+```
+src/
+├── config/           # Configuration
+├── middleware/       # Express middleware
+├── modules/          # Feature modules
+├── utils/            # Utility functions
+├── app.ts            # Express app setup
+├── index.ts          # Entry point
+└── server.ts         # Server startup
+```
+
+### Generated Files
+
+- `.env.example` - Environment variables template
+- `package.json` - Dependencies configured
+- `tsconfig.json` - TypeScript configuration
+- `.gitignore` - Git ignore rules
+- `README.md` - Project documentation
+
+## Quick Start After Generation
+
+```bash
+# 1. Navigate to project
+cd my-express-app
+
+# 2. Set up environment variables
+cp .env.example .env
+
+# 3. Configure MongoDB URI in .env
+# MONGODB_URI=mongodb://localhost:27017/your-db-name
+
+# 4. Start development server
+npm run dev
+
+# 5. Build for production
+npm run build
+npm start
+```
+
+## Environment Variables
+
+The `.env.example` file includes all available configuration options:
+
+- `NODE_ENV` - Application environment
+- `PORT` - Server port
+- `MONGODB_URI` - MongoDB connection string
+- `API_PREFIX` - API route prefix
+- `LOG_LEVEL` - Logging level
+- `CORS_ORIGIN` - CORS origin
+- And more...
+
+## API Examples
+
+### Success Response
+
+```json
+{
+  "status": "success",
+  "data": {...},
+  "message": "Retrieved successfully"
+}
+```
+
+### Error Response
+
+```json
+{
+  "status": "error",
+  "message": "Validation failed",
+  "errors": {...},
+  "statusCode": 422
+}
+```
+
+## Generating New Modules
+
+After project creation, generate new modules:
+
+```bash
+npm run generate-module <module-name>
+```
+
+This creates a complete CRUD module with:
+
+- Model
+- Service
+- Controller
+- Routes
+- Validation schema
+
+## Troubleshooting
+
+### Template Clone Failed
+
+- Ensure you have internet access
+- Check if the template repository is accessible
+- Verify the repository name is correct
+
+### Dependencies Installation Failed
+
+- Ensure you have Node.js >= 16.0.0 installed
+- Try running the package manager command manually
+- Check for permission issues
+
+### MongoDB Connection Failed
+
+- Ensure MongoDB is running
+- Verify `MONGODB_URI` in `.env` is correct
+- Check MongoDB connection permissions
+
+## Support
+
+For issues, questions, or suggestions, please visit the template repository:
+
+https://github.com/YOUR_GITHUB_USERNAME/express-mongo-starter
+
+## License
+
+MIT
+
+## Author
+
+Your Name
+
+---
+
+Built with ❤️ for developers

package/my-test/.env.example

@@ -0,0 +1,21 @@
+# Server Configuration
+NODE_ENV=development
+PORT=3000
+API_PREFIX=/api
+
+# Database Configuration
+MONGODB_URI=mongodb://localhost:27017/express-mongo-starter
+DB_MIN_POOL_SIZE=5
+DB_MAX_POOL_SIZE=10
+
+# Logging Configuration
+LOG_LEVEL=info
+ENABLE_FILE_LOGGING=false
+
+# Security & Rate Limiting
+CORS_ORIGIN=http://localhost:3000
+RATE_LIMIT_WINDOW_MS=900000 
+RATE_LIMIT_MAX_REQUESTS=100
+
+# Request Configuration
+REQUEST_BODY_LIMIT=10kb

package/my-test/README.md

@@ -0,0 +1,137 @@
+# Express MongoDB Starter Template
+
+A production-grade Express.js + MongoDB/Mongoose starter template with TypeScript, comprehensive error handling, Winston logging, Joi validation, and security best practices.
+
+## Features
+
+- ✅ **TypeScript** - Strict mode enabled
+- ✅ **Error Handling** - Centralized error middleware with standardized responses
+- ✅ **Response Handler** - Universal ApiResponseHandler with error/success/info methods
+- ✅ **Logging** - Winston logger with file rotation
+- ✅ **Validation** - Joi schema validation
+- ✅ **Security** - Helmet, CORS, Rate Limiting
+- ✅ **Database** - MongoDB with connection retry logic and graceful shutdown
+- ✅ **Async Handler** - Eliminate try-catch boilerplate
+- ✅ **Health Checks** - /health and /ready endpoints
+
+## Quick Start
+
+1. Clone this repository
+2. Install dependencies:
+
+   ```bash
+   npm install
+   # or
+   yarn install
+   # or
+   pnpm install
+   ```
+
+3. Copy `.env.example` to `.env` and configure:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+4. Start development server:
+
+   ```bash
+   npm run dev
+   ```
+
+5. Build for production:
+   ```bash
+   npm run build
+   npm start
+   ```
+
+## Project Structure
+
+```
+src/
+├── config/           # Configuration files
+│   ├── env.ts        # Environment variables
+│   ├── database.ts   # MongoDB connection
+│   └── winston-logger.ts  # Logger setup
+├── middleware/       # Express middleware
+│   ├── error.middleware.ts
+│   ├── auth.middleware.ts
+│   └── request-id.middleware.ts
+├── modules/          # Feature modules
+│   └── example/      # Example module
+│       ├── example.controller.ts
+│       ├── example.service.ts
+│       ├── example.model.ts
+│       ├── example.route.ts
+│       └── example.validation.ts
+├── utils/            # Utility functions
+│   ├── response.ts   # Response handler
+│   ├── asyncHandler.ts
+│   ├── apiError.ts
+│   └── validationMiddleware.ts
+├── app.ts            # Express app setup
+├── index.ts          # Entry point
+└── generate-module.ts # Module generator CLI
+```
+
+## API Response Format
+
+All endpoints return standardized responses:
+
+```typescript
+// Success Response
+{
+  "status": "success",
+  "data": {...},
+  "message": "Retrieved successfully"
+}
+
+// Error Response
+{
+  "status": "error",
+  "message": "Error message",
+  "errors": {...},
+  "statusCode": 400
+}
+
+// Info Response
+{
+  "status": "info",
+  "message": "Info message",
+  "data": {...}
+}
+```
+
+## Generating New Modules
+
+Generate a new module with all CRUD operations:
+
+```bash
+npm run generate-module <module-name>
+```
+
+This creates:
+
+- Controller
+- Service
+- Model
+- Routes
+- Validation schema
+
+## Environment Variables
+
+See `.env.example` for all available configuration options.
+
+## Error Handling
+
+Errors are automatically caught by the centralized error middleware and formatted consistently. Supports:
+
+- Mongoose validation errors
+- MongoDB duplicate key errors (11000)
+- JWT errors
+- Custom ApiError instances
+- Unhandled exceptions
+
+## License
+
+MIT

package/my-test/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "express-mongo-starter",
+  "version": "1.0.0",
+  "description": "Production-grade Express.js with MongoDB/Mongoose starter template",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "generate-module": "ts-node src/generate-module.ts"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.3.1",
+    "express": "^4.18.2",
+    "express-async-errors": "^3.1.1",
+    "express-rate-limit": "^7.1.5",
+    "express-validator": "^7.0.0",
+    "helmet": "^7.1.0",
+    "http-status-codes": "^2.3.0",
+    "joi": "^17.11.0",
+    "mongoose": "^8.1.0",
+    "morgan": "^1.10.0",
+    "uuid": "^13.0.0",
+    "winston": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^4.17.21",
+    "@types/morgan": "^1.9.10",
+    "@types/node": "^20.10.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/my-test/src/app.ts

@@ -0,0 +1,77 @@
+import express, { Express, Request, Response } from "express";
+import helmet from "helmet";
+import cors from "cors";
+import rateLimit from "express-rate-limit";
+import morgan from "morgan";
+import "express-async-errors";
+import { config } from "./config/env";
+import { errorMiddleware } from "./middleware/error.middleware";
+import { requestIdMiddleware } from "./middleware/request-id.middleware";
+import { logger } from "./config/winston-logger";
+import { ApiResponseHandler } from "./utils/response";
+
+export const createApp = (): Express => {
+  const app = express();
+
+  // Security middleware
+  app.use(helmet());
+  app.use(
+    cors({
+      origin: config.corsOrigin,
+      credentials: true,
+    }),
+  );
+
+  // Request ID middleware
+  app.use(requestIdMiddleware);
+
+  // Body parser middleware
+  app.use(express.json({ limit: config.requestBodyLimit }));
+  app.use(
+    express.urlencoded({ limit: config.requestBodyLimit, extended: true }),
+  );
+
+  // Rate limiting
+  const limiter = rateLimit({
+    windowMs: config.rateLimitWindowMs,
+    max: config.rateLimitMaxRequests,
+    message: "Too many requests from this IP, please try again later.",
+  });
+  app.use(limiter);
+
+  // Logging middleware
+  app.use(
+    morgan("combined", {
+      stream: {
+        write: (message) => logger.info(message.trim()),
+      },
+    }),
+  );
+
+  // Health check endpoints
+  app.get("/health", (req: Request, res: Response) => {
+    ApiResponseHandler.success(res, { status: "healthy" }, "Server is running");
+  });
+
+  app.get("/ready", (req: Request, res: Response) => {
+    ApiResponseHandler.success(res, { ready: true }, "Server is ready");
+  });
+
+  // API routes
+  app.use(config.apiPrefix, (req: Request, res: Response) => {
+    ApiResponseHandler.info(res, "API is running", {
+      version: "1.0.0",
+      apiPrefix: config.apiPrefix,
+    });
+  });
+
+  // 404 handler
+  app.use("*", (req: Request, res: Response) => {
+    ApiResponseHandler.error(res, "Route not found", 404);
+  });
+
+  // Error middleware (must be last)
+  app.use(errorMiddleware);
+
+  return app;
+};

package/my-test/src/config/database.ts

@@ -0,0 +1,54 @@
+import mongoose from "mongoose";
+import { config } from "./env";
+import { logger } from "./winston-logger";
+
+export const connectDatabase = async () => {
+  try {
+    const mongoOptions = {
+      minPoolSize: 5,
+      maxPoolSize: 10,
+    };
+
+    await mongoose.connect(config.mongodbUri, mongoOptions);
+
+    logger.info("Database connected successfully");
+
+    mongoose.connection.on("disconnected", () => {
+      logger.warn("Database disconnected");
+    });
+
+    mongoose.connection.on("error", (error) => {
+      logger.error("Database connection error:", error);
+    });
+
+    mongoose.connection.on("reconnected", () => {
+      logger.info("Database reconnected");
+    });
+  } catch (error: any) {
+    logger.error("Failed to connect to database:", error.message);
+    // Retry logic
+    const retryAttempts = 5;
+    for (let i = 1; i <= retryAttempts; i++) {
+      logger.info(`Retrying database connection (${i}/${retryAttempts})...`);
+      await new Promise((resolve) => setTimeout(resolve, 5000));
+      try {
+        await mongoose.connect(config.mongodbUri);
+        logger.info("Database connected successfully on retry");
+        return;
+      } catch (retryError: any) {
+        logger.error(`Retry attempt ${i} failed:`, retryError.message);
+      }
+    }
+    process.exit(1);
+  }
+};
+
+export const disconnectDatabase = async () => {
+  try {
+    await mongoose.disconnect();
+    logger.info("Database disconnected");
+  } catch (error: any) {
+    logger.error("Error disconnecting database:", error.message);
+    process.exit(1);
+  }
+};

package/my-test/src/config/env.ts

@@ -0,0 +1,42 @@
+import dotenv from "dotenv";
+
+dotenv.config();
+
+export interface IConfig {
+  port: number;
+  nodeEnv: string;
+  mongodbUri: string;
+  apiPrefix: string;
+  logLevel: string;
+  corsOrigin: string;
+  rateLimitWindowMs: number;
+  rateLimitMaxRequests: number;
+  requestBodyLimit: string;
+  enableFileLogging: boolean;
+}
+
+export const config: IConfig = {
+  port: parseInt(process.env.PORT || "3000"),
+  nodeEnv: process.env.NODE_ENV || "development",
+  mongodbUri:
+    process.env.MONGODB_URI ||
+    "mongodb://localhost:27017/express-mongo-starter",
+  apiPrefix: process.env.API_PREFIX || "/api",
+  logLevel: process.env.LOG_LEVEL || "info",
+  corsOrigin: process.env.CORS_ORIGIN || "http://localhost:3000",
+  rateLimitWindowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS || "900000"),
+  rateLimitMaxRequests: parseInt(process.env.RATE_LIMIT_MAX_REQUESTS || "100"),
+  requestBodyLimit: process.env.REQUEST_BODY_LIMIT || "10kb",
+  enableFileLogging: process.env.ENABLE_FILE_LOGGING === "true",
+};
+
+// Validate required environment variables in production
+if (config.nodeEnv === "production") {
+  const requiredVars = ["MONGODB_URI"];
+  const missingVars = requiredVars.filter((v) => !process.env[v]);
+  if (missingVars.length > 0) {
+    throw new Error(
+      `Missing required environment variables: ${missingVars.join(", ")}`,
+    );
+  }
+}

package/my-test/src/config/winston-logger.ts

@@ -0,0 +1,75 @@
+import winston from "winston";
+import path from "path";
+import { config } from "./env";
+
+const logsDir = path.join(process.cwd(), "logs");
+
+const levels = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3,
+};
+
+const colors = {
+  error: "red",
+  warn: "yellow",
+  info: "green",
+  debug: "blue",
+};
+
+winston.addColors(colors);
+
+const format = winston.format.combine(
+  winston.format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" }),
+  winston.format.printf(
+    (info) =>
+      `${info.timestamp} [${info.level}]: ${info.message}${info.error ? "\n" + info.error : ""}`,
+  ),
+);
+
+const transports: winston.transport[] = [
+  new winston.transports.Console({
+    format: winston.format.combine(
+      winston.format.colorize({ all: true }),
+      format,
+    ),
+  }),
+];
+
+if (config.nodeEnv === "production" || config.enableFileLogging) {
+  transports.push(
+    new winston.transports.File({
+      filename: path.join(logsDir, "error.log"),
+      level: "error",
+      format,
+      maxsize: 5242880,
+      maxFiles: 5,
+    }),
+    new winston.transports.File({
+      filename: path.join(logsDir, "combined.log"),
+      format,
+      maxsize: 5242880,
+      maxFiles: 5,
+    }),
+  );
+}
+
+export const logger = winston.createLogger({
+  level: config.logLevel || "info",
+  levels,
+  format,
+  transports,
+  exceptionHandlers: [
+    new winston.transports.File({
+      filename: path.join(logsDir, "exceptions.log"),
+    }),
+  ],
+  rejectionHandlers: [
+    new winston.transports.File({
+      filename: path.join(logsDir, "rejections.log"),
+    }),
+  ],
+});
+
+export default logger;

package/my-test/src/index.ts

@@ -0,0 +1,3 @@
+import { startServer } from "./server";
+
+startServer();