Tutorial — Build a Todo List

The official step-by-step walkthrough lives in docs/TUTORIAL.md in the repo. It produces exactly the app at examples/todo/.

Time: 20–40 minutes. You only need Docker and the pg-web CLI.

What you will build

An HTMX-driven todo list with add, toggle, and delete — every action round-trips through Postgres, is validated by a table CHECK constraint, and returns either a new <li> fragment or an inline error via hx-swap-oob.

Key stops along the way

• pg-web init my-todos --template todo (or the minimal scaffold + manual work)
• pg-web up (boots the pgweb/postgres + optional Caddy stack)
• A forward-only migration that creates public.todos with a CHECK
• pg-web migrate apply + the pgweb.migrations ledger
• Dynamic GET (index.html + index.sql) that returns { todos: [...] }
• POST returning a fragment through Tera (todos/post.*)
• Form validation using the table constraint + EXCEPTION WHEN check_violation + OOB error div
• Raw-text POST for delete (no sibling .html, returns '')
• Custom _404.html
• Dynamic route example: pages/todos/[id]/

After the tutorial

Read App Layout for the exhaustive rules, Overview for the current feature matrix, and Deployment for how to take the same pattern to a VPS.

The todo app is the primary companion app and the Tier 3 Docker E2E target. Every Phase 1 feature is exercised here on every commit.

Browse the final code or clone the repo and cd examples/todo && ../../target/debug/pg-web dev to run it locally.