create-xpressforge 1.0.0

package/README.md

@@ -0,0 +1,47 @@
+# create-xpressforge
+
+> Production-ready Node.js + Express project scaffolder
+
+[![npm version](https://img.shields.io/npm/v/create-xpressforge)](https://npmjs.com/package/create-xpressforge)
+[![license](https://img.shields.io/npm/l/create-xpressforge)](LICENSE)
+
+## Usage
+
+```bash
+npx create-xpressforge my-app
+```
+
+Or install globally:
+
+```bash
+npm install -g create-xpressforge
+create-xpressforge my-app
+```
+
+## What you get
+
+Interactive prompts let you choose:
+
+- **Structure** — MVC, Modular (feature-based), or Layered (controller/service/repository)
+- **Database** — MongoDB (Mongoose), PostgreSQL or MySQL (Prisma), or none
+- **Auth** — JWT with refresh tokens, Session, or none
+- **Extras** — Rate limiting, Helmet, CORS, Morgan, Validation, Multer, Socket.io, Swagger
+- **Language** — JavaScript (ES Modules) or TypeScript
+
+Every generated project includes:
+
+- Global error handler with Mongoose/Prisma/JWT error detection
+- Consistent `apiResponse` helper (`sendSuccess`, `sendError`, `sendPaginated`)
+- Custom logger utility
+- 404 not-found middleware
+- Working User CRUD example
+- `.env` + `.env.example` with all variables listed
+- Auto-generated README with your stack details
+
+## Author
+
+Hammad Sadi <hammad.sadi@yahoo.com>
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/index.js';
+
+run();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "create-xpressforge",
+  "version": "1.0.0",
+  "description": "Production-ready Node.js + Express project scaffolder — MVC, Modular, Layered structures with DB, Auth & more",
+  "author": "Hammad Sadi <hammad.sadi@yahoo.com>",
+  "license": "MIT",
+  "bin": {
+    "create-xpressforge": "./bin/cli.js"
+  },
+  "main": "./src/index.js",
+  "keywords": [
+    "express",
+    "nodejs",
+    "scaffold",
+    "cli",
+    "mvc",
+    "modular",
+    "boilerplate",
+    "generator",
+    "production",
+    "mongodb",
+    "postgresql",
+    "jwt"
+  ],
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^5.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "fs-extra": "^11.2.0",
+    "gradient-string": "^2.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hammadsadi/create-xpressforge"
+  },
+  "homepage": "https://github.com/hammadsadi/create-xpressforge#readme",
+  "bugs": {
+    "url": "https://github.com/hammadsadi/create-xpressforge/issues"
+  }
+}

package/src/generators/appGenerator.js

@@ -0,0 +1,65 @@
+export function generateAppJs(answers) {
+  const { extras, database, auth, structure } = answers;
+
+  const imports = [
+    `import express from 'express';`,
+    extras.includes('cors')      ? `import cors from 'cors';`                   : '',
+    extras.includes('helmet')    ? `import helmet from 'helmet';`               : '',
+    extras.includes('morgan')    ? `import morgan from 'morgan';`               : '',
+    extras.includes('rateLimit') ? `import rateLimit from 'express-rate-limit';` : '',
+    extras.includes('swagger')   ? `import swaggerUi from 'swagger-ui-express';\nimport { swaggerSpec } from './config/swagger.js';` : '',
+    database !== 'none'          ? `import { connectDB } from './config/db.js';` : '',
+    `import { errorHandler } from './middlewares/errorHandler.js';`,
+    `import { notFound } from './middlewares/notFound.js';`,
+    structure === 'mvc'      ? `import routes from './routes/index.js';`   : '',
+    structure === 'modular'  ? `import routes from './routes/index.js';`   : '',
+    structure === 'layered'  ? `import routes from './routes/index.js';`   : '',
+  ].filter(Boolean).join('\n');
+
+  const dbInit = database !== 'none' ? `\n// Connect to database\nconnectDB();\n` : '';
+
+  const rateLimitMiddleware = extras.includes('rateLimit') ? `
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100,
+  message: { success: false, message: 'Too many requests, please try again later' },
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+app.use('/api', limiter);
+` : '';
+
+  const middlewares = [
+    extras.includes('helmet')  ? `app.use(helmet());`                   : '',
+    extras.includes('cors')    ? `app.use(cors({ origin: process.env.CLIENT_URL || '*', credentials: true }));` : '',
+    `app.use(express.json({ limit: '10mb' }));`,
+    `app.use(express.urlencoded({ extended: true, limit: '10mb' }));`,
+    extras.includes('morgan')  ? `app.use(morgan(process.env.NODE_ENV === 'development' ? 'dev' : 'combined'));` : '',
+  ].filter(Boolean).join('\n');
+
+  const swaggerSetup = extras.includes('swagger') ? `\n// API Documentation\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));\n` : '';
+
+  const healthCheck = `
+// Health check
+app.get('/health', (req, res) => {
+  res.json({ success: true, message: 'Server is healthy', timestamp: new Date().toISOString() });
+});
+`;
+
+  return `${imports}
+${dbInit}
+const app = express();
+${rateLimitMiddleware}
+// Middlewares
+${middlewares}
+${swaggerSetup}${healthCheck}
+// Routes
+app.use('/api/v1', routes);
+
+// Error handlers
+app.use(notFound);
+app.use(errorHandler);
+
+export default app;
+`;
+}

package/src/generators/authGenerator.js

@@ -0,0 +1,210 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+export async function generateAuthFiles(answers, targetDir, ext) {
+  const { auth, database } = answers;
+
+  if (auth === 'jwt') {
+    // JWT middleware
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'middlewares', `authenticate.${ext}`),
+      jwtMiddleware()
+    );
+
+    // Auth controller
+    await fs.ensureDir(path.join(targetDir, 'src', 'controllers'));
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'controllers', `authController.${ext}`),
+      authController(database)
+    );
+
+    // Auth routes
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'routes', `authRoutes.${ext}`),
+      authRoutes()
+    );
+
+    // User model (if DB)
+    if (database === 'mongodb') {
+      await fs.writeFile(
+        path.join(targetDir, 'src', 'models', `User.${ext}`),
+        userModelMongo()
+      );
+    }
+  }
+
+  if (auth === 'session') {
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'middlewares', `sessionAuth.${ext}`),
+      sessionMiddleware()
+    );
+  }
+}
+
+function jwtMiddleware() {
+  return `import jwt from 'jsonwebtoken';
+import { env } from '../config/env.js';
+
+export const authenticate = (req, res, next) => {
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({ success: false, message: 'No token provided' });
+  }
+
+  const token = authHeader.split(' ')[1];
+  try {
+    const decoded = jwt.verify(token, env.JWT_SECRET);
+    req.user = decoded;
+    next();
+  } catch (err) {
+    return res.status(401).json({ success: false, message: err.name === 'TokenExpiredError' ? 'Token expired' : 'Invalid token' });
+  }
+};
+
+export const authorize = (...roles) => (req, res, next) => {
+  if (!roles.includes(req.user?.role)) {
+    return res.status(403).json({ success: false, message: 'Access denied' });
+  }
+  next();
+};
+`;
+}
+
+function authController(database) {
+  const userImport = database === 'mongodb'
+    ? `import User from '../models/User.js';`
+    : `import { prisma } from '../config/db.js';`;
+
+  return `import jwt from 'jsonwebtoken';
+import bcrypt from 'bcryptjs';
+${userImport}
+import { env } from '../config/env.js';
+import { sendSuccess, sendError } from '../utils/apiResponse.js';
+
+const signToken = (payload, secret, expiresIn) =>
+  jwt.sign(payload, secret, { expiresIn });
+
+export const register = async (req, res, next) => {
+  try {
+    const { name, email, password } = req.body;
+
+    const existing = await ${database === 'mongodb' ? 'User.findOne({ email })' : 'prisma.user.findUnique({ where: { email } })'};
+    if (existing) return sendError(res, 'Email already registered', 409);
+
+    const hashed = await bcrypt.hash(password, 12);
+    const user = await ${database === 'mongodb'
+      ? 'User.create({ name, email, password: hashed })'
+      : 'prisma.user.create({ data: { name, email, password: hashed } })'};
+
+    const accessToken  = signToken({ id: user._id || user.id, role: user.role }, env.JWT_SECRET, env.JWT_EXPIRES_IN);
+    const refreshToken = signToken({ id: user._id || user.id }, env.JWT_REFRESH_SECRET, env.JWT_REFRESH_EXPIRES_IN);
+
+    sendSuccess(res, { accessToken, refreshToken, user: { id: user._id || user.id, name: user.name, email: user.email } }, 'Registered successfully', 201);
+  } catch (err) { next(err); }
+};
+
+export const login = async (req, res, next) => {
+  try {
+    const { email, password } = req.body;
+
+    const user = await ${database === 'mongodb'
+      ? 'User.findOne({ email }).select(\'+password\')'
+      : 'prisma.user.findUnique({ where: { email } })'};
+    if (!user || !(await bcrypt.compare(password, user.password))) {
+      return sendError(res, 'Invalid email or password', 401);
+    }
+
+    const accessToken  = signToken({ id: user._id || user.id, role: user.role }, env.JWT_SECRET, env.JWT_EXPIRES_IN);
+    const refreshToken = signToken({ id: user._id || user.id }, env.JWT_REFRESH_SECRET, env.JWT_REFRESH_EXPIRES_IN);
+
+    sendSuccess(res, { accessToken, refreshToken, user: { id: user._id || user.id, name: user.name, email: user.email } }, 'Login successful');
+  } catch (err) { next(err); }
+};
+
+export const refreshToken = async (req, res, next) => {
+  try {
+    const { token } = req.body;
+    if (!token) return sendError(res, 'Refresh token required', 401);
+
+    const decoded = jwt.verify(token, env.JWT_REFRESH_SECRET);
+    const accessToken = signToken({ id: decoded.id }, env.JWT_SECRET, env.JWT_EXPIRES_IN);
+    sendSuccess(res, { accessToken }, 'Token refreshed');
+  } catch (err) { next(err); }
+};
+
+export const getMe = async (req, res, next) => {
+  try {
+    const user = await ${database === 'mongodb'
+      ? 'User.findById(req.user.id).select(\'-password\')'
+      : 'prisma.user.findUnique({ where: { id: req.user.id }, select: { id: true, name: true, email: true, role: true, createdAt: true } })'};
+    if (!user) return sendError(res, 'User not found', 404);
+    sendSuccess(res, user);
+  } catch (err) { next(err); }
+};
+`;
+}
+
+function authRoutes() {
+  return `import { Router } from 'express';
+import { register, login, refreshToken, getMe } from '../controllers/authController.js';
+import { authenticate } from '../middlewares/authenticate.js';
+
+const router = Router();
+
+router.post('/register', register);
+router.post('/login',    login);
+router.post('/refresh',  refreshToken);
+router.get('/me',        authenticate, getMe);
+
+export default router;
+`;
+}
+
+function userModelMongo() {
+  return `import mongoose from 'mongoose';
+
+const userSchema = new mongoose.Schema({
+  name: {
+    type: String,
+    required: [true, 'Name is required'],
+    trim: true,
+    minlength: 2,
+    maxlength: 50,
+  },
+  email: {
+    type: String,
+    required: [true, 'Email is required'],
+    unique: true,
+    lowercase: true,
+    trim: true,
+    match: [/^\\S+@\\S+\\.\\S+$/, 'Invalid email format'],
+  },
+  password: {
+    type: String,
+    required: [true, 'Password is required'],
+    minlength: 6,
+    select: false,
+  },
+  role: {
+    type: String,
+    enum: ['user', 'admin'],
+    default: 'user',
+  },
+}, { timestamps: true });
+
+userSchema.index({ email: 1 });
+
+const User = mongoose.model('User', userSchema);
+export default User;
+`;
+}
+
+function sessionMiddleware() {
+  return `export const requireAuth = (req, res, next) => {
+  if (!req.session?.userId) {
+    return res.status(401).json({ success: false, message: 'Not authenticated' });
+  }
+  next();
+};
+`;
+}

