@ifecodes/backend-template 1.0.0

package/README.md

@@ -0,0 +1,288 @@
+# 🚀 Backend Template Generator
+
+A powerful CLI tool to generate production-ready Node.js + TypeScript backend applications with Express.js. Supports both monolith and microservice architectures with optional features like authentication, CORS, rate limiting, and more.
+
+---
+
+## 📦 Installation & Usage
+
+### Quick Start
+
+```bash
+npx @ifecodes/backend-template my-project
+```
+
+Or install globally:
+
+```bash
+npm install -g @ifecodes/backend-template
+ifecodes-template my-project
+```
+
+### With Arguments
+
+```bash
+# Create a monolith
+npx @ifecodes/backend-template my-api mono
+
+# Create a microservice
+npx @ifecodes/backend-template my-project micro
+```
+
+---
+
+## 🧠 Interactive Setup
+
+When you run the CLI, you'll be prompted to choose:
+
+### 1. **Project Type**
+- **Monolith API** - Traditional single-server architecture
+- **Microservice** - Distributed services with API Gateway
+
+### 2. **Deployment Mode** (Microservices only)
+- **Docker** - Container-based deployment with docker-compose
+- **PM2** - Process manager for Node.js applications
+
+### 3. **Optional Features**
+- ✅ **CORS** - Cross-Origin Resource Sharing
+- ✅ **Helmet** - Security headers middleware
+- ✅ **Rate Limiting** - API request throttling
+- ✅ **Morgan** - HTTP request logger
+
+### 4. **Authentication**
+- ✅ **JWT Authentication** with MongoDB
+- Choose between **bcrypt** (recommended for Windows) or **argon2** for password hashing
+
+---
+
+## 🗂 Project Structure
+
+### Monolith
+
+```
+my-backend/
+├── src/
+│   ├── config/         # Configuration files
+│   ├── middlewares/    # Custom middlewares
+│   ├── modules/        # Feature modules
+│   │   └── v1/         # API version 1
+│   │       ├── auth/   # Auth module (if enabled)
+│   │       └── health/ # Health check
+│   ├── models/         # Database models (if auth)
+│   ├── utils/          # Utility functions
+│   ├── app.ts          # Express app setup
+│   ├── routes.ts       # Route definitions
+│   └── server.ts       # Server entry point
+├── .husky/             # Git hooks
+├── .env                # Environment variables
+├── package.json
+└── tsconfig.json
+```
+
+### Microservice
+
+```
+my-project/
+├── shared/              # Shared utilities across services
+│   ├── config/         # Database, environment configs
+│   └── utils/          # Logger, error handlers
+├── services/
+│   ├── gateway/        # API Gateway (port 4000)
+│   ├── health-service/ # Health checks (port 4001)
+│   └── auth-service/   # Authentication (port 4002)
+├── docker-compose.yml  # Docker setup (if selected)
+├── pm2.config.js       # PM2 setup (if selected)
+├── .husky/             # Git hooks
+└── package.json        # Root package.json
+```
+
+---
+
+## ▶️ Running the Application
+
+### Monolith
+
+```bash
+cd my-backend
+
+# Development
+npm run dev
+
+# Production
+npm run build
+npm start
+```
+
+### Microservice (Docker)
+
+```bash
+cd my-project
+
+# Start all services
+docker-compose up
+
+# Start in detached mode
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Stop all services
+docker-compose down
+```
+
+### Microservice (PM2)
+
+```bash
+cd my-project
+
+# Start all services
+pm2 start pm2.config.js
+
+# View logs
+pm2 logs
+
+# Monitor services
+pm2 monit
+
+# Stop all services
+pm2 stop all
+```
+
+---
+
+## 🛠 Tech Stack
+
+- **Runtime**: Node.js (v18+)
+- **Language**: TypeScript
+- **Framework**: Express.js
+- **Database**: MongoDB (with Mongoose, if auth enabled)
+- **Authentication**: JWT + bcrypt/argon2
+- **Security**: Helmet, CORS, Rate Limiting
+- **Logging**: Morgan, Custom Logger
+- **Git Hooks**: Husky
+- **Deployment**: Docker or PM2
+
+---
+
+## 🌟 Features
+
+### ✅ Smart Defaults
+- Auto-generates README with project-specific instructions
+- Creates `.env` from `.env.example` with default values
+- Configures TypeScript paths for clean imports (`@/config`, `@/utils`)
+
+### ✅ Microservice Architecture
+- **API Gateway** on port 4000 (single entry point)
+- **Service Discovery** - Automatically routes to correct service
+- **Shared Folder** - Common utilities across all services
+- **Health Checks** - Built-in monitoring endpoints
+
+### ✅ Developer Experience
+- **Hot Reload** - Development server with nodemon
+- **ESLint** - Code quality enforcement
+- **Git Hooks** - Pre-commit linting with Husky
+- **Type Safety** - Full TypeScript support
+
+---
+
+## 📡 API Endpoints
+
+### Monolith
+
+```
+GET  /              - API information
+GET  /v1/health     - Health check
+POST /v1/auth/register - Register user (if auth enabled)
+POST /v1/auth/login    - Login user (if auth enabled)
+```
+
+### Microservice
+
+All requests go through the API Gateway at `http://localhost:4000`
+
+```
+GET  /health        - Health service
+POST /auth/register - Auth service (if enabled)
+POST /auth/login    - Auth service (if enabled)
+```
+
+---
+
+## 🔧 Environment Variables
+
+### Basic Setup
+
+```env
+PORT=4000
+NODE_ENV=development
+```
+
+### With CORS
+
+```env
+ALLOWED_ORIGIN=http://localhost:3000
+```
+
+### With Authentication
+
+```env
+MONGO_URI=mongodb://localhost:27017/your-database-name
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+```
+
+---
+
+## 🚀 Adding Services (Microservice)
+
+You can add more services to an existing microservice project:
+
+```bash
+cd my-project
+npx @ifecodes/backend-template
+
+# You'll be prompted to name the new service
+# Example: user-service, order-service, etc.
+```
+
+The CLI will:
+- Create the new service
+- Update `docker-compose.yml` or `pm2.config.js`
+- Configure routing in the API Gateway
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+### Development
+
+```bash
+git clone https://github.com/ALADETAN-IFE/backend-template.git
+cd backend-template
+npm install
+npm link
+```
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## ✨ Author
+
+**Aladetan Fortune Ifeloju (IfeCodes)**  
+Full Stack Developer & TechPreneur
+
+- GitHub: [@ALADETAN-IFE](https://github.com/ALADETAN-IFE)
+- Twitter: [@IfeCodes](https://twitter.com/IfeCodes_)
+
+---
+
+## 🙏 Acknowledgments
+
+Built with ❤️ for the developer community to accelerate backend development.

package/bin/cli.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import { getProjectConfig } from "./lib/prompts.js";
+import { setupService } from "./lib/service-setup.js";
+import { generateReadme } from "./lib/readme-generator.js";
+import {
+  generateDockerCompose,
+  generatePm2Config,
+  copyDockerfile,
+} from "./lib/microservice-config.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Get project configuration from user
+const config = await getProjectConfig();
+const {
+  sanitizedName,
+  target,
+  isExistingProject,
+  mode,
+  isInMicroserviceProject,
+} = config;
+
+const base = path.join(__dirname, "../template/base");
+
+// Determine which services to create
+const servicesToCreate = [];
+if (isInMicroserviceProject) {
+  const newServiceName = config.serviceName.replace(/\s+/g, "-");
+  servicesToCreate.push(newServiceName);
+} else if (config.projectType === "microservice") {
+  servicesToCreate.push("gateway");
+  servicesToCreate.push("health-service");
+  if (config.auth) {
+    servicesToCreate.push("auth-service");
+  }
+}
+
+// Validate and prepare project
+if (!isInMicroserviceProject && config.projectType === "microservice") {
+  if (isExistingProject) {
+    console.error(`\n❌ Error: Project '${sanitizedName}' already exists!`);
+    process.exit(1);
+  }
+  console.log(
+    `\n🏗️  Creating microservices: ${servicesToCreate.join(", ")}...\n`
+  );
+} else if (!isInMicroserviceProject && config.projectType === "monolith") {
+  if (isExistingProject) {
+    console.error(`\n❌ Error: Project '${sanitizedName}' already exists!`);
+    process.exit(1);
+  }
+  fs.cpSync(base, target, { recursive: true });
+} else if (isInMicroserviceProject) {
+  console.log(`\n🏗️  Adding service: ${servicesToCreate[0]}...\n`);
+}
+
+// Process services
+if (isInMicroserviceProject || config.projectType === "microservice") {
+  // Create shared folder for config and utils (only once)
+  if (!isInMicroserviceProject) {
+    const sharedDir = path.join(target, "shared");
+    if (!fs.existsSync(sharedDir)) {
+      console.log(`\n📦 Creating shared folder for config and utils...`);
+      fs.mkdirSync(sharedDir, { recursive: true });
+
+      // Copy config and utils from base template
+      const baseConfigDir = path.join(base, "src", "config");
+      const baseUtilsDir = path.join(base, "src", "utils");
+      const sharedConfigDir = path.join(sharedDir, "config");
+      const sharedUtilsDir = path.join(sharedDir, "utils");
+
+      fs.cpSync(baseConfigDir, sharedConfigDir, { recursive: true });
+      fs.cpSync(baseUtilsDir, sharedUtilsDir, { recursive: true });
+
+      // Create shared package.json
+      const sharedPackageJson = {
+        name: "@shared/common",
+        version: "1.0.0",
+        type: "module",
+        exports: {
+          "./config/*": "./config/*",
+          "./utils/*": "./utils/*",
+        },
+      };
+      fs.writeFileSync(
+        path.join(sharedDir, "package.json"),
+        JSON.stringify(sharedPackageJson, null, 2)
+      );
+    }
+  }
+
+  for (const serviceName of servicesToCreate) {
+    const serviceRoot = path.join(target, "services", serviceName);
+
+    if (fs.existsSync(serviceRoot)) {
+      console.error(`\n❌ Error: Service '${serviceName}' already exists!`);
+      process.exit(1);
+    }
+
+    console.log(`\n🔨 Setting up ${serviceName}...`);
+    fs.cpSync(base, serviceRoot, { recursive: true });
+
+    // Remove config and utils from service (they'll use shared) - except gateway handles it differently
+    if (serviceName !== "gateway") {
+      const serviceConfigDir = path.join(serviceRoot, "src", "config");
+      const serviceUtilsDir = path.join(serviceRoot, "src", "utils");
+      if (fs.existsSync(serviceConfigDir))
+        fs.rmSync(serviceConfigDir, { recursive: true });
+      if (fs.existsSync(serviceUtilsDir))
+        fs.rmSync(serviceUtilsDir, { recursive: true });
+    }
+  }
+
+  // Get all services first (needed for gateway routing)
+  const servicesDir = path.join(target, "services");
+  const allServices = fs.existsSync(servicesDir)
+    ? fs
+        .readdirSync(servicesDir)
+        .filter((f) => fs.statSync(path.join(servicesDir, f)).isDirectory())
+    : servicesToCreate;
+
+  // Now setup each service with knowledge of all services
+  for (const serviceName of servicesToCreate) {
+    const serviceRoot = path.join(target, "services", serviceName);
+    const shouldIncludeAuth = isInMicroserviceProject
+      ? config.auth
+      : serviceName === "auth-service";
+    await setupService(
+      config,
+      serviceName,
+      serviceRoot,
+      shouldIncludeAuth,
+      allServices
+    );
+  }
+
+  if (mode === "docker") {
+    generateDockerCompose(target, allServices);
+    copyDockerfile(target, servicesToCreate);
+  } else {
+    generatePm2Config(target, allServices);
+  }
+
+  // Create root package.json for microservice monorepo if it doesn't exist
+  const rootPackageJsonPath = path.join(target, "package.json");
+  if (!fs.existsSync(rootPackageJsonPath)) {
+    const rootPackageJson = {
+      name: sanitizedName,
+      version: "1.0.0",
+      private: true,
+      scripts: {
+        prepare: "husky install",
+      },
+      devDependencies: {
+        husky: "^8.0.3",
+      },
+    };
+    fs.writeFileSync(
+      rootPackageJsonPath,
+      JSON.stringify(rootPackageJson, null, 2) + "\n"
+    );
+  }
+} else {
+  await setupService(config, null, target, true);
+}
+
+// Generate README.md
+if (!isInMicroserviceProject) {
+  console.log("\n📝 Generating README.md...\n");
+  const readmeContent = generateReadme(config);
+  fs.writeFileSync(path.join(target, "README.md"), readmeContent);
+  
+  // Generate .env from .env.example for each service or root
+  console.log("📄 Setting up environment files...\n");
+  if (config.projectType === "microservice") {
+    const servicesDir = path.join(target, "services");
+    const allServices = fs.readdirSync(servicesDir).filter((f) => 
+      fs.statSync(path.join(servicesDir, f)).isDirectory()
+    );
+    
+    for (const service of allServices) {
+      const envExamplePath = path.join(servicesDir, service, ".env.example");
+      const envPath = path.join(servicesDir, service, ".env");
+      if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
+        fs.copyFileSync(envExamplePath, envPath);
+      }
+    }
+  } else {
+    const envExamplePath = path.join(target, ".env.example");
+    const envPath = path.join(target, ".env");
+    if (fs.existsSync(envExamplePath) && !fs.existsSync(envPath)) {
+      fs.copyFileSync(envExamplePath, envPath);
+    }
+  }
+}
+
+// Initialize git and Husky
+if (!isInMicroserviceProject) {
+  execSync("git init", { cwd: target, stdio: "inherit" });
+
+  // Install husky and setup at root level
+  if (config.projectType === "microservice") {
+    console.log("\n📦 Installing Husky at root level...\n");
+    execSync("npm install", { cwd: target, stdio: "inherit" });
+    console.log("\n🔧 Setting up Husky...\n");
+    execSync("npm run prepare", { cwd: target, stdio: "inherit" });
+  } else if (config.projectType === "monolith") {
+    console.log("\n🔧 Setting up Husky...\n");
+    execSync("npm run prepare", { cwd: target, stdio: "inherit" });
+  }
+}
+
+// Success messages
+const servicesDir = path.join(target, "services");
+const allServices = fs.existsSync(servicesDir)
+  ? fs
+      .readdirSync(servicesDir)
+      .filter((f) => fs.statSync(path.join(servicesDir, f)).isDirectory())
+  : servicesToCreate;
+
+if (isInMicroserviceProject) {
+  console.log(`\n✅ Service '${servicesToCreate[0]}' added successfully!`);
+  console.log(`\n📦 All services: ${allServices.join(", ")}`);
+  console.log(`\n💡 Next steps:`);
+  console.log(
+    mode === "docker"
+      ? `   1. Start services: docker-compose up`
+      : `   1. Start services: pm2 start pm2.config.js`
+  );
+} else if (config.projectType === "microservice") {
+  console.log("\n✅ Backend created successfully!");
+  console.log(`\n📦 Created services: ${servicesToCreate.join(", ")}`);
+  console.log(`\n💡 Next steps:`);
+  console.log(`   1. cd ${sanitizedName}`);
+  console.log(
+    mode === "docker"
+      ? `   2. Start services: docker-compose up`
+      : `   2. Start services: pm2 start pm2.config.js`
+  );
+} else {
+  console.log("\n✅ Backend created successfully!");
+  console.log(`\n💡 Next steps:`);
+  console.log(`   1. cd ${sanitizedName}`);
+  console.log(`   2. npm run dev`);
+}

package/bin/lib/microservice-config.js

@@ -0,0 +1,89 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const generateDockerCompose = (target, allServices) => {
+  const dockerCompose = {
+    version: "3.8",
+    services: {},
+  };
+
+  for (const serviceName of allServices) {
+    // Gateway runs on 4000, other services start from 4001
+    const isGateway = serviceName === "gateway";
+    const serviceIndex = allServices.indexOf(serviceName);
+    const port = isGateway ? 4000 : 4001 + allServices.filter((s, i) => s !== "gateway" && i < serviceIndex).length;
+    
+    dockerCompose.services[serviceName] = {
+      build: `./services/${serviceName}`,
+      ports: [
+        `\${${serviceName
+          .toUpperCase()
+          .replace(/-/g, "_")}_PORT:-${port}}:${isGateway ? 4000 : 4000}`,
+      ],
+      environment: [`NODE_ENV=\${NODE_ENV:-development}`],
+      volumes: [`./services/${serviceName}:/app`, `/app/node_modules`],
+    };
+  }
+
+  fs.writeFileSync(
+    path.join(target, "docker-compose.yml"),
+    `version: "${dockerCompose.version}"\nservices:\n` +
+      Object.entries(dockerCompose.services)
+        .map(
+          ([name, config]) =>
+            `  ${name}:\n` +
+            `    build: ${config.build}\n` +
+            `    ports:\n      - "${config.ports[0]}"\n` +
+            `    environment:\n      - ${config.environment[0]}\n` +
+            `    volumes:\n` +
+            config.volumes.map((v) => `      - ${v}`).join("\n")
+        )
+        .join("\n")
+  );
+};
+
+export const generatePm2Config = (target, allServices) => {
+  const pm2Config = {
+    apps: allServices.map((serviceName, index) => {
+      const isGateway = serviceName === "gateway";
+      const port = isGateway ? 4000 : 4001 + allServices.filter((s, i) => s !== "gateway" && i < index).length;
+      
+      return {
+        name: serviceName,
+        script: `./services/${serviceName}/src/server.ts`,
+        instances: 1,
+        exec_mode: "fork",
+        env: {
+          PORT: port
+        }
+      };
+    }),
+  };
+
+  fs.writeFileSync(
+    path.join(target, "pm2.config.js"),
+    `module.exports = ${JSON.stringify(pm2Config, null, 2)};\n`
+  );
+};
+
+export const copyDockerfile = (target, servicesToCreate) => {
+  const dockerfilePath = path.join(
+    __dirname,
+    "../../template/microservice/docker/Dockerfile"
+  );
+  
+  for (const serviceName of servicesToCreate) {
+    const serviceDockerfile = path.join(
+      target,
+      "services",
+      serviceName,
+      "Dockerfile"
+    );
+    if (!fs.existsSync(serviceDockerfile)) {
+      fs.copyFileSync(dockerfilePath, serviceDockerfile);
+    }
+  }
+};