create-xpressforge 1.0.0 → 1.0.1

package/README.md

@@ -1,46 +1,137 @@
 # create-xpressforge
 
-> Production-ready Node.js + Express project scaffolder
+> Scaffold a production-ready Node.js + Express project in seconds — with your choice of architecture, database, auth, and language.
 
 [![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)
+[![tests](https://img.shields.io/badge/tests-73%20passed-brightgreen)](#)
 
-## Usage
+---
+
+## Quick start
 
 ```bash
 npx create-xpressforge my-app
 ```
 
-Or install globally:
+That's it. Follow the prompts, then:
 
 ```bash
-npm install -g create-xpressforge
-create-xpressforge my-app
+cd my-app
+npm install
+cp .env.example .env   # add your DB URI and secrets
+npm run dev
+```
+
+---
+
+## Interactive prompts
+
+```
+? Project name:          my-app
+? Project structure:     MVC  /  Modular  /  Layered
+? Database:              MongoDB  /  PostgreSQL  /  MySQL  /  None
+? Authentication:        JWT  /  Session  /  None
+? Extra features:        Rate limiting, Helmet, CORS, Morgan, Validation, Multer, Socket.io, Swagger
+? Language:              JavaScript  /  TypeScript
+```
+
+---
+
+## What gets generated
+
+Running `npx create-xpressforge my-app` with **MVC + MongoDB + JWT** produces:
+
+```
+my-app/
+├── src/
+│   ├── config/
+│   │   ├── db.js          # MongoDB connection with retry logic
+│   │   └── env.js         # Centralised env config
+│   ├── controllers/
+│   │   ├── authController.js   # register, login, refresh, getMe
+│   │   └── userController.js   # full CRUD with pagination
+│   ├── middlewares/
+│   │   ├── authenticate.js     # JWT verify + role-based authorize()
+│   │   ├── errorHandler.js     # global error handler
+│   │   └── notFound.js
+│   ├── models/
+│   │   └── User.js             # Mongoose schema with indexes
+│   ├── routes/
+│   │   ├── index.js
+│   │   ├── authRoutes.js
+│   │   └── userRoutes.js
+│   ├── services/
+│   │   └── userService.js
+│   └── utils/
+│       ├── apiResponse.js      # sendSuccess / sendError / sendPaginated
+│       └── logger.js           # coloured console logger
+├── .env                        # pre-filled with your choices
+├── .env.example                # safe to commit
+├── .gitignore
+├── package.json
+├── README.md                   # auto-generated for your stack
+└── server.js
+```
+
+---
+
+## API endpoints (out of the box)
+
+| Method   | Endpoint                | Description          | Auth     |
+| -------- | ----------------------- | -------------------- | -------- |
+| `POST`   | `/api/v1/auth/register` | Register a new user  | —        |
+| `POST`   | `/api/v1/auth/login`    | Login, get tokens    | —        |
+| `POST`   | `/api/v1/auth/refresh`  | Refresh access token | —        |
+| `GET`    | `/api/v1/auth/me`       | Get current user     | ✅       |
+| `GET`    | `/api/v1/users`         | Paginated user list  | ✅       |
+| `GET`    | `/api/v1/users/:id`     | Get user by ID       | ✅       |
+| `PUT`    | `/api/v1/users/:id`     | Update user          | ✅       |
+| `DELETE` | `/api/v1/users/:id`     | Delete user          | ✅ Admin |
+| `GET`    | `/health`               | Health check         | —        |
+
+---
+
+## Consistent API response format
+
+Every endpoint returns the same shape — no surprises:
+
+```json
+// success
+{ "success": true,  "message": "Login successful", "data": { ... } }
+
+// error
+{ "success": false, "message": "Invalid email or password" }
+
+// paginated
+{ "success": true, "data": [...], "pagination": { "total": 100, "page": 2, "limit": 10, "totalPages": 10 } }
 ```
 
-## What you get
+---
 
-Interactive prompts let you choose:
+## Available scripts
 
-- **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
+```bash
+npm run dev      # nodemon hot-reload (JS) / tsx watch (TS)
+npm start        # production
+npm run build    # compile TypeScript  (TS only)
+npm test         # vitest
+```
+
+---
+
+## Global install
 
-Every generated project includes:
+```bash
+npm install -g create-xpressforge
+create-xpressforge my-app
+```
 
-- 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>
+**Hammad Sadi** · [hammad.sadi@yahoo.com](mailto:hammad.sadi@yahoo.com)
 
 ## License
 

package/bin/cli.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-xpressforge",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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",
@@ -8,6 +8,7 @@
     "create-xpressforge": "./bin/cli.js"
   },
   "main": "./src/index.js",
+  "type": "module",
   "keywords": [
     "express",
     "nodejs",
@@ -27,7 +28,12 @@
     "src"
   ],
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@inquirer/prompts": "^5.0.0",
@@ -36,6 +42,10 @@
     "fs-extra": "^11.2.0",
     "gradient-string": "^2.0.2"
   },
+  "devDependencies": {
+    "vitest": "^1.6.0",
+    "@vitest/coverage-v8": "^1.6.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/hammadsadi/create-xpressforge"

package/src/generators/appGenerator.js

@@ -3,17 +3,15 @@ export function generateAppJs(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('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';`   : '',
+    `import routes from './routes/index.js';`,
   ].filter(Boolean).join('\n');
 
   const dbInit = database !== 'none' ? `\n// Connect to database\nconnectDB();\n` : '';

package/src/generators/projectGenerator.js

@@ -47,6 +47,14 @@ export async function generateProject(answers, targetDir) {
     // 7. server.js entry
     await fs.writeFile(path.join(targetDir, `server.${ext}`), serverContent(answers));
 
+    // 7b. Swagger config (only if swagger selected)
+    if (answers.extras.includes('swagger')) {
+      await fs.writeFile(
+        path.join(targetDir, 'src', 'config', `swagger.${ext}`),
+        swaggerConfigContent(answers)
+      );
+    }
+
     // 8. DB config
     if (answers.database !== 'none') {
       spinner.text = 'Setting up database connection...';
@@ -127,24 +135,52 @@ coverage/
 }
 
 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 ext = answers.language === 'ts' ? 'ts' : 'js';
+  return `import 'dotenv/config';
+import app from './src/app.js';
 
-const PORT = env.PORT || 3000;
+const PORT = process.env.PORT || 3000;
+const NODE_ENV = process.env.NODE_ENV || 'development';
 
 app.listen(PORT, () => {
-  console.log(\`Server running on http://localhost:\${PORT}\`);
-  console.log(\`Environment: \${env.NODE_ENV}\`);
+  console.log(\`✅ Server running on http://localhost:\${PORT}\`);
+  console.log(\`📦 Environment: \${NODE_ENV}\`);
 });
 `;
 }
 
+function swaggerConfigContent(answers) {
+  return `import swaggerJsdoc from 'swagger-jsdoc';
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: '${answers.projectName} API',
+      version: '1.0.0',
+      description: 'API documentation for ${answers.projectName}',
+    },
+    servers: [
+      { url: \`http://localhost:\${process.env.PORT || 3000}/api/v1\`, description: 'Development' },
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+      },
+    },
+  },
+  apis: ['./src/routes/*.js'],
+};
+
+export const swaggerSpec = swaggerJsdoc(options);
+`;
+}
+
 function envConfigContent(answers) {
   return `export const env = {
-  PORT: process.env.PORT || 3000,
+  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` : ''}};
+${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` : ''}};
 `;
 }