io.github.IbrahimKhaled19/backgen
Generate Express.js backend projects with ORMs, auth, payments, and DevOps
Open source Open in the app JSON README (API)
About
Generate Express.js backend projects with ORMs, auth, payments, and DevOps
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- ibrahimkhaled19
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.14.0
- Stars
- 4
- Last push
- 2026-06-29T12:09:13Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:58
- Updated
- 2026-08-29 03:01:58
- Origin id
io.github.IbrahimKhaled19/backgen
README
# BackGen
[](https://github.com/IbrahimKhaled19/BackGen/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@ibrahimkhaled19/backgen)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@ibrahimkhaled19/backgen)
[](https://github.com/IbrahimKhaled19/BackGen)
## 🤖 AI-Ready
[](https://glama.ai/mcp/servers/IbrahimKhaled19/BackGen)
[](https://glama.ai/mcp/servers/IbrahimKhaled19/BackGen)
BackGen ships a built-in **MCP (Model Context Protocol) server** that AI assistants
(Claude, Cursor, GitHub Copilot, VS Code) can use to scaffold projects on your behalf.
Run via CLI:
```bash
backgen mcp
```
Or configure your AI tool's MCP client:
```json
{
"mcpServers": {
"backgen": {
"command": "npx",
"args": ["-y", "@ibrahimkhaled19/backgen", "mcp"]
}
}
}
```
**Available MCP tools:**
| Tool | Description |
|------|-------------|
| `init_project` | Scaffold a new production-ready backend project with chosen ORM, preset, and plugins |
| `add_plugin` | Install a plugin (jwt, clerk, stripe, s3, ratelimit, ci-github, dependabot, codeql, docker-registry, release) |
| `remove_plugin` | Remove a previously installed plugin |
| `generate_resource` | Generate a CRUD resource with fields, relations, validation, and Swagger |
| `generate_seed` | Generate a database seed file for a resource |
| `generate_factory` | Generate a test factory for a resource |
| `doctor` | Validate an existing BackGen project for configuration issues |
| `list_plugins` | List all available plugins with descriptions |
| `list_presets` | List all available domain presets |
| `project_info` | Show project metadata from the manifest |
Then just ask: *"Scaffold a SaaS backend with Prisma, JWT auth, and Stripe payments"*
---
<img width="1600" height="900" alt="BackGen CLI generating Express.js backend with Prisma, Drizzle, and Mongoose — Swagger docs, Docker, auth, and multi-tenant SaaS preset" src="https://github.com/user-attachments/assets/cd3888d3-fa9d-4e4e-a595-4f10ae039871" />
> Generate production-ready backend foundations so developers can focus on business logic, not boilerplate.
BackGen is a CLI tool that generates complete Express.js backend projects on **Prisma, Drizzle, or Mongoose** — with authentication, multi-tenant infrastructure, production hardening, Docker, and testing — all working out of the box.
```bash
npx @ibrahimkhaled19/backgen init my-api --orm drizzle
cd my-api
npm run dev
```
Swagger docs at `http://localhost:3000/docs` in under 60 seconds. Pick your ORM, keep everything else.
---
## Features
- **Express + TypeScript** — strict mode, ESLint 9 (flat config), Vitest
- **Multi-ORM** — Prisma, Drizzle, or Mongoose. Pick at `init` time, switch later via the manifest
- **SaaS-ready** — `saas-core` preset ships Organizations, Memberships, Invitations, RBAC, tenant-scoped queries
- **Hardened by default** — helmet, strict CORS, request ID, request timeout, xss + mongo-sanitize, graceful shutdown, `/health` + `/ready`, error envelope
- **Plugin System** — JWT, Clerk, Stripe, S3, ratelimit via `backgen add`
- **Resource Generator** — CRUD modules with relations, validation, Swagger
- **Domain Presets** — saas-core, healthcare, SaaS, ecommerce, CRM, LMS — full domain in one command
- **Seed & Factory Generators** — development data and test factories
- **Docker** — multi-stage Dockerfile + docker-compose
- **Swagger/OpenAPI** — auto-generated API documentation
- **Manifest** — `.backgenrc.json` tracks ORM, plugins, versions, and ownership for **upgrade/rollback**
---
## Quick Start
```bash
# Install globally
npm install -g @ibrahimkhaled19/backgen
# Create a project (pick your ORM)
backgen init my-api --orm prisma
backgen init my-api --orm drizzle
backgen init my-api --orm mongoose
# Create a full multi-tenant domain
backgen init my-saas --preset saas-core --defaults
# Add authentication
backgen add jwt
backgen add clerk
# Add production hardening
backgen add ratelimit
# Generate a resource
backgen generate resource Product name:string price:number stock:number
# Start developing
cd my-api
npm run dev
```
---
## Commands
### `backgen init [name]`
Generate a new backend project.
```bash
backgen init my-api # interactive ORM picker
backgen init my-api --orm prisma # explicit ORM
backgen init my-api --orm drizzle --defaults # Drizzle, non-interactive
backgen init my-api --orm mongoose --skip-install
backgen init my-api --preset saas-core --defaults # full multi-tenant domain
backgen init my-api --preset healthcare # healthcare domain
```
**Output:**
- Express app with TypeScript strict mode
- ORM-specific data layer (Prisma / Drizzle / Mongoose)
- Environment validation (Zod)
- Swagger/OpenAPI documentation
- Docker + docker-compose
- Hardened by default: helmet, CORS, request ID, timeout, xss + mongo-sanitize, graceful shutdown, health checks
- ESLint 9 + Vitest
- `.backgenrc.json` manifest (records `project.orm` + plugins)
No auth by default — choose your auth provider with `backgen add`.
---
### `backgen add [plugin]`
Install a plugin. Interactive multi-select if no argument.
```bash
backgen add # interactive multi-select
backgen add jwt # JWT authentication
backgen add clerk # Clerk auth-as-a-service
backgen add stripe # Stripe payments
backgen add s3 # AWS S3 storage
backgen add ratelimit # Per-IP / per-user rate limiting
backgen add devops # Install all devops plugins at once
```
**Available Plugins:**
| Plugin | Category | Description |
|--------|----------|-------------|
| `jwt` | auth | JWT authentication with refresh tokens |
| `clerk` | auth | Clerk auth-as-a-service (conflicts with jwt) |
| `stripe` | payment | Stripe checkout, webhooks, customers |
| `s3` | storage | AWS S3 upload, download, presigned URLs |
| `ratelimit` | production | Per-IP rate limiting with Redis-ready store |
| `ci-github` | devops | GitHub Actions CI pipeline (lint, typecheck, test, build, optional deploy) |
| `dependabot` | devops | Automated dependency updates via Dependabot |
| `codeql` | devops | CodeQL security analysis on push and schedule |
| `docker-registry` | devops | Docker image build and publish to GHCR |
| `release` | devops | Semantic release with npm publish and GitHub releases |
**Conflict detection:** `jwt` and `clerk` cannot be installed together.
---
## Domain Presets
Generate a complete domain in one command. Each preset creates multiple resources with relations, auto-installs JWT auth, and wires everything together.
```bash
backgen init my-api --preset healthcare
backgen init my-api --preset saas --defaults
```
### healthcare
Patient, Doctor, Appointment, Prescription, MedicalRecord — appointments between patients and doctors, prescriptions linked to patients, medical records per patient.
### saas
Organization, Team, Membership, Subscription, Invoice — organizations with teams and memberships, subscriptions with invoices.
### ecommerce
Category, Product, Cart, Order, OrderItem, Payment — products in categories, carts with items, orders with line items and payments.
### crm
Contact, Company, Deal, Activity — companies with contacts, deals tracked through pipeline, activity logging.
### lms
Course, Lesson, Enrollment, Progress, Certificate — courses with lessons, student enrollments, progress tracking, certificates.
---
### `backgen remove [plugin]`
Remove a plugin. Interactive multi-select if no argument. Supports `devops` shorthand to remove all devops plugins.
```bash
backgen remove # interactive multi-select
backgen remove stripe # remove specific plugin
backgen remove devops # remove all devops plugins
```
---
### `backgen generate resource <name> [fields...]`
Generate a CRUD resource module.
```bash
# Interactive
backgen generate resource Product
# Non-interactive
backgen generate resource Product name:string price:number stock:number
# With relations
backgen generate resource Appointment date:datetime status:string \
--relations "doctor:Doctor,patient:Patient"
# With --fields flag
backgen generate resource Product --fields "name:string,price:number"
```
**Generated files:**
```
src/modules/product/
product.controller.ts # CRUD endpoints
product.service.ts # business logic
product.repository.ts # database operations
product.validation.ts # Zod schemas
product.types.ts # TypeScript interfaces
product.routes.ts # route definitions + Swagger
product.test.ts # test placeholder
```
**Field types:** `string`, `number`, `boolean`, `date`, `datetime`
**Relations:** `doctor:Doctor` (belongsTo), `patients:Patient` (hasMany)
---
### `backgen generate seed <resource>`
Generate seed data for development.
```bash
backgen generate seed Product --count 10
```
Output: `prisma/seeds/product.ts` (Prisma), `db/seeds/product.ts` (Drizzle), or `seeds/product.ts` (Mongoose)
---
### `backgen generate factory <resource>`
Generate a test factory.
```bash
backgen generate factory Product
```
Output: `src/factories/product.factory.ts`
Usage:
```ts
import { createProduct } from "./factories/product.factory.js";
const product = await createProduct({ name: "Widget" });
```
---
### `backgen generate route [name]`
Generate a custom route module with a complete controller, service, validation, types, and route file -- including Swagger annotations. Routes are automatically registered in `app.ts` with the `REGISTER_ROUTES` marker.
Use this when you need a custom endpoint that doesn't fit the CRUD pattern (e.g., dashboards, reports, webhooks, custom actions). For standard CRUD, use `generate resource` instead.
```bash
backgen generate route # interactive prompt
backgen generate route reports # generate a /api/reports module
backgen generate route webhooks # generate a /api/webhooks module
```
**Generated files:**
```
src/modules/reports/
reports.controller.ts # request handlers
reports.service.ts # business logic
reports.validation.ts # Zod schemas
reports.types.ts # TypeScript interfaces
reports.routes.ts # route definitions + Swagger
```
**Key differences from `generate resource`:**
- No database model, repository, or test file
- No field specification required
- Pure controller/service pattern for custom endpoints
- Mounted at `/api/<name>` with full Swagger docs
---
### `backgen generate migration [name]`
Generate a database migration (ORM-aware).
```bash
backgen generate migration add-product-table # runs prisma migrate dev / drizzle-kit generate / no-op for Mongoose
```
---
### `backgen sync`
Reconcile `.backgenrc.json` with the project. Regenerates missing plugin files.
```bash
backgen sync
```
---
### `backgen mcp`
Start BackGen as an MCP server over stdio. Used by AI assistants (Claude, Cursor, VS Code) to scaffold projects programmatically.
```bash
backgen mcp
```
This is the same server exposed via the `npx @ibrahimkhaled19/backgen backgen-mcp` binary. It registers all 10 MCP tools listed in the [AI-Ready](#-ai-ready) section.
---
### `backgen health`
Show system health information.
```bash
backgen health
```
**Displays:**
- Node.js version
- Platform and architecture
- BackGen version
---
### `backgen doctor`
Check project health with ownership integrity diagnostics.
```bash
backgen doctor # health check + ownership audit
backgen doctor --fix # auto-fix missing manifest entries
```
**Checks:**
- Node.js version (>= 18)
- npm availability
- .env file
- DATABASE_URL
- Prisma schema / Drizzle config / Mongoose connection
- Dependencies
- Package manager version
- **File integrity** — all manifest-tracked files exist on disk
- **Ownership integrity** — framework vs user file classification
---
### `backgen upgrade`
Upgrade a generated project to the latest template version. Creates a backup, then applies pending migrations sequentially.
```bash
backgen upgrade # show pending migrations, prompt before applying
backgen upgrade --yes # skip confirmation, apply all pending
```
**What happens:**
- Reads current `generatedVersion` from `.backgenrc.json`
- Loads pending core + plugin migrations
- Creates backup in `.backgen/backups/pre-<version>/`
- Applies migrations in order (semver-sorted)
- Updates ownership register + `generatedVersion` in manifest
---
### `backgen rollback`
Restore a project to its pre-upgrade state from the most recent backup.
```bash
backgen rollback # show latest backup, prompt before restoring
backgen rollback --yes # skip confirmation
```
**What happens:**
- Lists available backups in `.backgen/backups/`
- Restores the most recent backup (all tracked files + manifest)
- Project returns to exact pre-upgrade state
---
### `backgen rotate-secrets`
Rotate JWT secrets in the project's `.env` file. Generates cryptographically secure 256-bit random hex values for `JWT_SECRET` and `JWT_REFRESH_SECRET`, backs up the current `.env` to `.env.backup`, and writes new values.
All existing tokens are immediately invalidated on next server restart -- users must re-login.
```bash
backgen rotate-secrets
```
**What happens:**
- Generates two 256-bit random hex secrets via `crypto.randomBytes`
- Old `.env` saved to `.env.backup`
- Previous values preserved as comments in the new `.env`
- Print summary of changes
---
## Plugin System
Every plugin implements the `BackGenPlugin` interface:
```ts
interface BackGenPlugin {
name: string;
category: string;
description: string;
version: string;
dependencies?: string[];
devDependencies?: string[];
requires?: string[];
conflicts?: string[];
env?: Record<string, string>;
templates: string[];
migrations?: PluginMigration[]; // versioned plugin migration scripts
install(ctx: InstallContext): Promise<void>;
uninstall?(ctx: InstallContext): Promise<void>;
}
```
Plugins can:
- Install npm dependencies
- Inject environment variables
- Register routes in app.ts
- Replace existing middleware
- Add database models (Prisma / Drizzle / Mongoose)
- Carry versioned migrations for own upgrades
---
## Project Manifest
`.backgenrc.json` tracks plugins, versions, generated version, and file ownership:
```json
{
"version": "1.0.0",
"generatedVersion": "1.9.0",
"project": {
"name": "my-api",
"framework": "express",
"database": "postgresql",
"orm": "prisma",
"preset": "saas-core"
},
"plugins": {
"jwt": {
"version": "1.0.0",
"installedAt": "2026-06-01",
"source": "core"
}
},
"files": {
"src/app.ts": { "owner": "shared", "version": "1.9.0" },
"src/server.ts": { "owner": "framework", "version": "1.9.0" },
"src/config/env.ts": { "owner": "framework-editable", "version": "1.9.0" },
"prisma/schema.prisma": { "owner": "user" },
"src/modules/user/user.service.ts": { "owner": "user" },
"docker-compose.yml": { "owner": "shared", "version": "1.9.0" }
}
}
```
**Ownership levels:**
| Level | Description | Upgrade behavior |
|-------|-------------|-----------------|
| `framework` | BackGen owns fully | Safe to overwrite |
| `framework-editable` | Generated but user may customize | Smart merge via migration |
| `shared` | Generated skeleton, user extends (e.g. docker-compose) | Migration-aware update |
| `user` | User owns entirely | Never touched |
---
## Generated Project Structure
```
my-api/
├── prisma/ # Prisma ORM only
│ ├── schema.prisma
│ └── seeds/
├── src/db/ # Drizzle ORM only
│ ├── schema/
│ │ └── index.ts
│ └── seeds/
├── src/models/ # Mongoose ORM only
│ └── seeds/
├── src/
│ ├── app.ts # Express app setup
│ ├── server.ts # Server entry point
│ ├── config/
│ │ ├── env.ts # Zod env validation
│ │ ├── database.ts # Prisma client / Drizzle db / Mongoose connection
│ │ └── swagger.ts # Swagger config
│ ├── middleware/
│ │ ├── auth.ts # JWT/Clerk auth
│ │ ├── validate.ts # Zod validation
│ │ ├── error.ts # Global error handler
│ │ └── logger.ts # Request logging
│ ├── modules/
│ │ ├── auth/ # Auth module (if jwt installed)
│ │ ├── stripe/ # Stripe module (if installed)
│ │ └── <resource>/ # Generated resources
│ ├── services/
│ │ └── logger.service.ts # Winston logger
│ ├── utils/
│ │ ├── api-error.ts # Error class
│ │ ├── async-handler.ts # Async wrapper
│ │ └── response.ts # Response formatters
│ └── factories/ # Test factories
├── .env.example
├── .backgenrc.json # Manifest
├── Dockerfile
├── docker-compose.yml
├── package.json
└── tsconfig.json
```
---
## Development
```bash
# Clone
git clone https://github.com/your-username/backgen.git
cd backgen
# Install
npm install
# Build
npm run build
# Test
npm run test
# Lint
npm run lint
```
### Test Suite
277+ tests covering:
- CLI help and version
- Init: project structure, configs, manifest (all 3 ORMs)
- Init with domain presets: preset-specific resources and relations
- Init with saas-core preset: multi-tenant organizations, memberships, RBAC
- Add plugin: files, routes, env vars, manifest (V4.6 plugin suite)
- Generate resource: module files, ORM model, routes, validation
- Generate with relations: foreign keys, ORM includes
- Seed and factory generators (all 3 ORMs)
- Drizzle: schema generation, client setup, codegen
- Mongoose: model generation, schema definition, connection
- Remove plugin: file + dependency + manifest cleanup
- Sync: file restoration
- Doctor: health checks, ownership integrity
- Upgrade: migration engine, pending detection, backup creation
- Rollback: backup listing, file restoration, manifest recovery
- Error handling: unknown plugin, non-empty directory
---
## Tech Stack
| Layer | Technology |
|-------|------------|
| CLI | Commander.js |
| Prompts | Inquirer.js |
| Templates | Handlebars |
| Spinner | Ora |
| Colors | Chalk |
| Testing | Vitest |
| Linting | ESLint 9 (flat config) |
| Language | TypeScript (strict) |
### Generated Projects
| Layer | Technology |
|-------|------------|
| Framework | Express.js |
| Language | TypeScript (strict) |
| Database | PostgreSQL |
| ORM | Prisma / Drizzle / Mongoose |
| Validation | Zod |
| Auth | JWT or Clerk |
| Payments | Stripe |
| Storage | AWS S3 |
| Docs | Swagger/OpenAPI |
| Logging | Winston + Morgan |
| Testing | Vitest |
| Deployment | Docker |
---
## BackGen vs Alternatives
| Tool | ORM Choice | Auth | Plugin System | Presets | Upgrade Engine | Docs Site |
|------|-----------|------|---------------|---------|----------------|-----------|
| **BackGen** | Prisma, Drizzle, Mongoose | JWT, Clerk | ◈ 7+ plugins | 5 domains | ◈ Backup + rollback | — |
| NestJS CLI | No (fixed NestJS) | Built-in | ◈ Modules | — | — | ◈ |
| Express Generator | No (fixed plain JS) | — | — | — | — | — |
| T3 Stack | Prisma | NextAuth | — | — | — | ◈ |
| AdonisJS | Lucid ORM | Built-in | ◈ Ace | — | — | ◈ |
| LoopBack | Built-in | Built-in | ◈ | — | — | ◈ |
**Key differentiators:**
- ◈ **ORM-switchable** — change Prisma ↔ Drizzle ↔ Mongoose via manifest, not rewrite
- ◈ **Domain presets** — healthcare, SaaS, ecommerce, CRM, LMS in one command
- ◈ **Upgrade engine** — versioned migrations + backup + rollback for generated projects
- ◈ **Multi-ORM from day one** — not locked into one data layer
---
## Roadmap
| Version | Focus | Status |
|---------|-------|--------|
| V1 | Foundation | Done |
| V2 | Plugin System | Done |
| V3 | Resource Generator | Done |
| V4 | Domain Presets | Done |
| V4.5 | SaaS Essentials | Done |
| V4.6 | Production Hardening | Done |
| V4.6.1 | Base Hardening Default-On | Done |
| V5 | Multi-ORM (Prisma, Drizzle, Mongoose) | Done |
| V6 | DevOps & Infrastructure | Done |
| V6.1 | Ownership Tracking & Doctor --fix | Done |
| V6.2 | Upgrade Engine & Migration Runner | Done |
| V6.3 | Backups & Rollback | Done |
| V6.4 | Plugin Migrations | Done |
| V7 | Upgrade Polish & Diffing | In Progress |
| V8 | Schema-First Development | Planned |
| V9 | Enterprise Features | Planned |
| V10 | Plugin Authoring SDK | Planned |
| V11 | Marketplace | Planned |
| V12 | AI Context Layer | Planned |
See [docs/ROADMAP.md](docs/ROADMAP.md) for details.
---
## License
MIT