package/src/generators/dbGenerator.js

@@ -0,0 +1,75 @@
+export function generateDbConfig(answers) {
+  const { database } = answers;
+
+  if (database === 'mongodb') {
+    return `import mongoose from 'mongoose';
+import { logger } from '../utils/logger.js';
+
+const MAX_RETRIES = 5;
+let retries = 0;
+
+export const connectDB = async () => {
+  try {
+    const conn = await mongoose.connect(process.env.MONGO_URI, {
+      serverSelectionTimeoutMS: 5000,
+    });
+    logger.info(\`MongoDB connected: \${conn.connection.host}\`);
+    retries = 0;
+  } catch (err) {
+    retries++;
+    logger.error(\`MongoDB connection failed (attempt \${retries}/\${MAX_RETRIES}): \${err.message}\`);
+    if (retries < MAX_RETRIES) {
+      logger.info(\`Retrying in 5 seconds...\`);
+      setTimeout(connectDB, 5000);
+    } else {
+      logger.error('Max retries reached. Exiting...');
+      process.exit(1);
+    }
+  }
+};
+
+mongoose.connection.on('disconnected', () => {
+  logger.warn('MongoDB disconnected. Attempting reconnect...');
+  connectDB();
+});
+
+process.on('SIGINT', async () => {
+  await mongoose.connection.close();
+  logger.info('MongoDB connection closed due to app termination');
+  process.exit(0);
+});
+`;
+  }
+
+  if (database === 'postgresql' || database === 'mysql') {
+    return `import { PrismaClient } from '@prisma/client';
+import { logger } from '../utils/logger.js';
+
+const globalForPrisma = globalThis;
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient({
+  log: process.env.NODE_ENV === 'development'
+    ? ['query', 'info', 'warn', 'error']
+    : ['error'],
+});
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+
+export const connectDB = async () => {
+  try {
+    await prisma.$connect();
+    logger.info('Database connected via Prisma');
+  } catch (err) {
+    logger.error('Database connection failed: ' + err.message);
+    process.exit(1);
+  }
+};
+
+process.on('beforeExit', async () => {
+  await prisma.$disconnect();
+});
+`;
+  }
+
+  return '';
+}

