Skip to content

tempestweb 🌩️

Build web apps in typed Python. One declarative widget tree, a DOM renderer, and two execution modes that share 100% of the application code.

tempestweb is the web sibling of tempestroid — the same one tree, multiple renderers idea. You write a view() function in Python and it runs, unchanged, in two modes:

  • Mode A — WASM

    Your Python runs in the browser via Pyodide. Like PyScript. Fully offline after the initial load.

  • Mode B — Server

    Your Python runs on the server (FastAPI) and talks to a thin JS client over WebSocket or SSE. Like Phoenix LiveView.

The trick: the app never names a transport. The very same examples/counter/app.py runs under --mode wasm and --mode server without changing a line. 🚀

How it works

   view(app) ──build──▶ Node tree (IR)        ← shared core
                            │
                          diff
                            ▼
                        [ Patch ]              insert / remove / update / reorder / replace
                       ╱          ╲
              Mode A transport    Mode B transport
              (pyodide.ffi)       (WebSocket / SSE)
                       ╲          ╱
                  client/ (pure JS): apply patches to the DOM
                  + Style→CSS + event capture     ← same code in both modes

The view() function produces a widget tree (IR). The reconciler diffs the old tree against the new one and emits patches — plain serialized data. The JS client only knows how to consume a patch and mutate the DOM; it does not care where the patch came from. That is why the renderer is the same in both modes.

Where to start

Head straight to Installation and then follow the Tutorial — the Counter. In four short pages you build the canonical app and understand the wire contract end to end.

What you will find here

  • Installation — set up your environment in a minute.
  • Architecture — the four layers and why the renderer is shared.
  • Tutorial — build the counter, one concept per page.
  • Wire contract — the Python↔client wire format.
  • Capabilities — typed Web APIs (geolocation, clipboard, camera) as Python awaitables.
  • PWA & offline — installable app, service worker, IndexedDB, WebPush.
  • Observability — telemetry, logger, feature flags, auth.
  • Roadmap & design docs — what's coming and the project's living design plans.

Language

This documentation is bilingual. Use the language selector at the top of the page to switch between Português (Brasil) and English (US).

Project conventions

Python: double quotes, full typing (mypy --strict), Google docstrings in English, async-first. Client: plain JavaScript — no TypeScript, no framework, no build step.

Project status

🚧 tempestweb is in early construction. The living design docs are versioned in the repository: plan.md, roadmap.md and contract.md. This documentation reflects the surface already built and links to the plans for full detail.