Stario

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

Search titles and headings (min. 2 characters).

The Stario way

This page is a set of recommendations and rules of thumb for using Stario—not hard laws. It is the direction Stario wants to push you in, and it is influenced by The Tao of Datastar, because Datastar shaped a lot of how Stario thinks about UI, state, and realtime.

If you're not learning, it's the wrong way

Stario is about making you a better developer, not better at Stario trivia.

It is thin on purpose. It tries to arm you with durable ideas such as HTTP request handling, routing, telemetry, shared clients from bootstrap (how-to), response compression, and in-process Relay fan-out—not textbook CQRS with separate read models unless your product needs that.

The goal is not to trap you inside Stario. The goal is to help you understand the shape of the work well enough to build with Stario today, choose something else when it fits better, or even know when to ditch Python altogether.

If an abstraction stops you learning what is happening, it is probably the wrong abstraction.

Not an ASGI tutorial

Stario owns the HTTP server path for its apps: handlers receive Context and Writer, and you drive responses through stario.responses and helpers like SSE(w). That is closer to Go’s http.ResponseWriter than to “implement an ASGI callable and return a Response object.” You do not need ASGI middleware mental models to be productive here—learn HTTP, your handler contract, and when to keep a connection open.

Lean on the browser

The browser is already a jet engine. It is up to you whether you use it well or fight it.

Lean on the tools that already exist or are amazingly cheap: DOM morphing, signals, compression, links, browser history.

The fastest JavaScript is no JavaScript. Use Datastar to keep the client layer thin. Do not rebuild things the browser already does well, especially navigation and history.

Think multi-page application

Borrowing from Datastar's Tao:

  • build an MPA

  • each page is a resource

  • keep a stream open on the current state of that resource

  • ship, measure, repeat

In Stario terms: handlers return full documents where that fits, open SSE (or other streams) for live updates, and keep authoritative state on the server; signals hold UI-facing mirrors only. You do not need to read the Tao link first—those pieces are all documented here and in The go-to architecture.

The inefficiency of this approach is mostly in your head. Compression and CSS view transitions can make navigation feel responsive for many users, while staying simpler to scale and maintain than a full client-rendered SPA—your mileage depends on page weight and browser support. Where an MPA is a poor fit (heavy client-only interaction, offline-first), measure and choose a different shape deliberately.

URLs as data

Routes are UrlPath constants—plain path patterns you use in app.get / app.post and in HTML via .href(). Scope shared middleware on a prefix with app.use(pattern, *middleware) before routes on that branch (Routing — Middleware). Static files: build static = StaticAssets(ASSETS) in bootstrap, then static.register(app); logical paths like css/style.css resolve to fingerprinted URLs at import or bootstrap time.

That keeps links and registrations aligned without a separate name registry. When you need query strings or path params, UrlPath.href(query=..., **params) builds the browser URL in one place.

State lives on the backend

Most state should live on the backend.

The frontend is exposed to the user, so the backend should be the source of truth.

Signals are useful, but they are not your system of record. Use them for UI state, request payloads, and light reactive behavior. Keep real application state on the backend.

Optional realtime

Realtime is not the default product shape—it is what you add when live updates earn their complexity. A static HTML handler and stario watch are a complete app. SSE, Relay, and signal patches are the next step when multiple tabs or server pushes matter, not day-one requirements.

Where next