package/src/generators/envGenerator.js

@@ -0,0 +1,59 @@
+export function generateEnv(answers) {
+  const { database, auth, extras, projectName } = answers;
+
+  let content = `# App
+NODE_ENV=development
+PORT=3000
+CLIENT_URL=http://localhost:3000
+
+`;
+
+  if (database === 'mongodb') {
+    content += `# MongoDB
+MONGO_URI=mongodb://localhost:27017/${projectName}
+
+`;
+  }
+
+  if (database === 'postgresql') {
+    content += `# PostgreSQL (Prisma)
+DATABASE_URL=postgresql://user:password@localhost:5432/${projectName}?schema=public
+
+`;
+  }
+
+  if (database === 'mysql') {
+    content += `# MySQL (Prisma)
+DATABASE_URL=mysql://user:password@localhost:3306/${projectName}
+
+`;
+  }
+
+  if (auth === 'jwt') {
+    content += `# JWT
+JWT_SECRET=your_super_secret_jwt_key_change_this_in_production
+JWT_EXPIRES_IN=7d
+JWT_REFRESH_SECRET=your_super_secret_refresh_key_change_this_too
+JWT_REFRESH_EXPIRES_IN=30d
+
+`;
+  }
+
+  if (auth === 'session') {
+    content += `# Session
+SESSION_SECRET=your_session_secret_change_this_in_production
+SESSION_MAX_AGE=86400000
+
+`;
+  }
+
+  if (extras.includes('multer')) {
+    content += `# File Upload
+MAX_FILE_SIZE=5242880
+UPLOAD_DIR=uploads
+
+`;
+  }
+
+  return content.trimEnd() + '\n';
+}

package/src/generators/packageJsonGenerator.js

@@ -0,0 +1,70 @@
+export function generatePackageJson(answers) {
+  const { projectName, database, auth, extras, language } = answers;
+
+  const deps = {
+    express: '^5.0.0',
+  };
+
+  const devDeps = {
+    nodemon: '^3.1.0',
+  };
+
+  if (database === 'mongodb')    deps['mongoose']         = '^8.0.0';
+  if (database === 'postgresql' || database === 'mysql') {
+    deps['@prisma/client'] = '^5.0.0';
+    devDeps['prisma']      = '^5.0.0';
+  }
+
+  if (auth === 'jwt')     { deps['jsonwebtoken'] = '^9.0.0'; deps['bcryptjs'] = '^2.4.3'; }
+  if (auth === 'session') { deps['express-session'] = '^1.18.0'; deps['connect-mongo'] = '^5.1.0'; }
+
+  if (extras.includes('cors'))       deps['cors']                = '^2.8.5';
+  if (extras.includes('helmet'))     deps['helmet']              = '^7.1.0';
+  if (extras.includes('morgan'))     deps['morgan']              = '^1.10.0';
+  if (extras.includes('rateLimit'))  deps['express-rate-limit']  = '^7.0.0';
+  if (extras.includes('validation')) deps['express-validator']   = '^7.0.0';
+  if (extras.includes('multer'))     deps['multer']              = '^1.4.5';
+  if (extras.includes('socket'))     deps['socket.io']           = '^4.7.0';
+  if (extras.includes('swagger')) {
+    deps['swagger-ui-express'] = '^5.0.0';
+    deps['swagger-jsdoc']      = '^6.2.8';
+  }
+
+  deps['dotenv'] = '^16.4.0';
+
+  if (language === 'ts') {
+    devDeps['typescript']           = '^5.4.0';
+    devDeps['tsx']                  = '^4.7.0';
+    devDeps['@types/node']          = '^20.0.0';
+    devDeps['@types/express']       = '^5.0.0';
+    if (deps['cors'])           devDeps['@types/cors']         = '^2.8.17';
+    if (deps['morgan'])         devDeps['@types/morgan']       = '^1.9.9';
+    if (deps['bcryptjs'])       devDeps['@types/bcryptjs']     = '^2.4.6';
+    if (deps['jsonwebtoken'])   devDeps['@types/jsonwebtoken'] = '^9.0.6';
+    if (deps['multer'])         devDeps['@types/multer']       = '^1.4.11';
+  }
+
+  const scripts = language === 'ts'
+    ? {
+        dev:   'tsx watch server.ts',
+        build: 'tsc',
+        start: 'node dist/server.js',
+        lint:  'tsc --noEmit',
+      }
+    : {
+        dev:   'nodemon server.js',
+        start: 'node server.js',
+      };
+
+  return {
+    name: projectName,
+    version: '1.0.0',
+    description: '',
+    type: 'module',
+    main: language === 'ts' ? 'dist/server.js' : 'server.js',
+    scripts,
+    dependencies: deps,
+    devDependencies: devDeps,
+    engines: { node: '>=18.0.0' },
+  };
+}

