project-initializer 0.3.3

CLI tool to scaffold full-stack projects with FastAPI or NestJS, Angular, and Docker

project-initializer

CLI tool to scaffold full-stack projects with FastAPI or NestJS, Angular, and Docker — with optional authentication via token or Supabase. Scaffold the full stack, or just the backend or frontend with --scope.

Installation

pip install project-initializer

Or install from source:

git clone https://github.com/silviobaratto/project-initializer.git
cd project-initializer
pip install -e .

Quick Start

project-initializer my-project
cd my-project
# Edit api/.env with your real keys
docker-compose up -d

Framework Selection

Choose a backend framework with --fastapi (default) or --nestjs:

project-initializer my-app --fastapi    # FastAPI backend (default)
project-initializer my-app --nestjs     # NestJS backend

Feature	FastAPI	NestJS
Language	Python 3.12	TypeScript (Node 20)
ORM	SQLAlchemy + Alembic	Prisma
AI/LLM	BAML (Python)	BAML (TypeScript)
API style	REST with Pydantic	REST with class-validator
Architecture	Layered (routes/services/repos)	Modular (controllers/services/modules)

Authentication Modes

Add authentication with --auth token or --auth supabase:

project-initializer my-app --auth token      # Simple bearer-token auth
project-initializer my-app --auth supabase    # Supabase JWT auth + RLS

• No auth (default) — No authentication middleware. Good for prototyping.
• Token auth (--auth token) — Bearer-token middleware on the API. Frontend gets a login guard and an HTTP interceptor that attaches the token.
• Supabase auth (--auth supabase) — Supabase JWT validation on the API. Frontend integrates @supabase/supabase-js for login/signup. Docker Compose omits the local db service since Supabase hosts the database.

Project Scope (full-stack / backend-only / frontend-only)

By default the CLI scaffolds both halves (api/ + frontend/). Use --scope to generate only one:

project-initializer my-app                      # fullstack (default): api + frontend
project-initializer my-app --scope api          # backend only — no frontend/, no frontend service
project-initializer my-app --scope frontend     # frontend only — Angular app, no api/

• --scope api — emits api/ + docker-compose.yml (without the frontend service) + api/.env. Combine with --fastapi/--nestjs/--auth as usual.
• --scope frontend — emits just the Angular frontend/ (nginx /api/ proxy stripped). Cannot be combined with --fastapi/--nestjs/--auth (those are backend concerns).
• --scope fullstack (default) — both halves, current behavior.

Async Database (opt-in)

FastAPI backends scaffold the sync SQLAlchemy path by default — sync def path operations run in Starlette's threadpool, so a blocking Session never stalls the event loop. This is the recommended default per the FastAPI tutorial.

Pass --async-db to additionally lay down the async SQLAlchemy overlay (async engine + AsyncSession + get_async_db dependency, asyncpg driver):

project-initializer my-app --async-db              # fullstack + async DB path
project-initializer my-app --scope api --async-db  # backend only + async DB path

• FastAPI only — rejected with --nestjs and with --scope frontend.
• Additive: the sync path stays the default; the async modules are an isolated overlay you wire in explicitly.
• See the generated api/.claude/CLAUDE.md for the sync-vs-async convention (pick the keyword from the I/O, not by style).

All 6 Variants

Command	Backend	Auth
project-initializer app	FastAPI	None
project-initializer app --auth token	FastAPI	Token
project-initializer app --auth supabase	FastAPI	Supabase
project-initializer app --nestjs	NestJS	None
project-initializer app --nestjs --auth token	NestJS	Token
project-initializer app --nestjs --auth supabase	NestJS	Supabase

Additional flags:

project-initializer my-project --scope api       # Backend only
project-initializer my-project --scope frontend  # Frontend only
project-initializer my-project --async-db        # FastAPI async SQLAlchemy path (opt-in)
project-initializer my-project --force           # Overwrite existing files
project-initializer .                            # Scaffold in current directory
project-initializer --version                    # Show version

Generated Project Structure

my-project/
├── api/                    # Backend (FastAPI or NestJS)
│   ├── .env                # Auto-generated from variant
│   ├── Dockerfile
│   └── ...
├── frontend/               # Angular + Tailwind CSS
│   ├── Dockerfile
│   ├── nginx.conf
│   └── src/
├── docker-compose.yml      # Full-stack orchestration
├── .env.example            # Reference for environment variables
└── CLAUDE.md               # AI assistant guidance

Docker Services

Service	Port	Description	Supabase variants
db	5433:5432	PostgreSQL 16	Omitted (Supabase hosts DB)
adminer	8080:8080	DB management UI	Omitted
api	8000:8000	Backend with hot reload	Present
frontend	4200:80	Angular + nginx (proxies /api/ to backend)	Present

Environment Configuration

The CLI auto-generates api/.env based on the chosen variant. A root .env.example documents all possible variables.

For Supabase variants, configure these in api/.env:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_KEY=sb_publishable_...   # client-side (replaces legacy anon key)
SUPABASE_SECRET_KEY=sb_secret_...             # server-side, bypasses RLS (replaces service_role)

Development

FastAPI

cd api
pip install -r requirements.txt
uvicorn app.main:app --reload          # API on :8000
alembic upgrade head                   # Run migrations
pytest                                 # Run tests

NestJS

cd api
npm install
npm run start:dev                      # API on :8000
npx prisma migrate dev                 # Run migrations
npm run test                           # Run tests

Frontend (Angular)

cd frontend
npm install --legacy-peer-deps
ng serve                               # Dev server on :4200
ng build                               # Production build
ng test                                # Unit tests

Contributing

See CONTRIBUTING.md for development setup, template architecture, and PR guidelines.

License

MIT