@ifecodes/backend-template 1.0.0

package/bin/lib/service-setup.js

@@ -0,0 +1,316 @@
+import fs from "fs";
+import path from "path";
+import prompts from "prompts";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+
+export const setupService = async (
+  res,
+  serviceName,
+  serviceRoot,
+  shouldIncludeAuth,
+  allServices = []
+) => {
+  let imports = [];
+  let middlewares = [];
+  let deps = [];
+  let v1Imports = [];
+  let v1Routes = [];
+
+  // Special handling for gateway service
+  if (serviceName === "gateway") {
+    const gatewayModule = await import("../../template/gateway/inject.js");
+    deps.push(...gatewayModule.gatewayDeps);
+
+    // Copy gateway-specific files
+    const gatewayAppPath = path.join(serviceRoot, "src/app.ts");
+    const gatewayServerPath = path.join(serviceRoot, "src/server.ts");
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+    const gatewayAppContent = fs.readFileSync(
+      path.join(__dirname, "../../template/gateway/app.ts"),
+      "utf8"
+    );
+    const gatewayServerContent = fs.readFileSync(
+      path.join(__dirname, "../../template/gateway/server.ts"),
+      "utf8"
+    );
+
+    // Generate routes for all services
+    const routes = gatewayModule.generateGatewayRoutes(allServices);
+    const finalAppContent = gatewayAppContent.replace("/*__ROUTES__*/", routes);
+
+    fs.writeFileSync(gatewayAppPath, finalAppContent);
+    fs.writeFileSync(gatewayServerPath, gatewayServerContent);
+
+    // Remove unnecessary files for gateway
+    const routesPath = path.join(serviceRoot, "src/routes.ts");
+    const modulesPath = path.join(serviceRoot, "src/modules");
+    const middlewaresPath = path.join(serviceRoot, "src/middlewares");
+
+    if (fs.existsSync(routesPath)) fs.rmSync(routesPath);
+    if (fs.existsSync(modulesPath)) fs.rmSync(modulesPath, { recursive: true });
+    if (fs.existsSync(middlewaresPath))
+      fs.rmSync(middlewaresPath, { recursive: true });
+  } else {
+    // Regular service setup (existing code)
+    // Add features (only for monolith or health-service)
+    if (res.projectType === "monolith" || serviceName === "health-service") {
+      for (const f of res.features) {
+        const feature = await import(`../../template/features/${f}/inject.js`);
+        imports.push(feature.imports);
+        middlewares.push(feature.middleware);
+        deps.push(...feature.deps);
+      }
+    }
+
+    // Add authentication (only for monolith or auth-service)
+    if (shouldIncludeAuth && res.auth) {
+      const baseAuth = await import(
+        "../../template/features/auth/base/inject.js"
+      );
+      deps.push(...baseAuth.deps);
+
+      for (const file in baseAuth.files) {
+        const fullPath = path.join(serviceRoot, file);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, baseAuth.files[file]);
+      }
+
+      const algo = await prompts({
+        type: "select",
+        name: "hasher",
+        message: `Password hashing method${
+          serviceName ? ` for ${serviceName}` : ""
+        }`,
+        choices: [
+          { 
+            title: process.platform === "win32" 
+              ? "bcrypt (recommended for Windows)" 
+              : "argon2 (recommended)", 
+            value: process.platform === "win32" ? "bcrypt" : "argon2" 
+          },
+          { 
+            title: process.platform === "win32" 
+              ? "argon2 (requires build tools)" 
+              : "bcrypt", 
+            value: process.platform === "win32" ? "argon2" : "bcrypt" 
+          },
+        ],
+      });
+
+      const hashFeature = await import(
+        `../../template/features/auth/${algo.hasher}/inject.js`
+      );
+      deps.push(...hashFeature.deps);
+
+      for (const file in hashFeature.files) {
+        const fullPath = path.join(serviceRoot, file);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, hashFeature.files[file]);
+      }
+
+      v1Imports.push(baseAuth.imports);
+      v1Routes.push(baseAuth.middleware);
+    }
+
+    // Update app.ts
+    const appPath = path.join(serviceRoot, "src/app.ts");
+    let content = fs.readFileSync(appPath, "utf8");
+    content = content.replace("/*__IMPORTS__*/", imports.join("\n"));
+    // import env if cors is selected
+    if (res.features && res.features.includes("cors")) {
+        envContent = envContent.replace(
+          "/*__ENV_CORS__*/",
+          "import { ENV } from '@/config';"
+        );
+      }
+    content = content.replace("/*__MIDDLEWARE__*/", middlewares.join("\n"));
+    fs.writeFileSync(appPath, content);
+
+    // Update root endpoint middleware with project info
+    const rootMiddlewarePath = path.join(serviceRoot, "src/middlewares/root.middleware.ts");
+    if (fs.existsSync(rootMiddlewarePath)) {
+      let rootContent = fs.readFileSync(rootMiddlewarePath, "utf8");
+      rootContent = rootContent.replace("/*__PROJECT_NAME__*/", serviceName || res.sanitizedName);
+      rootContent = rootContent.replace("/*__PROJECT_TYPE__*/", res.projectType);
+      
+      // Add auth endpoint if auth is enabled
+      if (shouldIncludeAuth && res.auth) {
+        rootContent = rootContent.replace(
+          "/*__AUTH_ENDPOINT__*/",
+          'auth: "/v1/auth",'
+        );
+      } else {
+        rootContent = rootContent.replace("/*__AUTH_ENDPOINT__*/", "");
+      }
+      
+      fs.writeFileSync(rootMiddlewarePath, rootContent);
+    }
+
+    // Update v1 index.ts if needed
+    if (v1Imports.length || v1Routes.length) {
+      const v1IndexPath = path.join(serviceRoot, "src/modules/v1/index.ts");
+      let v1Content = fs.readFileSync(v1IndexPath, "utf8");
+
+      const lastImportIndex = v1Content.lastIndexOf("import");
+      const importEndIndex = v1Content.indexOf("\n", lastImportIndex) + 1;
+      v1Content =
+        v1Content.slice(0, importEndIndex) +
+        v1Imports.join("\n") +
+        "\n" +
+        v1Content.slice(importEndIndex);
+
+      const exportIndex = v1Content.lastIndexOf("export default");
+      v1Content =
+        v1Content.slice(0, exportIndex) +
+        v1Routes.join("\n") +
+        "\n\n" +
+        v1Content.slice(exportIndex);
+
+      fs.writeFileSync(v1IndexPath, v1Content);
+    }
+    
+    // Update env.ts to conditionally include ALLOWED_ORIGIN and MONGO_URI
+    const envPath = path.join(serviceRoot, "src/config/env.ts");
+    if (fs.existsSync(envPath)) {
+      let envContent = fs.readFileSync(envPath, "utf8");
+      
+      // Add ALLOWED_ORIGIN if CORS is selected
+      if (res.features && res.features.includes("cors")) {
+        envContent = envContent.replace(
+          "/*__ALLOWED_ORIGIN__*/",
+          'ALLOWED_ORIGIN: process.env.ALLOWED_ORIGIN!,'
+        );
+      } else {
+        envContent = envContent.replace("/*__ALLOWED_ORIGIN__*/", "");
+      }
+      
+      // Add MONGO_URI if auth is enabled
+      if (shouldIncludeAuth && res.auth) {
+        envContent = envContent.replace(
+          "/*__MONGO_URI__*/",
+          'MONGO_URI: process.env.MONGO_URI!,'
+        );
+      } else {
+        envContent = envContent.replace("/*__MONGO_URI__*/", "");
+      }
+      
+      fs.writeFileSync(envPath, envContent);
+    }
+    
+    // Update server.ts to connect to DB if auth is enabled
+    const serverPath = path.join(serviceRoot, "src/server.ts");
+    if (fs.existsSync(serverPath)) {
+      let serverContent = fs.readFileSync(serverPath, "utf8");
+      
+      if (shouldIncludeAuth && res.auth) {
+        serverContent = serverContent.replace(
+          "/*__DB_IMPORT__*/",
+          'import { connectDB } from "./config";'
+        );
+        serverContent = serverContent.replace(
+          "/*__DB_CONNECT__*/",
+          `// Connect to MongoDB
+await connectDB();`
+        );
+      } else {
+        serverContent = serverContent.replace("/*__DB_IMPORT__*/", "");
+        serverContent = serverContent.replace("/*__DB_CONNECT__*/", "");
+      }
+      
+      fs.writeFileSync(serverPath, serverContent);
+    }
+    
+    // Update .env.example to conditionally include environment variables
+    const envExamplePath = path.join(serviceRoot, ".env.example");
+    if (fs.existsSync(envExamplePath)) {
+      let envExampleContent = fs.readFileSync(envExamplePath, "utf8");
+      
+      // Add ALLOWED_ORIGIN if CORS is selected
+      if (res.features && res.features.includes("cors")) {
+        envExampleContent = envExampleContent.replace(
+          "/*__ALLOWED_ORIGIN_ENV__*/",
+          'ALLOWED_ORIGIN=http://localhost:3000'
+        );
+      } else {
+        envExampleContent = envExampleContent.replace("/*__ALLOWED_ORIGIN_ENV__*/", "");
+      }
+      
+      // Add MONGO_URI and JWT_SECRET if auth is enabled
+      if (shouldIncludeAuth && res.auth) {
+        envExampleContent = envExampleContent.replace(
+          "/*__MONGO_URI_ENV__*/",
+          'MONGO_URI=mongodb://localhost:27017/your-database-name'
+        );
+        envExampleContent = envExampleContent.replace(
+          "/*__JWT_SECRET_ENV__*/",
+          'JWT_SECRET=your-super-secret-jwt-key-change-this-in-production'
+        );
+      } else {
+        envExampleContent = envExampleContent.replace("/*__MONGO_URI_ENV__*/", "");
+        envExampleContent = envExampleContent.replace("/*__JWT_SECRET_ENV__*/", "");
+      }
+      
+      fs.writeFileSync(envExamplePath, envExampleContent);
+    }
+  } // End of else block for non-gateway services
+
+  // Update tsconfig.json for microservices to support @/ alias with shared folder
+  if (res.projectType === "microservice") {
+    const tsconfigPath = path.join(serviceRoot, "tsconfig.json");
+    let tsconfigContent = fs.readFileSync(tsconfigPath, "utf8");
+    
+    // Remove comments from JSON (strip-json-comments approach)
+    tsconfigContent = tsconfigContent
+      .replace(/\/\/.*$/gm, '') // Remove single-line comments
+      .replace(/\/\*[\s\S]*?\*\//g, ''); // Remove multi-line comments
+    
+    const tsconfig = JSON.parse(tsconfigContent);
+
+    // Update paths to include shared folder
+    tsconfig.compilerOptions.paths = {
+      "@/*": ["*"],
+      "@/config/*": ["../../shared/config/*"],
+      "@/utils/*": ["../../shared/utils/*"],
+    };
+
+    fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n");
+  }
+
+  // Update package.json
+  const packageJsonPath = path.join(serviceRoot, "package.json");
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  packageJson.name = serviceName || res.sanitizedName;
+  fs.writeFileSync(
+    packageJsonPath,
+    JSON.stringify(packageJson, null, 2) + "\n"
+  );
+
+  // Install dependencies
+  console.log(
+    `\n📦 Installing dependencies for ${serviceName || "project"}...\n`
+  );
+  
+  try {
+    if (deps.length) {
+      execSync(`npm install ${deps.join(" ")}`, {
+        cwd: serviceRoot,
+        stdio: "inherit",
+      });
+    }
+    execSync("npm install", { cwd: serviceRoot, stdio: "inherit" });
+  } catch (error) {
+    console.error("\n⚠️  Warning: Some dependencies failed to install.");
+    console.error("This is usually due to native modules (like argon2) requiring build tools.\n");
+    console.error("💡 Solutions:");
+    console.error("   1. Install build tools: npm install --global windows-build-tools");
+    console.error("   2. Or switch to bcrypt (works better on Windows)");
+    console.error("   3. Or manually install later: cd " + (serviceName || res.sanitizedName) + " && npm install\n");
+    
+    // Don't exit - let the project be created anyway
+    console.log("⏭️  Continuing with project creation...\n");
+  }
+
+  return deps;
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ifecodes/backend-template",
+  "version": "1.0.0",
+  "description": "Production-ready Express + TypeScript backend generator with optional features and microservice support",
+  "bin": {
+    "ifecodes-template": "bin/cli.js"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "template"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ALADETAN-IFE/backend-template.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ALADETAN-IFE/backend-template/issues"
+  },
+  "homepage": "https://github.com/ALADETAN-IFE/backend-template#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cli",
+    "template",
+    "boilerplate",
+    "typescript",
+    "backend",
+    "express",
+    "microservice",
+    "monolith",
+    "nodejs",
+    "generator",
+    "scaffold",
+    "docker",
+    "pm2",
+    "jwt",
+    "authentication"
+  ],
+  "license": "MIT",
+  "author": "Aladetan Fortune Ifeloju (IfeCodes) <ifecodes01@gmail.com>",
+  "dependencies": {
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/base/.env.example

@@ -0,0 +1,5 @@
+PORT=4000
+NODE_ENV=development
+/*__ALLOWED_ORIGIN_ENV__*/
+/*__MONGO_URI_ENV__*/
+/*__JWT_SECRET_ENV__*/

package/template/base/.eslintrc.json

@@ -0,0 +1,17 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": ["warn"],
+    "@typescript-eslint/no-explicit-any": "error"
+  }
+}