package/src/generators/projectGenerator.js

@@ -0,0 +1,275 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { generatePackageJson } from './packageJsonGenerator.js';
+import { generateEnv } from './envGenerator.js';
+import { generateAppJs } from './appGenerator.js';
+import { generateDbConfig } from './dbGenerator.js';
+import { generateAuthFiles } from './authGenerator.js';
+import { generateStructure } from './structureGenerator.js';
+import { generateReadme } from './readmeGenerator.js';
+
+export async function generateProject(answers, targetDir) {
+  const spinner = ora({ text: 'Creating project...', color: 'cyan' }).start();
+
+  try {
+    // 1. Check if directory exists
+    if (await fs.pathExists(targetDir)) {
+      spinner.fail(chalk.red(`Directory "${answers.projectName}" already exists!`));
+      process.exit(1);
+    }
+
+    await fs.ensureDir(targetDir);
+    spinner.text = 'Scaffolding folder structure...';
+
+    // 2. Generate folder structure based on chosen pattern
+    await generateStructure(answers, targetDir);
+    spinner.text = 'Writing configuration files...';
+
+    // 3. package.json
+    const pkg = generatePackageJson(answers);
+    await fs.writeJson(path.join(targetDir, 'package.json'), pkg, { spaces: 2 });
+
+    // 4. .env + .env.example
+    const envContent = generateEnv(answers);
+    await fs.writeFile(path.join(targetDir, '.env'), envContent);
+    await fs.writeFile(path.join(targetDir, '.env.example'), envContent.replace(/=.+/gm, '='));
+
+    // 5. .gitignore
+    await fs.writeFile(path.join(targetDir, '.gitignore'), gitignoreContent());
+
+    // 6. app.js / app.ts
+    const appContent = generateAppJs(answers);
+    const ext = answers.language === 'ts' ? 'ts' : 'js';
+    await fs.writeFile(path.join(targetDir, 'src', `app.${ext}`), appContent);
+
+    // 7. server.js entry
+    await fs.writeFile(path.join(targetDir, `server.${ext}`), serverContent(answers));
+
+    // 8. DB config
+    if (answers.database !== 'none') {
+      spinner.text = 'Setting up database connection...';
+      const dbContent = generateDbConfig(answers);
+      await fs.writeFile(path.join(targetDir, 'src', 'config', `db.${ext}`), dbContent);
+    }
+
+    // 9. env config
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'config', `env.${ext}`),
+      envConfigContent(answers)
+    );
+
+    // 10. Auth files
+    if (answers.auth !== 'none') {
+      spinner.text = 'Generating auth files...';
+      await generateAuthFiles(answers, targetDir, ext);
+    }
+
+    // 11. Utils
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'utils', `apiResponse.${ext}`),
+      apiResponseContent()
+    );
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'utils', `logger.${ext}`),
+      loggerContent()
+    );
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'middlewares', `errorHandler.${ext}`),
+      errorHandlerContent()
+    );
+    await fs.writeFile(
+      path.join(targetDir, 'src', 'middlewares', `notFound.${ext}`),
+      notFoundContent()
+    );
+
+    // 12. TypeScript config
+    if (answers.language === 'ts') {
+      await fs.writeJson(path.join(targetDir, 'tsconfig.json'), tsConfig(), { spaces: 2 });
+    }
+
+    // 13. README
+    spinner.text = 'Generating README...';
+    const readme = generateReadme(answers);
+    await fs.writeFile(path.join(targetDir, 'README.md'), readme);
+
+    spinner.succeed(chalk.green('Project created successfully!'));
+
+    // Success message
+    console.log('\n' + chalk.bold('  Next steps:\n'));
+    console.log(chalk.cyan(`  cd ${answers.projectName}`));
+    console.log(chalk.cyan('  npm install'));
+    if (answers.database === 'postgresql' || answers.database === 'mysql') {
+      console.log(chalk.cyan('  npx prisma migrate dev'));
+    }
+    console.log(chalk.cyan('  cp .env.example .env  # fill in your values'));
+    console.log(chalk.cyan('  npm run dev\n'));
+    console.log(chalk.dim('  Happy building! — create-xpressforge by Hammad Sadi\n'));
+
+  } catch (err) {
+    spinner.fail(chalk.red('Failed to create project'));
+    await fs.remove(targetDir).catch(() => {});
+    throw err;
+  }
+}
+
+function gitignoreContent() {
+  return `node_modules/
+.env
+dist/
+build/
+*.log
+.DS_Store
+coverage/
+.nyc_output/
+`;
+}
+
+function serverContent(answers) {
+  const ext = answers.language === 'ts' ? "import app from './src/app.js';" : "import app from './src/app.js';";
+  return `${ext}
+import { env } from './src/config/env.js';
+
+const PORT = env.PORT || 3000;
+
+app.listen(PORT, () => {
+  console.log(\`Server running on http://localhost:\${PORT}\`);
+  console.log(\`Environment: \${env.NODE_ENV}\`);
+});
+`;
+}
+
+function envConfigContent(answers) {
+  return `export const env = {
+  PORT: process.env.PORT || 3000,
+  NODE_ENV: process.env.NODE_ENV || 'development',
+${answers.database === 'mongodb' ? `  MONGO_URI: process.env.MONGO_URI,\n` : ''}${answers.database === 'postgresql' || answers.database === 'mysql' ? `  DATABASE_URL: process.env.DATABASE_URL,\n` : ''}${answers.auth === 'jwt' ? `  JWT_SECRET: process.env.JWT_SECRET,\n  JWT_EXPIRES_IN: process.env.JWT_EXPIRES_IN || '7d',\n  JWT_REFRESH_SECRET: process.env.JWT_REFRESH_SECRET,\n  JWT_REFRESH_EXPIRES_IN: process.env.JWT_REFRESH_EXPIRES_IN || '30d',\n` : ''}};
+`;
+}
+
+function apiResponseContent() {
+  return `/**
+ * Consistent API response helper
+ */
+export const sendSuccess = (res, data = null, message = 'Success', statusCode = 200) => {
+  return res.status(statusCode).json({
+    success: true,
+    message,
+    data,
+  });
+};
+
+export const sendError = (res, message = 'Something went wrong', statusCode = 500, errors = null) => {
+  return res.status(statusCode).json({
+    success: false,
+    message,
+    ...(errors && { errors }),
+  });
+};
+
+export const sendPaginated = (res, data, pagination) => {
+  return res.status(200).json({
+    success: true,
+    data,
+    pagination: {
+      total: pagination.total,
+      page: pagination.page,
+      limit: pagination.limit,
+      totalPages: Math.ceil(pagination.total / pagination.limit),
+    },
+  });
+};
+`;
+}
+
+function loggerContent() {
+  return `import { env } from '../config/env.js';
+
+const levels = { error: 0, warn: 1, info: 2, debug: 3 };
+const colors = { error: '\\x1b[31m', warn: '\\x1b[33m', info: '\\x1b[36m', debug: '\\x1b[35m', reset: '\\x1b[0m' };
+
+const log = (level, message, meta = {}) => {
+  if (env.NODE_ENV === 'test') return;
+  const timestamp = new Date().toISOString();
+  const color = colors[level] || '';
+  const metaStr = Object.keys(meta).length ? ' ' + JSON.stringify(meta) : '';
+  console.log(\`\${color}[\${timestamp}] [\${level.toUpperCase()}] \${message}\${metaStr}\${colors.reset}\`);
+};
+
+export const logger = {
+  error: (msg, meta) => log('error', msg, meta),
+  warn:  (msg, meta) => log('warn',  msg, meta),
+  info:  (msg, meta) => log('info',  msg, meta),
+  debug: (msg, meta) => log('debug', msg, meta),
+};
+`;
+}
+
+function errorHandlerContent() {
+  return `import { logger } from '../utils/logger.js';
+import { env } from '../config/env.js';
+
+export const errorHandler = (err, req, res, next) => {
+  let statusCode = err.statusCode || err.status || 500;
+  let message = err.message || 'Internal Server Error';
+
+  // Mongoose duplicate key
+  if (err.code === 11000) {
+    statusCode = 409;
+    const field = Object.keys(err.keyValue || {})[0];
+    message = \`\${field} already exists\`;
+  }
+
+  // Mongoose validation error
+  if (err.name === 'ValidationError') {
+    statusCode = 422;
+    message = Object.values(err.errors).map(e => e.message).join(', ');
+  }
+
+  // JWT errors
+  if (err.name === 'JsonWebTokenError') { statusCode = 401; message = 'Invalid token'; }
+  if (err.name === 'TokenExpiredError')  { statusCode = 401; message = 'Token expired'; }
+
+  logger.error(message, { statusCode, path: req.path, method: req.method });
+
+  res.status(statusCode).json({
+    success: false,
+    message,
+    ...(env.NODE_ENV === 'development' && { stack: err.stack }),
+  });
+};
+`;
+}
+
+function notFoundContent() {
+  return `export const notFound = (req, res) => {
+  res.status(404).json({
+    success: false,
+    message: \`Route \${req.method} \${req.originalUrl} not found\`,
+  });
+};
+`;
+}
+
+function tsConfig() {
+  return {
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'ESNext',
+      moduleResolution: 'node',
+      outDir: './dist',
+      rootDir: './',
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      forceConsistentCasingInFileNames: true,
+      resolveJsonModule: true,
+      declaration: true,
+      declarationMap: true,
+      sourceMap: true,
+    },
+    include: ['src/**/*', 'server.ts'],
+    exclude: ['node_modules', 'dist'],
+  };
+}

