v2.0 — Complete rewrite with signal-based reactivity, session-scoped state, plugin hooks, and a Streamlit-like API that doesn't re-run your entire script.

Quick Start

pip install cacao

import cacao as c

c.title("Hello, Cacao!")
c.text("Welcome to the simplest Python web framework")

cacao run app.py

That's it — 3 lines of Python and you have a live web app with hot reload.

Why Cacao?

Features

Reactive Signals

count = c.signal(0, name="count")

@c.on("increment")
async def increment(session, event):
    count.set(session, count.get(session) + 1)

Signals are the core of Cacao. When a value changes, only the affected components update — no full-page reruns, no diffing your entire tree.

60+ Built-in Components

Layouts, forms, charts, display elements, navigation — everything you need out of the box.

Multi-Page Apps

with c.page("/"):
    c.title("Home")

with c.page("/settings"):
    c.title("Settings")

Hash-based routing works both in server mode and static builds.

Static Builds

cacao build app.py

Export your app to a static site (HTML + JS + CSS) that runs entirely in the browser. Deploy to GitHub Pages, Netlify, or any static host — no Python server required.

Plugin Hooks & Auth

Extensible architecture with plugin registration, authentication hooks, and notification toasts.

Dark & Light Themes

c.config(theme="dark")  # or "light"

Examples

Interactive Counter

import cacao as c

c.config(title="Counter")
count = c.signal(0, name="count")

@c.on("increment")
async def increment(session, event):
    count.set(session, count.get(session) + 1)

@c.on("decrement")
async def decrement(session, event):
    count.set(session, count.get(session) - 1)

c.title("Counter")

with c.card():
    c.metric("Count", count)
    with c.row():
        c.button("-", on_click="decrement", variant="secondary")
        c.button("+", on_click="increment")

Dashboard with Charts

import cacao as c

c.config(title="Sales Dashboard", theme="dark")
sales = c.sample_sales_data()

c.title("Sales Dashboard")

with c.row():
    c.metric("Revenue", "$45,231", trend="+20.1%", trend_direction="up")
    c.metric("Orders", "1,247", trend="+12.5%", trend_direction="up")
    c.metric("Customers", "842", trend="+5.3%", trend_direction="up")

with c.row():
    with c.col(span=8):
        with c.card("Revenue Trend"):
            c.line(sales, x="date", y="revenue", area=True)
    with c.col(span=4):
        with c.card("By Category"):
            c.pie(sales[:5], values="revenue", names="category", donut=True)

with c.card("Recent Transactions"):
    c.table(sales[:10], columns=["date", "category", "revenue", "orders"])

More examples in the examples/ directory:

Components

Layout

Display

Form

Charts

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         PYTHON SERVER                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Signals  │  │ Sessions │  │  Events  │  │ WebSocket/HTTP│  │
│  │ (state)  │──│ (per-    │──│ (typed   │──│    Server     │  │
│  │          │  │  client) │  │  async)  │  │  (Starlette)  │  │
│  └──────────┘  └──────────┘  └──────────┘  └───────┬───────┘  │
└────────────────────────────────────────────────────┼───────────┘
                                                     │ JSON
                                                     │ WebSocket
┌────────────────────────────────────────────────────┼───────────┐
│                      REACT CLIENT                  │           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────┴──────┐   │
│  │  Hooks   │  │Components│  │  Event   │  │   State     │   │
│  │useCacao()│──│ (60+ UI) │──│Dispatcher│──│   Store     │   │
│  └──────────┘  └──────────┘  └──────────┘  └─────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Data flow:

Python API → JSON definition → WebSocket → React renders
     ↑                                         ↓
Signal.set() ←── Event handler ←── User action

CLI

cacao run app.py                     # Run with hot reload
cacao run app.py --port 3000         # Custom port
cacao run app.py --no-reload         # Disable hot reload
cacao create my-dashboard            # Scaffold a new project
cacao build app.py                   # Build static site
cacao build app.py --base-path /repo # For GitHub Pages subdirectory

Static Builds

Cacao generates static sites that run entirely in the browser — no Python server required.

cacao build app.py

Output:

dist/
├── index.html    # Your app
├── cacao.js      # Runtime + built-in handlers
└── cacao.css     # Styles

Built-in client-side handlers for common operations:

• Encoders — Base64, URL, HTML entities, JWT decode
• Generators — UUID, passwords, Lorem Ipsum
• Converters — JSON/YAML, case conversion, number bases
• Text — Statistics, regex testing
• Crypto — Hash generation, HMAC

Deploy to GitHub Pages:

# .github/workflows/deploy.yml
- run: pip install cacao
- run: cacao build app.py --base-path /${{ github.event.repository.name }}

See cacao-tools for a full static site example.

Tech Stack

Project Structure

cacao/
├── __init__.py          # Package exports
├── simple.py            # Streamlit-like API (import cacao as c)
├── server/              # Core server
│   ├── ui.py            # 60+ UI components
│   ├── chart.py         # Chart components
│   ├── signal.py        # Signal & Computed reactivity
│   ├── session.py       # Session management
│   ├── events.py        # Event handling
│   ├── server.py        # HTTP + WebSocket server
│   └── data.py          # Data utilities
├── cli/                 # CLI (run, build, create)
├── frontend/            # Frontend source (devs only)
│   ├── src/components/  # React components
│   ├── src/styles/      # LESS styles
│   ├── src/handlers/    # Static build handlers
│   └── dist/            # Build output
└── examples/            # Example apps

Contributing

Contributions are welcome! See the repo issues for ideas.

fork → feature branch → commit → push → pull request