package/template/base/.husky/pre-commit

@@ -0,0 +1,13 @@
+set -e
+
+echo "Checking format (prettier)..."
+npm run check-format
+
+echo "Running TypeScript type-check..."
+npx tsc --noEmit
+
+echo "Checking lint..."
+npm run lint -- --max-warnings=0
+
+echo "Building project..."
+npm run build

package/template/base/.prettierignore

@@ -0,0 +1,47 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+.next/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+
+./dist
+
+/*.yml
+/*.yaml
+/*.md
+/*.json
+README.md
+eslint.config.ts

package/template/base/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "printWidth": 90,
+  "tabWidth": 2
+}

package/template/base/eslint.config.js

@@ -0,0 +1,33 @@
+const tsParser = require("@typescript-eslint/parser");
+const tsPlugin = require("@typescript-eslint/eslint-plugin");
+
+module.exports = [
+  // Files/paths to ignore (replaces .eslintignore usage in flat config)
+  {
+    ignores: ["node_modules/**", "dist/**"],
+  },
+
+  // TypeScript rules for source files
+  {
+    files: ["src/**/*.{ts,tsx}"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: __dirname,
+        ecmaVersion: 2020,
+        sourceType: "module",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+    },
+    rules: {
+      // Disallow explicit `any`
+      "@typescript-eslint/no-explicit-any": "error",
+
+      // You can add or tune more TypeScript rules here
+      "@typescript-eslint/explicit-module-boundary-types": "off",
+    },
+  },
+];

