Docs
proa new site
Scaffold an opinionated Proa project.
Use proa new site to create a Rust project with the Proa site conventions.
Pass the complete destination path; its final segment becomes the package
name, and --title controls the human-facing title independently:
proa new site my-app --yes
cd my-app && proa run dev --open
The first proa dev build downloads dependencies and compiles the Rust crates,
which can take several minutes. Build stages appear in the terminal, and
--open opens the browser URL reported by the server when it is ready.
Custom servers that only bind a socket use the configured HTTP address.
To study a complete production-shaped application, scaffold ORIGIN:
proa new site origin-atlas --template origin --yes
For a Docker-ready deployment:
proa new site my-app --deploy docker --yes
Templates
--template selects a product preset:
| Template | Shape |
|---|---|
app (default) | SQLite/SQLx with request-scoped keyed data loading, proa-ui source components, Tailwind source, and guided application content. basic is an accepted alias. |
marketing | Content-oriented site without a database. |
docs | Documentation content and HTML/Markdown representations. |
minimal | Small CSS-based application with optional blank starter content. |
origin | ORIGIN, the complete reference application: a live routing atlas backed by a custom RIPEstat DataLoader, streamed Suspense sections, proa-ui components that each carry a Markdown representation, rsjs islands, and self-hosted fonts. |
Unknown template names fail with an error naming the presets.
Capability overrides
Presets resolve to orthogonal capabilities, each individually overridable:
| Flag | Values | Effect |
|---|---|---|
--database | sqlite, none | Database module, migrations, request-scoped loader, and guided data components. |
--ui | proa, none | Vendors proa-ui source components into src/components/. |
--styling | tailwind, css | Tailwind source input or a plain stylesheet. --tailwind and --no-tailwind are compatibility aliases. |
--starter | guided, blank | Guided starter content or empty pages. --empty is an alias for --template minimal --starter blank. |
--deploy | none, docker, railway, coolify | Provider-native deployment files. |
The origin preset owns its application content, so only --deploy can be
overridden there; proa_cli/src/site_scaffold/templates/origin/ in the Proa repository is
the canonical source. CI generates an app from it and runs its linked tests.
Options
| Flag | Behavior |
|---|---|
--title <TITLE> | Human-facing display title. The package name always comes from the path. |
--vscode / --no-vscode | Generate or omit the recommended VS Code workspace files. |
--agents-md / --no-agents-md | Generate or omit AGENTS.md local agent instructions (on by default). |
--no-git | Skip Git initialization. |
--verify | Run the full proa check --all validation after committing the project. |
--start / --open | Enter proa run dev after scaffolding, optionally opening the local URL. |
--offline | Forbid registry, tool, and Cargo network access. |
--dry-run / --json | Resolve and print the complete plan without writing anything. |
--yes | Accept recommended defaults; never implies verify, start, open, or deploy. |
Tailwind prerequisite
When Tailwind is enabled, proa dev and proa build invoke tailwindcss
from your PATH to create public/styles.css; a checked-in prebuilt
stylesheet keeps the first page styled even when the executable is missing.
Install it with the Tailwind-only installer mode:
curl -fsSL https://proa.so/install.sh | sh -s -- --tailwind-only
Or with Homebrew: brew install tailwindcss.
On Windows, download the Windows standalone executable from the
Tailwind CLI installation guide,
name it tailwindcss.exe, and add its directory to your user PATH.
Open a new terminal and confirm tailwindcss --help works before running
proa dev. The PowerShell Proa installer installs the Proa CLI; it does not
install Tailwind. The install.sh --tailwind-only command above is for macOS
and Linux.
A dry run never installs tools.
Dry runs
Use dry runs before generating into an existing directory:
proa new site my-app --dry-run
proa new site my-app --dry-run --json
The text dry run prints planned file writes; the JSON dry run emits the machine-readable scaffold plan. Scaffolding itself is transactional: files are assembled and validated in a staging directory and committed only after the whole plan succeeds, so a conflict never leaves partial writes.
Generated layout
The default app preset generates:
.cargo/config.toml.github/workflows/ci.yml.env.exampleCargo.tomlproa.config.rsproa.lock.jsonbuild.rsREADME.mdAGENTS.mdsrc/components/endpoints/layouts/pages/app.rsconfig.rsdb.rserror.rsloader.rsmain.rsroutes.rsstatic_assets.rsmigrations/data/public/favicon.svgstyles.cssstyles/input.csstests/What each directory holds:
| Path | Contents |
|---|---|
src/main.rs | Process startup: configuration, the database pool, and serving the router. |
src/routes.rs | Router assembly and middleware, kept visible so a deploy is easy to audit. |
src/pages/ | One module per route: the page component, its Markdown representation, and the handler. See Routing. |
src/endpoints/ | Operational endpoints such as /healthz and /readyz. |
src/layouts/ | Document shells shared across routes, such as root.rs. |
src/components/ | Source-owned render components, including any vendored with proa ui add. |
src/db.rs, src/loader.rs | The SQLx pool and the request-scoped DataLoader behind cx.load_typed. |
migrations/, data/ | SQL migrations and the local SQLite database location. |
public/ | Pre-built browser assets: CSS output, images, downloads. |
tests/ | Integration tests, including the representation and data-loading contracts. |
build.rs | Build-time wiring. The origin template also runs the proa_fonts_build collector for google_font!/local_font! declarations (see Fonts). |
proa.config.rs controls the proa run dev and proa run build scripts
and records component registry aliases. proa.lock.json records the scaffold
capabilities and every component installed by proa ui add. The generated
Cargo dependencies on Proa crates resolve from crates.io. A generated standalone
project needs no GitHub credentials or private registry token. Commit the
Cargo.lock produced by the first dependency-resolving command.
Live reload
proa dev reloads open browser tabs after a rebuild, so editing a page and
looking at it does not need a manual refresh.
A Rust change recompiles the site and replaces the server process, so the tab
does a full reload, in the same way Vite falls back to full-reload for
anything it cannot patch in place. The reload is only sent once the replacement
server is accepting connections again, which is what keeps a tab from landing
on a connection-refused page. When paths.public is set to None (unmanaged
serving), a stylesheet-only change rebuilds the stylesheet and re-fetches it in
place without restarting the server, so scroll position, form values, and open
dialogs survive. With managed public/ assets enabled (the default), public
file and stylesheet edits republish the catalog, and a server built with
FrameworkBuilder picks the new catalog up in place, so the tab reloads (or
re-fetches its stylesheets) without a server restart. A server that cannot
follow the catalog, such as one that loads it with PublicAssets::load or one
built against an older framework release, is restarted first. A failed build leaves
the last working server running and raises a dismissible overlay in the tab
with the failure summary. Cargo streams the compiler diagnostics themselves to
the proa dev terminal, and the overlay says so.
Nothing needs to be added to your source. proa dev runs the event stream in
its own process, so it outlives every server restart, and
proa::axum::serve injects the matching client into HTML responses.
Applications that do not serve through proa::axum::serve can add
proa::axum::DevReloadLayer themselves.
Injection is switched on by two variables that proa dev sets on the server
process it spawns: PROA_DEV_RELOAD_PORT and PROA_DEV_RELOAD_TOKEN. The
token is 16 random bytes drawn once per proa dev process, and the event
stream answers 403 to any request that does not present it. That is what
stops another site open in the same browser from reading your build failures,
which carry absolute paths and source snippets, and what stops a tab left over
from an earlier session from being reloaded by a server that never served it.
Because both variables are required and the token is never reused, a
PROA_DEV_RELOAD_PORT left exported in a shell profile cannot switch dev
tooling on in a release binary; it logs a warning and stays off.
A tab whose token has gone stale, which is what a restarted proa dev looks
like, reloads itself once to pick up the current one. Live reload holds one
Server-Sent Events connection per tab, and browsers allow six per origin, so
responses to embedded frames are left uninjected rather than spending a
connection each.
The controls are proa dev flags:
| Flag | Default | Effect |
|---|---|---|
--no-reload | reload on | Turns live reload off. |
--reload-port <PORT> | operating-system assigned | Port for the event stream. Set it only if you want a predictable one. proa dev passes it to the server as PROA_DEV_RELOAD_PORT. |
--no-css-hot-swap | hot swap on | Restarts the server for stylesheet changes instead of swapping them in place. Use it when stylesheets are compiled into the binary rather than served from disk. |
--debounce-ms <MILLISECONDS> | 200 | Quiet window a change must survive before a rebuild starts. Raise it if a formatter or code generator triggers extra cycles. |
--verbose | off | Print the detailed build log (commands, cache reuse, artifact paths) instead of the interactive summary. Piped output is always detailed. |
The debounce window cannot go below the 100ms file-watch poll interval. proa dev reads no PROA_DEV_* variables from your shell.
The site listens on 127.0.0.1:3000 unless you say otherwise. --host and --port win. Without them proa dev reads PROA_HOST and PORT, the variables the server itself reads, so one exported environment gives proa dev and proa start the same address. A generic HOST is honored only when it is an IP address or localhost, because shells and toolchains export it for unrelated purposes. A PORT that is not a port number is an error; pass --port to override it. proa dev --verbose prints which variable decided the address.
The event stream takes an operating-system assigned port by default. A fixed
offset from the dev port would claim the port your next site wants, and that
site would then fail to bind with an error naming neither live reload nor the
process holding it. A tab whose stream endpoint has moved reloads itself and
picks up the current one, so the port does not need to be stable. Pass
--reload-port if you want it to be.
Live reload is a watch-mode feature, so proa dev --no-restart does not start
it. Turning live reload off does not turn off the stylesheet fast path: a
stylesheet-only change still rebuilds assets without restarting the server, it
just does not tell the browser. Use --no-css-hot-swap for that, and note that
--no-assets disables it too, since there is nothing left to rebuild.
The fast path sees stylesheets under watched paths. Proa automatically watches
the configured public directory along with application sources. Pass
--watch PATH to the linked dev command in your dev script to watch more inputs.
When --deploy coolify is enabled, the generated project also includes Dockerfile, .dockerignore, coolify.env.example, and COOLIFY.md. See Coolify for the deployment flow and pull request preview URL setup.