Backgen

BackGen

[CI] [npm version] [License: MIT]

[npm downloads] [GitHub stars]

🤖 AI-Ready

[BackGen MCP server] [BackGen MCP server]

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:

backgen mcp

Or configure your AI tool's MCP client:

{  "mcpServers": {    "backgen": {      "command": "npx",      "args": ["-y", "@ibrahimkhaled19/backgen", "mcp"]    }  }}

Available MCP tools:

Then just ask: "Scaffold a SaaS backend with Prisma, JWT auth, and Stripe payments"

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.

npx @ibrahimkhaled19/backgen init my-api --orm drizzlecd my-apinpm 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

# Install globallynpm install -g @ibrahimkhaled19/backgen
# Create a project (pick your ORM)backgen init my-api --orm prismabackgen init my-api --orm drizzlebackgen init my-api --orm mongoose
# Create a full multi-tenant domainbackgen init my-saas --preset saas-core --defaults
# Add authenticationbackgen add jwtbackgen add clerk
# Add production hardeningbackgen add ratelimit
# Generate a resourcebackgen generate resource Product name:string price:number stock:number
# Start developingcd my-apinpm run dev

Commands

backgen init [name]

Generate a new backend project.

backgen init my-api                              # interactive ORM pickerbackgen init my-api --orm prisma                 # explicit ORMbackgen init my-api --orm drizzle --defaults     # Drizzle, non-interactivebackgen init my-api --orm mongoose --skip-installbackgen init my-api --preset saas-core --defaults   # full multi-tenant domainbackgen 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.

backgen add                 # interactive multi-selectbackgen add jwt             # JWT authenticationbackgen add clerk           # Clerk auth-as-a-servicebackgen add stripe          # Stripe paymentsbackgen add s3              # AWS S3 storagebackgen add ratelimit       # Per-IP / per-user rate limitingbackgen add devops          # Install all devops plugins at once

Available Plugins:

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.

backgen init my-api --preset healthcarebackgen 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.

backgen remove              # interactive multi-selectbackgen remove stripe       # remove specific pluginbackgen remove devops       # remove all devops plugins

backgen generate resource <name> [fields...]

Generate a CRUD resource module.

# Interactivebackgen generate resource Product
# Non-interactivebackgen generate resource Product name:string price:number stock:number
# With relationsbackgen generate resource Appointment date:datetime status:string \  --relations "doctor:Doctor,patient:Patient"
# With --fields flagbackgen 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.

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.

backgen generate factory Product

Output: src/factories/product.factory.ts

Usage:

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.

backgen generate route                  # interactive promptbackgen generate route reports          # generate a /api/reports modulebackgen 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).

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.

backgen sync

backgen mcp

Start BackGen as an MCP server over stdio. Used by AI assistants (Claude, Cursor, VS Code) to scaffold projects programmatically.

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 section.

backgen health

Show system health information.

backgen health

Displays:

• Node.js version
• Platform and architecture
• BackGen version

backgen doctor

Check project health with ownership integrity diagnostics.

backgen doctor              # health check + ownership auditbackgen 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.

backgen upgrade              # show pending migrations, prompt before applyingbackgen 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.

backgen rollback              # show latest backup, prompt before restoringbackgen 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.

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:

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:

{  "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:

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

# Clonegit clone https://github.com/your-username/backgen.gitcd backgen
# Installnpm install
# Buildnpm run build
# Testnpm run test
# Lintnpm 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

Generated Projects

BackGen vs Alternatives

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

See docs/ROADMAP.md for details.

License

MIT