package/template/base/package.json

@@ -0,0 +1,32 @@
+{
+  "scripts": {
+    "dev": "ts-node-dev --respawn --transpile-only -r tsconfig-paths/register src/server.ts",
+    "start": "node dist/server.js",
+    "build": "tsc",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "format": "prettier --write \"src/**/*.{ts,json}\"",
+    "check-format": "prettier --check \"src/**/*.{ts,json}\"",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "dotenv": "^16.3.1",
+    "express": "^5.2.1",
+    "module-alias": "^2.2.3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.1",
+    "@typescript-eslint/parser": "^8.50.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "husky": "^9.1.7",
+    "prettier": "^3.7.4",
+    "ts-node-dev": "^2.0.0",
+    "tsconfig-paths": "^4.2.0",
+    "typescript": "^5.9.3"
+  },
+  "_moduleAliases": {
+    "@": "dist"
+  }
+}

package/template/base/src/app.ts

@@ -0,0 +1,9 @@
+import express from "express";
+/*__IMPORTS__*/
+/*__ENV_CORS__*/
+
+const app = express();
+
+/*__MIDDLEWARE__*/
+
+export default app;

package/template/base/src/config/db.ts

@@ -0,0 +1,4 @@
+// MongoDB connection will be added here when authentication is enabled
+export const connectDB = async () => {
+  // Database connection placeholder
+};