package/src/generators/readmeGenerator.js

@@ -0,0 +1,77 @@
+export function generateReadme(answers) {
+  const { projectName, structure, database, auth, extras, language } = answers;
+
+  const dbSetup = database === 'mongodb'
+    ? `Set your \`MONGO_URI\` in \`.env\``
+    : database !== 'none'
+    ? `Set your \`DATABASE_URL\` in \`.env\`, then run:\n\`\`\`bash\nnpx prisma migrate dev\n\`\`\``
+    : '';
+
+  return `# ${projectName}
+
+> Scaffolded with [create-xpressforge](https://github.com/hammad-sadi/create-xpressforge)
+
+## Stack
+
+| | |
+|---|---|
+| Runtime | Node.js (ES Modules) |
+| Framework | Express.js v5 |
+| Language | ${language === 'ts' ? 'TypeScript' : 'JavaScript'} |
+| Structure | ${structure.toUpperCase()} |
+| Database | ${database === 'none' ? 'None' : database.charAt(0).toUpperCase() + database.slice(1)} |
+| Auth | ${auth === 'none' ? 'None' : auth.toUpperCase()} |
+
+## Getting started
+
+\`\`\`bash
+npm install
+cp .env.example .env   # fill in your values
+${dbSetup}
+npm run dev
+\`\`\`
+
+## Project structure
+
+\`\`\`
+src/
+├── config/        # DB connection, env validation
+├── controllers/   # Request handlers
+├── middlewares/   # Auth, error handler, not-found
+├── models/        # Data models / schemas
+├── routes/        # Express routers
+├── services/      # Business logic
+└── utils/         # apiResponse, logger
+\`\`\`
+
+## API endpoints
+
+| Method | Endpoint | Description | Auth |
+|--------|----------|-------------|------|
+${auth !== 'none' ? `| POST | /api/v1/auth/register | Register | No |
+| POST | /api/v1/auth/login | Login | No |
+| POST | /api/v1/auth/refresh | Refresh token | No |
+| GET  | /api/v1/auth/me | Get current user | Yes |
+` : ''}| GET  | /api/v1/users | List users | ${auth !== 'none' ? 'Yes' : 'No'} |
+| GET  | /api/v1/users/:id | Get user | ${auth !== 'none' ? 'Yes' : 'No'} |
+| PUT  | /api/v1/users/:id | Update user | ${auth !== 'none' ? 'Yes' : 'No'} |
+| DELETE | /api/v1/users/:id | Delete user | ${auth !== 'none' ? 'Admin' : 'No'} |
+| GET  | /health | Health check | No |
+
+## Scripts
+
+\`\`\`bash
+npm run dev    # development with hot reload
+npm start      # production
+${language === 'ts' ? 'npm run build  # compile TypeScript\nnpm run lint   # type check' : ''}
+\`\`\`
+
+## Environment variables
+
+See \`.env.example\` for all required variables.
+
+---
+
+Built with ❤️ by Hammad Sadi — powered by [create-xpressforge](https://npmjs.com/package/create-xpressforge)
+`;
+}

