shadlet 0.3.0

shadlet is a framework that lets developers build modern web applications in python. react renders the interface with authentic shadcn/ui components. python manages application state, events, routing and server-side logic. end users run applications with python only; node.js is needed only to build the renderer or an extension bundle.

release: shadlet 0.3.0. see the changelog and verified limitations for the release scope.

showcase

why shadlet

• python developers can build web applications using pure python.
• the frontend is genuine shadcn/ui (tailwind + base-ui), not an imitation.
• components are strictly typed and validated across the protocol.
• reactive session state, async event handlers, and incremental patches.

comparison

features

• typed python component api with enums and validation
• 56 built-in components from shadcn/ui base-vega
• official bundled geist variable & geist mono typography
• smooth animations, backdrop blur, and spring physics
• automatic port switching when default port is occupied
• hot reload with diff-based patches
• session-scoped reactive state
• async event handlers with cancellation
• pydantic v2 form submission validation with reactive field errors
• server-driven data table pagination, sorting, search, and validated queries
• session-owned async background tasks with reactive progress and cancellation
• multipart http uploads with per-request size limits and app authentication
• typed query-parameter state synchronized with browser history
• separately packaged react extensions discovered from python entry points
• versioned json protocol with incremental patches and shared pydantic/zod fixtures
• validated websocket handshake, token-based session restoration, and origin checks
• configurable connection authentication, event rate limits, and message size limits
• typer and rich cli
• github project templates
• mkdocs documentation website

installation

requirements:

• python 3.11 or newer

node.js is only required for maintainers building the renderer from source. installed python extensions load their bundled browser assets without node or npm.

pip install shadlet

for development from source:

uv pip install -e '.[dev]'

verify:

shadlet doctor
shadlet info

quick start

create a project:

shadlet create my-app
cd my-app
shadlet dev

or write main.py directly:

import shadlet as ui

app = ui.App("counter")


@app.page("/")
def home(ctx: ui.Context):
    count = ctx.state(0, key="count")

    def increment(event: ui.ClickEvent):
        count.value += 1

    return ui.Center(
        ui.Column(
            ui.Heading("counter"),
            ui.Text(count),
            ui.Button("increment", on_click=increment),
            gap=16,
        ),
        min_height="100vh",
    )


if __name__ == "__main__":
    app.run()

run:

python main.py

open http://127.0.0.1:8000.

architecture

flowchart LR
  A[python application] --> B[component api]
  B --> C[validation and normalisation]
  C --> D[versioned json protocol]
  D --> E[react renderer]
  E --> F[browser]

• python handles application logic.
• react handles rendering.
• communication uses a versioned json protocol over websocket.

project structure

shadlet/
  packages/python/shadlet   python runtime
  packages/renderer         react renderer
  templates                 project templates
  examples                  example applications
  tests                     python tests
  docs                      documentation

examples

• examples/counter minimal counter
• examples/todo todo list with forms
• examples/dashboard dashboard with charts and tables

run any example:

cd examples/counter
PYTHONPATH=../../packages/python python main.py

documentation

full documentation is in docs/ and built with mkdocs.

the python extension, upload, query-state, and browser testing APIs are documented in their guides. see limitations for the verified scope and remaining boundaries.

python -m mkdocs serve
python -m mkdocs build --strict

development

clone and set up:

git clone https://github.com/programmersd21/shadlet
cd shadlet
uv venv --python 3.11
uv pip install -e '.[dev]'
cd packages/renderer && npm ci

checks:

ruff check .
ruff format --check .
mypy .
pyright packages/python/shadlet
pytest
cd packages/renderer && npm run lint && npm run format:check && npm run typecheck && npm run test && npm run build
python -m mkdocs build --strict

compatibility

• python 3.11 or newer
• browsers: current evergreen browsers

community

• contributing
• code of conduct
• security
• support
• discussions
• changelog

ai assistance and transparency

shadlet is developed by human maintainers with assistance from ai tooling. ai assistance is used for drafting, refactoring, documentation, and review support. all code is reviewed by maintainers and must pass the project's lint, type, test, and build checks before release. see contributing for the ai code policy.

license

mit licensed. see LICENSE for full details.

status

release ready (v0.3.0). see limitations for the verified support matrix and capabilities.