Docs

proa site

Validate site structure and print discovered routes.

proa site commands inspect projects that follow the generated site conventions. Use them after scaffolding, after moving route files, and in CI before deployment.

They work from the nearest parent directory that contains both Cargo.toml and src/. Pass --root when you want to inspect a different project.

proa site check
proa site routes

Command Summary

Check

proa site check
proa site check --root ../my-site
proa site check --json

site check verifies the module structure generated by proa new site. For a site whose proa.config.json has an application section, that means:

• src/pages/mod.rs, src/components/mod.rs, src/layouts/mod.rs, src/endpoints/mod.rs
• src/routes.rs, src/app.rs, src/config.rs, src/error.rs, src/static_assets.rs
• the SQLite files, proa.lock.json component hashes, and paired .up.sql / .down.sql migrations when those capabilities are enabled
• the Markdown representation contract when representations are enabled
• empty src/models and src/services directories, reported as warnings

Older sites without an application section are checked for src/pages/mod.rs, src/components/mod.rs, src/layouts/mod.rs, and src/data/mod.rs, and the origin template has its own list.

It also scans Rust page files under src/pages and reports an error when a page file does not expose a handler or render function. src/islands is reported as invalid for the generated site convention because islands live in the page or component tree instead of a separate source root.

A passing text run prints:

Proa site check passed for /path/to/site

When errors exist, each one prints as an error: line and the command exits non-zero.

JSON Diagnostics

Use --json for CI summaries, editor tooling, or scripts:

proa site check --json > proa-site-check.json

The JSON report has a stable shape:

{
  "root": "/path/to/site",
  "errors": [],
  "warnings": []
}

Example failures:

{
  "root": "/path/to/site",
  "errors": [
    "missing src/layouts/mod.rs",
    "src/pages/pricing.rs does not expose a handler or render function"
  ],
  "warnings": []
}

Doctor

proa site doctor
proa site doctor --json

doctor currently runs the same implementation as site check. Use either command for structural diagnostics.

Routes

proa site routes
proa site routes --json

For a site with an application section in proa.config.json, site routes reads the Route::endpoint(...) registrations in src/routes.rs, adds the home page and the /healthz and /readyz endpoints every generated site has, and adds a .md representation route for each page when Markdown representations are enabled. The method comes from the routing::post(...)-style constructor on each line. Text output has five columns:

METHOD  PATH                             KIND            REPRESENTATIONS             SOURCE
GET     /                                page            html · md:/index.md         src/pages/home.rs
GET     /index.md                        representation  markdown                    src/pages/home.rs
GET     /healthz                         endpoint        json                        src/endpoints/health.rs
POST    /contact                         endpoint        json                        src/endpoints/contact.rs

JSON output returns one object per route with the same fields:

[
  {
    "method": "POST",
    "path": "/contact",
    "kind": "endpoint",
    "representations": "json",
    "file": "src/endpoints/contact.rs"
  }
]

Route Mapping Rules

Older sites without an application section fall back to a page-file convention: Rust files under src/pages map to routes, and every route is GET:

Rules:

• home.rs at the top level maps to /.
• index.rs maps to the containing folder route.
• Underscores become hyphens.
• Nested folders become nested route segments.
• Every discovered route uses GET.

Either way this is a static report. It does not execute the app, inspect Axum router state, or infer dynamic wildcard routes.

Root Resolution

By default, site commands walk upward from the current directory until they find a directory with both Cargo.toml and src/. Pass --root to inspect a different project:

proa site routes --root /path/to/site

Use --root in monorepos when your shell is outside the site package:

proa site check --root apps/marketing
proa site routes --root apps/marketing --json

CI Pattern

For generated Proa sites, add site check next to the normal Rust and Proa checks:

cargo fmt --all --check
cargo check
proa fmt --check --verify src
proa lint src
proa site check

When publishing a route manifest, capture the route report as an artifact:

proa site routes --json > proa-routes.json

What It Does Not Prove

proa site catches structural drift in the generated site convention. It does not replace:

• cargo check for Rust type errors.
• cargo test for route behavior.
• proa fmt --check --verify for template parse stability.
• proa lint for accessibility, composition, and render-path diagnostics.
• A live HTTP smoke test for deployed Axum routes.