hedron

FastAPI-native typed component framework for HTML and HTMX.

Build dashboards, admin tools, and CRUD apps as typed Python components — without a Node.js frontend stack. Hedron extends FastAPI with pages, addressable components, typed actions, CSRF-aware forms, HTMX fragment/OOB policy, OpenAPI text/html metadata, interaction built-ins (Lazy, Poll, Pagination, …), caching (cache_data / cache_component), ColorMode persistence, a thin Hedron() application facade, CLI (new / check / graph / build / …), plugin loading, and public hedron.testing helpers.

Built on framework-neutral hedron-core. Flask and Django hosts use hedron-flask and hedron-django.

Package maturity: Beta · Train: 0.23.0 (Published) · pin >=0.23.0,<0.24

Most public APIs remain compatibility level beta until listed in the small stable table. Capability readiness: What’s ready today.

Install

pip install "hedron>=0.23.0,<0.24"
# or
uv add "hedron>=0.23.0,<0.24"

Requires Python 3.11–3.14.

Optional extras

pip install "hedron[data,dev]>=0.23.0,<0.24"
pip install "hedron[charts]>=0.1.0,<0.2"   # Alpha — pin and expect churn

Quick start

Scaffold an app with a working HTMX Refresh status control:

# Need uv? https://docs.astral.sh/uv/getting-started/installation/
uvx --from "hedron>=0.23.0,<0.24" hedron new my-hedron-app
cd my-hedron-app && uv sync && uv run uvicorn app:app --reload

Open http://127.0.0.1:8000 — click Refresh status; the timestamp updates via an HTMX fragment swap.

Full walkthrough: Build your first app.

Minimal app

from hedron import Hedron, Page, Text

app = Hedron(
    title="Demo",
    security="standard",
    session_secret="replace-in-production",
    explorer="off",
)


@app.page("/")
def home() -> Page:
    return Page(Text("Hello, Hedron"), title="Demo")

pip install "hedron>=0.23.0,<0.24" "uvicorn[standard]"
uvicorn app:app --reload

Plain FastAPI

from fastapi import FastAPI
from hedron import HTML, HedronRouter, Text, hedron_response, mount_hedron_static
from hedron.security.policy import SecurityPolicy

app = FastAPI()
app.state.hedron_security = SecurityPolicy.from_name("standard")
mount_hedron_static(app)
router = HedronRouter()


@router.get("/card", **hedron_response())
def card():
    return HTML(Text("plain"))


app.include_router(router)

CLI

hedron new demoapp
cd demoapp
hedron --app app:app routes
hedron --app app:app components
hedron --app app:app preview home
hedron check --format json --severity error
hedron graph
hedron audit-components

If hedron is not on your PATH, use python -m hedron.

Links

• Documentation
• Optional packages
• What’s ready
• Changelog
• Source
• Issues
• hedron-core · hedron-flask · hedron-django

License

MIT. See LICENSE.