package/src/generators/structureGenerator.js

@@ -0,0 +1,265 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+export async function generateStructure(answers, targetDir) {
+  const { structure, database, auth } = answers;
+  const ext = answers.language === 'ts' ? 'ts' : 'js';
+
+  const base = (p) => path.join(targetDir, p);
+
+  // Common folders
+  const commonDirs = [
+    'src/config',
+    'src/middlewares',
+    'src/utils',
+    'src/routes',
+  ];
+
+  if (structure === 'mvc') {
+    const dirs = [
+      ...commonDirs,
+      'src/controllers',
+      'src/models',
+      'src/services',
+    ];
+    await Promise.all(dirs.map(d => fs.ensureDir(base(d))));
+    await writeMvcFiles(answers, targetDir, ext);
+  }
+
+  if (structure === 'modular') {
+    const dirs = [
+      ...commonDirs,
+      'src/modules/user/controller',
+      'src/modules/user/service',
+      'src/modules/user/model',
+      'src/modules/user/routes',
+      'src/modules/user/dto',
+    ];
+    await Promise.all(dirs.map(d => fs.ensureDir(base(d))));
+    await writeModularFiles(answers, targetDir, ext);
+  }
+
+  if (structure === 'layered') {
+    const dirs = [
+      ...commonDirs,
+      'src/controllers',
+      'src/services',
+      'src/repositories',
+      'src/models',
+    ];
+    await Promise.all(dirs.map(d => fs.ensureDir(base(d))));
+    await writeLayeredFiles(answers, targetDir, ext);
+  }
+}
+
+async function writeMvcFiles(answers, targetDir, ext) {
+  const base = (p) => path.join(targetDir, p);
+
+  // Example User controller
+  await fs.writeFile(base(`src/controllers/userController.${ext}`), `import { sendSuccess, sendError, sendPaginated } from '../utils/apiResponse.js';
+${answers.database === 'mongodb' ? "import User from '../models/User.js';" : "import { prisma } from '../config/db.js';"}
+
+export const getAllUsers = async (req, res, next) => {
+  try {
+    const page  = parseInt(req.query.page)  || 1;
+    const limit = parseInt(req.query.limit) || 10;
+    const skip  = (page - 1) * limit;
+
+    ${answers.database === 'mongodb'
+      ? `const [users, total] = await Promise.all([\n      User.find().select('-password').skip(skip).limit(limit).lean(),\n      User.countDocuments(),\n    ]);`
+      : `const [users, total] = await Promise.all([\n      prisma.user.findMany({ skip, take: limit, select: { id: true, name: true, email: true, role: true, createdAt: true } }),\n      prisma.user.count(),\n    ]);`}
+
+    sendPaginated(res, users, { total, page, limit });
+  } catch (err) { next(err); }
+};
+
+export const getUserById = async (req, res, next) => {
+  try {
+    const user = await ${answers.database === 'mongodb'
+      ? "User.findById(req.params.id).select('-password')"
+      : "prisma.user.findUnique({ where: { id: req.params.id }, select: { id: true, name: true, email: true, role: true } })"};
+    if (!user) return sendError(res, 'User not found', 404);
+    sendSuccess(res, user);
+  } catch (err) { next(err); }
+};
+
+export const updateUser = async (req, res, next) => {
+  try {
+    const { name } = req.body;
+    const user = await ${answers.database === 'mongodb'
+      ? "User.findByIdAndUpdate(req.params.id, { name }, { new: true, runValidators: true }).select('-password')"
+      : "prisma.user.update({ where: { id: req.params.id }, data: { name }, select: { id: true, name: true, email: true } })"};
+    if (!user) return sendError(res, 'User not found', 404);
+    sendSuccess(res, user, 'User updated');
+  } catch (err) { next(err); }
+};
+
+export const deleteUser = async (req, res, next) => {
+  try {
+    const user = await ${answers.database === 'mongodb'
+      ? "User.findByIdAndDelete(req.params.id)"
+      : "prisma.user.delete({ where: { id: req.params.id } })"};
+    if (!user) return sendError(res, 'User not found', 404);
+    sendSuccess(res, null, 'User deleted');
+  } catch (err) { next(err); }
+};
+`);
+
+  // Routes index
+  await fs.writeFile(base(`src/routes/index.${ext}`), `import { Router } from 'express';
+import userRoutes from './userRoutes.js';
+${answers.auth !== 'none' ? "import authRoutes from './authRoutes.js';" : ''}
+
+const router = Router();
+
+${answers.auth !== 'none' ? "router.use('/auth',  authRoutes);" : ''}
+router.use('/users', userRoutes);
+
+export default router;
+`);
+
+  // User routes
+  await fs.writeFile(base(`src/routes/userRoutes.${ext}`), `import { Router } from 'express';
+import { getAllUsers, getUserById, updateUser, deleteUser } from '../controllers/userController.js';
+${answers.auth === 'jwt' ? "import { authenticate, authorize } from '../middlewares/authenticate.js';" : ''}
+
+const router = Router();
+
+${answers.auth === 'jwt' ? "router.use(authenticate);" : ''}
+router.get('/',     getAllUsers);
+router.get('/:id',  getUserById);
+router.put('/:id',  updateUser);
+router.delete('/:id', ${answers.auth === 'jwt' ? "authorize('admin'), " : ''}deleteUser);
+
+export default router;
+`);
+}
+
+async function writeModularFiles(answers, targetDir, ext) {
+  const base = (p) => path.join(targetDir, p);
+
+  // user module controller
+  await fs.writeFile(base(`src/modules/user/controller/user.controller.${ext}`), `import { UserService } from '../service/user.service.js';
+import { sendSuccess, sendError } from '../../../utils/apiResponse.js';
+
+const userService = new UserService();
+
+export const getUsers = async (req, res, next) => {
+  try {
+    const users = await userService.findAll();
+    sendSuccess(res, users);
+  } catch (err) { next(err); }
+};
+
+export const getUser = async (req, res, next) => {
+  try {
+    const user = await userService.findById(req.params.id);
+    if (!user) return sendError(res, 'User not found', 404);
+    sendSuccess(res, user);
+  } catch (err) { next(err); }
+};
+`);
+
+  // user service
+  await fs.writeFile(base(`src/modules/user/service/user.service.${ext}`), `${answers.database === 'mongodb' ? "import User from '../model/user.model.js';" : "import { prisma } from '../../../config/db.js';"}
+
+export class UserService {
+  async findAll() {
+    return ${answers.database === 'mongodb' ? "User.find().select('-password').lean()" : "prisma.user.findMany({ select: { id: true, name: true, email: true } })"};
+  }
+  async findById(id) {
+    return ${answers.database === 'mongodb' ? "User.findById(id).select('-password')" : "prisma.user.findUnique({ where: { id } })"};
+  }
+}
+`);
+
+  // user routes
+  await fs.writeFile(base(`src/modules/user/routes/user.routes.${ext}`), `import { Router } from 'express';
+import { getUsers, getUser } from '../controller/user.controller.js';
+
+const router = Router();
+router.get('/', getUsers);
+router.get('/:id', getUser);
+export default router;
+`);
+
+  // main routes index
+  await fs.writeFile(base(`src/routes/index.${ext}`), `import { Router } from 'express';
+import userRoutes from '../modules/user/routes/user.routes.js';
+${answers.auth !== 'none' ? "import authRoutes from './authRoutes.js';" : ''}
+
+const router = Router();
+${answers.auth !== 'none' ? "router.use('/auth', authRoutes);" : ''}
+router.use('/users', userRoutes);
+export default router;
+`);
+}
+
+async function writeLayeredFiles(answers, targetDir, ext) {
+  const base = (p) => path.join(targetDir, p);
+
+  // Repository layer
+  await fs.writeFile(base(`src/repositories/userRepository.${ext}`), `${answers.database === 'mongodb' ? "import User from '../models/User.js';" : "import { prisma } from '../config/db.js';"}
+
+export class UserRepository {
+  async findAll({ skip = 0, limit = 10 } = {}) {
+    return ${answers.database === 'mongodb' ? "User.find().select('-password').skip(skip).limit(limit).lean()" : "prisma.user.findMany({ skip, take: limit, select: { id: true, name: true, email: true } })"};
+  }
+  async findById(id) {
+    return ${answers.database === 'mongodb' ? "User.findById(id).select('-password')" : "prisma.user.findUnique({ where: { id } })"};
+  }
+  async findByEmail(email) {
+    return ${answers.database === 'mongodb' ? "User.findOne({ email })" : "prisma.user.findUnique({ where: { email } })"};
+  }
+  async update(id, data) {
+    return ${answers.database === 'mongodb' ? "User.findByIdAndUpdate(id, data, { new: true }).select('-password')" : "prisma.user.update({ where: { id }, data })"};
+  }
+  async delete(id) {
+    return ${answers.database === 'mongodb' ? "User.findByIdAndDelete(id)" : "prisma.user.delete({ where: { id } })"};
+  }
+}
+`);
+
+  // Service layer
+  await fs.writeFile(base(`src/services/userService.${ext}`), `import { UserRepository } from '../repositories/userRepository.js';
+
+export class UserService {
+  constructor() { this.repo = new UserRepository(); }
+
+  async getAllUsers(query) { return this.repo.findAll(query); }
+  async getUserById(id) {
+    const user = await this.repo.findById(id);
+    if (!user) throw Object.assign(new Error('User not found'), { statusCode: 404 });
+    return user;
+  }
+  async updateUser(id, data) { return this.repo.update(id, data); }
+  async deleteUser(id) { return this.repo.delete(id); }
+}
+`);
+
+  // Controller
+  await fs.writeFile(base(`src/controllers/userController.${ext}`), `import { UserService } from '../services/userService.js';
+import { sendSuccess } from '../utils/apiResponse.js';
+
+const userService = new UserService();
+
+export const getAllUsers  = async (req, res, next) => { try { sendSuccess(res, await userService.getAllUsers(req.query)); } catch(e){next(e);} };
+export const getUserById  = async (req, res, next) => { try { sendSuccess(res, await userService.getUserById(req.params.id)); } catch(e){next(e);} };
+export const updateUser   = async (req, res, next) => { try { sendSuccess(res, await userService.updateUser(req.params.id, req.body), 'User updated'); } catch(e){next(e);} };
+export const deleteUser   = async (req, res, next) => { try { await userService.deleteUser(req.params.id); sendSuccess(res, null, 'User deleted'); } catch(e){next(e);} };
+`);
+
+  // Routes
+  await fs.writeFile(base(`src/routes/index.${ext}`), `import { Router } from 'express';
+import { getAllUsers, getUserById, updateUser, deleteUser } from '../controllers/userController.js';
+${answers.auth !== 'none' ? "import authRoutes from './authRoutes.js';\nimport { authenticate } from '../middlewares/authenticate.js';" : ''}
+
+const router = Router();
+${answers.auth !== 'none' ? "router.use('/auth', authRoutes);" : ''}
+router.get('/users',     ${answers.auth === 'jwt' ? 'authenticate, ' : ''}getAllUsers);
+router.get('/users/:id', ${answers.auth === 'jwt' ? 'authenticate, ' : ''}getUserById);
+router.put('/users/:id', ${answers.auth === 'jwt' ? 'authenticate, ' : ''}updateUser);
+router.delete('/users/:id', ${answers.auth === 'jwt' ? 'authenticate, ' : ''}deleteUser);
+export default router;
+`);
+}

