Frontage

documentation · PyPI

A fine-grained reactive UI framework for Python in the browser. Signals, memos and effects; templates that clone once and bind only their holes; a keyed For; a nested router; running on MicroPython compiled to WebAssembly, with the framework delivered as precompiled bytecode. No JavaScript, no Node, no bundler: you write Python and the browser runs it.

Status: 0.8.3, alpha. The rewrite planned in DESIGN.md is complete through its M5 milestone: reactive core, store, templates (h and html(t"…")), control flow and boundaries, Resource/Action, a nested router, widgets, State, timers, the playground; 0.3.0 added the command line (export, tailwind, check); 0.4.0 added prerendering with hydration (M6): pages that show before Python loads; 0.5.0 adds transitions (transition, is_pending, Optimistic), async memos, the debug warnings, the frontage console script and prerender --crawl (M7); 0.6.0 builds the new state off screen during a transition and lets the router navigate inside one (M8); 0.7.0 makes async memos the router's data primitive: they count toward is_routing, and prerender settles and hydrates them (M9); 0.8.0 adds frontage serve, a dev server that reloads the page on save; 0.9.0 replaces PyScript with a direct WebAssembly boot (M11): four requests instead of twenty-nine, 52 ms instead of 88, the framework precompiled, and a dev server that swaps a module into the running page without reloading it. The API is young and will move; the browser suite runs every example on Chromium each push and on Firefox and WebKit nightly.

from frontage import Signal, component, html, mount


@component
def counter(initial=0):
    count = Signal(initial)

    def inc(ev):
        count.update(lambda n: n + 1)

    def dec(ev):
        count.update(lambda n: n - 1)

    return html(t"""
        <div class="counter">
            <button on:click={dec}>-</button>
            <span>Value: {count}</span>
            <button on:click={inc}>+</button>
        </div>
    """)


mount(lambda: counter(initial=0), "#app")

Signals hold state; anything callable in a template is a hole that updates in place when what it read changes; a component body runs once. Name the functions you put in holes: MicroPython does not accept a lambda inside a template's braces.

Try it at frontage.optersoft.com/playground, which runs your code on MicroPython and keeps it in the link. Learn it at academy.optersoft.com/python/frontage, ten chapters with exercises, nine of them with an app published on GitLab Pages. Install it with pip, and frontage build writes a directory that runs anywhere:

uvx frontage build myapp        # index.html, your .py, and _frontage/ beside them

Most of that is the interpreter: the framework is 82 KB of precompiled bytecode, and none of it is parsed in the browser. Medians of five, this laptop's Chromium; DESIGN.md §12 has the method.

The same package is a small command line on your machine, stdlib only:

uvx frontage serve              # a dev server that reloads the page whenever a file changes
uvx frontage check app.py       # the rules MicroPython enforces and CPython does not
uvx frontage tailwind           # Tailwind CSS: the standalone CLI, fetched once, no Node
uvx frontage export . --out build              # a self-contained static folder
uvx frontage prerender . --out build --crawl   # every route the pages link to, as finished HTML

(uvx runs the frontage script straight from PyPI; pip install frontage puts the same frontage command on PATH, and python -m frontage is the same thing.)

prerender runs the app on your machine, waits for its resources and async memos, and writes each route as finished HTML with the values embedded. In the browser mount hydrates: it adopts the HTML already on screen instead of building it, skips the fetches the page already holds, and replays the clicks made before Python was ready. Static hosting only, no server: Leptos's async rendering mode as a build step.

Tailwind with no build at all: the playground loads Tailwind's browser build, so utility classes work as you type. The Style, Ship and Prerender chapters cover all of it.

Why

Python in the browser exists (MicroPython and CPython both compile to WebAssembly) and the frameworks that use it either carry a server into the browser (Streamlit's stlite, Shiny's Shinylive: tens of seconds to start) or rebuild and diff the page on every change. Frontage is browser-first: no session, no transport, no DSL, and a state change touches only the DOM nodes that read it. The whole reasoning, with the frameworks it learned from, is in DESIGN.md; the behaviours it must have, one line each, are in SPEC.md.

Develop

The repo uses uv and mkrun (mk).

mk sync                 # .venv with every dependency group
mk check                # lint, types, unit tests: the gate
mk runtime.fetch        # the pinned micropython.mjs + .wasm into frontage/_runtime/
mk serve                # examples and playground at http://127.0.0.1:8000/, package read live, reload on save
mk test --browser       # every example in Chromium, on MicroPython in WebAssembly
mk build examples/todo  # a static directory that boots from WebAssembly
mk site.deploy          # publish frontage.optersoft.com by hand (Cloudflare Pages): landing page, gallery, playground, wheels

Without mk: uv sync --all-groups, uv run pytest, uv run ruff check, uv run ty check.

Contributing

Contributions are welcome and are accepted under the Apache License 2.0, the same terms the project is published under. By opening a pull request you agree that your contribution may be distributed under that license, including its patent grant (section 3). There is no separate contributor agreement. The rewrite is clean-room: code is written from SPEC.md, not from any reference framework's source, and a pull request says so.

License

Apache License 2.0, copyright Optersoft, S.L. See LICENSE and NOTICE.

Frontage and the Frontage logo are trademarks of Optersoft, S.L. The license grants no rights to the name or the logo (Apache License section 6). You may say that your work uses or is built with Frontage; a fork or a derivative must ship under another name.

Frontage's reactive model follows Solid and Leptos.