Getting started

Soda is a web framework for Rust, built on Datastar. You write an app the way you'd write a SvelteKit or Next.js one: routes are folders, pages are view! markup made of components, forms post to typed actions, and Tailwind styles everything through design tokens. soda dev patches each change into the running app in about a second, and keeps what it holds.

A page is a function of what it reads and its address. An action changes things, and every open page draws itself again. There are no loaders, caches or client state to keep in step.

What you need#

Rust, through rustup. Each app pins its toolchain in rust-toolchain.toml, and rustup fetches it the first time.
The soda command. From a checkout of the repository:

cargo install --path cli

A local-first app also builds to WebAssembly. Its build adds the target and fetches the pinned tools it needs, so there's nothing more to install.

A new app#

soda new notes          # an app on a server, called Notes
cd notes && soda dev    # serve it at http://localhost:5180, each change patched in

The name comes from the folder, in words (family-pantry is Family Pantry), unless you give one: soda new notes "Field Notes". The app starts as a shared checklist that builds, runs and passes its tests as it is.

notes/
  Cargo.toml
  src/
    main.rs              the program: soda_server::app!(list::List)
    list.rs              what the server keeps (SQLite)
    components.rs        what the pages share
    routes/
      layout.rs          around every page
      page.rs            /
      actions.rs         what its forms and buttons post to
      items/[item]/
        page.rs          /items/:item
  migrations/            the database's schema
  web/
    app.css              the look: its design tokens
  tests/
    e2e.mjs              the end-to-end tests, in a real browser

Change a page and save. soda dev compiles the change and patches it into the running app, and the page draws again in place: the form you were typing in, the scroll and what the server holds all stay.

Pick a backend#

Where an app runs is its backend. Its routes, pages, components and layouts are written the same on each, and naming one is one line in src/main.rs:

soda_server::app!(list::List);         // on a server
soda_local::app!(model::Items);        // local-first, in each person's browser
soda_static::app!(handbook::Handbook); // static, every page drawn as it's built

	On a server (`soda-server`)	Local-first (`soda-local`)	Static (`soda-static`)
Runs	A program you deploy, which draws every page from what it keeps	In each person's own browser, in a service worker. There's no server of its own	Once, as it's built: every page into a file any host serves
Keeps	Whatever you like: the template uses SQLite	The open space's history, signed and sealed on each device, synced through a store that can't read it	What it's made of (Markdown files, data), read as it's built
You get	Sessions, one stream per open page, every page drawn again after anyone's action	Accounts, devices and passkeys, sharing, sync, undo, history and offline, all built in	Each page's own head, a 404 page and a sitemap; no server to run at all
Start with	`soda new notes`	`soda new --local pantry --noun pantry`	`soda new --static handbook`
Deploy	`soda deploy`: a container image, or straight to a Docker host	`soda deploy`: static files, published with Vercel	`soda deploy`: the built site, published with Vercel (or any host)

A static site has no actions, since nothing posts to a site of files; the same pages move to a server or local-first when it needs some.

For a local-first app, --noun says what one space is called (a pantry, a board, a circle), and its plural is English's unless --plural says otherwise.

The commands#


`soda new <dir>`	A new app on a server (`--local` for local-first, `--static` for a static site)
`soda dev`	Serve it, patching each change into the running app
`soda check`	Its tests, Clippy, and the check that every color, font, radius and shadow is a token
`soda test`	`check`, then a build and the end-to-end tests in a real browser
`soda build`	The site in `dist/`, and a server's program beside it
`soda deploy`	Ship it

Where next#

The tutorial builds a guestbook on a server, from soda new to running: pages, forms and actions, layouts, downloads, styling and tests.
Local-first builds Pantry, from soda new --local to deployed: a model of events, dragging between shelves, undo, and edits that collide.
A static site builds a handbook of Markdown pages, from soda new --static to deployed: a page for each, each page's head, and a site any host serves.
The reference is everything an app writes, in one place.
Styling is how the look is decided, and how to change it.