package/src/index.js

@@ -0,0 +1,38 @@
+import gradient from 'gradient-string';
+import chalk from 'chalk';
+import path from 'path';
+import { askQuestions } from './prompts/questions.js';
+import { generateProject } from './generators/projectGenerator.js';
+
+export async function run() {
+  console.clear();
+
+  const banner = gradient(['#6C63FF', '#48CAE4'])(
+    `
+  ██╗  ██╗██████╗ ██████╗ ███████╗███████╗███████╗
+  ╚██╗██╔╝██╔══██╗██╔══██╗██╔════╝██╔════╝██╔════╝
+   ╚███╔╝ ██████╔╝██████╔╝█████╗  ███████╗███████╗
+   ██╔██╗ ██╔═══╝ ██╔══██╗██╔══╝  ╚════██║╚════██║
+  ██╔╝ ██╗██║     ██║  ██║███████╗███████║███████║
+  ╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝
+              F O R G E
+  `
+  );
+
+  console.log(banner);
+  console.log(chalk.dim('  Production-ready Node.js + Express scaffolder\n'));
+  console.log(chalk.dim('  by Hammad Sadi\n'));
+
+  try {
+    const answers = await askQuestions();
+    const targetDir = path.resolve(process.cwd(), answers.projectName);
+    await generateProject(answers, targetDir);
+  } catch (err) {
+    if (err.name === 'ExitPromptError') {
+      console.log(chalk.yellow('\n  Cancelled. See you next time!\n'));
+      process.exit(0);
+    }
+    console.error(chalk.red('\n  Error: ' + err.message));
+    process.exit(1);
+  }
+}