package/template/base/src/config/env.ts

@@ -0,0 +1,9 @@
+import dotenv from "dotenv";
+dotenv.config();
+
+export const ENV = {
+  PORT: process.env.PORT!,
+  /*__ALLOWED_ORIGIN__*/
+  NODE_ENV: process.env.NODE_ENV!,
+  /*__MONGO_URI__*/
+};

package/template/base/src/config/index.ts

@@ -0,0 +1,2 @@
+export { connectDB } from "./db";
+export { ENV } from "./env";

package/template/base/src/middlewares/index.ts

@@ -0,0 +1,3 @@
+export { default as methodNotAllowedHandler } from "./method-not-allowed.middleware";
+export { notFound } from "./not-found.middleware";
+export { rootHandler } from "./root.middleware";

package/template/base/src/middlewares/method-not-allowed.middleware.ts

@@ -0,0 +1,17 @@
+// middlewares/methodNotAllowed.ts
+import { Request, Response, NextFunction } from "express";
+
+const methodNotAllowed =
+  (allowedMethods: string[]) => (req: Request, res: Response, next: NextFunction) => {
+    if (!allowedMethods.includes(req.method)) {
+      res.set("Allow", allowedMethods.join(", "));
+      return res.status(405).json({
+        status: "error",
+        message: `Method ${req.method} not allowed for ${req.originalUrl}`,
+        allowed: allowedMethods,
+      });
+    }
+    next();
+  };
+
+export default methodNotAllowed;

