FastAPI + React Starter Template

Overview

Starting a new full-stack project usually means an afternoon of plumbing: wiring CORS, getting migrations to find your models, teaching your settings loader about .env files, and remembering the exact incantation to boot three services at once. This template packages all of that as a GitHub template repository — click "Use this template", rename a placeholder, and start writing features.

What's included

• Backend. Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic migrations, managed with uv.
• Frontend. React 19 + TypeScript with the React Compiler, built with Vite.
• Database. PostgreSQL 16 in Docker via docker-compose.
• Wired up out of the box. CORS configured, Alembic reads the DB URL from .env, settings load via pydantic-settings, and OpenAPI docs are auto-generated.
• One-command dev workflow. dev.ps1 spins up Postgres and opens the backend and frontend in Windows Terminal tabs; reset_db.ps1 wipes and rebuilds the local database in one shot.

Project Structure

The backend keeps a strict separation of concerns: models.py for ORM models, schemas.py for Pydantic request/response shapes, routers/ for endpoints, and config.py for env-driven settings. The frontend is a standard Vite + React workspace. Docker Compose, the dev scripts, and a shared .env.example live at the root.

Design Decisions

• Credentials never live in committed files. The sqlalchemy.url field in alembic.ini is intentionally blank; alembic/env.py injects DATABASE_URL from .env before any engine is created.
• Migrations can't silently miss tables. alembic/env.py imports app.models so every model class registers itself with Base.metadata, which is what autogenerate scans.
• React Compiler by default. Components are auto-memoized at build time; the ESLint plugin flags Rules-of-React violations.
• Disposable local database. reset_db.ps1 drops the Postgres volume and re-applies every migration from scratch — the escape hatch for bad seed data or a half-applied migration.

Developer Experience

A single .\dev.ps1 boots the whole stack: Postgres detached on port 5432, the FastAPI backend (with Swagger UI at /docs) and the Vite frontend each in their own Windows Terminal tab. The README documents first-time setup, common tasks (adding dependencies, creating migrations, running pytest), a renaming checklist for rebranding the planner placeholder, and a troubleshooting section covering the Windows papercuts that actually bite — stale PATHs, Pylance interpreter selection, and Notepad's infamous .env.txt.

I used this template to build Web Planner, a personal calendar and task-planning app.