fastapi-init

fastapi-init

Scaffold a new FastAPI project end-to-end. This skill coordinates with others in the plugin — invoke them at the right steps rather than reinventing what they already encode.

Prerequisite skills

• uv skill: use for all uv add, uv run, and environment commands — never fall back to pip
• click-cli skill: consult if the user wants an extended CLI beyond the basic server entry point
• fastapi-errors skill: the authority on the full error architecture — domain subclasses, error codes, auth error patterns, and existing-repo strategy

---

Step 1 — Confirm the service name

Ask: "What's the name of this service?"

Use a single snake_case variable {pkg_name} for everything — the project directory, the Python package, the pyproject.toml name, and the CLI command (e.g. my_service). The uv run {pkg_name} serve command will use it directly. Derive {PkgName} as the PascalCase form of {pkg_name} (e.g. my_service → MyService) — used only for the exception class name.

---

Step 2 — Initialize with uv

uv init {pkg_name} --app --no-workspace
cd {pkg_name}

Remove the stub file uv generates (hello.py), then add dependencies:

uv add fastapi "uvicorn[standard]" "sqlalchemy[asyncio]" aiosqlite "pydantic-settings" click
uv add --dev pytest pytest-asyncio httpx

After uv init, add the hatchling build backend to pyproject.toml so [project.scripts] works:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["{pkg_name}"]

---

Step 3 — Directory structure

Build this layout under the project root:

{pkg_name}/
├── pyproject.toml
├── uv.lock
├── {pkg_name}/                         ← Python package, same name as project root
│   ├── __init__.py
│   ├── main.py                # FastAPI app + lifespan
│   ├── cli.py                 # click entry point
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py          # pydantic-settings Settings
│   │   └── exceptions.py      # {PkgName}Error base + usage note
│   ├── api/
│   │   ├── __init__.py
│   │   ├── deps.py            # shared Annotated Depends providers
│   │   └── v1/
│   │       ├── __init__.py
│   │       └── routes/
│   │           ├── __init__.py
│   │           └── health.py
│   ├── db/
│   │   ├── __init__.py
│   │   ├── base.py            # Base, TimestampMixin, naming convention
│   │   └── session.py         # engine, AsyncSessionLocal, get_db
│   ├── models/
│   │   └── __init__.py        # SQLAlchemy declarative models
│   └── schemas/
│       ├── __init__.py
│       └── base.py            # APIModel + ReadModel base schemas
└── tests/
    ├── __init__.py
    ├── conftest.py
    └── api/
        └── v1/
            ├── __init__.py
            └── test_health.py