Stario

Matches page titles and section headings (h2+). Paragraph text is not searched.

Search titles and headings (min. 2 characters).

AI-assisted development

Stario works well with agents when the repo has one obvious shape: a small bootstrap, explicit routes, feature folders, pure views, and one local instruction file. This how-to is the shortest path from an empty folder to a Stario app an agent can extend without guessing.

1. Create the project

bash
uv init --app my-app
cd my-app
uv add "stario>=4,<5"
uv add --dev ruff pyright pytest pytest-asyncio
curl -o AGENTS.md https://stario.dev/AGENTS.md

That AGENTS.md file is the important part. It contains the commands, project layout, Stario invariants, Datastar guidance, and common mistakes. In many editors, that one file is enough agent context.

If your tool wants web context too, point it at llms.txt for a short doc index or llms-full.txt for compact framework notes.

2. Start with the product shape

Use the layout in AGENTS.md from the first commit. Do not start with a flat root-level main.py, routes.py, and handlers.py and plan to split later.

The fastest path is to copy examples/chat-room, rename the features, and delete what you do not need. It shows the structure Stario apps should grow into:

  • app/main.py is the composition root.

  • app/common/ holds shared shell, markup, identity, and helpers.

  • app/features/<name>/urls.py owns UrlPath constants.

  • app/features/<name>/handlers.py owns handler factories and register_<feature>(app, ...).

  • app/features/<name>/views.py turns data into HTML.

  • Optional data.py, models.py, signals.py, and subjects.py appear only when the feature needs them.

  • tests/test_<feature>.py uses TestClient against the production bootstrap.

The single-file examples, Hello world and Realtime tiles, are for learning mechanics. They are not the preferred shape for a new product.

3. Run the app

bash
uv run stario watch app.main:bootstrap

Open http://127.0.0.1:8000. For a one-shot server without reload, run uv run stario serve app.main:bootstrap. If the port is busy, set STARIO_PORT.

4. Use the examples as references

When you ask an agent to build a feature, give it AGENTS.md plus the closest example project:

  • examples/chat-room for the recommended product layout: app/main.py, app/common/, app/features/, SQLite, Relay, Datastar, and tests.

  • examples/tiles for a single-file walkthrough of Relay, SSE, broad Datastar morphs, and command/query routes.

  • examples/hello-world for the smallest handler, markup, and signal shape.

Use chat-room as the reference for project structure. Use tiles and hello-world to understand mechanics before you split them into the product layout.

5. Add realtime only when it helps

Most Stario routes can stay plain HTTP: render a page, receive a form or action, redirect or return a response. Add Datastar when the user experience needs push updates: presence, collaborative state, background progress, live search results, or another server-originated change.

The shape stays simple:

  1. GET /page renders the first document.

  2. The page opens GET /subscribe with Datastar.

  3. Action routes mutate server state and publish a Relay notification.

  4. The subscribe handler re-reads authoritative state and sends HTML patches with SSE(w).

Start by morphing the whole page or a large stable fragment on each update. That keeps the code easy to review: server state in, HTML out. Datastar morphs the live DOM, and compression makes repeated markup reasonable for many apps.

Only switch to dedicated target patches after the broad morph is correct and has proved too expensive or too disruptive. A common second step is a stable shell that owns data.signals(...) and data.init(...), plus an inner #feature-live fragment patched with selector=... and mode="outer".

Related