package/src/prompts/questions.js

@@ -0,0 +1,68 @@
+import { input, select, checkbox } from '@inquirer/prompts';
+import chalk from 'chalk';
+
+export async function askQuestions() {
+  console.log(chalk.bold('  Let\'s configure your project:\n'));
+
+  const projectName = await input({
+    message: 'Project name:',
+    default: 'my-express-app',
+    validate: (val) => {
+      if (!val.trim()) return 'Project name cannot be empty';
+      if (!/^[a-z0-9-_]+$/.test(val)) return 'Use lowercase letters, numbers, hyphens only';
+      return true;
+    },
+  });
+
+  const structure = await select({
+    message: 'Project structure:',
+    choices: [
+      { name: 'MVC          — controllers, models, views, routes', value: 'mvc' },
+      { name: 'Modular      — feature-based modules (recommended for large apps)', value: 'modular' },
+      { name: 'Layered      — controllers, services, repositories, models', value: 'layered' },
+    ],
+  });
+
+  const database = await select({
+    message: 'Database:',
+    choices: [
+      { name: 'MongoDB      — with Mongoose ODM', value: 'mongodb' },
+      { name: 'PostgreSQL   — with Prisma ORM', value: 'postgresql' },
+      { name: 'MySQL        — with Sequelize ORM', value: 'mysql' },
+      { name: 'None         — no database', value: 'none' },
+    ],
+  });
+
+  const auth = await select({
+    message: 'Authentication:',
+    choices: [
+      { name: 'JWT          — access + refresh token', value: 'jwt' },
+      { name: 'Session      — express-session + cookie', value: 'session' },
+      { name: 'None         — skip auth setup', value: 'none' },
+    ],
+  });
+
+  const extras = await checkbox({
+    message: 'Extra features (space to select):',
+    choices: [
+      { name: 'Rate limiting       (express-rate-limit)', value: 'rateLimit', checked: true },
+      { name: 'Security headers    (helmet)', value: 'helmet', checked: true },
+      { name: 'CORS                (cors)', value: 'cors', checked: true },
+      { name: 'Request logger      (morgan)', value: 'morgan', checked: true },
+      { name: 'Input validation    (express-validator)', value: 'validation', checked: false },
+      { name: 'File upload         (multer)', value: 'multer', checked: false },
+      { name: 'Socket.io           (real-time)', value: 'socket', checked: false },
+      { name: 'Swagger docs        (swagger-ui-express)', value: 'swagger', checked: false },
+    ],
+  });
+
+  const language = await select({
+    message: 'Language:',
+    choices: [
+      { name: 'JavaScript   — ES Modules (type: module)', value: 'js' },
+      { name: 'TypeScript   — fully typed', value: 'ts' },
+    ],
+  });
+
+  return { projectName, structure, database, auth, extras, language };
+}