python-first web applications with a shadcn/ui-based react renderer.

shadlet is a framework that lets developers build modern web applications in python. react renders the interface with shadlet's shadcn/ui-based components and base ui primitives. 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.

shadlet 0.7.0 is a focused performance and verification release. the renderer lazy-loads chart, calendar/date picker, and carousel adapters, reducing the main entry chunk from ~1,590kB to ~1,060kB minified (~483kB to ~328kB gzip). a generated component compatibility matrix and automated bundle budgets keep release claims checkable in CI. protocol v2 is maintained with source compatibility for 0.6.x applications. see the changelog and migration guide for details.

warning shadlet 0.7.0 does not claim complete parity with the current shadcn/ui catalogue. see the component catalogue and compatibility matrix for the supported and partial set.

note the auth and crud templates are local demonstrations; they do not provide production authentication, authorization, or database persistence.

showcase

dashboard

components

charts

why shadlet

• python developers can build web applications using pure python.
• the renderer uses shadcn/ui design conventions, tailwind css, and base ui.
• components are strictly typed and validated across the protocol.
• reactive session state, async event handlers, and incremental patches.

comparison

feature	shadlet	typical python web ui
rendering	react + shadcn/ui-based components	server-rendered templates
state	reactive session state	request/response state
components	built-in shadcn/ui-based component library	custom widget sets
packaging	python wheel with bundled renderer	manual frontend build

features

• typed python component api with enums and validation
• built-in components based on shadcn/ui base-vega
• complete generated lucide icon catalogue with a python namespace
• 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
• reactive data table loading/error states, retry controls, per-column filters, and column visibility
• 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
• shadlet extension create, build, check, and info commands
• local upload storage with safe keys, atomic writes, and size limits
• 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, payload, message, and render-tree 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]

Loading

• 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

• runnable examples and learning path: state, forms, routing, components, responsive layouts, tables, charts, background tasks, storage, multipart uploads, icons, and deployment.

install shadlet from the repository root, then start an example:

python -m pip install -e .
cd examples/counter && python main.py

agent skills

the repository includes ten task-specific agent skills for building apps, designing interfaces, authoring components and extensions, debugging, contributing, review, testing, releases, and migrations. canonical skills are shared across codex, cursor, gemini cli, and github copilot; claude code and copilot code review receive validated mirrors.

documentation

full documentation is in docs/ and built with mkdocs. the agent skills guide describes the included workflows and host discovery locations.

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

see limitations for the verified support matrix and capabilities.