package/template/base/src/middlewares/not-found.middleware.ts

@@ -0,0 +1,8 @@
+import { Request, Response } from "express";
+
+export const notFound = (req: Request, res: Response) => {
+  res.status(404).json({
+    status: "error",
+    message: `Route ${req.originalUrl} not found`,
+  });
+};

package/template/base/src/middlewares/root.middleware.ts

@@ -0,0 +1,14 @@
+import { Request, Response } from "express";
+
+export const rootHandler = (req: Request, res: Response) => {
+  res.json({
+    name: "/*__PROJECT_NAME__*/",
+    type: "/*__PROJECT_TYPE__*/",
+    version: "1.0.0",
+    status: "running",
+    endpoints: {
+      health: "/v1/health",
+      /*__AUTH_ENDPOINT__*/
+    },
+  });
+};

package/template/base/src/modules/index.ts

@@ -0,0 +1,8 @@
+import { Router } from "express";
+import V1Routes from "./v1";
+
+const router = Router();
+
+router.use("/v1", V1Routes);
+
+export default router;

package/template/base/src/modules/v1/health/health.controller.ts

@@ -0,0 +1,18 @@
+import { Request, Response } from "express";
+import { logger } from "@/utils";
+
+export const healthCheck = async (_: Request, res: Response) => {
+  logger.info("Health", "healthy");
+
+  return res.status(200).json({
+    status: "healthy",
+    uptime: process.uptime(),
+    timestamp: new Date().toISOString(),
+    services: {
+      memory: {
+        rss: process.memoryUsage().rss,
+        heapUsed: process.memoryUsage().heapUsed,
+      },
+    },
+  });
+};

package/template/base/src/modules/v1/health/health.route.ts

@@ -0,0 +1,9 @@
+import { Router } from "express";
+import { healthCheck } from "./health.controller";
+import { methodNotAllowedHandler } from "@/middlewares";
+
+const router = Router();
+router.use(methodNotAllowedHandler(["GET"]));
+router.get("/", healthCheck);
+
+export default router;

package/template/base/src/modules/v1/health/index.ts

@@ -0,0 +1 @@
+export { default as healthRoutes } from "./health.route";

package/template/base/src/modules/v1/index.ts

@@ -0,0 +1,8 @@
+import { Router } from "express";
+import { healthRoutes } from "./health";
+
+const router = Router();
+
+router.use("/health", healthRoutes);
+
+export default router;

package/template/base/src/routes.ts

@@ -0,0 +1,15 @@
+import { Router } from "express";
+import modulesRouter from "./modules";
+import { notFound, rootHandler } from "./middlewares";
+
+const router = Router();
+
+// Root endpoint
+router.get("/", rootHandler);
+
+router.use("/", modulesRouter);
+
+// 404 handler - must be last
+router.use(notFound);
+
+export default router;