claude-scaffold: Skill for Claude Code

HTMX Frontend

When to Load This Skill

Load when working with: Jinja2 templates, HTMX attributes, static files, server-side rendering, admin panels, dashboards integrated into FastAPI.

Architecture Decision

HTMX frontend lives inside the FastAPI application — no separate frontend service, no build step, no npm. This is intentional and correct for our use cases (internal tools, admin panels, dashboards with moderate load).

For high-traffic public frontends, consider a separate service. For everything else, co-location in FastAPI is simpler, easier to deploy, and has zero JS toolchain overhead.

Router Separation

JSON API routes and HTMX page routes live in separate routers and must never mix:

api/
├── routers/
│   ├── items.py       # JSON API — returns Pydantic models
│   └── health.py
└── pages/
    ├── dashboard.py   # HTMX pages — returns TemplateResponse
    ├── admin.py
    └── chat.py

from fastapi import APIRouter, Depends, Request
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates

templates = Jinja2Templates(directory="src/project_name/templates")
router = APIRouter()


@router.get("/", response_class=HTMLResponse)
async def dashboard(request: Request) -> HTMLResponse:
    return templates.TemplateResponse(
        "dashboard.html",
        {"request": request, "title": "Dashboard"},
    )


@router.get("/items/list", response_class=HTMLResponse)
async def items_list(request: Request, service=Depends(get_item_service)) -> HTMLResponse:
    items = await service.list_all()
    return templates.TemplateResponse(
        "partials/items_list.html",
        {"request": request, "items": items},
    )

Template Structure

src/{project_name}/
├── templates/
│   ├── base.html           # base layout
│   ├── dashboard.html
│   ├── admin.html
│   └── partials/           # HTMX partial responses
│       ├── items_list.html
│       ├── chat_message.html
│       └── toast.html
└── static/
    ├── htmx.min.js         # pinned version, served locally
    ├── css/
    │   └── styles.css
    └── js/
        └── app.js          # minimal custom JS only