create-forgekit-app

Scaffold a production-ready fullstack project in seconds. Choose your frontend and backend, and ForgeKit assembles the project structure, Docker Compose setup, CI pipeline, and environment configuration for you.

Prerequisites

• Node.js >= 18
• Docker (for docker compose up)
• Supabase account — the generated project expects a Supabase PostgreSQL database

Installation

No global install required. Use npx to always run the latest version:

npx create-forgekit-app my-app

Or install globally:

npm install -g create-forgekit-app
create-forgekit-app my-app

Quick start

npx create-forgekit-app my-app
cd my-app
cp .env.example .env   # fill in DATABASE_URL and JWT_SECRET
docker compose up --build

The frontend will be available at http://localhost:3000 and the backend at http://localhost:8000.

What gets generated

my-app/
├── frontend/          # React (Vite) or Next.js app
├── backend/           # FastAPI or NestJS app
├── docker-compose.yml # ready-to-run Compose file (if selected)
├── .gitlab-ci.yml     # GitLab CI pipeline (if selected)
└── .env.example       # all required environment variables

The generated README.md inside my-app/ describes the full local dev workflow for your chosen stack.

Supported combinations

| Frontend | Backend | Docker | CI | |----------|---------|:------:|:--:| | React (Vite + TypeScript + Tailwind) | FastAPI (Python + SQLAlchemy + Alembic) | yes | yes | | React (Vite + TypeScript + Tailwind) | NestJS (TypeScript + TypeORM) | yes | yes | | Next.js (App Router + TypeScript + Tailwind) | FastAPI (Python + SQLAlchemy + Alembic) | yes | yes | | Next.js (App Router + TypeScript + Tailwind) | NestJS (TypeScript + TypeORM) | yes | yes |

Docker Compose and GitLab CI are optional at generation time.

Stack

| Layer | Options | |-------|---------| | Frontend | React (Vite) / Next.js (App Router) | | Backend | FastAPI / NestJS | | Database | Supabase (PostgreSQL) | | Auth | JWT Bearer tokens | | Containerisation | Docker + Docker Compose | | CI/CD | GitLab CI |

API contract

Both backend templates expose the same HTTP surface so the frontend code is portable across backends. See docs/API_CONTRACT.md for:

• All 5 routes with method, path, auth requirement, request/response format
• Consistent error envelope ({ "detail": "..." })
• JWT auth header format
• Environment variable reference
• Port reference (FastAPI/NestJS: 8000, React Docker: 8080, Next.js: 3000)

License

MIT