volfpeter/holm/holm-web

Building holm web applications

Architecture summary

• FastAPI: underlying web framework; all holm pages, layouts, actions, and metadata are FastAPI dependencies (so they can all be async)
• htmy: async, pure-Python HTML component engine; JSX-like syntax with html.div(...), full typing, async support, and context (no prop drilling)
• FastHX (fasthx.htmy.HTMY): the rendering layer; htmy.page() renders HTML for all requests; htmy.hx() renders HTML only for HTMX requests, otherwise keeps FastAPI route behavior
• holm: file-system based routing (similar to Next.js), automatic layout composition, page metadata, actions, and submit handlers
• Optional Jinja2 layout/template support via layout.jinja and holm.JinjaTemplate — see references/jinja.md

Application initialization

from holm import App
app = App()

Call holm.App() directly within a module in the root application package

Optional:

• pass a pre-configured FastAPI app
• pass a custom fasthx.htmy.HTMY renderer

File-system based routing

Dynamic routes: _id_ or {id} package names become path parameters (/user/{id})

Private packages: prefix with underscore (_components) — ignored entirely

The default path for actions is the decorated function's name, underscores replaced with hyphens

Apply REST principles whenever possible

URL construction

from fastapi import Request
def some_page(request: Request) -> ComponentType:
    url = request.url_for("my_app.users.page")
    return html.a("Users", href=str(url))

• Pages and submit handlers: "my_app.page", "my_app.users.page" (path is the same, method is different)
• Actions: "my_app.users.actions.enable_user"

Pages vs Actions

• Pages (page.py) return full HTML (wrapped in layouts); they handle regular browser navigation requests
• Actions (@action.*) return HTML fragments without layouts by default; ideal for HTML/HTMX partials

Reference files

Gotchas

1. Forms without method="POST" submit as GET and hit page(), not handle_submit()
2. page.py and actions.py and api.py in the same package have their routes merged into a single APIRouter
3. Returning Response objects from pages, actions, or handlers bypasses rendering
4. holm auto-wraps page() and layout() list/tuple returns in Fragment. Do not return a list/tuple unless it is a component sequence
5. htmy does not flatten nested component sequences: [comp1, comp2] is valid, but [[comp1, comp2]] is not. Use list unpacking or Fragment when mapping/generating components
6. Strongly prefer ComponentType and ComponentSequence return type annotations over Component to avoid component nesting problems!
7. holm uses htmy.page() for both pages and actions automatically. Actions always return HTML; use api.py if you need standard FastAPI behavior
8. Path parameters from _id_ or {id} packages are available as standard FastAPI dependencies in pages, layouts, actions, metadata, and APIs