# Bretzel

> Bretzel is a full-stack Python web framework for reactive web apps, built on server-driven UI. Python owns the routes, the typed state, the actions and the interface; the browser receives targeted HTML updates and stays in sync, with no separate JavaScript application and no npm pipeline in production. Status: alpha (0.1.0a2), MIT licence, Python 3.12, 3.13 and 3.14.

Install: `pip install bretzel`, then `bretzel new hello`, `cd hello`, `pip install -e .`, `bretzel dev`.

Key ideas:

- Typed state classes (`PageState`, `SessionState`, `UserState`, `AppState`, `ClientState`); a mutation re-renders only the `@refreshable(deps=[...])` fragments that read it, and `broadcast=` sends it to other open windows over SSE.
- 100+ `ui.*` components, server-rendered SVG charts, drag and drop arbitrated by the server, forms validated on the state.
- Signed actions, CSRF protection, security headers, signed-cookie identity, OAuth/OIDC sign-in.
- Built on FastAPI/Starlette, HTMX and idiomorph, with a small in-house browser runtime and Tailwind v4 compiled by a Rust binary.
- `bretzel describe` prints the exact API; `bretzel check` judges an app against it.

How it compares: NiceGUI keeps a live server-side UI object tree, Reflex compiles Python into a React application, and FastHTML stays deliberately close to HTML. Bretzel combines typed state and declared dependencies with targeted server-rendered fragments, multi-user updates and integrated components, without a Node or Bun build pipeline.

## Docs

- [Documentation](https://docs.bretzel-py.dev/): the live reference, read from the framework's code
- [Documentation map for LLMs](https://docs.bretzel-py.dev/llms.txt): every chapter, one line each
- [Quickstart](https://docs.bretzel-py.dev/quickstart): install, create, run, edit a page
- [How Bretzel compares](https://docs.bretzel-py.dev/compare): NiceGUI, Reflex, FastHTML, Streamlit — where state lives, transport, build step, when to pick each
- [Component gallery](https://ui.bretzel-py.dev/): every component in real uses, with its Python code

## Examples

- [Live Kanban](https://demo.bretzel-py.dev/): shared drag and drop across browser windows, in Python only
- [Example apps](https://github.com/JeanHoccart/bretzel/tree/main/examples)

## Project

- [Source on GitHub](https://github.com/JeanHoccart/bretzel)
- [Package on PyPI](https://pypi.org/project/bretzel/)
- [Changelog](https://github.com/JeanHoccart/bretzel/blob/main/CHANGELOG.md)