Installation¶

Requirements¶

Python ≥ 3.12
Litestar: the reference mount adapter (mounts components as routers), installed with situ[litestar]. Since 0.4.0 it ships as an extra, so a FastAPI user does not download Litestar. The mount core is framework-neutral: a generic ASGI adapter (situ.mount.asgi.asgi_app) ships in the base install and needs no extra. It is built on the ASGI protocol, so it imports no web framework. A Flask (WSGI) adapter comes with situ[flask]. Importing either pulls in no Litestar.

Install¶

pip install situ                     # the compiler + the generic ASGI adapter (no web framework)

Install situ with pip and add the extras you need:

Extra	Installs	When you need it
`situ[litestar]`	Litestar	the reference mount (`mount_component`, `mount_tree`, declui's `mount_model`)
`situ[flask]`	Flask	serving a compiled component on Flask/WSGI (`situ.mount.flask.mount_flask`) in place of Litestar
`situ[sqlalchemy]`	async SQLAlchemy engine helper + a Dishka session provider (`situ.infra.db`, `situ.infra.di`)	server-backed components against a real database
`situ[model-adapters]`	attrs, msgspec, pydantic	declui models written in those libraries (plain `@dataclass` needs nothing)

The component kit ships in the same distribution as a second package, situ_ui, with nothing extra to install.

Installing situ also puts a situ command on your PATH:

situ new Counter --to components   # scaffold a component's .html + .py pair
situ new Counter --server          # ...with a Server facade and an async command
situ check components/board --kit  # resolve every <Tag/> before the app boots

Both also run as python -m situ.new / python -m situ.check. See the CLI reference.

The Litestar mount assumes a Dishka container

Litestar's mount_component resolves your service per request from request.state.dishka_container. The [sqlalchemy] extra ships a ready-made provider, or wire your own; see Server components. This is a detail of the Litestar adapter: the Flask adapter takes a plain resolve callable and uses no Dishka.

Wire the static files and templates¶

The generated island loads a small runtime shim from /static/_rt.js, and situ ships a minimal default page template. Both come from the package, so wire them into your app once:

import situ
from litestar.static_files import create_static_files_router
from litestar.template.config import TemplateConfig
from litestar.plugins.jinja import JinjaTemplateEngine

static = create_static_files_router(path="/static", directories=[situ.static_dir()])
templates = TemplateConfig(directory=situ.templates_dir(), engine=JinjaTemplateEngine)

If you use the component kit, also serve situ_ui.STATIC (its stylesheet + widget runtime) from the same /static route by passing both directories to create_static_files_router.

Working on situ itself¶

The repository uses uv and hatchling:

uv sync                                # installs everything, extras mirrored into the dev group
make lint                              # the gate: ruff ×2 + ty + pyrefly + mypy + `situ check`
make test                              # the full pytest suite
uv run playwright install chromium     # one-time, for the real-browser e2e tier

A feature in this repo only counts when a Playwright e2e passes and make lint is clean. See Status & roadmap.