tempestweb

📚 Documentation: Português (Brasil) · English (US) — bilingual docs site (PT-BR default + EN-US), deployed to GitHub Pages.

Build web apps in typed Python. One declarative widget tree, a DOM renderer, and three execution modes that share 100% of the application code: Mode A (WASM) runs your Python in the browser via Pyodide; Mode B (server) runs it on the server (FastAPI) and talks to a thin JS client over WebSocket or SSE; Mode C (transpile) transcribes your Python to native JavaScript — zero Python runtime, static hosting, great first-paint/SEO. Installable PWA, offline-first (service worker + IndexedDB), and WebPush are first-class — parity with tempest-react-sdk.

Sister project to tempestroid — same "one tree, multiple renderers" architecture. The renderer-agnostic engine (IR, reconciler, state, style, widgets) is shared; tempestweb adds a DOM leaf renderer (pure JavaScript, no framework, no build step, no TypeScript) and two patch transports.

Status

Published on PyPI and functional across all three modes — a working counter runs live under WASM, server, and transpile; the full test gate is green and every example builds. The transpile mode (C) is now a mature, first-class mode — 100% of tempest_core widgets, a wide typed-Python subset, and a full PWA story (installable, offline, WebPush). Only a handful of advanced constructs sit outside its subset, and the compiler fails early with file:line when you hit one. Design docs:

• docs/plan.md — full design and phase plan.
• docs/roadmap.md — phase checklist.
• docs/arquitetura.md — architecture.
• docs/contract.md — the Python↔client wire format.
• docs/agents/MANIFEST.md — parallel agent task plan.

Want runnable apps? Browse the Example Gallery (PT-BR) — 50+ single-concept demos (stopwatch, forms, data table/grid, kanban, chat, theming, i18n, canvas charts, app shells, native capabilities, observability, PWA/WebPush, a Mode C tour, and a server-mode walkthrough), each running unchanged across the execution modes.

Building something real? Read the App architecture & best practices guide (EN) — the ideal layered structure (routes · pages · components · styles · controllers · services · storages · schemas · utils · core), mirroring tempest-fastapi-sdk, so your app doesn't rot into garbage code.

Get started

pip install "tempestweb[server,cli]"   # or: uv add "tempestweb[server,cli]"

tempestweb new myapp                   # scaffold app.py + tempestweb.toml
cd myapp
tempestweb dev                         # http://127.0.0.1:8000, hot-reload (wasm)

The scaffold's app.py exposes the two callables every project needs — make_state() and view(app) — and tempestweb.toml names the entrypoint (app.py by default, configurable). tempestweb dev runs any mode locally with hot-reload — pick the mode at dev/build time, never in the app:

tempestweb dev   --mode wasm       --path myapp   # Mode A: Python in the browser
tempestweb dev   --mode server     --path myapp   # Mode B: FastAPI + WebSocket
tempestweb dev   --mode transpile  --path myapp   # Mode C: native JS bundle
tempestweb build --mode transpile  --path myapp   # emit a static, CDN-servable bundle

dev serves all three modes with watch + reload — including Mode B (server), which rebuilds and restarts on every edit. To serve the built app without a watcher (production-like), use tempestweb run --mode server — it's what the generated deploy Dockerfile runs. Every command takes the project directory via --path (default: cwd) — not a positional .py file. Check your install with tempestweb --version.

Full walkthrough: the Using the CLI, Installation and Tutorial guides.

Code quality

You write typed Python, so the CLI polices that Python too. tempestweb check is the one-command gate — it runs ruff check → ruff format --check → mypy → pytest against your project and stops at the first error:

tempestweb check                       # the full gate
tempestweb lint / fix / format / fmt-check / type / test   # individual steps

The gate layers opinion on top of your own ruff/mypy config via a strictness level — [quality] typing_strictness in tempestweb.toml (lenient | standard | strict, default standard, tempestweb new scaffolds it). It only adds rules, never loosens yours, and ANN401 is never enabled — Any is a valid annotation. --strictness overrides per invocation. Full details in the Code quality guide.

How it works

   view(app) ──build──▶ Node tree (IR) ──diff──▶ [ Patch ]   ← shared core (tempest-core)
                                                    │          insert/remove/update/reorder/replace
              ╭─────────────────┬───────────────────┤
       Mode A transport   Mode B transport     Mode C: transpile view() → native JS;
       (pyodide.ffi)      (WebSocket | SSE)     the core runs IN JS, patches in-process
              ╰─────────────────┴───────────────────╯
                  client/ (pure JS): apply patches to the DOM
                  + Style→CSS + event capture          ← same client code in every mode

The application's view() never names a transport — the same examples/counter/app.py runs under --mode wasm, --mode server and --mode transpile unchanged. Capabilities (native/) are typed awaitables with the same Python API in every mode — Mode A calls the Web API in-process, Mode B proxies it over a round-trip, Mode C routes to the same JS glue via an in-process facade (see docs/contract.md). Track T brings web-platform parity: beyond the core (http, audio, share, geolocation, clipboard, storage, camera, install, offline, notifications), the bridge now covers Tier 1 ( vibration, badge, wakelock, fullscreen, network, visibility, orientation, quota, rich clipboard, battery, sensors), Tier 2 (speech, recorder, filesystem, bgsync, tabs, idle), and Tier 3 / Chromium-only (bluetooth, usb, serial, hid, nfc, contacts, payment, pip, eyedropper, pointerlock, gamepad, midi, webaudio). A native event channel streams continuous capabilities (geolocation/network/ battery watch, sensors, STT, …) as typed async for iterators. See the capability reference (EN) and the event-channel guide.

