create-xpress-backend 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,725 @@
+# create-xpress-backend
+
+> Scaffold a production-ready **Express + Prisma + PostgreSQL** backend in seconds.  
+> Choose **TypeScript** (default) or **JavaScript** — everything wired up, zero boilerplate.
+
+```bash
+npx create-xpress-backend
+```
+
+---
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [How to Use the CLI](#how-to-use-the-cli)
+- [TypeScript vs JavaScript](#typescript-vs-javascript)
+- [What Gets Scaffolded](#what-gets-scaffolded)
+- [Project Structure Explained](#project-structure-explained)
+- [Every File — What It Does](#every-file--what-it-does)
+- [Environment Variables](#environment-variables)
+- [First-Time Setup (Step by Step)](#first-time-setup-step-by-step)
+- [Available Scripts](#available-scripts)
+- [API Reference](#api-reference)
+- [How the Architecture Works](#how-the-architecture-works)
+- [Adding a New Module](#adding-a-new-module)
+- [File Upload System](#file-upload-system)
+- [JWT Auth System](#jwt-auth-system)
+- [Database Workflows](#database-workflows)
+- [Deployment Checklist](#deployment-checklist)
+- [FAQ](#faq)
+
+---
+
+## Requirements
+
+| Requirement | Minimum | Check |
+|-------------|---------|-------|
+| Node.js | ≥ 18.0.0 | `node -v` |
+| npm | ≥ 8.0.0 | `npm -v` |
+| PostgreSQL | ≥ 13 | running locally or on a cloud service |
+
+> PostgreSQL can be local, Docker, or a hosted service — Supabase, Neon, Railway, Render, etc.
+
+---
+
+## How to Use the CLI
+
+No global install needed. Just run:
+
+```bash
+npx create-xpress-backend
+```
+
+You will see the banner and then a short series of prompts:
+
+```
+  ┌─────────────────────────────────────────────┐
+  │  🚀  create-xpress-backend  v1.0.0          │
+  │  Express · Prisma · PostgreSQL · Node.js     │
+  └─────────────────────────────────────────────┘
+
+  project_name          :  my-api
+  language              :  ❯ TypeScript  (recommended)
+                             JavaScript
+  port                  :  5050
+  file upload system    :  include? (Y/n)
+  JWT auth module       :  include? (y/N)
+  git init              :  initialize? (Y/n)
+```
+
+### Prompt Reference
+
+| Prompt | What it does | Default |
+|--------|-------------|---------|
+| `project_name` | Folder name + npm package name. Lowercase letters, numbers, hyphens, underscores only. | — |
+| `language` | TypeScript or JavaScript. Arrow-key selection. | **TypeScript** |
+| `port` | Port written into `.env` and used in startup logs. | `5050` |
+| `file upload system` | Adds Multer, an `/uploads` directory, and upload/list/delete routes. | Yes |
+| `JWT auth module` | Adds register + login endpoints and a JWT guard middleware. | No |
+| `git init` | Runs `git init` inside the generated folder. | Yes |
+
+After confirming, the CLI scaffolds everything and prints:
+
+```
+  ✔ Done! Project "my-api" created! (TypeScript)
+
+  Get started:
+    cd my-api
+    npm install
+    # configure DATABASE_URL in .env, then:
+    npm run db:push
+    npm run dev
+
+  Build for production:
+    npm run build
+    npm start
+
+  Health check  →  http://localhost:5050/health
+  Prisma Studio →  npm run db:studio
+```
+
+---
+
+## TypeScript vs JavaScript
+
+The CLI generates a **complete**, properly typed codebase for whichever language you pick. There is no "TS wrapper around JS" — every file is written natively.
+
+| | TypeScript | JavaScript |
+|--|-----------|-----------|
+| Source files | `.ts` | `.js` |
+| Module system | ES module imports (`import/export`) | CommonJS (`require/module.exports`) |
+| Dev server | `ts-node-dev` | `nodemon` |
+| Build step | `tsc` → `dist/` | None — runs directly |
+| Start (prod) | `node dist/server.js` | `node src/server.js` |
+| Type checking | ✅ Strict mode | — |
+| `tsconfig.json` | ✅ Included | — |
+| `src/types/express.d.ts` | ✅ Included (`req.user` typed) | — |
+| Type packages | `@types/*` included | — |
+
+> **Recommendation:** Use TypeScript. It catches bugs at compile time and makes refactoring safer — especially important as your API grows.
+
+---
+
+## What Gets Scaffolded
+
+Depending on your choices, between **17 and 25 files** are generated:
+
+| Language | Base | + Upload | + Auth | + Both |
+|----------|------|----------|--------|--------|
+| TypeScript | 19 | 20 | 24 | 25 |
+| JavaScript | 17 | 18 | 22 | 23 |
+
+---
+
+## Project Structure Explained
+
+### TypeScript
+
+```
+my-api/
+├── prisma/
+│   └── schema.prisma              ← database models
+├── src/
+│   ├── app.ts                     ← Express config (middleware, routes, error handler)
+│   ├── server.ts                  ← HTTP server + graceful shutdown
+│   ├── types/
+│   │   └── express.d.ts           ← augments req.user with JwtPayload type
+│   ├── database/
+│   │   ├── prisma.ts              ← shared PrismaClient singleton
+│   │   └── seed.ts                ← database seeder
+│   ├── middleware/
+│   │   ├── validate.ts            ← Joi validation wrapper
+│   │   ├── upload.ts              ← Multer config (if uploads selected)
+│   │   └── auth.ts                ← JWT guard middleware (if auth selected)
+│   └── modules/
+│       ├── index.ts               ← central router
+│       ├── demo/                  ← example CRUD module
+│       │   ├── demo.controller.ts
+│       │   ├── demo.service.ts
+│       │   ├── demo.routes.ts
+│       │   └── demo.validation.ts
+│       └── auth/                  ← auth module (if auth selected)
+│           ├── auth.controller.ts
+│           ├── auth.service.ts
+│           ├── auth.routes.ts
+│           └── auth.validation.ts
+├── uploads/                       ← file storage (if uploads selected)
+├── tsconfig.json
+├── prisma.config.ts
+├── .env
+├── .env.example
+├── .gitignore
+└── package.json
+```
+
+### JavaScript
+
+Same structure but with `.js` extensions, `require/module.exports`, no `tsconfig.json`, no `types/` folder.
+
+---
+
+## Every File — What It Does
+
+### `src/server.ts` / `src/server.js`
+Entry point. Creates an `http.Server` around the Express app, starts listening on `PORT`, logs startup info, and handles `SIGINT`/`SIGTERM` for graceful shutdown with a 5-second forced-exit fallback.
+
+### `src/app.ts` / `src/app.js`
+Configures the Express app — does **not** start the server. Middleware stack applied in order:
+1. `helmet()` — secure HTTP headers
+2. `cors()` — CORS from `CLIENT_URL`
+3. `morgan('dev')` — request logging
+4. `express.json()` — JSON body parsing (10 MB limit)
+5. `express.urlencoded()` — form body parsing
+6. `/uploads` static route — serves uploaded files (if uploads enabled)
+7. `/api` — all module routes
+8. `/health` — health check
+9. 404 handler
+10. Central error handler — anything passed to `next(error)` lands here
+
+### `src/database/prisma.ts` / `prisma.js`
+Creates and exports a **single shared PrismaClient** using the `@prisma/adapter-pg` driver adapter with a `pg` connection pool. Every module imports from here.
+
+### `src/database/seed.ts` / `seed.js`
+Standalone seeder. Safe to run multiple times — checks for existing records before inserting. Extend this to seed any initial data your app needs.
+
+### `prisma/schema.prisma`
+Defines your database models. Base includes `User`. If file uploads were selected, `File` is also included with a `User` relation. Edit here, then run `npm run db:push`.
+
+### `src/types/express.d.ts` *(TypeScript only)*
+Augments Express's `Request` interface to add `user?: string | JwtPayload`. This is what makes `req.user` type-safe in every controller and middleware.
+
+### `src/middleware/validate.ts` / `validate.js`
+Takes a Joi schema, returns Express middleware. On failure, returns `400` with the first validation error. Usage:
+```ts
+router.post('/', validate(createSchema), controller.create);
+```
+
+### `src/middleware/upload.ts` / `upload.js` *(if uploads selected)*
+Multer configured with disk storage, unique filenames, file type filtering (JPEG/PNG/GIF/PDF/TXT/DOC/DOCX), and size limit from `MAX_FILE_SIZE` env var.
+
+### `src/middleware/auth.ts` / `auth.js` *(if auth selected)*
+Reads `Authorization: Bearer <token>`, verifies against `JWT_SECRET`, attaches decoded payload to `req.user`. Returns `401` for missing or invalid tokens.
+```ts
+router.get('/me', authMiddleware, controller.getMe);
+```
+
+### `src/modules/index.ts` / `index.js`
+The central router. Add one line per new module:
+```ts
+router.use('/users', usersRoutes);
+```
+
+### Demo Module (`src/modules/demo/`)
+Working example of the **Controller → Service → Routes → Validation** pattern:
+- **Validation** — Joi schemas for create and update
+- **Routes** — maps HTTP verbs + paths to controller methods, attaches middleware
+- **Controller** — handles `req`/`res`, calls service, passes errors to `next()`
+- **Service** — all Prisma calls live here, returns plain data, throws on error
+
+This is your **template module**. Copy it, rename everything, and replace the Prisma calls for your first real feature.
+
+### Auth Module (`src/modules/auth/`) *(if selected)*
+- **Register** — hashes password (bcrypt, 10 rounds), creates user, returns user without password field
+- **Login** — finds user, compares password, signs JWT, returns `{ user, token }`
+
+---
+
+## Environment Variables
+
+Your `.env` is pre-filled when the project is created:
+
+```env
+NODE_ENV=development
+PORT=5050
+
+# Database — edit to match your Postgres instance
+DATABASE_URL="postgresql://postgres:admin@localhost:5432/my_api_db"
+# Format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE_NAME
+
+# JWT — change JWT_SECRET to a long random string before deploying
+JWT_SECRET=your-super-secret-jwt-key-change-this
+JWT_EXPIRES_IN=7d        # 7d | 24h | 3600 (seconds)
+
+# File Upload (if included)
+MAX_FILE_SIZE=10         # megabytes
+
+# CORS
+CLIENT_URL=http://localhost:3000
+SERVER_URL=http://localhost:5050
+```
+
+> `.env` is git-ignored. Commit `.env.example` — it shows required keys without real values.
+
+---
+
+## First-Time Setup (Step by Step)
+
+```bash
+# 1. Scaffold
+npx create-xpress-backend
+
+# 2. Enter your project
+cd my-api
+
+# 3. Install dependencies
+npm install
+
+# 4. Create the database (if it doesn't exist yet)
+#    psql -U postgres -c "CREATE DATABASE my_api_db;"
+
+# 5. Set DATABASE_URL in .env
+#    DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/my_api_db"
+
+# 6. Push schema to DB + generate Prisma Client
+npm run db:push
+
+# 7. (Optional) Seed initial data
+npm run db:seed
+
+# 8. Start dev server
+npm run dev
+```
+
+Visit `http://localhost:5050/health`:
+
+```json
+{
+  "status": "OK",
+  "message": "API Running ✅",
+  "timestamp": "2026-07-09T10:00:00.000Z",
+  "uptime": 3.2
+}
+```
+
+---
+
+## Available Scripts
+
+### TypeScript project
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start with `ts-node-dev` (auto-restarts + transpiles on save) |
+| `npm run build` | Compile TypeScript → `dist/` |
+| `npm start` | Run compiled production build (`node dist/server.js`) |
+| `npm run db:push` | Push schema changes + regenerate Prisma Client |
+| `npm run db:generate` | Regenerate Prisma Client without pushing |
+| `npm run db:dev` | `db:push` + `db:generate` in one command |
+| `npm run db:seed` | Run the database seeder |
+| `npm run db:studio` | Open Prisma Studio |
+| `npm run db:reset` | ⚠️ Force-reset database (drops all data) |
+
+### JavaScript project
+
+Same as above except:
+- `npm run dev` uses `nodemon`
+- No `npm run build` — runs directly
+- `npm start` runs `node src/server.js`
+
+---
+
+## API Reference
+
+### Health
+
+```
+GET /health
+```
+```json
+{ "status": "OK", "message": "API Running ✅", "timestamp": "...", "uptime": 120.4 }
+```
+
+---
+
+### Demo — CRUD (always included)
+
+#### Create
+```
+POST /api/demo
+Content-Type: application/json
+
+{ "name": "Alice", "email": "alice@example.com" }
+```
+Returns `201` with the created record.
+
+#### Get All
+```
+GET /api/demo
+```
+Returns `200` with array of records (newest first).
+
+#### Get by ID
+```
+GET /api/demo/:id
+```
+Returns `200` with the record, or `404`.
+
+#### Update
+```
+PUT /api/demo/:id
+Content-Type: application/json
+
+{ "name": "Alice Updated" }
+```
+Returns `200` with updated record.
+
+#### Delete
+```
+DELETE /api/demo/:id
+```
+Returns `200` with `{ "message": "Demo deleted successfully" }`.
+
+---
+
+### File Upload *(if selected)*
+
+#### Upload
+```
+POST /api/demo/upload
+Content-Type: multipart/form-data
+
+field: file
+```
+Returns `201` with the stored file record.
+
+#### List
+```
+GET /api/demo/files/all
+```
+Returns `200` with array of file records.
+
+#### Delete
+```
+DELETE /api/demo/files/:fileId
+```
+Deletes physical file from disk + database record.
+
+**Allowed types:** JPEG, PNG, GIF, PDF, TXT, DOC, DOCX  
+**Max size:** `MAX_FILE_SIZE` MB (default 10)
+
+---
+
+### Auth *(if selected)*
+
+#### Register
+```
+POST /api/auth/register
+Content-Type: application/json
+
+{ "name": "Alice", "email": "alice@example.com", "password": "secret123" }
+```
+Returns `201` with user object (no password field).
+
+#### Login
+```
+POST /api/auth/login
+Content-Type: application/json
+
+{ "email": "alice@example.com", "password": "secret123" }
+```
+Returns `200` with:
+```json
+{
+  "success": true,
+  "data": {
+    "user": { "id": "...", "name": "Alice", "email": "alice@example.com" },
+    "token": "eyJhbGci..."
+  }
+}
+```
+
+Use the token on protected routes:
+```
+Authorization: Bearer eyJhbGci...
+```
+
+---
+
+## How the Architecture Works
+
+Every request flows through the same layers in the same order:
+
+```
+Incoming Request
+  │
+  ▼
+Middleware Stack  (app.ts)
+  helmet → cors → morgan → body-parser
+  │
+  ▼
+Module Router  (src/modules/index.ts)
+  /api/demo  →  demo.routes.ts
+  /api/auth  →  auth.routes.ts
+  │
+  ▼
+Route  (*.routes.ts)
+  validate(schema) → authMiddleware → controller.method
+  │
+  ▼
+Controller  (*.controller.ts)
+  calls service → formats JSON → passes errors to next()
+  │
+  ▼
+Service  (*.service.ts)
+  all Prisma / database logic
+  throws typed errors
+  │
+  ▼
+Central Error Handler  (app.ts)
+  catches everything passed to next(error)
+  returns { success: false, message }
+```
+
+**Key rules:**
+- Controllers never touch the database — that belongs in the service
+- Services never touch `req`/`res` — they work with plain data and types
+- Validation runs before the controller — invalid requests are rejected early
+- All errors bubble to one place — the central error handler in `app.ts`
+
+---
+
+## Adding a New Module
+
+Example: adding a `products` module.
+
+**1. Add a Prisma model**
+```prisma
+model Product {
+  id          String   @id @default(uuid())
+  name        String
+  price       Float
+  createdAt   DateTime @default(now())
+  updatedAt   DateTime @updatedAt
+}
+```
+
+**2. Push the schema**
+```bash
+npm run db:push
+```
+
+**3. Create the module folder**
+```
+src/modules/products/
+├── products.validation.ts
+├── products.service.ts
+├── products.controller.ts
+└── products.routes.ts
+```
+
+**4. Write the service** (Prisma calls go here)
+```ts
+import prisma from '../../database/prisma';
+
+class ProductsService {
+  async getAll() {
+    return prisma.product.findMany({ orderBy: { createdAt: 'desc' } });
+  }
+}
+export default new ProductsService();
+```
+
+**5. Register the route** in `src/modules/index.ts`
+```ts
+import productsRoutes from './products/products.routes';
+router.use('/products', productsRoutes);
+```
+
+`GET /api/products` is now live.
+
+---
+
+## File Upload System
+
+```
+Client → multipart/form-data (field: "file")
+  │
+  ▼
+upload.single('file')            ← Multer middleware
+  validates type + size
+  writes to  uploads/<name>-<timestamp>-<random>.<ext>
+  attaches to req.file
+  │
+  ▼
+Controller reads req.file
+  passes userId + file to service
+  │
+  ▼
+Service creates File record in database
+  stores: filename, originalName, path, size, mimetype, userId
+  │
+  ▼
+File on disk:  uploads/file-1720524000000-123456789.jpg
+DB record in:  files  table
+Accessible at: GET /uploads/<filename>
+```
+
+To **restrict file types**, edit `allowedMimes` in `src/middleware/upload.ts`.  
+To **change max size**, update `MAX_FILE_SIZE` in `.env` (value in MB).
+
+---
+
+## JWT Auth System
+
+```
+POST /api/auth/register
+  validate { name, email, password }
+  check if email exists   → 409 if yes
+  bcrypt.hash(password, 10)
+  prisma.user.create(...)
+  return user (password stripped)
+
+POST /api/auth/login
+  validate { email, password }
+  find user by email      → 401 if not found
+  bcrypt.compare(...)     → 401 if wrong
+  jwt.sign({ id, email }, JWT_SECRET, { expiresIn })
+  return { user, token }
+
+Protected Route
+  Authorization: Bearer <token>
+  authMiddleware verifies token
+  attaches decoded payload → req.user
+  → 401 if missing or invalid
+```
+
+**To protect a route:**
+```ts
+// TypeScript
+import authMiddleware from '../../middleware/auth';
+router.get('/me', authMiddleware, controller.getMe.bind(controller));
+```
+```js
+// JavaScript
+const authMiddleware = require('../../middleware/auth');
+router.get('/me', authMiddleware, controller.getMe);
+```
+
+Inside the controller, `req.user` will contain `{ id, email, iat, exp }`.
+
+---
+
+## Database Workflows
+
+### Iterating on your schema
+
+```bash
+# 1. Edit prisma/schema.prisma
+# 2. Push + regenerate
+npm run db:push
+# 3. Browse your data
+npm run db:studio
+```
+
+### Reset for a clean slate (dev only)
+
+```bash
+npm run db:reset   # ⚠️ drops all data
+npm run db:seed    # re-seed if needed
+```
+
+### Connecting to a hosted database
+
+```env
+# Supabase
+DATABASE_URL="postgresql://postgres:[password]@db.[ref].supabase.co:5432/postgres"
+
+# Neon
+DATABASE_URL="postgresql://[user]:[password]@[host].neon.tech/[db]?sslmode=require"
+
+# Railway
+DATABASE_URL="postgresql://postgres:[password]@[host].railway.app:5432/railway"
+```
+
+---
+
+## Deployment Checklist
+
+- [ ] `NODE_ENV=production` set in hosting environment
+- [ ] `JWT_SECRET` is a long, random, unique string — never the default
+- [ ] `CLIENT_URL` set to your real frontend domain (not `*`)
+- [ ] `DATABASE_URL` points to production database
+- [ ] `npm run db:push` run against the production database
+- [ ] **TypeScript only:** `npm run build` run before deploy — serve from `dist/`
+- [ ] `uploads/` is on persistent storage (not ephemeral filesystem)
+- [ ] Demo routes removed or protected before go-live
+
+**Production start:**
+```bash
+# TypeScript
+npm run build && npm start
+
+# JavaScript
+npm start
+```
+
+**Minimal Dockerfile (TypeScript):**
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+EXPOSE 5050
+CMD ["npm", "start"]
+```
+
+---
+
+## FAQ
+
+**Q: Which should I pick — TypeScript or JavaScript?**  
+A: TypeScript is the default for a reason. Strict typing catches bugs before runtime, makes refactoring reliable, and improves IDE autocomplete. If you're already comfortable with TS, pick it. If you're learning or need a quick prototype, JS is perfectly fine.
+
+**Q: What does `ts-node-dev` do?**  
+A: It's the TypeScript equivalent of `nodemon` — it watches `.ts` files, transpiles them on the fly, and restarts the server on changes. No manual `tsc` step during development.
+
+**Q: Do I need to run `npm run build` during development?**  
+A: No. `npm run dev` uses `ts-node-dev` which runs TypeScript directly. `npm run build` is only needed when preparing for production.
+
+**Q: Can I use MySQL or SQLite instead of PostgreSQL?**  
+A: The generated project uses `@prisma/adapter-pg` (PostgreSQL-specific). To switch, remove the adapter, change `provider` in `schema.prisma`, and replace the `pg` pool. Prisma supports MySQL, SQLite, MongoDB, and others.
+
+**Q: Why is there a `demo` module instead of a real resource?**  
+A: It's intentionally generic so it doesn't clash with your actual domain models. It shows the pattern — rename and replace it for your first real feature.
+
+**Q: How do I add the `password` field if I didn't choose JWT auth?**  
+A: Add it to the `User` model in `schema.prisma`:
+```prisma
+model User {
+  ...
+  password  String?
+}
+```
+Then run `npm run db:push`.
+
+**Q: What is `prisma.config.ts` / `prisma.config.js` for?**  
+A: Prisma 7 introduced a new config file format. It tells the Prisma CLI where to find `DATABASE_URL`. You don't need to edit it.
+
+---
+
+## License
+
+MIT © [ayushsolanki29](https://github.com/ayushsolanki29/create-xpress-backend)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-xpress-backend",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Scaffold a production-ready Express + Prisma + PostgreSQL backend in seconds",
   "main": "src/index.js",
   "bin": {