Static SSR — render_to_html

Another render target, alongside the interactive modes: the same typed tree renders to a static HTML string on the server — no JavaScript, no DOM, no runtime. HTML is just another leaf renderer.

from tempest_core import Column, Text, Button, Style
from tempest_core.style import Edge
from tempestweb.html import render_to_html, render_document

tree: Column = Column(
    style=Style(gap=8.0, padding=Edge.all(16)),
    children=[Text(content="Hello"), Button(label="Click")],
)

fragment: str = render_to_html(tree)                 # an HTML fragment
page: str = render_document(tree, title="Home", htmx=True)  # a full document

The CSS is byte-identical to what the DOM client emits (the style_to_css port mirrors client/style.js), and the new tempest-core 0.9.0 Widget.tag / Widget.attrs fields let you emit semantic, htmx-ready markup (Container(tag="nav", attrs={"hx-get": "/x"})). All text/attributes are escaped. See the Static SSR guide (EN).

Mode C — transpile to native JS 🚀

The "TypeScript story" for Python: you write the typed-Python app; a compiler transcribes the app layer (state, view(), handlers) to native JavaScript, reusing the whole shared JS renderer. Zero Python runtime in the browser — static hosting, small bundle, great first-paint/SEO.

# examples/counter/app.py  (unchanged from Modes A/B)
@dataclass
class CounterState:
    value: int = 0

def view(app: App[CounterState]) -> Widget:
    def increment() -> None:
        app.set_state(lambda s: setattr(s, "value", s.value + 1))
    return Column(children=[
        Text(content=f"Count: {app.state.value}", key="label"),
        Button(label="+", on_click=increment, key="inc"),
    ])

from tempestweb.transpile import transpile_file

js: str = transpile_file("examples/counter/app.py")  # -> native ES module

The generated module runs on the native runtime (client/transpile/runtime.js) with a JS diff locked against a core-derived golden. Coverage is now 100% of tempest_core: all ~64 widgets, MD3 styling, state-with-methods, navigation (routes + URL), i18n, theme + responsiveness, native capabilities (http/storage/ cookies/…), field validators and both declarative and imperative animation. The tempestweb build/dev --mode transpile CLI emits a static, CDN-servable bundle that is a first-class PWA — installable and offline out of the box (manifest

• cache-first service worker precaching the whole shell; customize via [pwa] in tempestweb.toml).

See the canonical examples/transpile-tour — one app exercising the whole surface — and the guide (PT · EN). It is a first-class mode: only a handful of advanced constructs sit outside the typed subset (out-of-subset constructs fail loud with file:line).

Scaffold a PWA

tempestweb new myapp --template pwa    # Mode C: installable, offline PWA
tempestweb build --mode transpile --path myapp

The pwa template pre-configures mode = "transpile" + a [pwa] manifest block and ships a counter with an Install button. Omit --template for the plain counter starter that runs unchanged in all three modes.

WebPush (end-to-end)

Push works client-to-server out of the box. Generate VAPID keys, mount the router, subscribe from the client:

tempestweb vapid --env        # -> VAPID_PUBLIC_KEY=… / VAPID_PRIVATE_KEY=…

from fastapi import FastAPI
from tempestweb.server import VapidConfig, WebPushService, webpush_router

service = WebPushService(VapidConfig.from_env())
app = FastAPI()
app.include_router(webpush_router(service))   # /webpush/{subscribe,unsubscribe,send}

The client subscribes with native.notifications.subscribe(public_key) and POSTs the subscription to /webpush/subscribe; POST /webpush/send pushes to it. See the runnable examples/webpush-server.

Computer vision (ONNX)

pip install "tempestweb[vision]"   # pulls ort-vision-sdk + numpy

from tempestweb.vision import Detector, to_detection_schemas

det = await Detector.create("./models/yolov8n.onnx", labels="coco")
result = (await det.predict("./images/street.jpg"))[0]
for d in result:
    print(d.name, d.conf, d.box.xyxy)          # Ultralytics-style views
payload = to_detection_schemas(result)          # JSON for a tempest-fastapi-sdk backend

Classifier / Detector / Segmenter share the same input/output contract as ort-vision-sdk and tempest-fastapi-sdk's vision layer, but run the model over the native.onnx bridge (onnxruntime-web) so inference works in the browser — no onnxruntime wheel needed. Preprocessing, postprocessing and the .boxes/.probs/.masks result objects are ort-vision-sdk's, unchanged; only the model run crosses the (async) bridge, so construction and predict are awaited. See the Computer vision guide.

Deploy (server mode)

tempestweb deploy --server-name app.example.com --tls    # -> deploy/
cd deploy && docker compose up --build

Generates a tailored nginx.conf (WebSocket upgrade, streaming timeouts, sticky ip_hash, optional TLS), a Dockerfile, docker-compose.yml and a DEPLOY.md. Harden the app with a SecurityConfig (auth, CORS, limits, rate limiting, headers) — see the Security and Deploy guides. Static modes (A/C) need no server — publish the build to any CDN.

Develop

uv venv && uv pip install -e ".[dev,server,cli]"
make check          # ruff + mypy + pytest + JS (jsdom) tests

Layout

Conventions

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