# Proa documentation corpus

This plain text endpoint concatenates the Markdown source used to build the Proa site.


---

# Docs: Quickstart

URL: /docs
Description: Create a Proa site, run it, and edit your first route in five minutes.

---
title: Quickstart
description: Create a Proa site, run it, and edit your first route in five minutes.
sidebar_title: Quickstart
---

This quickstart gets you from an empty directory to a hello world Proa. It should take about five minutes once Rust and the Proa CLI are ready.

<Callout type="info">

Building with an AI agent? The complete documentation is served at [/llms-full.txt](/llms-full.txt) for agent consumption. [LLM docs](/docs/llms) lists the other machine-readable interfaces.

</Callout>


## 1. Install Proa

Install the latest stable CLI from crates.io using a current Rust toolchain:

```bash
cargo install proa-cli --locked
```

Run the same command to update an existing Cargo installation.
Proa is public; no GitHub credential or Cargo publishing token is needed.
[Troubleshooting](/docs/guides/troubleshooting) covers dependency resolution
failures. The Basic app also requires the Tailwind CSS CLI on your `PATH`;
see [Tailwind prerequisite](/docs/cli/new-site#tailwind-prerequisite) before
continuing.

## 2. Create A Site

<Tabs data-items="Basic app|ORIGIN (kitchen sink)">


<Tab value="Basic app">


A minimal Axum-backed application with the core boundaries in place:

```bash
proa new site hello-proa --yes
```

```proa-filetree
Cargo.toml
proa.config.json
proa.lock.json
build.rs
src/
  components/
  endpoints/
  layouts/
  pages/
  app.rs
  main.rs
  routes.rs
migrations/
public/
  favicon.svg
  styles.css
styles/
  input.css
tests/
```

Checkpoint: `Cargo.toml`, `src/main.rs`, `src/pages/home.rs`, and
`src/layouts/root.rs` should exist.

</Tab>


<Tab value="ORIGIN (kitchen sink)">


The kitchen-sink starter, and the fastest way to see a production Proa app
fit together:

```bash
proa new site origin-atlas --template origin --yes
```

This scaffolds ORIGIN, a live routing atlas that exercises the whole
framework: a custom RIPEstat `DataLoader` with request-scoped deduplication
and a TTL cache, streamed Suspense sections, proa-ui components that each
carry a Markdown representation (the same page serves `/site/<host>.md` for
command-line clients, retrieval pipelines, and agents), rsjs islands for the
interactive surfaces, Tailwind styling with a themed token set, self-hosted
fonts. The generated `README.md` doubles as
an editing guide.

Checkpoint: `src/lib.rs`, `src/loader.rs`, and `src/components/` should
exist, and `proa dev --open` shows the atlas.

</Tab>


</Tabs>


Generated sites use the `proa` crate for their application API. Common types and
macros come from `proa::`; the Axum integration is `proa::axum` and loaders live
under `proa::stream`. To add Proa to an existing application:

```toml
[dependencies]
proa = { version = "0.4", features = ["axum"] }
```

You do not have to build the common UI yourself: [proa-ui](https://ui.proa.so) is a shadcn-style catalog of ready-made Proa components, and `proa ui add button` vendors the source into `src/components/` where you own and edit it like any other file. Worth knowing before you write your first card, dialog, or form by hand.

The Basic app starter writes its document title directly in `RootDocument` and uses manual head rendering. Its pages keep the default component role. To adopt managed metadata, follow [Layouts and Pages](/docs/framework/layouts-and-pages) and add an explicit Page boundary and head outlet together. ORIGIN already uses that managed document pattern.

The remaining steps use the **Basic app** named `hello-proa`. If you chose
ORIGIN, follow its generated `README.md` and run commands inside `origin-atlas`.

If `styles/starter.css` already exists and `styles/input.css` imports it,
continue to the next step.

<Accordions>


<Accordion title="My starter has no styles/starter.css yet">


Inside `hello-proa`, preserve the starter design before Tailwind rebuilds
`public/styles.css`:

1. Move `public/styles.css` to `styles/starter.css`. If `styles/starter.css`
   already exists, keep that file.
2. Replace the contents of `styles/input.css` with:

```css
@layer theme, base, proa-compat, components, utilities;
@import "tailwindcss";
@import "./starter.css" layer(components);
@source "../src/**/*.rs";
```

Tailwind will regenerate `public/styles.css` with the starter design included.

</Accordion>


</Accordions>


## 3. Run The Server

```bash
cd hello-proa && proa dev --open
```

`proa dev` builds configured assets, runs the linked RSJS pipeline, starts the
Axum server on [http://localhost:3000](http://localhost:3000), and restarts
when Rust, style, or config files change.

The first build downloads dependencies and compiles the Rust crates, which can
take several minutes. The terminal reports each build stage; `--open` waits
until the server accepts connections before opening your browser.

Open tabs reload themselves once the rebuilt server is accepting connections
again, so you do not have to refresh by hand. Stylesheet edits are applied
without navigating, which keeps scroll position and form state. Turn it off or
retune it with `--no-reload`, `--no-css-hot-swap`, and `--debounce-ms`; see
[Live reload](/docs/cli/new-site#live-reload).

## 4. Edit The First Page

Set up [your editor](/docs/guides/editor-setup) for Rust navigation and
completion, including expressions inside raw Markdown templates.

Open `src/pages/home.rs`. Inside `impl<L: DataLoader> WebRender<L> for
HomePage`, find the `<section class="hero">` in the existing `html!` macro.
Replace only its `<h1>` and `<p class="lede">` with these two elements:

```rust
<h1>"Fast SSR, typed in Rust"</h1>
<p class="lede">"This page renders from a compiled template macro."</p>
```

Keep the surrounding template, including `DatabaseBadge` and `DatabaseCard`.
Those children load the database status, so this page uses async `WebRender`
and `html!`. A static component can use `WebRenderSync` and `html_sync!`, as
shown by the About page below.

In **the same file**, find `impl<L: DataLoader> MdRender<L> for HomePage`.
Inside `render_md`'s existing `md! { r###"…"### }` template, replace the old
heading and the paragraph immediately after it with these Markdown lines:

```markdown
Fast SSR, typed in Rust

This page renders from a compiled template macro.
```

Keep the other Markdown content and child expressions. Proa's content-coverage
lint compares rendered content across the two implementations; changing both
keeps the HTML and Markdown representations consistent with the same page edit.

Refresh the browser and open [/index.md](http://localhost:3000/index.md) to see
both representations. Edit `styles/starter.css` to change the starter's design;
`public/styles.css` is the generated output and is rebuilt by Tailwind.

## 5. Add A Route

Create `src/pages/about.rs`:

```rust
use axum::response::IntoResponse;
use proa::{to_async, DataLoader, WebContext, WebRenderSync, WriteError};
use proa::axum::RouteResponse;
use proa::html_sync;

use crate::layouts::RootDocument;

pub async fn handler() -> impl IntoResponse {
    RouteResponse::ssr_async(RootDocument {
        title: "About",
        content: to_async(AboutPage {
            heading: "About",
            body: "This route renders from src/pages/about.rs.",
        }),
    })
}

struct AboutPage {
    heading: &'static str,
    body: &'static str,
}

impl<L: DataLoader> WebRenderSync<L> for AboutPage {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <main data-component="about-page" class="mx-auto max-w-3xl px-6 py-16">
                <h1 class="text-4xl font-semibold">{self.heading}</h1>
                <p class="mt-4 text-zinc-600">{self.body}</p>
            </main>
        }
        .render(cx)
    }
}
```

Export it from `src/pages/mod.rs`, keeping the generated `home` module:

```rust
pub mod about;
pub mod home;
```

Register it in `src/routes.rs`, between the markers the generator maintains:

```rust
let (router, metadata) = router_from_spec(vec![
    // proa:route-specs:start
    Route::endpoint("/", get(pages::home::handler)),
    Route::endpoint("/about", get(pages::about::handler)),
    // proa:route-specs:end
]);
```

That is the whole route flow. `RouteResponse` renders the page and finalizes
the HTTP response, `RootDocument` supplies the shared page shell (it is
async-capable, so a synchronous page goes in through `to_async`), and the
fields passed to `AboutPage` are compile-time-checked props. Add
[page caching](/docs/framework/page-caching) to the route spec when the
response should carry CDN cache headers. Add Axum extractors such as `Path`,
`Query`, or `State` to `handler` when the route needs request data.

Open [http://localhost:3000/about](http://localhost:3000/about). Check the route table:

```bash
proa site routes
```

Checkpoint: `/about` appears in the route report and renders in the browser.

## 6. Validate Before Moving On

Run Proa's source-aware checks before the full build:

```bash
proa fmt --check --verify src
proa lint src --deny warnings
proa test
proa build
```

`proa fmt --check --verify` checks the canonical template layout and verifies
that formatting would preserve the rendered output. `proa lint` understands
Proa render paths, so `--deny warnings` catches performance problems such as
intermediate rendered strings, avoidable allocations, and async renderers that
never await. Once those focused checks are clean, `proa build` validates the
complete linked application. `proa test` also checks both page representations
and that the two database components share one origin query.

## Next steps

- [Tutorial](/docs/guides/tutorial)
  - Add typed data, components, routes, and a form action.
- [proa new site](/docs/cli/new-site)
  - Scaffold a project and see where pages, layouts, components, and assets live.
- [HTML rendering](/docs/core/html-rendering)
  - Render typed Rust values to HTML with render traits and the html! macros.
- [Troubleshooting](/docs/guides/troubleshooting)
  - Fix the most common Proa setup, registry, template, component, island, routing, and CI failures.
- [Deploy](/docs/framework/deployment)
  - Pick a deployment target, then follow the guide for it.


---

# Docs: Editor setup

URL: /docs/guides/editor-setup
Description: Configure VS Code, Neovim, Vim, Helix, and Zed for Rust navigation and completion inside Proa Markdown templates.

---
title: Editor setup
description: Configure VS Code, Neovim, Vim, Helix, and Zed for Rust navigation and completion inside Proa Markdown templates.
keywords: [editor, vscode, "VS Code", VSIX, rust-analyzer, proa-lsp, Neovim, nvim, Vim, vim-lsp, Helix, Zed, autocomplete, "go to definition"]
---

Proa's editor tools add Rust go-to-definition, hover, completion, rename, and
semantic highlighting inside raw-string `md!` and `md_sync!` templates,
including `r###"..."###`. They use rust-analyzer for Rust analysis.

```rust
md_sync! { r###"
    **{a.user_name.as_str()}**

    {a.note.as_str()}
    "###
}
```

With editor support enabled, selecting `user_name` in this template navigates
to its Rust field declaration. Hover shows its type, and completion works
while typing an unfinished access such as `{a.}`.

Use the **Proa extension** in VS Code. In other editors, configure
**`proa-lsp`** as the Rust language-server command. For Tailwind class
completion in HTML templates, see [Tailwind](/docs/guides/tailwind-intellisense).

## Live lint diagnostics

The editor tools also run Proa's source linter after a short typing pause,
using your unsaved changes. Adding a field or child to HTML can immediately
flag its absence in a paired Markdown view, including when that view is not
open. The diagnostic includes repair guidance and the HTML contribution's
location. Including the content or acknowledging an intentional omission clears
it. The editor also runs Proa's usual template formatting, accessibility, and
performance lints on open Rust files.

Install an updated Proa CLI from the same checkout:

```bash
cargo install --path proa_cli --bin proa --locked --force
```

VS Code runs `proa` from PATH. Set `proa.lint.path` to another executable path,
or `proa.lint.enable` to `false` to disable these diagnostics. The standalone
bridge accepts `--proa /absolute/path/to/proa` or `PROA_LINT`, and `--no-lint`
disables live lints. If the CLI is missing or outdated, the tools report it
while keeping Rust navigation available. Restart the bridge or reload VS Code
after updating the CLI.

A persistent worker checks original source buffers without writing files or
compiling the application. File changes refresh affected views, and results
from older buffer versions are discarded. Rust syntax errors pause content
comparisons for that package until the source is parseable. The content check
uses the same bounded HTML → Markdown policy as
[`proa lint`](/docs/cli/format-lint-check); it does not automatically choose a
child's representation in another format. Rust type checking and compiler
diagnostics continue through rust-analyzer and Cargo.

## VS Code

Install the official
[rust-analyzer extension](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
and the Rust toolchain used by your project. Open the project in a trusted
workspace.

The current Proa extension can be packaged from a
[Proa repository checkout](https://github.com/Proa-Labs/proa). With Node.js 22
or newer installed, run these commands from the repository root:

```bash
cd editors/vscode
pnpm test
pnpm dlx @vscode/vsce package --no-dependencies
code --install-extension ./proa-0.2.0.vsix
```

You can also install the resulting file through **Extensions: Install from
VSIX...** in the Command Palette. Reload the VS Code window after installing.
The extension ID is `proa-labs.proa`; `proa new site` recommends that ID in
generated projects. These installation steps use a local VSIX and do not
require a Proa Marketplace release.

If you used the earlier `proa-labs.proa-markdown` prototype, uninstall it before
enabling Proa so that only one extension handles template analysis.

Proa attaches to the official rust-analyzer extension's existing server. No
workspace settings are required, and `rust-analyzer.server.path` should keep
pointing to your normal analyzer, not `proa-lsp`.

## Install the bridge for other editors

The standalone bridge requires **Node.js 22+**, **rust-analyzer**, and your
project's Rust toolchain, including Cargo and rustfmt. From the Proa repository
root:

```bash
rustup component add rust-analyzer rustfmt
pnpm add --global ./editors/lsp
proa-lsp --version
```

This installs from the checkout and does not require an npm registry release.
Configure your editor to launch `proa-lsp --stdio`; the bridge starts one
rust-analyzer process for that LSP connection.

The default analyzer is `rust-analyzer` on `PATH`. To choose a particular
executable, add these arguments to your editor's command:

```bash
proa-lsp --stdio --rust-analyzer /absolute/path/to/rust-analyzer
```

`PROA_RUST_ANALYZER` can set the same path. Node, Cargo, and rustfmt must also be
available to the editor process, including in remote sessions and containers.

Use the bridge for your existing Rust LSP connection, or disable the direct
rust-analyzer connection before adding a new one. Running both on the same
buffer produces duplicate results.

## Neovim

Neovim **0.11 or newer** includes the LSP configuration API used below.

If nvim-lspconfig already provides your `rust_analyzer` configuration, change
its command in `init.lua`. Your other settings and completion plugins can stay
in that configuration:

```lua
vim.lsp.config('rust_analyzer', {
  cmd = { 'proa-lsp', '--stdio' },
})
vim.lsp.enable('rust_analyzer')
```

For a setup without an existing Rust LSP configuration, use this instead:

```lua
vim.lsp.config('proa', {
  cmd = { 'proa-lsp', '--stdio' },
  filetypes = { 'rust' },
  root_markers = { 'Cargo.toml', 'rust-project.json', '.git' },
  settings = { ['rust-analyzer'] = {} },
})
vim.lsp.enable('proa')
```

Open a Rust file and run `:checkhealth vim.lsp`. There should be one attached
Rust client. Use `K` for hover and the usual `vim.lsp.buf.definition()`,
`vim.lsp.buf.rename()`, and `vim.lsp.buf.format()` functions through your
preferred keymaps. See [Neovim's LSP documentation](https://neovim.io/doc/user/lsp/)
for completion and keymap configuration.

## Vim

Install [vim-lsp](https://github.com/prabirshrestha/vim-lsp) using your plugin
manager, then register the bridge in your vimrc:

```vim
augroup proa_lsp
  autocmd!
  autocmd User lsp_setup call lsp#register_server({
        \ 'name': 'proa',
        \ 'cmd': {server_info -> ['proa-lsp', '--stdio']},
        \ 'allowlist': ['rust'],
        \ 'workspace_config': {'rust-analyzer': {}},
        \ })
augroup END
```

Disable any existing direct Rust server registration. Use vim-lsp's
`:LspDefinition`, `:LspHover`, `:LspRename`, and `:LspDocumentFormat` commands.
Completion and semantic coloring depend on your Vim client and plugins.

## Helix

Override the command for Helix's existing Rust server in
`~/.config/helix/languages.toml`:

```toml
[language-server.rust-analyzer]
command = "proa-lsp"
args = ["--stdio"]
```

This retains your Rust language settings. See
[Helix language-server configuration](https://docs.helix-editor.com/languages.html#language-server-configuration)
for additional options.

## Zed

Use `command -v proa-lsp` to find the bridge's absolute path, then set it as the
command for Zed's existing Rust server in `settings.json`:

```json
{
  "lsp": {
    "rust-analyzer": {
      "binary": {
        "path": "/absolute/path/to/proa-lsp",
        "arguments": ["--stdio"]
      }
    }
  }
}
```

See [Zed's Rust binary settings](https://zed.dev/docs/languages/rust#binary).

## Verify the setup

Open a Rust file in your Cargo project that uses a raw Markdown template.
With the example at the top of this page:

1. Use go-to-definition on `user_name` and check that it reaches the field declaration.
2. Hover over the field to inspect its Rust type.
3. Replace `a.user_name.as_str()` with `a.` and request completion. The fields on `a` should appear.
4. Restore the expression, then run Format Document. The Markdown content should remain intact.

Template loops and conditions, including nested blocks and `if let`, retain
their Rust bindings. Unicode text before an expression does not move its
navigation target.

## Formatting and supported scope

Format Document runs rustfmt on the original unsaved Rust file, using the
owning Cargo target's edition and nearest rustfmt configuration. It respects
`rust-analyzer.rustfmt.extraArgs` and `rust-analyzer.rustfmt.overrideCommand`.
Use [proa fmt](/docs/cli/format-lint-check) to additionally normalize indentation
inside the Markdown template.

Analysis does not rewrite files on disk. Edits that would overwrite literal
Markdown are rejected. Range and on-type formatting are suppressed in files
with projected templates.

The current editor support covers single raw-string templates with closed
delimiters. Cooked strings, named-argument templates, and unclosed template
delimiters fall back to native Rust analysis. Braces inside Markdown code
spans, fenced code, and escaped braces remain literal.

References inside **unopened raw templates** remain limited to rust-analyzer's
native analysis. Open those files before a workspace rename and review the
resulting edits. Markdown prose keeps the editor's string styling; semantic
Rust colors depend on the editor's support for LSP semantic tokens.

VS Code and Neovim have real-editor integration tests covering navigation,
completion, rename, formatting, unsaved edits, and restart. The Vim, Helix,
and Zed configurations use their documented LSP interfaces; they have not yet
received equivalent end-to-end tests in Proa.

## Troubleshooting

| Symptom | Check |
|---------|-------|
| No Rust features inside raw templates in VS Code | Enable both Proa and the official rust-analyzer extension, trust the workspace, and reload the window. |
| `proa-lsp` cannot start | Check `node --version`, `proa-lsp --version`, and `rust-analyzer --version` from the environment that launches your editor. |
| A rustup shim reports that rust-analyzer is missing | Run `rustup component add rust-analyzer` for the project's toolchain, or select a working executable with `--rust-analyzer`. |
| Duplicate diagnostics or completion entries | Keep one Rust LSP connection per buffer and disable the old Proa Markdown prototype if installed. |
| UTF-16 initialization error | Include `utf-16` in the client's `general.positionEncodings` capability. |
| Formatting fails | Check that Cargo and rustfmt are available and that any configured rustfmt override accepts the document on stdin. |

The bridge logs to stderr; use your editor's LSP log to inspect failures. In
Neovim, use `:checkhealth vim.lsp` and `:LspLog`. Restart the Rust LSP client
after changing its command or toolchain path.


---

# Docs: Tutorial: A Product Page

URL: /docs/guides/tutorial
Description: Server-render a catalog, then add a quantity stepper that still works with JavaScript off.

---
title: "Tutorial: A Product Page"
description: Server-render a catalog, then add a quantity stepper that still works with JavaScript off.
---

Here you'll be building a sample product page! Build a small product catalog and a product page whose add-to-cart form is a plain HTML form. Then add an interactive quantity stepper with a live subtotal.

<Demo src="/demos/quantity-stepper" title="Quantity stepper" height="470" />



Start from the project created in [Getting Started](/docs):

```bash
proa new site shop-demo --template marketing --tailwind --yes
cd shop-demo
proa dev --open
```

`proa dev` builds the Tailwind assets before starting the server, runs the
binary through the linked pipeline, and restarts on changes. Open tabs reload
themselves after each rebuild, and stylesheet edits are applied without
navigating. See [Live reload](/docs/cli/new-site#live-reload) for the flags.

The generated site already has a home page, a `RootDocument` layout in
`src/layouts/root.rs`, a router in `src/routes.rs`, and health endpoints. You
will add files beside them and register new routes between the
`proa:route-specs` markers.

## Target Files


```proa-filetree
src/
  components/
    mod.rs
    product_card.rs
    quantity_stepper.rs
  data/
    mod.rs
    products.rs
  endpoints/
    mod.rs
    cart.rs
  layouts/
    root.rs
  pages/
    mod.rs
    products.rs
    product.rs
  routes.rs
  main.rs
```


## Product Data

Prices are whole dollars as `i64` so the browser can multiply them later without
a money-formatting helper.

<CodeExplorer>


<CodeFile name="src/data/products.rs">


```rust
#[derive(Debug, Clone, Copy)]
pub struct Product {
    pub slug: &'static str,
    pub path: &'static str,
    pub name: &'static str,
    pub category: &'static str,
    pub price_usd: i64,
    pub summary: &'static str,
}

pub const PRODUCTS: &[Product] = &[
    Product {
        slug: "atlas-jacket",
        path: "/products/atlas-jacket",
        name: "Atlas Jacket",
        category: "Men's Weatherproof Shell",
        price_usd: 248,
        summary: "Weatherproof shell with a quiet technical finish.",
    },
    Product {
        slug: "field-pack",
        path: "/products/field-pack",
        name: "Field Pack",
        category: "Everyday Backpack",
        price_usd: 168,
        summary: "Structured everyday pack with laptop and camera storage.",
    },
    Product {
        slug: "merino-tee",
        path: "/products/merino-tee",
        name: "Merino Tee",
        category: "Men's Base Layer",
        price_usd: 78,
        summary: "Lightweight base layer for travel, training, and daily wear.",
    },
];

pub fn find_product(slug: &str) -> Option<&'static Product> {
    PRODUCTS.iter().find(|product| product.slug == slug)
}
```

</CodeFile>


<CodeFile name="src/data/mod.rs">


```rust
pub mod products;
```

</CodeFile>


<CodeFile name="src/main.rs">


```rust
// The generated main.rs declares each module explicitly. Add the new one:
mod data;
```

</CodeFile>


</CodeExplorer>


## Product Card

The generated starter uses a manual document head. This tutorial keeps that
mode; to adopt managed metadata, migrate the document outlet and page/layout
roles together as shown in [Layouts and Pages](/docs/framework/layouts-and-pages).

The whole card is the link, and the image slot is a placeholder box until you
have real photography.

<CodeExplorer>


<CodeFile name="src/components/product_card.rs">


```rust
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;

use crate::data::products::Product;

pub struct ProductCard {
    pub product: &'static Product,
}

impl<L: DataLoader> WebRenderSync<L> for ProductCard {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let product = self.product;
        html_sync! {
            <a class="grid gap-3" href={cx.url(product.path)}>
                <div class="flex aspect-square w-full items-center justify-center rounded-lg bg-zinc-100">
                    <span class="text-xs uppercase tracking-[0.25em] text-zinc-400">
                        {product.name}
                    </span>
                </div>
                <div>
                    <h2 class="text-base font-medium text-zinc-950">{product.name}</h2>
                    <p class="text-sm text-zinc-500">{product.category}</p>
                    <p class="mt-2 text-base font-medium text-zinc-950">"$"{product.price_usd}</p>
                </div>
            </a>
        }
        .render(cx)
    }
}
```

</CodeFile>


<CodeFile name="src/components/mod.rs">


```rust
pub mod badge;
pub mod button;
pub mod card;
pub mod product_card;

pub use badge::Badge;
pub use button::Button;
pub use card::Card;
```

</CodeFile>


</CodeExplorer>


The scaffold's `mod.rs` already declares the vendored `Badge`, `Button`, and
`Card`, which the home page uses, so append to it rather than replacing it.

## Routes

Two pages: a listing that maps over `PRODUCTS`, and a detail page whose
add-to-cart control is a native form posting `sku` and `qty`. There is no
JavaScript in either one.

Each handler wraps its page in the generated `RootDocument` layout and hands it
to `RouteResponse::ssr_async`, the same shape as the generated `src/pages/home.rs`.
`RootDocument` is async-capable, so a synchronous page goes in through
`proa::to_async`. A loop body is its own template, so it needs its own
`html_sync!` block.

<CodeExplorer>


<CodeFile name="src/pages/products.rs">


```rust
use axum::response::IntoResponse;
use proa::{to_async, DataLoader, WebContext, WebRenderSync, WriteError};
use proa::axum::RouteResponse;
use proa::html_sync;

use crate::components::product_card::ProductCard;
use crate::data::products::PRODUCTS;
use crate::layouts::RootDocument;

pub async fn handler() -> impl IntoResponse {
    RouteResponse::ssr_async(RootDocument {
        title: "Products",
        content: to_async(ProductsPage),
    })
}

struct ProductsPage;

impl<L: DataLoader> WebRenderSync<L> for ProductsPage {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <main class="mx-auto grid max-w-6xl gap-8 px-6 py-12">
                <h1 class="text-3xl font-medium text-zinc-950">"Products"</h1>
                <ul class="grid gap-8 sm:grid-cols-2 lg:grid-cols-3">
                    {for product in PRODUCTS {
                        html_sync! { <li>{ProductCard { product }}</li> }
                    }}
                </ul>
            </main>
        }
        .render(cx)
    }
}
```

</CodeFile>


<CodeFile name="src/pages/product.rs">


```rust
use axum::{extract::Path, http::StatusCode, response::IntoResponse};
use proa::{to_async, DataLoader, WebContext, WebRenderSync, WriteError};
use proa::axum::RouteResponse;
use proa::html_sync;

use crate::data::products::{find_product, Product};
use crate::layouts::RootDocument;

pub async fn handler(Path(slug): Path<String>) -> Result<impl IntoResponse, StatusCode> {
    let product = find_product(&slug).ok_or(StatusCode::NOT_FOUND)?;
    Ok(RouteResponse::ssr_async(RootDocument {
        title: product.name,
        content: to_async(ProductPage { product }),
    }))
}

struct ProductPage {
    product: &'static Product,
}

impl<L: DataLoader> WebRenderSync<L> for ProductPage {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let product = self.product;
        html_sync! {
            <main class="mx-auto max-w-6xl px-6 py-10">
                <nav class="flex items-center gap-2 text-xs text-zinc-500">
                    <a href={cx.url("/products")}>"Products"</a>
                    <span>"/"</span>
                    <span class="text-zinc-900">{product.name}</span>
                </nav>
                <div class="mt-6 flex flex-col gap-10 lg:flex-row">
                    <div class="lg:w-[55%]">
                        <div class="flex aspect-square w-full items-center justify-center rounded-lg bg-zinc-100">
                            <span class="text-xs uppercase tracking-[0.25em] text-zinc-400">
                                {product.name}
                            </span>
                        </div>
                    </div>
                    <div class="lg:w-[45%]">
                        <h1 class="text-[28px] font-medium leading-tight text-zinc-950">
                            {product.name}
                        </h1>
                        <p class="mt-1 text-base text-zinc-500">{product.category}</p>
                        <p class="mt-4 text-xl font-medium text-zinc-950">"$"{product.price_usd}</p>
                        <p class="mt-6 text-base leading-7 text-zinc-600">{product.summary}</p>
                        <form method="post" action={cx.url("/cart")} class="mt-8">
                            <input type="hidden" name="sku" value={product.slug} />
                            <input type="hidden" name="qty" value="1" />
                            <button
                                class="mt-6 flex h-[60px] w-full items-center justify-center rounded-full bg-zinc-950 text-lg font-medium text-white transition hover:opacity-80"
                                type="submit"
                            >
                                "Add to Bag"
                            </button>
                        </form>
                        <div class="mt-8 border-t border-zinc-200 pt-2 text-sm text-zinc-600">
                            <p class="py-2">"Free standard shipping on orders over $150."</p>
                            <p class="py-2">"Free 60-day returns."</p>
                        </div>
                    </div>
                </div>
            </main>
        }
        .render(cx)
    }
}
```

</CodeFile>


<CodeFile name="src/pages/mod.rs">


```rust
pub mod home;
pub mod product;
pub mod products;
```

</CodeFile>


</CodeExplorer>


## Form Action

Add the POST handler beside the generated health endpoints, then register all
three routes in `src/routes.rs`.

<CodeExplorer>


<CodeFile name="src/endpoints/cart.rs">


```rust
use axum::{extract::Form, http::StatusCode, response::Redirect};
use proa::axum::app_url;
use serde::Deserialize;

#[derive(Deserialize)]
pub struct AddToCart {
    sku: String,
    qty: u32,
}

pub async fn add_to_cart(Form(form): Form<AddToCart>) -> Result<Redirect, StatusCode> {
    if crate::data::products::find_product(&form.sku).is_none()
        || !(1..=99).contains(&form.qty)
    {
        return Err(StatusCode::BAD_REQUEST);
    }
    // Persist the validated cart change in your application's session/store.
    tracing::info!(sku = %form.sku, qty = form.qty, "add to cart");
    Ok(Redirect::to(&app_url("/products").to_string()))
}
```

</CodeFile>


<CodeFile name="src/endpoints/mod.rs">


```rust
pub mod cart;
pub mod health;
```

</CodeFile>


<CodeFile name="src/routes.rs">


```rust
use axum::routing::{get, post};

// ... inside router(), between the markers the generator maintains:

let (router, metadata) = router_from_spec(vec![
    // proa:route-specs:start
    Route::endpoint("/", get(pages::home::handler)),
    Route::endpoint("/products", get(pages::products::handler)),
    Route::endpoint("/products/:slug", get(pages::product::handler)),
    Route::endpoint("/cart", post(endpoints::cart::add_to_cart)),
    // proa:route-specs:end
]);
```

</CodeFile>


</CodeExplorer>


Two pieces of Axum vocabulary are worth naming here, because they look unusual
the first time:

- `Form<T>` is a newtype wrapper, `struct Form<T>(pub T)`. The type is the
  instruction: it tells Axum to parse the request body as
  `application/x-www-form-urlencoded` into `T`. Swap it for `Json<T>`, `Path<T>`,
  or `Query<T>` to read a different part of the request.
- `Form(form):` is ordinary Rust pattern destructuring in the parameter
  position, the same thing as `let Form(form) = ...` written inline. You can
  write `form: Form<AddToCart>` instead and reach the value through `form.0`.

Deserializing into a typed struct rather than a `HashMap` means a missing or
non-numeric `qty` is rejected by the extractor with a 422 before your handler
runs.

Open `http://localhost:3000/products/atlas-jacket` and submit the form. It posts
`sku=atlas-jacket` and `qty=1`, then redirects. No JavaScript has been involved
so far.

## The Island

Now make the quantity adjustable in the browser, without giving up anything
above.

<CodeExplorer>


<CodeFile name="Cargo.toml">


```toml
rsjs = "0.3.0"
```

`rsjs` re-exports the `#[rsjs]` attribute, so no separate macro crate is
needed, and the scaffold already depends on `serde`.

</CodeFile>


<CodeFile name="src/components/quantity_stepper.rs">


```rust
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::{html_sync, text};
use rsjs::{rsjs, signal};

pub struct QuantityStepper {
    pub unit_price: i64,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for QuantityStepper {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let qty = signal(1_i64);
        let unit_price: rsjs::Signal<i64> = signal(self.unit_price);
        let subtotal = rsjs::memo(|| qty.get() * unit_price.get());

        html_sync! {
            <div>
                <div class="flex items-center justify-between">
                    <span class="text-base font-medium text-zinc-950">"Quantity"</span>
                    <span class="text-sm text-zinc-500" aria-live="polite">
                        {text!("Subtotal ${}", subtotal.get())}
                    </span>
                </div>
                <div class="mt-3 flex items-center gap-2">
                    <button
                        type="button"
                        class="h-12 w-12 rounded-lg border border-zinc-300 text-lg transition hover:border-zinc-950 disabled:border-zinc-100 disabled:bg-zinc-100 disabled:text-zinc-400"
                        aria-label="Decrease quantity"
                        disabled={qty.get() == 1}
                        on_click={|_| qty.update(|q| if q > 1 { q - 1 } else { q })}
                    >
                        "-"
                    </button>
                    <span class="flex h-12 w-16 items-center justify-center rounded-lg border border-zinc-300 text-base font-medium">
                        {qty.get()}
                    </span>
                    <button
                        type="button"
                        class="h-12 w-12 rounded-lg border border-zinc-300 text-lg transition hover:border-zinc-950"
                        aria-label="Increase quantity"
                        disabled={qty.get() == 99}
                        on_click={|_| qty.update(|q| if q < 99 { q + 1 } else { q })}
                    >
                        "+"
                    </button>
                </div>
                <input type="hidden" name="qty" value={qty.get()} />
            </div>
        }
        .render(cx)
    }
}
```

</CodeFile>


<CodeFile name="src/components/mod.rs">


```rust
pub mod badge;
pub mod button;
pub mod card;
pub mod product_card;
pub mod quantity_stepper;

pub use badge::Badge;
pub use button::Button;
pub use card::Card;
```

</CodeFile>


<CodeFile name="src/pages/product.rs">


```rust
use crate::components::quantity_stepper::QuantityStepper;

// ...

<form method="post" action={cx.url("/cart")} class="mt-8">
    <input type="hidden" name="sku" value={product.slug} />
    {QuantityStepper { unit_price: product.price_usd }}
    <button
        class="mt-6 flex h-[60px] w-full items-center justify-center rounded-full bg-zinc-950 text-lg font-medium text-white transition hover:opacity-80"
        type="submit"
    >
        "Add to Bag"
    </button>
</form>
```

</CodeFile>


</CodeExplorer>


Four things in `quantity_stepper.rs` carry the whole idea:

- `#[rsjs(component, client)]` marks an otherwise ordinary `WebRenderSync` impl
  for analysis. `component` asks the compiler to analyze it; `client` grants
  permission to originate browser behavior.
- `signal(1_i64)` is island-local state. `signal(self.unit_price)` seeds a prop
  into browser-visible state once, at mount. The explicit
  `rsjs::Signal<i64>` annotation gives the arithmetic a proven fixed-width
  integer domain, which the compiler requires before it will lower `*` into
  JavaScript; without it you get `rsjs/integer-domain-unproven`.
- `rsjs::memo(...)` derives the subtotal. It recomputes in the browser when
  either input changes, and it is evaluated once on the server for the initial
  HTML.
- The hidden input is the bridge back to the plain form. Its `value` is a
  reactive attribute, and the runtime writes the DOM `value` property, so the
  form submits the current quantity.

In `product.rs` the stepper replaces the fixed hidden `qty` input. An island is
invoked exactly like any other component: a struct literal in a slot. That is
the component running in the demo at the top of this page.

## Serving the Island

The generated site's router already merges
`proa::axum::rsjs_assets_router(&base_path)` after `.with_state(state)`.
Keep that shared asset router: it serves the linked core runtime, query runtime,
island modules, and component fragments with the configured URL prefix.

`RouteResponse` records the rendered owners and emits the required runtime tags
automatically, including owners arriving in streamed boundaries. Do not append
runtime tags in `RootDocument` or add a separate `rsjs_assets.rs` implementation.
A response without hydrated owners emits no RSJS runtime tags.

For an existing hand-written server, follow [Runtime wiring](/docs/rsjs/runtime)
and install `FrameworkBuilder::with_rsjs_assets()` or merge the shared asset
router explicitly.

## Verify

`proa dev` restarts on its own after the change; if you stopped it, run it
again. Open `http://localhost:3000/products/atlas-jacket` and check three
things.

**The server sent working HTML.** View source. The stepper is real markup with
the correct starting state, wrapped in an island boundary next to a small seed
script:

```html
<rsjs-island data-rsjs-island-root="rsjs_owner_...">
  <div>
    <div class="flex items-center justify-between">
      <span class="...">Quantity</span>
      <span class="..." aria-live="polite" data-rsjs-bind="4">Subtotal $248</span>
    </div>
    <div class="mt-3 flex items-center gap-2">
      <button type="button" class="..." aria-label="Decrease quantity" disabled data-rsjs-attr="6" data-rsjs-handler="6">-</button>
      <span class="..." data-rsjs-bind="8">1</span>
      <button type="button" class="..." aria-label="Increase quantity" data-rsjs-handler="9">+</button>
    </div>
    <input type="hidden" name="qty" value="1" data-rsjs-attr="11">
  </div>
</rsjs-island>
<script type="application/json" data-rsjs-island="rsjs_owner_...">{"signals":["1","248"]}</script>
```

The `data-rsjs-*` attributes are compiler-owned markers that tell the runtime
which nodes to bind on hydration. The seed script carries the exact initial
signal values, so the browser rebuilds state without re-fetching anything.

The minus button is already `disabled` because `qty` starts at 1. That state was
computed on the server, not after hydration.

**The island works.** Click `+` twice. The quantity reads `3`, the subtotal
reads `$744`, the minus button re-enables, and the hidden input now submits
`qty=3`.

**It degrades.** Disable JavaScript in devtools and reload. The stepper buttons
do nothing, but the hidden input still carries `value="1"`, so "Add to Bag"
posts `sku=atlas-jacket` and `qty=1` exactly as it did before the island
existed. Nothing on the page is blank or broken.

That is the whole trade. The island is opt-in behavior layered onto HTML that
already works, not the mechanism that makes the page appear.

## Validate

```bash
cargo fmt --all
cargo check
proa fmt --check --verify src
proa lint src
```

`cargo check` still works on a project with islands. `cargo build` and
`cargo run` do not: the link step deliberately fails so that a binary is never
shipped without its compiled island modules. Use `proa dev`, `proa run`, or
`proa build` instead.

## Next

| Add | Read |
|-----|------|
| More island shapes | [Islands: when and why](/docs/guides/islands) |
| Signal semantics and props | [RSJS Signals](/docs/rsjs/signals) and [Component props](/docs/rsjs/component-props) |
| Server data loading | [Framework Data Loading](/docs/framework/data-loading) |
| Richer forms and typed actions | [Forms and actions](/docs/guides/forms-actions) |
| Production cache rules | [Page caching](/docs/framework/page-caching) |


---

# Docs: HTML rendering

URL: /docs/core/html-rendering
Description: Render typed Rust values to HTML with render traits and the html! macros.

---
title: HTML rendering
description: Render typed Rust values to HTML with render traits and the html! macros.
keywords: [html_sync, html!, html_sync!, text!, template]
---

Proa lets you use ordinary Rust for dynamic values,
components, conditions, matches, and loops. You write templates with `html!` or
`html_sync!`, then implement a render trait to turn the template into a component.

Everything on this page renders on the server. That is not a mode you select per
route or per component: a component writes bytes into the response, the reader
gets a complete page, and nothing on it needs JavaScript to appear. There is no
hydration pass by default, and a page ships no client JavaScript at all until you
add an [island](/docs/guides/islands), which is opt-in per component.

## Writing templates

`html_sync!` and `html!` share the same template syntax. The examples in this
section use `html_sync!` because most components do not need to await anything.

### DOM Elements

Standard elements, attributes, dynamic values, and components share one tree:

```rust filename="src/components/hero.rs" {4-5}
html_sync! {
    <section data-component="hero" aria-labelledby="hero-title">
        <h1 id="hero-title">"Hello World!"</h1>
        <p>"Count: "{self.count}</p>
        {Price { amount: self.price }}
    </section>
}
```

Write attribute names with their HTML spelling: `aria-label`,
`aria-labelledby`, and `data-component` stay kebab-case in the template and
rendered DOM.

Text nodes are string literals in double quotes, and Proa escapes them
automatically. Characters like `<`, `>`, `&`, and non-breaking spaces are encoded per the
[HTML serialization algorithm](https://html.spec.whatwg.org/multipage/parsing.html#serialising-html-fragments).

Rust expressions go in curly braces. Values render as text, while components use rust `struct` syntax and render in place.

### Formatted text with `text!`

Use a plain `{value}` slot for one dynamic value. Use `text!` when a text node
mixes static text, multiple values, or Rust formatting directives:

```rust filename="src/components/block_gallery.rs" {5,9}
html_sync! {
    <article class="block-gallery-card">
        <iframe
            src={block.preview_href}
            title={text!("{} block preview", block.name)}
            loading="lazy"
        ></iframe>
        <p>{text!("Explore the {} block.", block.name)}</p>
    </article>
}
```

`text!` escapes for its position: attribute escaping in `title`, and text-node
escaping in the caption. Bare `{}` placeholders use Proa rendering; format
specifiers such as `{:.2}` use Rust formatting. Write `{{` or `}}` for literal
braces.

Unlike `format!()`, `text!` writes directly to Proa's output buffer. This avoids
allocating an intermediate `String` and then copying it into the response on
every render, which reduces work in a hot render path.

The Proa CLI is designed to catch this mistake. If you use `format!()` while
rendering, `proa lint` reports the allocation and suggests a streaming
alternative:

```console
$ proa lint src/components/greeting.rs
src/components/greeting.rs:4:17: warning[perf/format]: format!() in a Proa render path allocates a String on every render
  help: for text, render adjacent pieces like `"$"{price}" / night"`; for attrs, precompute or use `text!(...)`
```

Placeholder-bearing `text!` is rejected in URL attributes such as `href` and
`src`; use a validated URL value or typed URL helper instead.

### Control flow (if, for, match, etc.) is Rust

Inside an ordinary server-rendered component, a `{ ... }` slot accepts Rust
expressions. Use `if`, `match`, and `for` directly in the render tree. When a
branch or loop iteration produces markup, return another template fragment:

```rust filename="src/components/product_list.rs" {2-3,10,13,21}
html_sync! {
    <section class={if self.featured { "featured-products" } else { "products" }}>
        {if self.products.is_empty() {
            html_sync! {
                <p>"No products found"</p>
            }
        } else {
            html_sync! {
                <ul>
                    {for product in self.products {
                        html_sync! {
                            <li>
                                {match &product.status {
                                    Status::Active => html_sync! {
                                        <span class="text-green-600">"Active"</span>
                                    },
                                    Status::Inactive => html_sync! {
                                        <span class="text-red-600">"Inactive"</span>
                                    },
                                }}
                                {ProductCard { product }}
                            </li>
                        }
                    }}
                </ul>
            }
        }}
    </section>
}
```

The `class` conditional returns strings directly; branches that
produce elements return template fragments.

### `Option<T>`

`Option<T>` renders its value when it is `Some` and nothing when it is `None`,
so optional content often needs no explicit branch:

```rust filename="src/components/panel.rs"
html_sync! {
    <section>
        <h2>{self.title}</h2>
        {self.subtitle}
    </section>
}
```

> **RSJS note**: These examples show ordinary server-rendered components.
> Expressions that must also compile into browser JavaScript inside an
> RSJS-analyzed component use a deliberately portable subset of Rust. See
> [Islands: when and why](/docs/guides/islands) before moving behavior to the
> browser.

### Attributes

Static values are string literals; dynamic values go in braces and are escaped before rendering:

```rust filename="src/components/link.rs"
html_sync! {
    <a href={self.href} aria-label={self.label}>{self.children}</a>
}
```

`Option<&str>` omits the attribute entirely when `None`:

```rust filename="src/components/tab.rs"
let selected: Option<&str> = self.selected.then_some("true");

html_sync! {
    <button aria-selected={selected}>"Tab"</button>
}
```

Valueless attributes render as the bare attribute name (`disabled`, `open`), which is spec-compliant:

```rust filename="src/components/form.rs"
html_sync! {
    <input type="text" disabled />
    <details open>
        <summary>"Click"</summary>
    </details>
}
```

The macro accepts **any** attribute name, so htmx, Alpine, ARIA, and `data-*`
attributes work without a fixed allowlist. Prefer their canonical hyphenated
HTML spelling; underscores are accepted and normalized to dashes when needed:

```rust filename="src/components/save.rs"
html_sync! {
    <button hx-post="/api/submit" hx-swap="outerHTML">"Save"</button>
    <div data-user-id="123" data-role="admin">"content"</div>
}
```

Prefer data attributes for JavaScript hooks and tests, and classes for styling. Never parse a generated class string as state.

### Documents and comments

`<!DOCTYPE html>` works inside the macro, and `<>...</>` renders siblings without a wrapper.

Rust comments inside `html!` are stripped by the compiler and never reach the output. `///` doc comments do not work there, they are only valid before item definitions.

There is no `<!-- -->` syntax. HTML comments in SSR output are almost always wasted bytes, so including one is deliberate:

```rust filename="src/layouts/root.rs"
use proa::StaticRaw;

html_sync! {
    {StaticRaw("<!-- page boundary -->")}
    <div>"content"</div>
}
```

## Choosing a render trait

| Output | Synchronous | Async-capable |
|--------|-------------|---------------|
| HTML | `WebRenderSync` + `html_sync!` | `WebRender` + `html!` |
| Markdown | `MdRenderSync` + `md_sync!` | `MdRender` + `md!` |

Every component picks one of these two, and the choice is narrow: **use the
synchronous trait unless its body or metadata hook has to `.await`.**
Both render on the server; the difference is whether rendering can suspend.

A synchronous component writes its bytes and returns. There is no future, no
driver, and no scheduling. An async-capable component returns a `RenderOutcome`
instead, which a driver at the route or adapter boundary resolves. Most route
bodies, layouts, and UI components stay synchronous.

<Tabs data-items="Synchronous|Async-capable">


<Tab value="Synchronous">


`WebRenderSync` with `html_sync!`. This is the shape of almost every component
you will write.

```rust filename="src/components/price.rs"
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;

pub struct Price {
    pub amount: u32,
}

impl<L: DataLoader> WebRenderSync<L> for Price {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <span data-component="price" class="font-semibold">"$"{self.amount}</span>
        }
        .render(cx)
    }
}
```

</Tab>


<Tab value="Async-capable">


`WebRender` with `html!`. The signature is heavier because the returned future
borrows the context, so reach for it only when you need to `.await`.
An async `render_head` is also a reason to implement `WebRender`, even when the
body is synchronous. See [Metadata](/docs/framework/metadata).

```rust filename="src/components/async_price.rs"
use std::future::Future;

use proa::{
    DataLoader, LoadKey, RenderOutcome, WebContext, WebRender, WriteError,
};
use proa::{html, text};

pub struct AsyncPrice;

impl<L: DataLoader> WebRender<L> for AsyncPrice {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let amount = cx.load_typed::<u32>(LoadKey::named("price", "featured")).await?;
            html! {
                <span>{text!("${}", *amount)}</span>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

</Tab>


</Tabs>


This async example expects the route's loader to return
`LoadValue::typed(42_u32)` for `price:featured`. Use a normal value and the
synchronous implementation when there is no async work.

For managed HTML documents, the selected Page declares `ROLE = PAGE`, ancestor
layouts declare `LAYOUT`, and the document contains one head outlet. Ordinary
components keep the default `COMPONENT` role. The low-level drivers below use
manual rendering unless you configure a managed document explicitly. See
[Layouts and Pages](/docs/framework/layouts-and-pages).


Ordinary authored implementations are generic only over `L: DataLoader`.
`WebContext<L>` owns the default reusable `RenderBuffer`; the second `B`
parameter is reserved for lower-level custom-writer integrations.

## Driving an async render

`WebRender` never blocks to render itself. It returns a `RenderOutcome`,
`Done(result)` on the sync path or `Pending(future)` on the async path, and a
driver at the route or adapter boundary resolves it.

For framework routes, use `RouteResponse::ssr_async(...)`, `ssr_async_with_loader(...)`, or the `ssr_stream*` constructors. For custom adapters and tests, `proa` exports drivers:

| Driver | Use it when |
|--------|-------------|
| `render_to_vec_async(root)` | You want an owned contiguous byte buffer. |
| `render_to_string_async(root)` | You want a UTF-8 string. The output is not scanned: text writes are UTF-8 by type and raw byte writes are validated where they are written. |
| `render_into_async(&mut buf, root)` | You want to reuse a caller-owned `RenderBuffer`. |
| `render_in_context_async(&mut cx, root)` | You need to customize `WebContext` first. |

```rust filename="src/adapter.rs"
use std::sync::Arc;

use proa::{render_in_context_async, WebContext};

let mut out = Vec::new();
let mut cx = WebContext::with_loader_buffer(
    &mut out,
    Arc::new(loader),
);

render_in_context_async(&mut cx, PageWithData).await?;
```

> **Good to know**: Streaming render modes also need the matching framework state installed, stream recorders and chunk flushers. Use the framework response helpers unless you are writing that adapter layer. See [Streaming SSR](/docs/core/streaming-ssr).

## Next steps

- [Components](/docs/core/components)
  - Nest components, pass children, and branch inside a render tree.
- [Markdown rendering](/docs/core/markdown)
  - Render typed Rust values to Markdown for docs, feeds, and agents.
- [WriteBuf](/docs/core/write-buf)
  - Pick the buffer a route renders into.
- [Escaping and raw HTML](/docs/core/escaping)
  - How Proa encodes dynamic values, and the two ways to opt out.
- [Route responses](/docs/framework/responses)
  - Return synchronous, buffered async, or streaming SSR with islands.


---

# Docs: Components

URL: /docs/core/components
Description: How Proa components are plain structs, how props and children flow, and how the recipe system styles them.

---
title: Components
description: How Proa components are plain structs, how props and children flow, and how the recipe system styles them.
keywords: [WebRenderSync, WebRender, to_async, await_component, ProaComponent]
---

A Proa component is a struct plus a render impl. Its fields are props, its impl defines the template, and Rust checks both.

<Callout>

You do not have to write the common ones yourself. [proa-ui](https://ui.proa.so/docs) is a shadcn-style catalog of Proa components, and `proa ui add button` vendors the source into `src/components/button/` in your project. You own the files and edit them exactly like the ones on this page.

</Callout>


```rust filename="src/components/button/button.rs"
use super::recipe::{ButtonSize, ButtonVariant};

pub struct Button<C = ()> {
    pub variant: ButtonVariant,
    pub size: ButtonSize,
    pub disabled: bool,
    pub class: Option<&'static str>,
    pub children: Option<C>,
}

impl<C> Default for Button<C> {
    fn default() -> Self {
        Self {
            variant: ButtonVariant::Solid,
            size: ButtonSize::Md,
            disabled: false,
            class: None,
            children: None,
        }
    }
}
```

That declaration is the component's public API. Every field is a prop, `rustdoc` documents it for free, and passing an unknown one is a compile error rather than a silently ignored attribute.

## Rendering a component

Put a struct literal in braces inside a template and it renders in place:

```rust filename="src/pages/home.rs"
html_sync! {
    <div class="flex gap-2">
        {Button { children: Some("Save"), ..Button::default() }}
        {Button {
            variant: ButtonVariant::Outline,
            children: Some("Cancel"),
            ..Button::default()
        }}
    </div>
}
```

Struct-literal syntax is doing real work here. `..Button::default()` is Rust's functional update, so a component with twelve props stays readable when a caller sets two, and the defaults live in one `Default` impl instead of being scattered across call sites.

There is no separate props type to keep in sync. The literal is constructed on the stack and consumed by `render`.

## Writing the render impl

The impl decides which trait the component supports. Use `WebRenderSync` unless its body or metadata hook needs to await work:

```rust filename="src/components/button/button.rs"
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use super::recipe::button_classes;

impl<L, C> WebRenderSync<L> for Button<C>
where
    L: DataLoader,
    C: WebRenderSync<L>,
{
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <button
                data-button
                data-variant={self.variant.as_str()}
                data-size={self.size.as_str()}
                type="button"
                class={button_classes(self.variant, self.size, self.class)}
                disabled={self.disabled}
            >
                {self.children}
            </button>
        }
        .render(cx)
    }
}
```

`render` takes `self` by value, so props move into the template with no clone and no borrow to satisfy.

## Children

A component that wraps caller content is generic over its children, and the bound is the same render trait the parent implements:

```rust
impl<L, C> WebRenderSync<L> for Button<C>
where
    C: WebRenderSync<L>,
```

`C = ()` supplies the default child type when you write a type such as `let button: Button = Button::default()`. A child like `Some("Save")` infers its own `C`; for an otherwise unconstrained empty button, write `Button::<()>::default()`. The manual `Default` implementation does not require `C: Default`.

The render bound constrains only types actually rendered as children.

Children are `Option<C>` because `Option<T>` renders nothing when `None`. Optional content needs no branch in the template:

```rust filename="src/components/panel.rs"
html_sync! {
    <section data-panel>{self.subtitle}{self.children}</section>
}
```

## Styling: recipes, not class strings

Proa is opinionated about where classes live. A component does not build a class string at render time; it selects between static fragments that were resolved at compile time. For reusable components, keep style decisions in `recipe.rs` beside the render implementation.

`recipe.rs` owns the styling. Each variant axis is an enum whose `classes()` maps a semantic name to a class fragment:

```rust filename="src/components/button/recipe.rs"
use proa::ClassList;

mod base {
    pub const BUTTON_BASE: &str =
        "inline-flex items-center justify-center rounded-md text-sm font-medium";
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ButtonVariant {
    #[default]
    Solid,
    Outline,
    Ghost,
}

impl ButtonVariant {
    pub const fn classes(self) -> &'static str {
        match self {
            Self::Solid => "bg-primary text-primary-foreground hover:bg-primary/90",
            Self::Outline => "border border-input bg-background hover:bg-accent",
            Self::Ghost => "hover:bg-accent hover:text-accent-foreground",
        }
    }

    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Solid => "solid",
            Self::Outline => "outline",
            Self::Ghost => "ghost",
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ButtonSize {
    #[default]
    Md,
    Sm,
}

impl ButtonSize {
    pub const fn classes(self) -> &'static str {
        match self {
            Self::Md => "h-9 px-4",
            Self::Sm => "h-8 px-3",
        }
    }

    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Md => "md",
            Self::Sm => "sm",
        }
    }
}
```

Both methods support const evaluation. At render time, a variant selects an existing `&'static str` fragment without constructing a class string. The paired `as_str` is what the component renders into `data-variant`.

One function composes the axes, returning a stack-allocated [`ClassList`](/docs/core/class-composition) rather than a `String`:

```rust filename="src/components/button/recipe.rs"
pub fn button_classes(
    variant: ButtonVariant,
    size: ButtonSize,
    class: Option<&'static str>,
) -> ClassList<4> {
    ClassList::new()
        .add(base::BUTTON_BASE)
        .add(variant.classes())
        .add(size.classes())
        .add_opt(class)
}
```

`add_opt` is the escape hatch: callers extend a component with `class: Some("w-full")` without the component owning every combination.

Rendering `Button { children: Some("Save"), ..Button::default() }` produces:

```html
<button data-button data-variant="solid" data-size="md" type="button"
        class="inline-flex items-center justify-center rounded-md text-sm font-medium bg-primary text-primary-foreground hover:bg-primary/90 h-9 px-4">Save</button>
```

Two conventions show up in that output and both are deliberate:

- **`data-button`** marks the component root. Every component renders a bare `data-<name>` attribute so tests and browser automation can select it without depending on class strings.
- **`data-variant` / `data-size`** publish the resolved variant. Styling reads from `class`, but assertions, visual regression tooling, and CSS overrides read the semantic value.

## One component, multiple render targets

Rendering is a trait implemented by a component's Rust type. Components share data and typed children across HTML, Markdown, and other render targets, while each implementation defines its output. HTML uses `WebRenderSync` and Markdown uses `MdRenderSync`; other targets can define their own rendering traits. A target can produce a document format or use a different rendering backend.

The following example gives a button a Markdown implementation alongside its HTML implementation.

Most interactive chrome has no Markdown equivalent, so the Markdown impl usually renders the meaning rather than the widget. A button is its label:

```rust filename="src/components/button/md.rs"
use proa::{DataLoader, MdRenderSync, WebContext, WriteError};
use super::Button;

/// Button renders as just its label text; the visual chrome is meaningless in Markdown.
impl<L: DataLoader, C: MdRenderSync<L>> MdRenderSync<L> for Button<C> {
    fn render_md(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        proa::md_sync! { "{self.children}" }.render_md(cx)
    }
}
```

The ordinary-string template selects inline mode while its children render and restores the enclosing mode on success, error, or panic unwinding. Block templates are rejected inside that scope, including through typed children. Give a block component an inline representation when it needs to appear in a label or table cell.

A physically multiline raw template selects block mode and inserts only the missing paragraph-boundary bytes before its body and after successful rendering. The hash count only delimits the literal. Single-line raw literals are inline. The macro body is always one string literal; to render components in sequence without authoring Markdown, use a tuple such as `(overview, impact).render_md(cx)`. Lower-level renderers can still call `cx.md_block_boundary()` explicitly.

> **Good to know**: Target implementations are independent. A component can support one target or several. For HTML, use `WebRenderSync` by default and `WebRender` when rendering needs to `.await`; Markdown has the same split with `MdRenderSync` and `MdRender`. See [HTML rendering](/docs/core/html-rendering) and [Markdown rendering](/docs/core/markdown) for those built-in traits and macros.

## Crossing the sync and async boundary

A sync-only component composes into an async tree through `to_async(...)`:

```rust filename="src/pages/dashboard.rs"
html! {
    <main>{proa::to_async(Button { children: Some("Save"), ..Button::default() })}</main>
}
```

When a future resolves to a renderable child, use `await_component(...)` instead. An async child cannot appear inside `html_sync!` at all: move the boundary up to `WebRender` and `html!`, or await the data before rendering.

## How proa-ui scales this

The [proa-ui](https://ui.proa.so/docs) component library runs the same model with two additions that matter once a component has several independent style axes.

**A resolver instead of a helper function.** Props arrive as `Option`, and a const recipe resolves them against defaults into one `Copy` style value:

```rust filename="proa_ui/src/components/button/recipe.rs"
pub const BUTTON_RECIPE: ButtonRecipe = ButtonRecipe {
    base: base::BUTTON_BASE,
    size_default: Some(ButtonSize::Md),
    color_default: Some(ButtonColor::Primary),
    variant_default: Some(ButtonVariant::Solid),
    radius_default: Some(ButtonRadius::Md),
};
```

`BUTTON_RECIPE.resolve(props)` returns a `ButtonStyle` that implements `AttrValue`, so it streams its class fragments straight into the response buffer with no intermediate `ClassList` or `String`. It also carries the effective values, which is what feeds `data-size`, `data-color`, `data-variant`, and `data-radius`.

**Compound variants.** Independent axes concatenate, but `color x variant` does not: an outline destructive button is not "destructive classes plus outline classes". proa-ui resolves that pair in one place, `color.classes_for(variant)`, rather than layering two fragments and hoping the cascade agrees.

The library also derives `#[derive(ProaVariant)]` on its variant enums to publish variant metadata (labels, values, classes) for its catalog and TypeScript codegen. That derive expands to an impl of proa-ui's own `VariantSpec` trait, so it belongs to the library's infrastructure rather than to application components; a component in your app uses plain enums exactly as shown above.

## Next steps

- [HTML rendering](/docs/core/html-rendering)
  - Elements, attributes, control flow, and the sync and async render traits.
- [Class composition](/docs/core/class-composition)
  - `ClassList`, capacity, and the allocation to avoid in a render path.
- [Markdown rendering](/docs/core/markdown)
  - The `md_sync!` and `md!` template macros behind an `MdRenderSync` impl.
- [Islands: when and why](/docs/guides/islands)
  - Add browser behavior to a component with RSJS.


---

# Docs: Markdown rendering

URL: /docs/core/markdown
Description: Compose Markdown as one of a component's render targets, sharing data and typed children across formats.

---
title: Markdown rendering
description: Compose Markdown as one of a component's render targets, sharing data and typed children across formats.
---

Markdown is an interface for documentation, feeds, command-line clients, and content inside conversations. These consumers need a useful representation of the same application data a browser displays.

Proa makes rendering a trait rather than a fixed output format. A Rust component can share fields and typed children across HTML, Markdown, and other render targets, defining its output for each target. HTML uses `WebRenderSync` and Markdown uses `MdRenderSync`; other targets can define their own rendering traits. Use `WebRender` and `MdRender` when the HTML or Markdown implementation needs to await work.

For an agent consuming content, direct Markdown rendering also avoids extracting text from browser markup. The Markdown implementation chooses which content and structure to include, using the same component data as the HTML implementation.

```rust filename="src/components/product_summary.rs"
use proa::{DataLoader, MdRenderSync, WebContext, WriteError};
use proa::md_sync;

pub struct ProductSummary {
    pub title: &'static str,
    pub description: &'static str,
}

impl<L: DataLoader> MdRenderSync<L> for ProductSummary {
    fn render_md(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        md_sync! { r###"
            ## {self.title}

            {self.description}
            "###
        }
        .render_md(cx)
    }
}
```

That makes Markdown composable. Components nest, loop, and take children, so a `SearchPage` builds a document out of fifty `Listing` components and none of them concatenates a string. Change `Listing` and every document containing one changes.

## Writing a template

Reach for this when a route serves docs source, an agent-readable representation, a feed, or any dense text output that is not HTML.

Follow [Editor setup](/docs/guides/editor-setup) for go-to-definition, hover,
completion, and rename inside `r###"..."###` templates in VS Code, Neovim,
and other LSP editors.

> **Good to know**: `cargo proa fmt` re-anchors a template to its macro's indentation and `cargo proa lint` reports one that has drifted, but both tools only see brace-delimited invocations. Write `md_sync! { ... }`, not `md_sync!( ... )`.

## Choosing a trait and a macro

| Trait | Template macro | Use it when |
|-------|----------------|-------------|
| `MdRenderSync<L, B>` | `md_sync!` | The component writes Markdown without `.await`. |
| `MdRender<L, B>` | `md!` | The component may await, or composes async Markdown children. |

HTML and Markdown share `WebContext<L, B>`. Both Markdown traits default to
`L = NoLoader` and `B = RenderBuffer`, in that order. Application components
usually implement `MdRenderSync<L>` or `MdRender<L>` and take
`&mut WebContext<L>`; the owned buffer needs no lifetime parameter. Keep `B` as
the second generic only when a component needs to support custom writers.

Create an owned root with `WebContext::new()`, render with
`component.render_md(&mut cx)`, and consume `cx.into_output()` afterward.
`WebContext::with_buffer(&mut out)` also accepts a borrowed writer for components
implemented over that writer type.

Use `md_sync!` by default:

```rust filename="src/pages/summary.rs"
use proa::md_sync;

let summary = md_sync! { r###"
    # {title}

    {description}
    "###
};
```

Use `md!` when an interpolated child awaits:

```rust filename="src/pages/report.rs"
use proa::render_md_to_string_async;
use proa::md;

let output = render_md_to_string_async(
    md! { r###"
        # Report

        {proa::await_md_component(load_report_body())}
        "###
    },
)
.await;
```

Strings and numbers work directly in both macros. Lift a custom sync-only child into an async tree with `to_md_async(...)`, and use `await_md_component(...)` when a future resolves to a Markdown child.

The canonical form is one multiline raw Markdown template. Use three hashes by default: `md_sync! { r###"..."### }` or `md! { r###"..."### }`. Source newlines render directly, so ordinary paragraphs, sections, and lists do not need `"\n"` or `"\n\n"`. Common Rust source indentation is stripped while deeper relative Markdown indentation is preserved.

Each `{expression}` is a typed render child. Slots contain ordinary Rust control flow; branches re-enter Markdown through nested templates. Braces inside fenced code blocks and inline code spans remain literal Markdown. Outside code, write `{{` or `}}` for a literal brace. Three hashes let ordinary quotes and Rust raw strings with fewer hashes appear without escaping; increase the delimiter only when the document itself contains the exact closing sequence `"###`.

The body is always one string literal. Token composition such as `md_sync! { "# " { title } }` is a compile error that points back to the string form. To render children in sequence without authoring Markdown, use a tuple: `(overview, impact).render_md(cx)`.

An async child cannot appear inside `md_sync!`. Move the boundary to `MdRender` and `md!`.

The Markdown macros use the default-enabled `markdown` feature of `proa`.
An HTML/XML-only application can disable default features to omit the Markdown
parser dependencies. If defaults are disabled, opt in with `features = ["markdown"]`
when using `md!` or `md_sync!`. Cargo enables a feature if any dependency requests it.

## Loops and branches

The template has one lexical rule at every depth: text outside `{ ... }` is Markdown, and text inside is a Rust expression. Control flow is ordinary Rust, exactly as in `html_sync!`, and a branch renders only its final expression. Earlier statements retain ordinary Rust side effects; a semicolon discards a value. Compose multiple fragments in one nested template. Markdown re-enters a branch through a nested `md_sync!` call:

```rust filename="src/pages/summary.rs"
let summary = md_sync! { r###"
    # {title}

    ## Features

    {for feature in features.iter() {
        md_sync! { "- {feature}\n" }
    }}

    {if in_stock {
        md_sync! { "**In stock**" }
    } else {
        md_sync! { "Backordered" }
    }}
    "###
};
```

A bare string tail such as `"Backordered"` renders as escaped text; markup needs the nested template. Use ordinary one-line string templates for short fragments, such as `md_sync! { "- {feature}\n" }`. Keep the row-ending `\n` so iterations do not run together. Reserve raw literals for substantial multiline sections or when they substantially reduce escaping, and use fewer hashes for nested raw literals:

```rust filename="src/pages/report.rs"
md_sync! { r###"
    {for entry in self.entries {
        md_sync! { r#"
            ### {entry.question}

            {entry.answer}

            "#
        }
    }}
    "###
}
```

Because plain Markdown is never parsed inside a slot, `if`, `for`, and `match` are ordinary words in prose, and a line means the same thing at the top level and inside a branch. Writing Markdown directly inside a branch is a compile error that points at the nested-template form. Both macros share this grammar; in `md!` the nested templates and interpolated children may await.

> **Good to know**: Interpolation, slots, and children follow the same rules as the HTML macros. See [Components](/docs/core/components) for the composition model; the difference here is that a Markdown template is one string literal, so control flow lives inside it.

## Composing documents from components

A slot holds a component, not a string. Give the child an `MdRenderSync` impl:

```rust filename="src/components/listing.rs"
impl<L: DataLoader> MdRenderSync<L> for &Listing {
    fn render_md(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        md_sync! { r###"
            ### {self.title}

            **${self.price}/night** · ★{self.rating}
            "###
        }
        .render_md(cx)
    }
}
```

Then interpolate it. The `{listing}` slot dispatches into that impl, the same way an `html_sync!` slot dispatches into a `WebRenderSync` child:

```rust filename="src/pages/search.rs"
impl<L: DataLoader> MdRenderSync<L> for &SearchPage {
    fn render_md(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        md_sync! { r###"
            # {self.title}

            {self.listings.len()} stays

            ---

            {for listing in self.listings.iter() { listing }}
            "###
        }
        .render_md(cx)
    }
}
```

```md filename="output"
# Malibu stays

2 stays

---

### Cliffside cottage

**$420/night** · ★4\.9

### Surf shack

**$180/night** · ★4\.7
```

The page never learns that a listing renders as an `h3`, and never allocates a `String` for one.

Note the `4\.9`: `rating` is a string here, and string interpolations are Markdown-escaped, so data cannot inject structure. A title of `# Free money` arrives as text, not a heading. Numbers are written verbatim, so an `f64` rating would print `4.9`.

## One component, multiple representations

Each render target has its own implementation on the same struct. Here, the HTML implementation emits a browser callout and the Markdown implementation emits a blockquote. The same component data can support other formats or rendering backends through additional implementations:

```rust filename="src/components/callout.rs"
impl<L: DataLoader> WebRenderSync<L> for &Callout {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <aside data-callout role="note">
                <strong>{self.label}</strong>
                <p>{self.body}</p>
            </aside>
        }
        .render(cx)
    }
}

impl<L: DataLoader> MdRenderSync<L> for &Callout {
    fn render_md(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        md_sync! { r###"
            > **{self.label}:** {self.body}
            "###
        }
        .render_md(cx)
    }
}
```

One value, rendered two ways:

```html filename="Accept: text/html"
<aside data-callout role="note"><strong>Note</strong><p>Cross-origin writes return 403.</p></aside>
```

```md filename="Accept: text/markdown"
> **Note:** Cross\-origin writes return 403\.
```

A component with no text form renders its content instead: a button becomes its label, a tab strip becomes its panels. The component decides, because it is the only thing that knows. See [Content negotiation](/docs/framework/content-negotiation) for serving both from one URL.

## Block boundaries: the contract that makes nesting safe

Markdown is whitespace-sensitive, which is what usually makes it uncomposable. A heading is only a heading at the start of a line, and a component cannot know what its previous sibling wrote.

A physically multiline raw template establishes block boundaries automatically:

```rust filename="src/components/section.rs"
impl<L: DataLoader> MdRenderSync<L> for Heading {
    fn render_md(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        md_sync! { r#"
            ## {self.0}
            "# }.render_md(cx)
    }
}
```

It writes only the newlines that are missing: two of these back to back produce one blank line, not four, and the first one in a document writes nothing.

```md filename="output"
Intro line.

## First

## Second
```

That is what lets any block component sit next to any other, in any order.

An ordinary-string template selects inline mode and adds no automatic paragraph boundaries. Explicit newlines, such as the one in `md_sync! { "- {item}\n" }`, remain output. Use an inline template for a label:

```rust filename="src/components/button/md.rs"
md_sync! { "{self.children}" }.render_md(cx)?;
```

The mode is selected when the template renders, not when it is constructed. Nested scopes restore their enclosing mode on success, error, and panic unwinding. Async `md!` also restores it when a pending render is dropped. No closure or manual `md_set_inline` restoration is needed. Partial bytes and boundary tracking remain live after failure; error cleanup adds no trailing boundary.

Block templates inside an inline scope are errors, including typed children in link labels and table cells. A directly rendered qualified block macro is rejected at compile time when detectable; other block children fail at render time before writing their boundary or body. Earlier prefix bytes remain. Supply an inline representation instead of silently flattening a block.

Raw-string hashes only control delimiting. All physically multiline raw literals select block mode, including `r"..."`; single-line raw literals select inline mode. Ordinary strings stay inline even when they contain newlines. Existing dedenting and authored whitespace are unchanged: only automatic boundaries are deduplicated, and an empty block can still establish a boundary after preceding prose. The line breaks directly after a slot at block position are boundaries too: written after inline text, skipped after a child that already ended its line or paragraph, so a block child on its own line keeps exactly one blank line after it.

Inline/block scopes restore rendering mode only. Do not restore a full `MdState` snapshot to clean up formatting: it would replace suffix tracking without undoing emitted bytes.

## Embedded HTML

Markdown permits inline HTML, but keep it on the typed HTML path instead of mixing an HTML parser into the Markdown macro:

```rust filename="src/components/callout.rs"
use proa::html_sync;

cx.render_html_in_md(html_sync! {
    <aside data-callout>
        <strong>{self.title}</strong>
    </aside>
})?;
```

`WebContext::render_html_in_md(...)` reuses the current loader, output, and request metadata while tracking Markdown boundaries. Its child receives an observed writer; custom HTML components used here must support generic `B: WriteBuf`. `html_sync!` applies the normal compile-time HTML validation and escaping rules.

> **Good to know**: Slots, children, and branching behave identically to the HTML macros. See [Components](/docs/core/components); everything there applies with `md_sync!` in place of `html_sync!`.

## Data loading

Markdown uses the same `DataLoader` API as HTML. An `MdRender<L>` implementation
can await `cx.load_typed(...)`, `cx.load_bytes(...)`, or `cx.load_json(...)`.
Start the root with `WebContext::with_loader(Arc::clone(&loader))`; nested
Markdown children and tracked HTML bridges keep that same loader instance.
`MdRenderSync<L>` can participate in the same tree, but cannot await a load.
See [Data loading](/docs/framework/data-loading) for request-scoped loaders.

For an async Axum route, return the plan from
`negotiate_async_with_loader(...)` or `explicit_markdown_async_with_loader(...)`.
The adapter creates the local render future during finalization, so the handler
can remain `Send` without requiring a `Send` Markdown render future.

## Streaming Markdown

Async Markdown roots can use the in-order stream driver from `proa_stream`:

```rust filename="src/pages/report.rs"
use std::rc::Rc;

use proa::StreamChunkFlusher;
use proa::stream::render_md_in_order_to_flusher;

let flusher: Rc<dyn StreamChunkFlusher> = Rc::new(MyMarkdownFlusher::new());

render_md_in_order_to_flusher(PageMd, flusher).await?;
```

The driver renders through the shared `WebContext` into the standard `RenderBuffer`, flushes through `StreamChunkFlusher`, and preserves Markdown-local state across `Suspense` boundaries. Pass an existing request loader with `render_md_in_order_to_flusher_with_loader(PageMd, loader, flusher)` when the page loads data.

Use it for `text/markdown` responses where a generated document should stream top to bottom instead of buffering the whole body first.

## Next steps

- [HTML rendering](/docs/core/html-rendering)
  - Render typed Rust values to HTML with render traits and the html! macros.
- [Components](/docs/core/components)
  - Nest components, pass children, and branch inside a render tree.
- [Streaming SSR](/docs/core/streaming-ssr)
  - Flush the page shell first and stream slow sections as they resolve.
- [Sink](/docs/core/sink)
  - Migrate deprecated page-pool writers to RenderBuffer.
- [Content negotiation](/docs/framework/content-negotiation)
  - Serve HTML and Markdown representations of one resource through HTTP content negotiation.


---

# Docs: WriteBuf

URL: /docs/core/write-buf
Description: Pick the buffer a route renders into.

---
title: WriteBuf
description: Pick the buffer a route renders into.
keywords: [WriteBuf, RenderBuffer]
---

All web rendering writes into a `WriteBuf`. The buffer controls allocation behaviour, capacity handling, and how the response is finalized.

Use `RenderBuffer` unless you have a reason not to.

```rust filename="src/pages/about.rs"
use proa::{WebContext, WebRenderSync};

let mut cx = WebContext::new();
page.render(&mut cx)?;
let html = cx.into_output().into_string();
```

## Choosing a buffer

| Buffer | Use when |
|--------|----------|
| `RenderBuffer` | Routes, tests, and adapters. The default. |
| `ZeroCopyBuf` | A custom transport experiment preserves large static byte slices. |
| `StreamingZeroCopyBuf` | You are building a manual checkpoint-based streaming response. |

`RenderBuffer` grows by chaining reusable 4 KB pages, never relocates bytes it has already written, and recycles pages after `clear()`.

For framework-managed streaming, see [Streaming SSR](/docs/core/streaming-ssr).

## Reusing a buffer

For a long-lived service, keep the writer request-local or worker-local and clear it between renders:

```rust filename="src/render_worker.rs"
use proa::{RenderBuffer, WebContext, WebRenderSync, WriteBuf};

pub struct RenderWorker {
    out: RenderBuffer,
}

impl RenderWorker {
    pub fn render_page<P>(&mut self, page: P) -> Result<&RenderBuffer, proa::WriteError>
    where
        P: WebRenderSync,
    {
        self.out.clear();
        let mut cx = WebContext::with_buffer(std::mem::take(&mut self.out));
        let result = page.render(&mut cx);
        self.out = cx.into_output();
        result?;
        Ok(&self.out)
    }
}
```

The caller flattens or streams the returned slices before the next `clear()`.

For most Axum handlers, creating a fresh `RenderBuffer` per request and calling `into_string()` is also fine. Reuse matters when profiling shows allocation churn in a high-throughput render loop.

> **Good to know**: Fixed-capacity writers and contiguous byte-vector helpers exist for low-level tests, benchmarks, and narrow adapters. Normal routes should not depend on guessing an output size.

## Context state

`WebContext` carries the output buffer plus request-scoped render state: escape mode and dialect, request metadata and route params, an optional data loader, streaming recorders and flushers, and RSJS island usage records.

Components treat `cx` as the place to render children and write output. Route and framework code choose the buffer and finalize the response.

When the render tree needs request-scoped data loading:

```rust filename="src/pages/blog.rs"
use std::sync::Arc;
use proa::WebContext;

let mut cx = WebContext::with_loader(Arc::new(loader));
```

## At the route boundary

`ZeroCopyBuf` stores large static template slices as static parts and dynamic bytes in an owned buffer. Reach for it only when a custom transport preserves scatter-gather response structure instead of flattening immediately:

```rust filename="src/pages/home.rs"
use proa::{WebContext, WebRenderSync, ZeroCopyBuf};

let mut cx = WebContext::with_buffer(ZeroCopyBuf::with_capacity(128, 16 * 1024));
page.render(&mut cx)?;
let out = cx.into_output();
```

This is the advanced custom-writer path: the page tree must explicitly support
`WebRenderSync<L, ZeroCopyBuf>`. If you flatten the result right away,
`RenderBuffer` and the default `WebRenderSync<L>` form are simpler.

Using `proa::axum` directly? Return `RouteResponse::ssr(Page)` from the handler to use the standard `RenderBuffer` path. See [Route responses](/docs/framework/responses).

Before you ship: use `RenderBuffer` for app routes and tests, call `render_static` first for docs routes, keep response finalization at the route boundary, and reach for zero-copy buffers only when the transport path actually uses them.

## Next steps

- [Sink](/docs/core/sink)
  - Migrate deprecated page-pool writers to RenderBuffer.
- [Route responses](/docs/framework/responses)
  - Return synchronous, buffered async, or streaming SSR with islands.
- [Streaming SSR](/docs/core/streaming-ssr)
  - Flush the page shell first and stream slow sections as they resolve.
- [Writing performant pages](/docs/guides/performance)
  - How to write zero-allocation Proa pages that render in microseconds. Covers format!() avoidance, SafeText, ClassList, numeric rendering, buffer selection, and pre-formatting patterns.


---

# Docs: Route responses

URL: /docs/framework/responses
Description: Return synchronous, buffered async, or streaming SSR.

---
title: Route responses
description: Return synchronous, buffered async, or streaming SSR.
---

Handlers return `RouteResponse` when they want Proa's framework finalizer to render a component and finalize the document.

Use ordinary Axum responses for JSON APIs, form handlers, early status codes, redirects, and handler-level errors. See [Route handlers](/docs/framework/route-handlers) for endpoint patterns and [Status, redirects, and errors](/docs/framework/errors) for 404 pages, response headers, streaming constraints, and public error bodies.

## Synchronous SSR

Use `RouteResponse::ssr` for ordinary `WebRenderSync` components.

```rust
use proa::axum::RouteResponse;

pub async fn handler() -> RouteResponse {
    RouteResponse::ssr(HomePage)
}
```

Write ordinary page components as `WebRenderSync<L>`; the framework supplies
the owned `RenderBuffer` response writer.

## Async SSR

Use `RouteResponse::ssr_async` for components that implement `WebRender` and do not use a loader. The full render completes before the response begins, so root errors, status, and headers remain available to the HTTP layer.

```rust
pub async fn handler() -> RouteResponse {
    RouteResponse::ssr_async(PageWithAwait)
}
```

For typed data loaders, return `impl IntoResponse` and pass the loader explicitly:

```rust
use std::sync::Arc;

pub async fn handler() -> impl axum::response::IntoResponse {
    let loader = Arc::new(MyLoader::new());
    RouteResponse::ssr_async_with_loader(Page, loader)
}
```

Prefer typed loaders when the concrete loader type is known. Use the `*_dyn` constructors only at real dynamic boundaries.

See [Data loading and streaming](/docs/framework/data-loading) for loader keys, cache hints, request-local dedupe, and preloading.

## Streaming SSR

Use `ssr_stream` or `ssr_stream_with_loader` when the page should flush work incrementally.

```rust
pub async fn handler() -> impl axum::response::IntoResponse {
    let loader = Arc::new(MyLoader::new());
    RouteResponse::ssr_stream_with_loader(StreamedPage, loader)
}
```

Streaming responses default to out-of-order chunked rendering. Use `with_render_mode` when a route needs a different render mode.

Use [Data loading and streaming](/docs/framework/data-loading) for `Suspense` boundaries, `PreparedLoader`, and streamed data patterns.

`RouteResponse::ssr_stream*` is the HTML response surface. For generated `text/markdown` responses, use `proa::stream::render_md_in_order_to_flusher` or `InOrderMarkdownDriver` from a custom handler/adapter and set the response content type yourself. See [Streaming Markdown Output](/docs/framework/data-loading#streaming-markdown-output).

## Responses outside the render pipeline

Already-rendered HTML is an ordinary HTTP response, not a render plan. Return Axum's `Html` response directly:

```rust
use axum::response::Html;

pub async fn handler() -> Html<&'static str> {
    Html("<main>Already rendered</main>")
}
```

If a compile-time HTML fragment must participate in Proa finalization or browser navigation, treat it as a renderable node instead of a response kind:

```rust
RouteResponse::ssr(proa::static_html(b"<main>Static fragment</main>"))
```

Serve browser-rendered applications through Axum file services and configure their fallback routing explicitly. `RouteResponse` handles deferred server rendering.

## Rendering without a server

`RouteResponse::render_to_bytes` finalizes a response into one HTML document with no HTTP server, no island manifest, and no async runtime. It applies the same managed head and RSJS runtime tags the Axum adapter would, so static exports, snapshot tests, and plain `fn main` programs render the exact bytes a route serves.

```rust filename="src/main.rs"
use proa::HeadConfig;
use proa::framework::RouteResponse;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let html = RouteResponse::ssr(RootDocument { children: HomePage })
        .with_head(HeadConfig::default())
        .render_to_bytes()?;
    std::fs::write("./output/index.html", html)?;
    Ok(())
}
```

`render_to_string` returns the same document as a `String`, and the `proa::axum::RouteResponse` wrapper exposes both methods. What differs from a served request:

- Async plans render buffered. `Suspense` content appears inline rather than as a fallback plus a later swap, and the streaming driver is never involved.
- There is no request. The base path is the origin root, route parameters are absent, and `render_metadata_head` resolves to nothing. Pages that read those should go through the built router with `tower::ServiceExt::oneshot`.
- Headers are discarded, and a status outside 2xx is returned as `FrameworkError::StaticStatus` instead of being written out as a page.
- Call it from synchronous code. Inside async code, await `into_framework_response`; an async plan called from a current-thread tokio runtime returns `FrameworkError::StaticRenderInsideRuntime` rather than deadlocking.

Programs that only render this way can depend on `proa_framework_core` with `default-features = false`, which leaves tokio out of the build. Eager `proa_stream` preloads need a tokio runtime and are the one feature that does not work there.


---

# Docs: Streaming SSR

URL: /docs/core/streaming-ssr
Description: Flush the page shell first and stream slow sections as they resolve.

---
title: Streaming SSR
description: Flush the page shell first and stream slow sections as they resolve.
keywords: [Suspense, streaming, out-of-order]
---

Streaming sends the parts of a page that are ready before the parts that are not. The reader sees the shell immediately; a slow section arrives when its data resolves.

Wrap the slow part in `Suspense` and give it a fallback:

```rust filename="src/pages/product.rs"
html! {
    <main>
        <h1>{self.product.name}</h1>
        {Suspense::new(
            Reviews { id: self.product.id },
            html_sync! { <div class="skeleton" /> },
        )}
    </main>
}
```

Ready shell bytes can flush while the boundary remains pending. If the child suspends in out-of-order mode, the fallback appears until its content arrives. Managed documents first complete their metadata preparation.

## When streaming helps

Streaming can reduce time to the first useful content while independent work continues. It helps when one section is meaningfully slower than the rest of the page, and hurts when you split a page that was already fast.

| Situation | Do this |
|---|---|
| One slow query, rest of the page is cheap | Wrap the slow section in `Suspense` |
| Every section is slow | Fix the data layer first; streaming will not hide it |
| The whole page is fast | Prefer a buffered response; streaming adds scheduling and framing work. |
| The consumer does not execute JavaScript | Use buffered or in-order HTML so resolved content is available without swaps. |

With managed metadata enabled, Proa runs layout and Page head hooks before publishing the response head. Make status, cookie, redirect, and cache decisions in the handler or those hooks. Publication requires both the sealed Page metadata and the head outlet; body work streams afterward. Manual streaming documents commit headers before rendering begins. See [Metadata and streaming](/docs/framework/metadata#metadata-and-streaming) and [Status, redirects, and errors](/docs/framework/errors).

## Returning a streaming response

Use the framework response helpers rather than driving the stream yourself:

```rust filename="src/pages/product.rs"
use proa::axum::RouteResponse;

RouteResponse::ssr_stream(ProductPage { id })
```

The framework installs the stream recorder and the chunk flusher, then renders the root through them. [Route responses](/docs/framework/responses) covers the full set of constructors.

## In-order and out-of-order

Two boundaries on one page, one slow and one fast:

```rust filename="src/pages/product.rs"
html! {
    <main>
        <h1>"Product"</h1>
        {Suspense::new(Reviews { id }, html_sync! {
            <p>"loading reviews"</p>
        })}
        {Suspense::new(Stock { id }, html_sync! {
            <p>"loading stock"</p>
        })}
    </main>
}
```

Reviews takes 40 ms and comes first in the document. Stock takes 5 ms and comes second. The two modes resolve that conflict differently:

```text
time ─────────────────────────────────────────────────────────────►
                 0 ms            5 ms                        40 ms

out-of-order     shell           stock                       reviews
                 flushed         sent the moment             sent when it
                                 it resolves                 resolves

in-order         shell                                       reviews, stock
                 flushed                                     stock was ready at
                                                             5 ms and waited
```

Out-of-order sends each boundary as it resolves. In-order preserves document order, so a slow boundary holds up every boundary behind it.

That difference is visible on the wire. Out-of-order writes the fallback between comment markers, then sends each boundary later as a `<template>` plus a one-line swap call:

```html filename="out-of-order (default)"
<main><h1>Product</h1><!--proa:start:1--><p>loading reviews</p><!--proa:end:1--><!--proa:start:2--><p>loading stock</p><!--proa:end:2--></main>
<script>/* $proa swap runtime, sent once */</script>
<template id="proa-tpl-2" data-proa-encoding="base64-v1">…stock…</template><script>$proa(2);</script>
<template id="proa-tpl-1" data-proa-encoding="base64-v1">…reviews…</template><script>$proa(1);</script>
```

Boundary `2` arrives before boundary `1`: stock was second in the document and first on the wire. The swap script replaces the marked region and dispatches `proa:boundary-ready`.

In-order writes the resolved content inline, in document order, and emits nothing else:

```html filename="in-order"
<main><h1>Product</h1><section>reviews</section><section>stock</section></main>
```

No markers, no templates, no script. That is the whole response.

| | In-order | Out-of-order |
|---|---|---|
| Arrival | Document order | Readiness order |
| A slow boundary | Blocks the ones behind it | Blocks nothing |
| Client JavaScript | None | One small swap script |
| `priority` and `timeout` | Ignored | Honored |
| Output equals the buffered render | Yes | Yes, after the swaps run |

Out-of-order is the default for `ssr_stream`. Ask for the other one explicitly:

```rust filename="src/pages/product.rs"
use proa::RenderMode;

RouteResponse::ssr_stream(ProductPage { id })
    .with_render_mode(RenderMode::ChunkedInOrder)
```

Choose in-order when the reader must not depend on JavaScript, or when the response is consumed by something that reads bytes in order rather than executing a document. Choose out-of-order, the default, for a browser page where one section is much slower than the rest.

For generated `text/markdown`, the choice does not arise: Markdown is always in-order, because a swap script cannot run in a text document. `proa::stream::render_md_in_order_to_flusher` drives it. See [Markdown rendering](/docs/core/markdown).

## Priority and timeouts

`Suspense` carries two scheduling options. Both are struct fields:

```rust filename="src/pages/product.rs"
use std::time::Duration;
use proa::Priority;
use proa::stream::Suspense;

Suspense {
    child: Recommendations { id },
    fallback: html_sync! {
        <p>"loading recommendations"</p>
    },
    priority: Priority::Defer,
    timeout: Some(Duration::from_millis(200)),
}
```

`Priority` orders boundaries that become ready in the same turn: `Critical` (the default), then `Optional`, then `Defer`. `timeout` bounds how long the driver waits before it gives up, cancels the future, keeps the fallback on screen, and emits `<!--proa:timeout:N-->` for observability.

Both are out-of-order features. In-order, static, and Markdown renders ignore them by design: reordering would violate their wire contract, and cancelling a child that has already flushed would leave partial markup on the wire.

## Where the data comes from

This page is about delivery. Getting the data into a boundary is [Data loading and streaming](/docs/framework/data-loading), and the two meet at one constructor:

```rust filename="src/pages/product.rs"
RouteResponse::ssr_stream_with_loader(ProductPage { id }, loader)
```

Loading through `WebContext` is what lets independent boundaries overlap instead of running one after another, and request-local dedupe keeps two boundaries that need the same record from fetching it twice. If a page streams but every boundary waits on the same serial query, the data layer is the problem and streaming will not hide it.

## What happens underneath

Three pieces cooperate, and you rarely name any of them directly:

| Piece | Role |
|---|---|
| `Suspense` | Marks the boundary and holds the fallback |
| `RenderBuffer` | Buffers boundary bytes in pages the context owns and recycles |
| `StreamChunkFlusher` | Hands ordered chunks to the transport |

In-order boundaries flush and reuse the parent `RenderBuffer`, so a page with twenty boundaries renders through one recycled buffer. Out-of-order gives each detached boundary its own `RenderBuffer` and flattens it once when the chunk is framed. [Sink](/docs/core/sink) documents the legacy pool-backed writer these replaced.

For manual checkpoint control without a page pool, `StreamingZeroCopyBuf` flushes complete parts and never half-written dynamic content. Normal routes should not manage checkpoints by hand.

> **Good to know**: A reverse proxy can cache a completed streamed HTML response when its policy permits it. Set cache headers before streaming begins, and check the proxy's buffering behavior: cached delivery need not preserve the origin's chunk timing. Loader caching remains useful on cache misses and private routes. See [Page caching](/docs/framework/page-caching).

## Next steps

- [Loading data and streaming](/docs/framework/data-loading)
  - Load request data, apply cache hints, dedupe repeated loads, and stream slow page sections with Suspense.
- [Sink](/docs/core/sink)
  - Migrate deprecated page-pool writers to RenderBuffer.
- [Route responses](/docs/framework/responses)
  - Return synchronous, buffered async, or streaming SSR with islands.
- [Markdown rendering](/docs/core/markdown)
  - Render typed Rust values to Markdown for docs, feeds, and agents.
- [Page caching](/docs/framework/page-caching)
  - Cache public HTML and static assets at browsers and CDNs.


---

# Docs: Sink

URL: /docs/core/sink
Description: Migrate deprecated page-pool writers to RenderBuffer.

---
title: Sink
description: Migrate deprecated page-pool writers to RenderBuffer.
---

The deprecated page-pool writer has been removed. Use `RenderBuffer`, which owns
and recycles its pages, for synchronous, asynchronous, and streaming rendering.
See [WriteBuf](/docs/core/write-buf) and [Streaming SSR](/docs/core/streaming-ssr).

Custom transport adapters can still implement `StreamChunkFlusher` or
`SendStreamChunkFlusher`; those transport boundaries remain supported.


---

# Docs: Routing

URL: /docs/framework/routing
Description: Register an Axum route, render a Page, and read request parameters through cx.

---
title: Routing
sidebar_title: Routing
description: Register an Axum route, render a Page, and read request parameters through cx.
---

## Register a route

Start with an Axum `Router`. This route sends `/shop/products/42` to the `product` handler:

```rust filename="Routes"
use axum::{routing::get, Router};

let routes = Router::new()
    .route("/shop/products/:id", get(product));
```

The handler composes the document, shared shop layout, and selected Page:

```rust filename="Product handler"
use proa::axum::RouteResponse;
use crate::{layouts::{RootDocument, ShopLayout}, pages::ProductPage};

async fn product() -> RouteResponse {
    RouteResponse::ssr(RootDocument {
        children: ShopLayout {
            children: ProductPage,
        },
    })
}
```

![The file tree and explicitly composed layouts lead to one selected Page.](/static/images/docs/nested-layouts.svg?v=2)

`RootDocument` and `ShopLayout` declare `const ROLE: ComponentRole = ComponentRole::LAYOUT`; `ProductPage` declares `PAGE`. See [Layouts and Pages](/docs/framework/layouts-and-pages) for their full implementations and document markup.

### Install the router

Pass the router to `FrameworkBuilder`. Enable managed metadata with `with_head`:

```rust filename="App configuration"
use proa::{HeadConfig, HeadUrlPolicy};
use proa::axum::FrameworkBuilder;

let head = HeadConfig::default()
    .with_urls(HeadUrlPolicy::new("https://acme.example", "/")?);

let app = FrameworkBuilder::new()
    .with_head(head)
    .with_dynamic_routes(routes)
    .build();
```

Use your configured public origin in place of `https://acme.example`. The framework makes Axum's matched path parameters available through `cx` before head and body rendering.

## Read route parameters from cx

A segment beginning with `:` captures a path value:

| Route | Request | Read through cx |
| --- | --- | --- |
| `/shop/products/:id` | `/shop/products/42` | `cx.param("id")` → `Some("42")` |
| `/blog/:slug` | `/blog/red-shoes` | `cx.param("slug")` → `Some("red-shoes")` |

These are URL patterns, registered explicitly; Rust filenames organize the source code.

Here is the `ProductPage` used above. It reads the same `id` in its head and body:

```rust filename="src/pages/product.rs"
use proa::{
    ComponentRole, DataLoader, SyncHeadOperation, WebContext, WebRenderSync,
    WriteError,
};
use proa::html_sync;

pub struct ProductPage;

impl<L: DataLoader> WebRenderSync<L> for ProductPage {
    const ROLE: ComponentRole = ComponentRole::PAGE;

    fn render_head(&self, cx: &mut WebContext<L>) -> impl SyncHeadOperation {
        let id = cx.param("id")
            .ok_or_else(|| WriteError::render("missing product id"))?;
        let title = format!("Product {id}");
        cx.head_mut().title(title)
    }

    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let params = cx.route_params().cloned().unwrap_or_default();
        let id = params.get("id")
            .ok_or_else(|| WriteError::render("missing product id"))?;

        html_sync! {
            <main data-product-page>
                <h1>"Product "{id}</h1>
            </main>
        }
        .render(cx)
    }
}
```

`cx.param(name)` returns `Option<&str>`. `cx.route_params()` exposes the shared collection. Clone that handle before rendering when the template needs to borrow a parameter while writing through `cx`; this does not copy parameter strings.

For `/shop/products/42`, `ShopLayout`'s `title_template("%s | Shop")` formats the Page's dynamic title:

```html filename="Selected output"
<title>Product 42 | Shop</title>
<main data-product-page><h1>Product 42</h1></main>
```

The title goes in the document head and `<main>` in its body. Title templates work the same for `:id` and `:slug`: the Page supplies its title, often from a loader, and the nearest ancestor template formats it. A slug is not automatically turned into a display title. See [Load metadata from data](/docs/framework/metadata#load-metadata-from-data) for an async example.

### Query strings

Path captures and query strings are separate:

```rust filename="Inside a render method or head hook"
let path = cx.request_location().map(|location| location.path());
let query = cx.request_location().and_then(|location| location.query());
```

For `/shop/products/42?currency=usd`, these return `Some("/shop/products/42")` and `Some("currency=usd")`. `query()` returns the raw query string. Use a query parser or Axum's typed `Query` extractor for decoded fields.

## Add and nest routes

Chain `.route(...)` calls to add Pages. Use Axum's `.nest(...)` to share a URL prefix:

```rust filename="More routes"
let shop = Router::new()
    .route("/", get(shop_index))
    .route("/products/:id", get(product));

let routes = Router::new()
    .route("/about", get(about))
    .nest("/shop", shop);
```

This registers `/about`, `/shop`, and `/shop/products/:id`; Axum maps the nested `/` route to the prefix itself. Each handler explicitly composes its layout and Page. URL nesting does not add HTML wrappers.

### Route specifications

Use Proa's `Route::endpoint` when you also need route modes, static-path declarations, or route-specification metadata. It produces an Axum router you can merge with the rest of the app:

```rust filename="Route specification"
use proa::axum::{Route, RouteMode};

let routes = Router::new().merge(
    Route::endpoint("/shop/products/:id", get(product))
        .with_route_mode(RouteMode::Server)
        .into_router(),
);
```

`Server`, `Static`, and `ClientBrowser` describe routes to tooling; they do not set component roles or compose layouts. The older `Route::layout` and `Route::page` APIs describe route metadata independently of `render_head`. See [metadata migration](/docs/framework/metadata#existing-metadata-code) when updating those documents.

## Next steps

- [Layouts and Pages](/docs/framework/layouts-and-pages): document markup, component roles, and nesting.
- [Metadata and OG images](/docs/framework/metadata): dynamic titles, defaults, and social images.
- [Route handlers](/docs/framework/route-handlers): JSON, forms, and non-page endpoints.
- [Linking and navigating](/docs/framework/linking): public URLs and mount prefixes.


---

# Docs: Layouts and Pages

URL: /docs/framework/layouts-and-pages
Description: Create role-marked Pages, compose shared layouts, and connect them to routes.

---
title: Layouts and Pages
description: Create role-marked Pages, compose shared layouts, and connect them to routes.
---

A **Page** is the selected content for a document. A **layout** wraps that content with shared UI and metadata defaults. Both are ordinary render components; declare their intent with `const ROLE` on the render-trait implementation.

| Component | Role | Metadata lifecycle |
| --- | --- | --- |
| Shared layout | `ComponentRole::LAYOUT` | Contribute defaults; render the child with metadata still open. |
| Selected Page | `ComponentRole::PAGE` | Finalize metadata before rendering its own body. |
| Ordinary body component | `ComponentRole::COMPONENT` (default) | Skip head invocation entirely. |

![Source files and two nested LAYOUT components around one selected PAGE.](/static/images/docs/nested-layouts.svg?v=2)

The router selects a handler. The handler composes the layout and Page. Rust filenames organize the code; URLs are registered explicitly. See [Routing](/docs/framework/routing) for route patterns and request parameters.

## Create a Page

Declare `PAGE` even when a Page inherits all of its metadata. This example accepts its content through props and uses the same title in the head and body:

![A Rust Page component is selected by a registered route and renders the page's main content.](/static/images/docs/page-and-route.svg?v=2)

```rust filename="src/pages/content.rs"
use proa::{
    ComponentRole, DataLoader, SyncHeadOperation, WebContext, WebRenderSync,
    WriteError,
};
use proa::html_sync;

pub struct ContentPage {
    pub title: &'static str,
    pub message: &'static str,
}

impl<L: DataLoader> WebRenderSync<L> for ContentPage {
    const ROLE: ComponentRole = ComponentRole::PAGE;

    fn render_head(&self, cx: &mut WebContext<L>) -> impl SyncHeadOperation {
        cx.head_mut().title(self.title)
    }

    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <main data-content-page>
                <h1>{self.title}</h1>
                <p>{self.message}</p>
            </main>
        }
        .render(cx)
    }
}
```

The Page renders inside a managed document, configured below. Its `render_head` completes before its `render` body starts. A Page with no hook still declares `PAGE` and seals inherited metadata.

These first examples use `WebRenderSync` and `html_sync!` because they do not await data. [Async Pages and layouts](#async-pages-and-layouts) use the same roles.

## Create a root layout

A root layout owns the document's `<html>`, `<head>`, and `<body>`. Put `{cx.head()}` at the position where generated metadata belongs, then render the child through the template.

![RootDocument declares LAYOUT, owns the document and head outlet, and wraps a ContentPage declaring PAGE.](/static/images/docs/layout-and-page.svg)

```rust filename="src/layouts/root.rs"
use proa::{
    ComponentRole, DataLoader, SyncHeadOperation, WebContext, WebRenderSync,
    WriteError,
};
use proa::html_sync;

pub struct RootDocument<C> {
    pub children: C,
}

impl<L, C> WebRenderSync<L> for RootDocument<C>
where
    L: DataLoader,
    C: WebRenderSync<L>,
{
    const ROLE: ComponentRole = ComponentRole::LAYOUT;

    fn render_head(&self, cx: &mut WebContext<L>) -> impl SyncHeadOperation {
        cx.head_mut().title("Acme")?;
        cx.head_mut().title_template("%s | Acme")?;
        cx.head_mut().description("News and products from Acme.")?;
        Ok(())
    }

    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <!DOCTYPE html>
            <html lang="en" data-root-document>
                <head>
                    <meta charset="utf-8" />
                    <meta name="viewport" content="width=device-width, initial-scale=1" />
                    {cx.head()}
                </head>
                <body>
                    <header>
                        <a href={cx.url("/")}>"Acme"</a>
                    </header>
                    {self.children}
                </body>
            </html>
        }
        .render(cx)
    }
}
```

The layout supplies a default title and description. Its title template applies to descendant titles. The selected Page can override the description or any other field it writes. Charset and viewport are manual tags in the template.

Use template composition for children. A raw `self.children.render(cx)` call invokes only the child's body and skips lifecycle dispatch.

## Connect Pages to routes

Re-export the components from your `pages` and `layouts` modules. Each handler chooses the tree it renders. The same Page component can serve different routes with different props:

```rust filename="src/app.rs"
use axum::{routing::get, Router};
use proa::{HeadConfig, HeadUrlPolicy, WriteError};
use proa::axum::{FrameworkBuilder, RouteResponse};
use crate::{layouts::RootDocument, pages::ContentPage};

async fn home() -> RouteResponse {
    RouteResponse::ssr(RootDocument {
        children: ContentPage {
            title: "Home",
            message: "Welcome to Acme.",
        },
    })
}

async fn about() -> RouteResponse {
    RouteResponse::ssr(RootDocument {
        children: ContentPage {
            title: "About",
            message: "Meet the people behind Acme.",
        },
    })
}

pub fn app() -> Result<Router, WriteError> {
    let routes = Router::new()
        .route("/", get(home))
        .route("/about", get(about));
    let head = HeadConfig::default()
        .with_urls(HeadUrlPolicy::new("https://acme.example", "/")?);

    Ok(FrameworkBuilder::new()
        .with_head(head)
        .with_dynamic_routes(routes)
        .build())
}
```

Use your configured public origin in place of `https://acme.example`. `FrameworkBuilder::with_head` enables managed metadata for rendered routes.

A request to `/about` selects the `about` handler, composes `RootDocument → ContentPage`, and produces this head:

```html filename="Generated head for /about"
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>About | Acme</title>
<meta name="description" content="News and products from Acme.">
```

There is one document, one head outlet, and one selected Page. Components declaring `LAYOUT` or `PAGE` require managed rendering, even without a head hook. They cannot render through a plain `WebContext::new()` or a `.without_head()` response.

## Nest layouts

A layout can render another layout as its child. This shop layout adds shared navigation and supplies a nearer title template:

```rust filename="src/layouts/shop.rs"
use proa::{
    ComponentRole, DataLoader, SyncHeadOperation, WebContext, WebRenderSync,
    WriteError,
};
use proa::html_sync;

pub struct ShopLayout<C> {
    pub children: C,
}

impl<L, C> WebRenderSync<L> for ShopLayout<C>
where
    L: DataLoader,
    C: WebRenderSync<L>,
{
    const ROLE: ComponentRole = ComponentRole::LAYOUT;

    fn render_head(&self, cx: &mut WebContext<L>) -> impl SyncHeadOperation {
        cx.head_mut().title_template("%s | Shop")?;
        cx.head_mut().description("Explore the Acme shop.")?;
        Ok(())
    }

    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <section data-shop-layout>
                <nav aria-label="Shop">
                    <a href={cx.url("/shop")}>"Products"</a>
                </nav>
                {self.children}
            </section>
        }
        .render(cx)
    }
}
```

Compose the nesting in a handler. Re-export `ShopLayout` from your `layouts` module first:

```rust filename="Shop handler"
use crate::layouts::ShopLayout;

async fn shop() -> RouteResponse {
    RouteResponse::ssr(RootDocument {
        children: ShopLayout {
            children: ContentPage {
                title: "Products",
                message: "Find your next everyday essential.",
            },
        },
    })
}
```

Register it with `.route("/shop", get(shop))`. The explicitly composed tree is `RootDocument → ShopLayout → ContentPage`:


```html filename="Generated title and description"
<title>Products | Shop</title>
<meta name="description" content="Explore the Acme shop.">
```

The nearest ancestor template applies once: the title uses `Shop`. The Page seals metadata after its hook; the layouts remain ancestors around its body. Ordinary cards, buttons, and islands inside the Page keep the default `COMPONENT` role.

These examples render the composed tree on each server request. Keep interactive behavior in RSJS islands inside the selected Page.

## Async Pages and layouts

When a head or body needs to await data, implement `WebRender<L>` and use `html!` for asynchronous child composition. An async head hook returns `Result` directly:

```rust filename="Inside a Page's WebRender<L> implementation"
const ROLE: ComponentRole = ComponentRole::PAGE;

async fn render_head(&self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
    let key = LoadKey::named(
        "product",
        cx.param("id").ok_or_else(|| WriteError::render("missing product id"))?,
    );
    let product = cx.load_typed::<Product>(key).await?;
    cx.head_mut().title(product.name.clone())?;
    Ok(())
}
```

Use a `WebRender` layout around an async Page, keeping `ROLE = LAYOUT` on that implementation. A sync-only child inside an async tree uses `to_async(child)`. A synchronous Page uses `RouteResponse::ssr`; an async-capable tree uses `ssr_async` or `ssr_stream`.

The [metadata guide](/docs/framework/metadata) covers async document templates, request-scoped loader reuse, and social images. [Routing](/docs/framework/routing#read-route-parameters-from-cx) shows how the route above supplies `cx.param("id")`.

## Roles are explicit

Declaring `PAGE` or `LAYOUT` controls metadata lifecycle; it does not register a URL or wrap another component automatically. A Page still needs `PAGE` when it has no head hook. A layout above it uses `LAYOUT`. There must be exactly one selected Page in each managed document.

These rules apply equally to sync, async, Send, `to_async`, and `to_send` rendering. A `LAYOUT` must be above the selected Page; it is rejected after metadata seals or inside Suspense, captures, and fallbacks, even when its hook is the default no-op. A visual wrapper used inside a Page or in a manual document keeps the default `COMPONENT` role.

Run `cargo proa lint <changed-paths> --deny warnings` to catch head overrides with missing roles or an explicit `COMPONENT` role. Native async hooks rely on this source check; synchronous hooks also retain a code-generation role assertion, so build those implementations too.

Proa also has a route-metadata `Layout` trait and `Route::layout` constructor. They describe metadata in a route specification; they do not compose the rendered HTML or replace these component roles. [Route specifications](/docs/framework/routing#route-specifications) explains when to use them.

## Next steps

- [Routing](/docs/framework/routing): URL patterns, nesting, and request parameters.
- [Metadata and OG images](/docs/framework/metadata): head mutations and generated HTML.
- [HTML rendering](/docs/core/html-rendering): synchronous and async composition.
- [Linking and navigating](/docs/framework/linking): public URLs and mount prefixes.


---

# Docs: Linking and navigating

URL: /docs/framework/linking
Description: Navigate between Proa pages with anchors, optional prefetching, and Turbo Drive.

---
title: Linking and navigating
description: Navigate between Proa pages with anchors, optional prefetching, and Turbo Drive.
---

Use an anchor tag.

```rust filename="src/components/nav.rs"
html_sync! {
    <nav>
        <a href="/blog">"Blog"</a>
        <a href="/about">"About"</a>
    </nav>
}
```

There is no `<Link>` component or client router to configure. Proa pages are server-rendered HTML, so normal document navigation is the baseline. Prefetching and Turbo Drive are optional enhancements to those same anchors; neither changes your routes.

## Deployments under a path prefix

When serving behind a prefix-stripping proxy, configure a runtime base path and
use `cx.url("/blog")` for your anchors, forms, and asset attributes:

```rust filename="src/components/nav.rs"
let blog = cx.url("/blog");
let about = cx.url("/about");
html_sync! {
    <nav>
        <a href={blog}>"Blog"</a>
        <a href={about}>"About"</a>
    </nav>
}
.render(cx)
```

`cx.url(...)` explicitly applies the configured base path and writes directly
into the output buffer without an intermediate `String`. Plain URL strings
stay unchanged. External URLs, protocol-relative URLs, document-relative paths,
queries, and fragments pass through the helper unchanged. Pass an unprefixed
application path so the base path is applied once.

This also works in streamed components. In an Axum handler, use
`Redirect::to(&proa::axum::app_url("/").to_string())` for an
application-root redirect. See [URL prefix deployments](/docs/framework/deployment#serving-behind-a-url-path-prefix)
for startup configuration and island asset serving.

## Why there is no Link component

Client-side routing avoids a full document reload, but it does not eliminate network requests for server data. Proa keeps routing and rendering on the server, where a route can return useful HTML immediately.

A framework-specific link and router add a JavaScript bundle, a scroll and focus restoration model to get right, and a second source of truth for what page you are on.

A plain anchor has none of that, and it works before JavaScript loads, with JavaScript disabled, and in a crawler.

| You want | Do this |
|---|---|
| Navigate to another page | `<a href="/path">` |
| Prefetch a likely next page | `<link rel="prefetch" href="/path">` |
| Add SPA-like page transitions | Add Turbo Drive; keep the same anchors and routes |
| Restore scroll on back/forward navigation | Browser history restoration, or the navigation library's restoration policy |
| Show progress on a slow page | Stream it. See [Streaming SSR](/docs/core/streaming-ssr) |
| Update the URL without navigating | RSJS history helpers, below |
| Preserve state across a navigation | Reconsider, that state probably belongs in the URL |

> **Good to know**: Prefetching and Turbo can make the transition feel faster, but they do not make slow server work disappear. Stream a slow section so the destination can return its shell immediately.

## Prefetching a likely next page

For a high-confidence next destination, add a document prefetch hint to the current page's `<head>`:

```rust filename="src/app/layout.rs" {4}
html_sync! {
    <html lang="en">
        <head>
            <link rel="prefetch" href="/checkout" />
        </head>
        <body>{content}</body>
    </html>
}
```

This is a low-priority browser hint, not a Proa-specific navigation system. The browser may ignore it, and cache headers on the response affect whether the prefetched document can be reused. Use it for a small number of likely, same-site destinations rather than every link. A prefetch is a real `GET` request, so `GET` routes must remain safe and free of side effects.

## SPA-like navigation with Turbo Drive

[Turbo Drive](https://turbo.hotwired.dev/handbook/drive) is not bundled with Proa. It is a backend-agnostic progressive enhancement that works with Proa's existing HTML responses. It intercepts eligible same-origin links, fetches the destination document, replaces the `<body>`, merges the `<head>`, and updates browser history. The server still owns routing and renders every destination; if JavaScript is unavailable, the anchors continue to perform normal document navigation.

Install Turbo and import it once from your browser entry module:

```shell
pnpm add @hotwired/turbo
```

```javascript filename="src/client.js"
import "@hotwired/turbo";
```

Bundle that entry module with your application's JavaScript and load it from the document `<head>`. Importing Turbo starts Drive; Proa routes and anchor markup do not need to change.

Turbo 8 prefetches eligible links shortly after hover by default. You can preload a particularly important destination when the page loads, disable hover prefetch for an expensive destination, or opt a link out of Turbo entirely:

```rust filename="src/components/nav.rs" {3-5}
html_sync! {
    <nav>
        <a href="/dashboard" data-turbo-preload>"Dashboard"</a>
        <a href="/reports" data-turbo-prefetch="false">"Reports"</a>
        <a href="/downloads/archive.zip" data-turbo="false">"Download archive"</a>
    </nav>
}
```

Turbo changes the page lifecycle, so custom browser code that runs after every navigation should listen for `turbo:load` instead of only `DOMContentLoaded`. Keep the application bundle in `<head>`. RSJS observes detached island roots and tears down their resources when Turbo replaces the body; the destination response's body scripts hydrate its new islands. Test any state you intentionally preserve across forward, back, and cached Turbo visits. See Turbo's [installation](https://turbo.hotwired.dev/handbook/installing) and [application lifecycle](https://turbo.hotwired.dev/handbook/building) guidance for the integration details.

## Updating the URL from an island

Filtering, sorting, and tab state belong in the URL so they survive a reload and a shared link. RSJS exposes the browser history API for exactly this:

```rust filename="src/components/sort_products.rs"
use rsjs::{event_handler, rsjs};

let sort_ascending = event_handler(|_: rsjs::MouseEvent<rsjs::elem::Button>| {
    rsjs::history::push_state("?sort=asc");
});
```

| Helper | Effect |
|---|---|
| `history::push_state(url)` | Adds a history entry. The user can go back |
| `history::replace_state(url)` | Replaces the current entry. No back step |
| `history::back()` / `history::forward()` | Moves through the stack |
| `history::go(delta)` | Jumps by a relative offset |

Use `push_state` when the change is a place the user might want to return to, and `replace_state` when it is a correction to where they already are.

None of these fetch anything. They update the address bar; the page keeps whatever the server already rendered. To reflect new data, refetch it with a [query](/docs/rsjs/queries-mutations).

## Linking to another origin

Add `rel="noopener noreferrer"` whenever you open a new tab:

```rust filename="src/components/external.rs"
html_sync! {
    <a href="https://example.com" target="_blank" rel="noopener noreferrer">"Docs"</a>
}
```

Modern browsers imply `noopener` for `target="_blank"`. Writing it explicitly
keeps the policy visible; `noreferrer` also suppresses the Referer header, which
you can omit when referral information is wanted. See [MDN: noopener](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/rel/noopener)
and [Escaping and raw HTML](/docs/core/escaping).

## Next steps

- [Routes and layouts](/docs/framework/routing)
  - Define route trees, layouts, and static paths.
- [Streaming SSR](/docs/core/streaming-ssr)
  - Flush the page shell first and stream slow sections as they resolve.
- [Queries and mutations](/docs/rsjs/queries-mutations)
  - Seed browser queries from server-rendered data, refetch them, and run invalidating mutations.
- [Browser APIs](/docs/rsjs/browser-apis)
  - Reach browser capabilities through the analyzed RSJS surface.


---

# Docs: Route handlers

URL: /docs/framework/route-handlers
Description: Build JSON, form, and webhook endpoints with Route::endpoint.

---
title: Route handlers
description: Build JSON, form, and webhook endpoints with Route::endpoint.
---

Proa does not invent a second request-handler model: a route handler is an Axum handler, and `Route::endpoint` registers routes that need no page metadata. This page covers [registering an endpoint](#registering-an-endpoint), [returning JSON](#returning-json), [handling forms](#handling-forms), [sharing application state](#sharing-application-state), and [the security defaults](#what-do-endpoints-inherit-from-the-framework) every endpoint inherits.

## Registering an endpoint

Use route handlers for:

- JSON APIs consumed by islands or external clients
- form submissions and mutations
- webhooks and machine-to-machine callbacks
- health checks, [robots.txt](/docs/framework/robots), [sitemaps](/docs/framework/sitemaps), and downloads
- redirects and canonical URL handlers

Use ordinary Axum `.route(...)` calls for handlers. Use `Route::endpoint` when you also need Proa route specifications, such as page-cache policy. Document layouts and metadata belong to the rendered components' `ROLE` and `render_head`, independently of route registration.

`Route::endpoint` accepts an Axum `MethodRouter`, so compose methods exactly as you would in Axum:

```rust filename="src/routes/mod.rs"
use axum::{routing::{get, post}, Router};
use proa::axum::{router_from_spec, Route};

let (router, metadata) = router_from_spec(vec![
    Route::endpoint("/api/search", get(search).post(search_post)),
    Route::endpoint("/contact", post(submit_contact)),
    Route::endpoint("/healthz", get(healthz)),
]);
let router = Router::new().route("/", get(home_page)).merge(router);
```

Pass `router` and `metadata` to `FrameworkBuilder::with_dynamic_routes_and_metadata(...)`.

What each of those handlers returns is plain Axum, starting with JSON.

## Returning JSON

Use `Json<T>` for ordinary JSON responses:

```rust filename="src/routes/search.rs"
use axum::{extract::Query, Json};
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize)]
pub struct SearchQuery {
    q: String,
}

#[derive(Debug, Serialize)]
pub struct SearchResponse {
    query: String,
    results: Vec<SearchResult>,
}

pub async fn search(Query(query): Query<SearchQuery>) -> Json<SearchResponse> {
    let results = run_search(&query.q).await;
    Json(SearchResponse {
        query: query.q,
        results,
    })
}
```

If you need custom headers, return a tuple or `Response`:

```rust filename="src/routes/search.rs"
use axum::{http::header, response::IntoResponse, Json};

pub async fn search() -> impl IntoResponse {
    (
        [(header::CACHE_CONTROL, "private, max-age=30")],
        Json(SearchResponse::empty()),
    )
}
```

Axum extractors pull path and query data into those handlers.

## Handling dynamic params

Use Axum extractors for path and query data:

```rust filename="src/routes/product.rs"
use axum::{
    extract::Path,
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};

pub async fn product(Path(id): Path<String>) -> Response {
    let Some(product) = load_product(&id).await else {
        return (StatusCode::NOT_FOUND, "Not found").into_response();
    };

    Json(product).into_response()
}
```

Register the path with Axum-style parameters:

```rust filename="src/routes/mod.rs"
Route::endpoint("/api/products/:id", get(product));
```

Form posts use the same extractor pattern with a different body type.

## Handling forms

Use native HTML forms in the page and `Form<T>` in the endpoint:

```rust filename="src/routes/contact.rs"
use axum::{extract::Form, response::Redirect};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct ContactForm {
    email: String,
    message: String,
}

pub async fn submit_contact(Form(form): Form<ContactForm>) -> Redirect {
    validate_contact(&form).expect("return a validation response in real code");
    save_contact(form).await;

    Redirect::to("/contact/thanks")
}
```

For validation failures, return `Response` and render a Proa page with the invalid field state:

```rust filename="src/routes/contact.rs"
use axum::response::{IntoResponse, Response};
use proa::axum::RouteResponse;

pub async fn submit_contact(Form(form): Form<ContactForm>) -> Response {
    if let Err(errors) = validate_contact(&form) {
        return RouteResponse::ssr(ContactPage { form, errors }).into_response();
    }

    save_contact(form).await;
    Redirect::to("/contact/thanks").into_response()
}
```

See [Forms and actions](/docs/guides/forms-actions) for the full form workflow.

Handlers that touch a database need one more thing: a way to reach it.

## Sharing application state

`FrameworkBuilder` is not generic over typed Axum state. Use `Extension<Arc<T>>` for app-wide services when building with the framework builder:

```rust filename="src/app.rs"
use std::sync::Arc;

use axum::{
    extract::{Extension, Path},
    http::StatusCode,
    response::{IntoResponse, Response},
};
use proa::axum::RouteResponse;
use tower::ServiceBuilder;

#[derive(Clone)]
pub struct AppState {
    db: DbPool,
}

pub async fn product(
    Extension(state): Extension<Arc<AppState>>,
    Path(id): Path<String>,
) -> Response {
    match state.db.product_by_id(&id).await {
        Some(product) => RouteResponse::ssr(ProductPage { product }).into_response(),
        None => StatusCode::NOT_FOUND.into_response(),
    }
}

let app = FrameworkBuilder::new()
    .with_dynamic_routes_and_metadata(router, metadata)
    .build()
    .layer(ServiceBuilder::new().layer(Extension(Arc::new(AppState { db }))));
```

Keep request-specific values in extractors or `WebContext` locals, not in shared state.

Webhook handlers break the extractor habit deliberately, because a parsed body loses its signature.

## Handling raw bodies and webhooks

Use bytes for signed webhook bodies so signature verification checks the exact payload:

```rust filename="src/routes/webhook.rs"
use axum::{
    body::Bytes,
    http::{HeaderMap, StatusCode},
};

pub async fn webhook(headers: HeaderMap, body: Bytes) -> StatusCode {
    if !verify_signature(&headers, &body) {
        return StatusCode::UNAUTHORIZED;
    }

    enqueue_webhook(body).await;
    StatusCode::ACCEPTED
}
```

The framework builder applies a 1 MiB default request-body limit. Raise it for a specific endpoint with an Axum layer when the route legitimately needs larger bodies:

```rust filename="src/routes/mod.rs"
use axum::{extract::DefaultBodyLimit, routing::post};

Route::endpoint(
    "/webhooks/payment",
    post(webhook).layer(DefaultBodyLimit::max(2 * 1024 * 1024)),
);
```

Prefer narrow per-route limits over raising the global framework limit.

That body limit is one of four defaults every endpoint inherits.

## What do endpoints inherit from the framework?

`FrameworkBuilder::build()` applies the same outer hardening to endpoints and pages:

| Default | Endpoint effect |
|---------|-----------------|
| Cross-origin protection | Browser-issued cross-origin unsafe requests return `403` unless trusted. |
| Body limit | Requests cap at 1 MiB unless you override the limit. |
| Request timeout | Handlers must produce a response within 30 seconds by default. |
| Security headers | Every response gets baseline hardening headers unless the handler already set them. |

For browser-facing mutations, keep using normal same-origin forms or same-origin `fetch`. For cross-origin API clients, configure trusted origins deliberately. The alternative is mounting a separately configured Axum router outside the framework builder.

Those defaults apply in tests too, so test through the built router rather than the bare handler.

## Testing handlers

Test endpoints with Tower `oneshot` so the extractor and response behavior matches production:

```rust filename="tests/healthz.rs"
use axum::{
    body::{to_bytes, Body},
    http::{Request, StatusCode},
    routing::get,
};
use proa::axum::{router_from_spec, FrameworkBuilder, Route};
use tower::ServiceExt;

#[tokio::test]
async fn health_check_returns_ok() {
    let (router, metadata) = router_from_spec(vec![
        Route::endpoint("/healthz", get(healthz)),
    ]);

    let app = FrameworkBuilder::new()
        .with_dynamic_routes_and_metadata(router, metadata)
        .build();

    let response = app
        .oneshot(Request::builder().uri("/healthz").body(Body::empty()).unwrap())
        .await
        .unwrap();

    assert_eq!(response.status(), StatusCode::OK);

    let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
    assert_eq!(body.as_ref(), b"ok");
}
```

## Reviewing an endpoint

Before shipping:

- Use `Route::endpoint` for API, form, webhook, health, and static text handlers.
- Declare `ROLE = PAGE` and use `render_head` for a managed document's selected Page; compose its layout in the handler.
- Return `Json<T>`, tuples, `Redirect`, `StatusCode`, or `Response` directly from Axum handlers.
- Keep server mutations in handlers or service-layer functions.
- Validate form and JSON input on the server.
- Keep webhook signature verification on the raw body.
- Set explicit cache headers for JSON and generated text endpoints.
- Test status, headers, and bodies with `oneshot`.

## Next steps

- [Routes and layouts](/docs/framework/routing)
  - Define route trees, layouts, and static paths.
- [Route responses](/docs/framework/responses)
  - Return synchronous, buffered async, or streaming SSR with islands.
- [Status, redirects, and errors](/docs/framework/errors)
  - Set status codes, return redirects, and render error pages.
- [Cross-origin and CSRF](/docs/framework/cross-origin)
  - Reject forged cross-origin writes, and add the CSRF defense Proa does not.


---

# Docs: Sitemaps

URL: /docs/framework/sitemaps
Description: Generate sitemap.xml, add page metadata, and split large sites into multiple sitemaps.

---
title: Sitemaps
description: Generate sitemap.xml, add page metadata, and split large sites into multiple sitemaps.
---

A sitemap lists page URLs for search engines to discover. Configure one document with `with_sitemap`, or named documents and an index with `with_sitemaps`.

The Rust filenames below show one way to organize your app. Register generators explicitly on `FrameworkBuilder`. XML output is formatted for readability.

## Generating a sitemap using Rust

Add the page entries to your application builder:

```rust filename="src/main.rs" {5-8}
use proa::axum::{FrameworkBuilder, SitemapUrl};

let app = FrameworkBuilder::new()
    .with_public_origin("https://example.com")?
    .with_sitemap([
        SitemapUrl::new("/")?,
        SitemapUrl::new("/pricing")?.lastmod("2026-10-25")?,
    ])
    .try_build()?;
```

Output:

```xml filename="example.com/sitemap.xml"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
  </url>
  <url>
    <loc>https://example.com/pricing</loc>
    <lastmod>2026-10-25</lastmod>
  </url>
</urlset>
```

Each `SitemapUrl` is one page entry in this single document. The example includes the home page and pricing page; it does not create two sitemaps. Register the actual page routes separately. Adding a `Route::page` does not automatically add it to the sitemap.

> **Good to know:** `try_build()` validates and renders the document once at startup. Requests serve cached bytes. Enable [robots.txt](/docs/framework/robots) on the same builder to advertise the generated sitemap automatically.

## Sitemap entries

An entry can include a modification date, expected change frequency, and priority:

```rust filename="src/main.rs" {6-8}
use proa::axum::{
    ChangeFreq, FrameworkBuilder, SitemapPriority, SitemapUrl,
};

let pricing = SitemapUrl::new("/pricing")?
    .lastmod("2026-10-25")?
    .changefreq(ChangeFreq::Weekly)
    .priority(SitemapPriority::tenths(8).expect("priority within 0..=10"));

let app = FrameworkBuilder::new()
    .with_public_origin("https://example.com")?
    .with_sitemap([pricing])
    .try_build()?;
```

Output:

```xml filename="example.com/sitemap.xml"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/pricing</loc>
    <lastmod>2026-10-25</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>
```

| Entry API | Meaning |
|---|---|
| `SitemapUrl::new(path)?` | An application-local path or a same-origin absolute HTTP(S) URL. |
| `.lastmod(date)?` | The page's actual modification date as `YYYY-MM-DD`; valid calendar dates span years `0001` through `9999`, including leap years. |
| `.lastmod_date(date)?` | The same modification date supplied as a `jiff::civil::Date`, without string conversion. |
| `.changefreq(value)` | An optional `ChangeFreq` value, such as `Weekly`. |
| `.priority(value)` | An optional `SitemapPriority`, stored in tenths from `0.0` to `1.0`. |

Dates are validated and stored using Jiff. String inputs must be exactly `YYYY-MM-DD`; timestamps are rejected rather than silently truncated. If your app already uses Jiff, pass its date directly (add `jiff = "0.2"` to your app's dependencies):

```rust filename="src/sitemap.rs" {4}
use proa::axum::SitemapUrl;

let pricing = SitemapUrl::new("/pricing")?
    .lastmod_date(jiff::civil::date(2026, 10, 25))?;
```

Output (`<lastmod>` element):

```xml filename="example.com/sitemap.xml"
<lastmod>2026-10-25</lastmod>
```

Both methods produce the same `<lastmod>` element shown above, and are also available on `SitemapIndexEntry` for the modification date of a sitemap document. Date formatting writes into the XML output without a temporary string.

Local paths receive the builder's base path exactly once. Absolute entries retain their spelling and are not prefixed. Absolute URLs must match the configured scheme, host, and effective port: HTTPS with no port matches `:443`, and HTTP matches `:80`. Origin comparison uses canonical URL hosts, including case, internationalized domains/punycode, IPv6 spellings, and default ports.

For prefix-mounted apps, absolute page and sitemap-index URLs must resolve inside the final mount directory ([Sitemaps: location](https://www.sitemaps.org/protocol.html#location)). With `/apps/demo`, `/apps/demo/page` and `/apps/demo/` are inside; `/apps/demo`, `/apps/demo2/page`, and `/apps/demo/../../secret` are outside. `try_build()` rejects them with `DiscoveryError::OutsideBasePath`. Standalone documents check scope when rendering. Use local `/` for the application root; it renders as `/apps/demo/`. Local paths cannot traverse above the application root, including through percent-encoded `..` segments.

Query strings are XML-escaped. Paths and URLs reject fragments, malformed percent escapes, C0/C1 controls, XML-forbidden characters, and raw characters excluded from URI syntax such as quotes, angle brackets, and braces. Square brackets are allowed around IPv6 hosts, but must be percent-encoded in paths and queries. Origins and absolute URL hosts are parsed and validated as HTTP(S) URLs. Each final loc must be shorter than 2048 bytes. Dates should reflect actual content changes, rather than the time the generator runs.

Supply URL-encoded components when needed; XML entity escaping is a separate step ([Sitemaps: escaping](https://www.sitemaps.org/protocol.html#escaping)). Non-ASCII hosts and paths remain accepted and are written as supplied; provide encoded URLs when required by your server or crawler. The XML writer handles all five listed entities without temporary URL strings. Parsed absolute URLs are retained for origin and scope checks, so rendering does not reparse them. Proa's upper byte limit is conservative for Unicode IRIs; the protocol states a character limit. Final locations also need at least 12 characters under the official XML schemas. The date-only `lastmod` API and priorities in tenths are supported subsets of the protocol.

## Multiple sitemaps

Use `with_sitemaps` to split pages, products, or other collections into separate documents. Each `SitemapFile` contains page entries; its ID determines the document's route:

```rust filename="src/main.rs" {5-13}
use proa::axum::{FrameworkBuilder, RobotsTxt, SitemapFile, SitemapUrl};

let app = FrameworkBuilder::new()
    .with_public_origin("https://example.com")?
    .with_sitemaps([
        SitemapFile::new("pages", [
            SitemapUrl::new("/")?,
            SitemapUrl::new("/pricing")?,
        ])?,
        SitemapFile::new("products-0", [
            SitemapUrl::new("/products/1")?.lastmod("2026-10-25")?,
        ])?,
    ])
    .with_robots(RobotsTxt::new())
    .try_build()?;
```

Output:

```xml filename="example.com/sitemap.xml"
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-pages.xml</loc>
  </sitemap>
  <sitemap>
    <loc>https://example.com/sitemap-products-0.xml</loc>
  </sitemap>
</sitemapindex>
```

```xml filename="example.com/sitemap-pages.xml"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
  </url>
  <url>
    <loc>https://example.com/pricing</loc>
  </url>
</urlset>
```

```xml filename="example.com/sitemap-products-0.xml"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/products/1</loc>
    <lastmod>2026-10-25</lastmod>
  </url>
</urlset>
```

```text filename="example.com/robots.txt"
Sitemap: https://example.com/sitemap.xml
```

`/sitemap.xml` now contains a `<sitemapindex>` linking to the two `<urlset>` documents. Robots.txt advertises the index. Named documents live alongside the index so their [default directory scope](https://www.sitemaps.org/protocol.html#location) includes the application's page paths. Incoming handler paths are `/sitemap.xml`, `/sitemap-pages.xml`, `/sitemap-products-0.xml`, and `/robots.txt`.

IDs must be unique, nonempty, and contain only ASCII letters, digits, `-`, or `_`. An empty file list or sitemap with no page entries returns a startup error. `with_sitemap` and `with_sitemaps` select alternative modes; the last call replaces the previous configuration. One file passed to `with_sitemaps` still produces an index and a child document.

### Async generation from application data

An application-owned `generate_sitemaps` function can query a database or CMS and group the resulting URLs into named documents. This example assumes your app defines `crate::db::Database`, whose `published_products()` method returns products with `path` and `last_modified` strings:

```rust filename="src/sitemap.rs" {7,13,18}
use crate::db::Database;
use proa::axum::{
    DiscoveryError, SitemapFile, SitemapUrl, MAX_SITEMAP_ENTRIES,
};

pub async fn generate_sitemaps(db: &Database) -> anyhow::Result<Vec<SitemapFile>> {
    let products = db.published_products().await?;
    let mut files = vec![SitemapFile::new("pages", [
        SitemapUrl::new("/")?,
        SitemapUrl::new("/pricing")?,
    ])?];

    for (id, products) in products.chunks(MAX_SITEMAP_ENTRIES).enumerate() {
        let urls = products.iter().map(|product| {
            SitemapUrl::new(product.path.as_str())?
                .lastmod(product.last_modified.as_str())
        }).collect::<Result<Vec<_>, DiscoveryError>>()?;
        files.push(SitemapFile::new(format!("products-{id}"), urls)?);
    }
    Ok(files)
}
```

Await the generator when configuring the builder:

```rust filename="src/main.rs" {10}
mod sitemap;

use proa::axum::{FrameworkBuilder, RobotsTxt};

// Inside async main, before binding the listener:
let app = FrameworkBuilder::new()
    .with_dynamic_routes_and_metadata(routes, metadata)
    .with_base_path(base_path)
    .with_public_origin(&origin)?
    .with_sitemaps(sitemap::generate_sitemaps(&db).await?)
    .with_robots(RobotsTxt::new())
    .try_build()?;
```

For one published product at `/products/1`, last changed on `2026-10-25`, the generated product document is:

Output:

```xml filename="example.com/sitemap-products-0.xml"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/products/1</loc>
    <lastmod>2026-10-25</lastmod>
  </url>
</urlset>
```

The index and pages document follow the same structure as the preceding example. This uses the named-document approach of [Next.js generateSitemaps](https://nextjs.org/docs/app/api-reference/functions/generate-sitemaps), with each Proa result supplying both an ID and its entries.

Generation runs once at startup, followed by validation and rendering. New content requires regenerating/restarting the app, or custom handlers with application-managed refresh.

Sitemaps and indexes enforce the [protocol limits](https://www.sitemaps.org/protocol.html#index): at most 50,000 entries and 50 MiB of uncompressed UTF-8 XML per document, including escaping. Long URLs may require batches smaller than `MAX_SITEMAP_ENTRIES`. Oversized documents return a `DiscoveryError` during rendering, before the response buffer is flattened into a string.

## Configure public URLs

Set an explicit public origin and optional runtime [base path](/docs/framework/deployment). The origin contains only a scheme, host, and optional port; the mount prefix belongs in `with_base_path`:

```rust filename="src/main.rs" {4-5}
use proa::axum::{BasePath, FrameworkBuilder, RobotsTxt, SitemapUrl};

let app = FrameworkBuilder::new()
    .with_public_origin("https://example.com")?
    .with_base_path(BasePath::new("/apps/demo")?)
    .with_sitemap([SitemapUrl::new("/pricing")?])
    .with_robots(RobotsTxt::new().allow("/")?.disallow("/admin")?)
    .try_build()?;
```

Output:

```xml filename="example.com/apps/demo/sitemap.xml"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/apps/demo/pricing</loc>
  </url>
</urlset>
```

Configuration order does not matter: documents use the final origin and base path. Request `Host` and forwarded headers do not override that configuration. Index links receive the same prefix as page URLs.

Incoming routes stay unprefixed behind a [prefix-stripping proxy](/docs/framework/deployment#serving-behind-a-url-path-prefix). Forward both the index and its child sitemap documents. Crawlers also need [robots.txt at the origin root](/docs/framework/robots#origin-root-robots-txt).

## Run an application

Configure discovery endpoints and start the HTTP server in `src/main.rs`. Route definitions are abbreviated below; replace the comment in `vec![]` with your application routes.

```rust filename="src/main.rs" {19-22}
use std::time::Duration;

use proa::axum::{
    BasePath, FrameworkBuilder, RobotsTxt, SitemapUrl,
    router_from_spec, serve,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let base_path = BasePath::new(&std::env::var("PROA_BASE_PATH").unwrap_or_default())?;
    let origin = std::env::var("PUBLIC_BASE_URL")?;

    let (routes, metadata) = router_from_spec(vec![/* your application routes */]);

    let app = FrameworkBuilder::new()
        .with_dynamic_routes_and_metadata(routes, metadata)
        .with_base_path(base_path)
        .with_public_origin(&origin)?
        .with_sitemap([
            SitemapUrl::new("/")?,
            SitemapUrl::new("/pricing")?.lastmod("2026-10-25")?,
        ])
        .with_robots(RobotsTxt::new().allow("/")?.disallow("/admin")?)
        .try_build()?;

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
    serve(listener, app, Duration::from_secs(30)).await?;
    Ok(())
}
```

From the application crate, run with an empty base path for local development:

```bash filename="Terminal"
PUBLIC_BASE_URL=http://127.0.0.1:3000 PROA_BASE_PATH="" proa run
```

Visit `http://127.0.0.1:3000/sitemap.xml` for the sitemap and `/robots.txt` for crawler rules. The example sitemap lists `/` and `/pricing`; register those page routes in the application route list.

`try_build()` returns an Axum router. Pass it to `serve()` with a bound TCP listener to start accepting requests. The server runs until Ctrl+C or SIGTERM, then allows up to 30 seconds for in-flight requests to finish.

## Custom and dynamic handlers

`with_sitemap` and `with_sitemaps` install their routes explicitly. Do not register custom handlers at the same paths when using them.

Use standalone `Sitemap`, `SitemapIndex`, `sitemap_xml`, and `sitemap_index_xml` for request-time generation or application-managed refresh. Pass the configured origin and base path explicitly. The response helpers return UTF-8 `application/xml`; render failures are logged and returned as a generic 500.

`try_build()` returns invalid discovery configuration as a `DiscoveryError`. The existing `build()` API also works, but panics on invalid configuration. Axum's duplicate-route restrictions apply to both.

## Next steps

- [Robots.txt](/docs/framework/robots)
  - Configure bot-specific crawler rules and advertise the sitemap or index.
- [Deployment](/docs/framework/deployment)
  - Configure the public prefix and proxy routes.
- [Configuration](/docs/framework/configuration)
  - Configure FrameworkBuilder and its router integrations.
- [Environment](/docs/framework/environment)
  - Load the public origin and base path at startup.


---

# Docs: robots.txt

URL: /docs/framework/robots
Description: Generate robots.txt, configure specific user agents, and publish optional crawler directives.

---
title: robots.txt
description: Generate robots.txt, configure specific user agents, and publish optional crawler directives.
---

Robots.txt tells crawlers which URLs they may access. Configure one document at the origin root with `FrameworkBuilder::with_robots`; it can contain several user-agent groups and sitemap links.

The Rust filenames below show one way to organize your app. Register generators explicitly on the builder; filenames do not automatically install routes.

## Generating robots.txt using Rust

Add crawler rules to your application builder:

```rust filename="src/main.rs" {4}
use proa::axum::{FrameworkBuilder, RobotsTxt};

let app = FrameworkBuilder::new()
    .with_robots(RobotsTxt::new().allow("/")?.disallow("/private/")?)
    .try_build()?;
```

Output:

```text filename="example.com/robots.txt"
User-agent: *
Allow: /
Disallow: /private/
```

`with_robots` is opt-in and needs no public origin unless you also enable sitemap generation. For listener binding and `serve()`, see the [complete application example](/docs/framework/sitemaps#run-an-application).

> **Good to know:** The builder renders robots.txt once at startup, then serves cached bytes. When a [sitemap or sitemap index](/docs/framework/sitemaps) is enabled on the same builder, it automatically adds its public `Sitemap` link. Existing links are preserved, without adding an identical automatic link twice.

## Customizing specific user agents

Use `group` for one bot or `group_agents` to share a rule group between several bots:

```rust filename="src/main.rs" {4,7}
use proa::axum::{FrameworkBuilder, RobotsTxt};

let robots = RobotsTxt::new()
    .group("Googlebot")?
    .allow("/")?
    .disallow("/private/")?
    .group_agents(["Applebot", "Bingbot"])?
    .disallow("/")?;

let app = FrameworkBuilder::new()
    .with_robots(robots)
    .try_build()?;
```

Output:

```text filename="example.com/robots.txt"
User-agent: Googlebot
Allow: /
Disallow: /private/

User-agent: Applebot
User-agent: Bingbot
Disallow: /
```

`group_agents` emits consecutive `User-agent` lines sharing the rules that follow. `group` starts an independent group. Named bots use their matching rules; the wildcard group is a fallback rather than an inherited set of rules.

Use a product token such as `Googlebot`, not a full HTTP User-Agent header or versioned name. Proa follows [RFC 9309 §2.2.1](https://www.rfc-editor.org/rfc/rfc9309.html#section-2.2.1): tokens are `*` or ASCII letters, underscores, and hyphens. Google tolerates some malformed names; Proa rejects them when constructing groups.

Calling a rule or per-group option before starting a group creates a wildcard group. A group with no allow/disallow rules renders an empty `Disallow:` so it does not merge into the next group.

## Nonstandard directives

As in [Next.js robots metadata](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/robots), configure optional crawler-specific directives alongside the standard rules:

```rust filename="src/main.rs" {7-10}
use std::time::Duration;
use proa::axum::{FrameworkBuilder, RobotsTxt};

let robots = RobotsTxt::new()
    .group("SeznamBot")?
    .allow("/")?
    .crawl_delay(Duration::from_millis(1500))
    .directive("Request-Rate", "10/1m")?
    .host("https://example.com")?
    .sitemap("https://example.com/news-sitemap.xml")?;

let app = FrameworkBuilder::new()
    .with_robots(robots)
    .try_build()?;
```

Output:

```text filename="example.com/robots.txt"
User-agent: SeznamBot
Allow: /
Crawl-delay: 1.5
Request-Rate: 10/1m

Host: https://example.com
Sitemap: https://example.com/news-sitemap.xml
```

`crawl_delay` uses a Rust `Duration` and renders exact decimal seconds. Repeating `directive` emits repeated fields, preserving their names and values. `host` accepts a hostname with optional port, or an HTTP(S) origin; it is explicit and is not inferred from request headers or set automatically by the public origin.

Extension support depends on the crawler; for example, [Google ignores crawl-delay](https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec). Custom directive names must start with an ASCII letter and contain only ASCII letters, digits, or `-`. Values can contain spaces, but not `#` or control characters. Reserved fields use the typed methods. Extension values render verbatim and do not receive the application's base path.

## Async generation

An application-owned `generate_robots` function can read configuration, a database, or a CMS. This example assumes your app defines `crate::db::Database`, whose `crawler_exclusions()` method returns application-local path strings:

```rust filename="src/robots.rs" {5,8}
use crate::db::Database;
use proa::axum::RobotsTxt;

pub async fn generate_robots(db: &Database) -> anyhow::Result<RobotsTxt> {
    let paths = db.crawler_exclusions().await?;
    let mut robots = RobotsTxt::new().group("*")?;
    for path in paths {
        robots = robots.disallow(&path)?;
    }
    Ok(robots)
}
```

Await the result when configuring the same builder as the [sitemap generator](/docs/framework/sitemaps#async-generation-from-application-data):

```rust filename="src/main.rs" {12}
mod robots;
mod sitemap;

use proa::axum::FrameworkBuilder;

// Inside async main, before binding the listener:
let app = FrameworkBuilder::new()
    .with_dynamic_routes_and_metadata(routes, metadata)
    .with_base_path(base_path)
    .with_public_origin(&origin)?
    .with_sitemaps(sitemap::generate_sitemaps(&db).await?)
    .with_robots(robots::generate_robots(&db).await?)
    .try_build()?;
```

For a database containing the exclusion `/private/`, an empty base path, and public origin `https://example.com`:

Output:

```text filename="example.com/robots.txt"
User-agent: *
Disallow: /private/

Sitemap: https://example.com/sitemap.xml
```

The generator runs once at startup, followed by text rendering. New configuration requires regenerating/restarting the app, or a custom handler with application-managed refresh. Multiple sitemap documents still use this one origin-root robots.txt.

## Origin-root robots.txt

Crawlers fetch `https://example.com/robots.txt`, even when the app lives at `/apps/demo/`. They do not discover robots rules from `/apps/demo/robots.txt`.

Incoming Proa routes stay unprefixed. For a [prefix-stripping proxy](/docs/framework/deployment#serving-behind-a-url-path-prefix), forward origin-root `/robots.txt` to the builder's `/robots.txt` handler in addition to stripping `/apps/demo` for the app's other routes. Builder configuration cannot change the proxy's public routing.

Root-relative robots rules supplied to `with_robots` are application-local paths: pass `/admin`, not `/apps/demo/admin`. The builder's base path replaces any base path already set on the document, so rules are never prefixed twice. Application-wide rules such as `/` or `/*` also cover the bare mount URL and its query variants, so `disallow("/")` blocks `/apps/demo`, `/apps/demo?query`, and everything under `/apps/demo/`. The exact-root rule `/$` covers only the bare mount and slash root, without query variants. Literal `*` and `$` characters in the mount prefix are percent-escaped so they cannot become robots pattern operators. Empty rules and wildcard-leading patterns such as `*.pdf$` remain unchanged; those patterns match public paths directly. To scope a wildcard to the mount, use a root-relative rule such as `/*.pdf$`.

Wildcard-leading rules follow the example in [RFC 9309 §5.1](https://www.rfc-editor.org/rfc/rfc9309.html#section-5.1), despite the slash-leading grammar in §2.2. Prefer `/*.pdf$` for Google's [documented path syntax](https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec#syntax). Whitespace, `#` and control characters are rejected in rule fields.

Show the mount behavior with a concrete configuration:

```rust filename="src/main.rs" {5,7}
use proa::axum::{BasePath, FrameworkBuilder, RobotsTxt, SitemapUrl};

let app = FrameworkBuilder::new()
    .with_public_origin("https://example.com")?
    .with_base_path(BasePath::new("/apps/demo")?)
    .with_sitemap([SitemapUrl::new("/pricing")?])
    .with_robots(RobotsTxt::new().allow("/")?.disallow("/admin")?)
    .try_build()?;
```

Output:

```text filename="example.com/robots.txt"
User-agent: *
Allow: /apps/demo$
Allow: /apps/demo?
Allow: /apps/demo/
Disallow: /apps/demo/admin

Sitemap: https://example.com/apps/demo/sitemap.xml
```

The sitemap link includes `/apps/demo`; robots.txt itself must still be publicly available at `https://example.com/robots.txt`.

Explicit `sitemap` links may point to another origin. They reject fragments, malformed percent escapes, controls, and raw characters excluded from URL syntax. Use `%23` for a literal hash in a URL: an unescaped `#` starts a robots comment ([RFC 9309 §2.2.3](https://www.rfc-editor.org/rfc/rfc9309.html#section-2.2.3)).

## Document size

The builder and `robots_txt` response helper reject documents above [Google's 500 KiB processing limit](https://developers.google.com/crawling/docs/robots-txt/robots-txt-spec#file-format), including mount expansion and automatically added sitemap links. `try_build()` returns `DiscoveryError::RobotsTooLarge`; a custom `robots_txt` handler returns a logged, generic 500. Rules are never silently truncated.

This is a Google compatibility limit, not an RFC maximum. Use `RobotsTxt::try_render_txt()` for the same check in another adapter. The low-level `render_txt()` serializer remains uncapped for applications targeting other crawlers.

## API reference

| API | Purpose |
|---|---|
| `group` / `group_agents` | Start rules for one bot or several bots. |
| `allow` / `disallow` | Add a path rule to the current group. |
| `crawl_delay` | Set an optional per-group `Duration`. |
| `directive` | Add a validated custom field to the current group. |
| `host` | Set an optional explicit document-level host. |
| `sitemap` / `sitemap_path` | Add an absolute sitemap link, or compose one from origin, base path, and application path. |
| `try_render_txt` | Render text with the Google-compatible 500 KiB size check. |

## Custom and dynamic handlers

Use standalone `RobotsTxt` and `robots_txt` for request-time generation or application-managed refresh. Pass the application's base path to `RobotsTxt::with_base_path` before rendering. `robots_txt(&robots)` returns a UTF-8 `text/plain` response.

Configure sitemap links explicitly in custom handlers. Do not register a custom `/robots.txt` handler when using the builder's `with_robots` method.

## Next steps

- [Sitemaps](/docs/framework/sitemaps)
  - Generate single or multiple sitemap documents and their index.
- [Configuration](/docs/framework/configuration)
  - Configure FrameworkBuilder and its router integrations.
- [Deployment](/docs/framework/deployment)
  - Set the public prefix and forward origin-root `/robots.txt`.


---

# Docs: Content negotiation

URL: /docs/framework/content-negotiation
Description: Serve HTML and Markdown representations of one resource through HTTP content negotiation.

---
title: Content negotiation
description: Serve HTML and Markdown representations of one resource through HTTP content negotiation.
---

One URL, one resource, more than one representation. A browser asks for `text/html` and gets a page. A command-line client, retrieval pipeline, or agent can ask for `text/markdown` and get the content as a document.

This is ordinary HTTP. The resource advertises what else it can be, and the client picks.

```http
GET /docs/framework/routing

HTTP/2 200
Content-Type: text/html
Link: </docs/framework/routing.md>; rel="alternate"; type="text/markdown"
Vary: Accept
```

## Why not a separate agent endpoint

The alternative is a parallel surface: a site, an API, an `llms.txt`, a scraping adapter, and an agent-specific endpoint for every piece of public information. Each one is a thing to build, secure, and keep in sync.

Multiple representations of one resource is the design the web already has. `rel="alternate"` is [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288) web linking, and content negotiation is as old as HTTP. The agent needs no prior knowledge of your conventions beyond the standard.

Proa's programming model supports rendering across HTML, Markdown, and other render targets: a component is a typed Rust value with an implementation for each target. In this HTTP example, [`MdRenderSync`](/docs/core/markdown) defines a Markdown representation using the same data and typed children as the HTML implementation.

## What Proa emits today

| Piece | Status |
|---|---|
| Typed page → Markdown from one component | Ships. `MdRenderSync` / `MdRender` / `md!` |
| Per-page Markdown artifact | Ships. `DocPage::markdown_path`, emitted for every page |
| `text/markdown` responses | Ships. `DocsResponse::markdown()` |
| `Link` header infrastructure | Ships. `DISCOVERY_LINKS` |
| `rel="service-desc"` pointing at OpenAPI | Ships |
| `/.well-known/proa-site.json`, `/llms-full.txt` | Ships |
| `rel="alternate"` per page | Ships. Every HTML docs page links its Markdown path with `Vary: Accept` |
| `Accept: text/markdown` negotiation | Ships. Docs pages return Markdown when `Accept` lists `text/markdown` with nonzero quality (`q=0` is respected) |

Both halves are standard-shaped today: the service description and the negotiated Markdown representation.

## Two layers, not one

`.well-known` and `rel="alternate"` answer different questions, and an agent needs both:

| Question | Mechanism |
|---|---|
| What can I *read* here? | `Link: rel="alternate"` on the resource |
| What can I *do* here? | `rel="service-desc"`, OpenAPI, MCP |

Reading is a representation problem. Acting is a service-description problem. Do not collapse them into one endpoint.

## Caching, before you ship it

An HTTP cache that honors `Vary: Accept` keeps representations separate. Raw `Accept` values can create many variants because clients send different preference lists. Cloudflare does not honor arbitrary `Vary` fields by default; enable its [Vary support](https://developers.cloudflare.com/cache/concepts/vary/) or explicitly include the selected representation in the cache key before caching negotiated routes.

Choose a representation policy:

- **Normalize `Accept` at the edge** to the representations you actually serve, preserving the origin's negotiation semantics, and include that choice in the cache key. Changing the forwarded header alone does not separate cached responses.
- **Use the `.md` URL for Markdown caching** and bypass shared caching on the negotiated canonical URL until its variants are configured. A separate Markdown URL does not by itself make a URL-only cache safe for the canonical route.

See [Page caching](/docs/framework/page-caching).

> **Good to know**: Markdown is a good representation for today's models, not the final destination. The same `Link` mechanism carries `application/ld+json` for entity data or an OpenAPI document for actions. The page advertises its interfaces; the agent picks the one that fits the job.

## Next steps

- [Markdown rendering](/docs/core/markdown)
  - Render typed Rust values to Markdown for docs, feeds, and agents.
- [Docs as LLM context](/docs/llms)
  - Serve Proa docs as Markdown context for coding agents.
- [Agent setup](/docs/agents)
  - Configure coding agents to edit Proa projects with local instructions.
- [Page caching](/docs/framework/page-caching)
  - Cache public HTML and static assets at browsers and CDNs.
- [Route responses](/docs/framework/responses)
  - Return synchronous, buffered async, or streaming SSR with islands.


---

# Docs: Page caching

URL: /docs/framework/page-caching
Description: Cache pages at the edge and refresh them after deployment.

---
title: Page caching
description: Cache pages at the edge and refresh them after deployment.
---

By default, Proa renders pages on every request; it does not enable page caching. Use your CDN for [static pages](#caching-static-pages) and [ISR](#enabling-isr), and configure [RSJS bundles](#caching-rsjs-bundles) separately.

## Caching static pages

Add a cache policy to a public route. `PageCache::new()` requires no provider credentials, application identity, or environment variables:

```rust filename="src/pages/promo.rs"
use axum::routing::get;
use proa::axum::{PageCache, Route, RouteResponse};
use crate::pages::PromoPage;

pub fn route() -> Route<()> {
    Route::endpoint(
        "/promo/summer",
        get(promo_page),
    ).with_page_cache(PageCache::new())
}

async fn promo_page() -> RouteResponse {
    RouteResponse::ssr(PromoPage)
}
```

Add the page's route to your router:

```rust filename="src/routes.rs"
use axum::Router;
use crate::pages::promo;

pub fn routes() -> Router {
    Router::new().merge(promo::route().into_router())
}
```

Pass the returned router to `FrameworkBuilder::with_dynamic_routes`.

This configures response headers, not an in-process cache. Without a CDN, requests still reach Proa and render the page.

Configure your CDN to use those headers:

| Setting | Configuration |
| --- | --- |
| Public pages | Cache public HTML responses. Exclude account and personalized routes. |
| Private requests | Bypass caching for requests containing `Cookie`, `Authorization`, or `Range`. |
| Cache lifetime | Respect origin cache-control headers. Never force caching of `private` or `no-store` responses. |
| Cache key | Preserve the hostname, path, and query string. Honor `Vary` for `Accept`, `Accept-Encoding`, `Accept-Language`, and `X-Proa-Client`, or include them in the cache key. |
| Unsupported variants | Bypass caching when the response varies on headers your CDN cannot distinguish. |

Proa also excludes private requests, non-HTML responses, streaming bodies, cookies, and per-request CSP nonces from caching. **The CDN's bypass rules are still required:** cached requests never reach Proa's checks.

The first request without a cached copy reaches Proa. The CDN stores the rendered HTML near visitors and serves subsequent requests without contacting your server.

The policy uses a one-year TTL. To keep pages until your next deployment, your deployment must invalidate the CDN cache. Eviction or TTL expiry can trigger an earlier render.

![Visitors receive cached HTML from the CDN; misses reach Proa, and deployment invalidation removes old cached responses.](/static/images/docs/page-cache-flow.svg)

For content that changes between deployments, add ISR to the route.

## Enabling ISR

Let's say you want to re-render the page and cache it on an interval, like every hour or every day. Add `.revalidate(...)`:

```rust filename="src/pages/promo.rs"
use std::time::Duration;
use axum::routing::get;
use proa::axum::{PageCache, Route, RouteResponse};
use crate::pages::PromoPage;

pub fn route() -> Route<()> {
    Route::endpoint(
        "/promo/summer",
        get(promo_page),
    ).with_page_cache(PageCache::new().revalidate(Duration::from_secs(3600)))
}

async fn promo_page() -> RouteResponse {
    RouteResponse::ssr(PromoPage)
}
```

Use `86400` seconds for daily refreshes.

After the interval, the next request triggers a fresh render. A CDN supporting `stale-while-revalidate` can serve stale HTML during regeneration, then cache the replacement. This is **request-driven**, not a scheduled job.

The default stale-serving window is one day. Override it after `.revalidate(...)` with `.stale_while_revalidate(Duration::from_secs(300))` for five minutes.

Proa emits standard shared-cache headers and CDN-specific equivalents. Your CDN's cache policy must honor the requested TTL and stale-serving behavior.

Both static caching and ISR need deployment invalidation when you want a new version to replace cached pages immediately.

## Deploying with your CDN

**A new build or server restart does not invalidate a remote CDN cache.** Response headers cannot notify a CDN that is still serving an old response.

Use your hosting platform's deployment invalidation, or configure an integration for `proa deploy run`. Provider configuration belongs to deployment, not your route constructors.

### Cloudflare

For Cloudflare, proxy your hostname and create a Cache Rule for your public HTML routes:

| Setting | Configuration |
| --- | --- |
| Cache eligibility | Mark public HTML routes **Eligible for cache**. |
| Request bypass | Bypass requests containing `Cookie`, `Authorization`, or `Range`. Exclude personalized routes. |
| Edge and browser TTLs | Respect origin cache-control headers. |
| Stale-while-revalidate | Enable serving stale HTML during revalidation. |
| [Vary](https://developers.cloudflare.com/cache/concepts/vary/) | Use `passthrough` for `Accept`, `Accept-Encoding`, `Accept-Language`, and `X-Proa-Client`. Bypass unsupported variation headers. |

Add `cdn` to your existing `deploy` configuration, using your zone ID and application hostname:

```json filename="proa.config.json"
{
  "deploy": {
    "cdn": {
      "provider": "cloudflare",
      "zoneId": "your-cloudflare-zone-id",
      "hostname": "www.example.com"
    }
  }
}
```

Set `CLOUDFLARE_API_TOKEN` in the deployment job with **Cache Purge** permission scoped to that zone. The application does not need this credential.

This integration [purges the configured hostname](https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-hostname/), including its cached assets. Use a hostname dedicated to this deployment; other hostnames in the zone remain untouched.

### Other CDNs

If your hosting platform already invalidates its cache on deployment, use that workflow. Proa does not require Cloudflare or `proa deploy run`.

For a provider with an invalidation CLI, configure its command once. For example, with the [AWS CloudFront CLI](https://docs.aws.amazon.com/cli/latest/reference/cloudfront/create-invalidation.html):

```json filename="proa.config.json"
{
  "deploy": {
    "cdn": {
      "provider": "command",
      "command": [
        "aws", "cloudfront", "create-invalidation",
        "--distribution-id", "YOUR_DISTRIBUTION_ID",
        "--paths", "/*",
        "--no-cli-pager"
      ]
    }
  }
}
```

Configure the provider CLI and its credentials in the deployment job. This example invalidates the entire distribution, including assets; narrow the paths if needed.

The command integration executes the argument array directly, without shell expansion. It does not require Cloudflare credentials.

For CloudFront caching, [set minimum TTL to zero](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html) so private responses remain uncacheable. Include page variants in its cache key and allow the requested TTL within its maximum TTL.

### Running deployment and invalidation

After configuring one integration, wrap your deployment command with `proa deploy run`. The command must wait until all servers receiving traffic run the new version.

For a Docker Compose application with a readiness health check:

```bash filename="Terminal"
proa deploy run -- \
  docker compose up --build --wait --wait-timeout 300
```

Proa validates the selected configuration, runs your deployment command, then invokes CDN invalidation. A failed deployment skips invalidation; a failed invalidation makes the command fail.

Success means the provider accepted the request or its configured command succeeded. Invalidation can take time to propagate; configure a command that waits if your deployment requires completion.

A bare build, restart, or deployment outside this workflow does not invoke Proa's invalidation integration. Without an integration, pages can remain cached until expiry or eviction.

Page invalidation is separate from JavaScript bundle versioning.

## Caching RSJS bundles

Proa's default RSJS URLs are stable, including `/rsjs-runtime.js` and `/rsjs/island/<asset_id>.js`. An asset ID is not a guarantee that the URL changes with its contents.

Configure these headers on your static asset server:

| Asset URL | `Cache-Control` |
| --- | --- |
| Stable URL | `public, no-cache` |
| Content-hashed URL | `public, max-age=31536000, immutable` |

For stable URLs, `no-cache` allows storage but requires revalidation before reuse. Do not give these files a long immutable lifetime: their contents can change at the same URL.

For long-lived caching, content-hash the runtime files and every generated module. Rewrite their imports, HTML references, and preloads to those versioned URLs.

`rsjs::manifest::rewrite_runtime_import_specifiers` rewrites the runtime imports only. It does not fingerprint the entire module graph.

Keep previous bundles available for already-open tabs. New HTML references the new bundle URLs; invalidating HTML does not replace JavaScript in already-open tabs.

## Next steps

- [Routing](/docs/framework/routing): Register pages and compose routers.
- [Streaming SSR](/docs/core/streaming-ssr): Stream responses instead of caching complete HTML pages.


---

# Docs: Status, redirects, and errors

URL: /docs/framework/errors
Description: Set status codes, return redirects, and render error pages.

---
title: Status, redirects, and errors
description: Set status codes, return redirects, and render error pages.
---

A Proa route is an Axum handler: return an Axum response to decide early, or `RouteResponse` to let the Proa finalizer render a page. This page covers [status in the handler](#setting-status-in-the-handler), [rendered 404 pages](#rendering-a-404-page), [redirects](#redirecting), and [framework errors](#handling-framework-errors).

## Setting status in the handler

Return ordinary Axum responses when the handler can decide before rendering:

```rust filename="src/routes/product.rs"
use axum::{
    extract::Path,
    http::StatusCode,
    response::{IntoResponse, Response},
};
use proa::axum::RouteResponse;

pub async fn product(Path(id): Path<String>) -> Response {
    let Some(product) = load_product(&id).await else {
        return (StatusCode::NOT_FOUND, "Not found").into_response();
    };

    RouteResponse::ssr(ProductPage { product }).into_response()
}
```

This keeps missing records, auth failures, and validation failures out of the render tree when they do not need a full page shell.

Some error states do need that shell, and those become real pages.

## Rendering a 404 page

Render a full Proa document when the error state needs the site's layout, metadata, or island bootstrap. For a managed document, declare the selected Page and set its status in the head hook:

```rust filename="src/pages/not_found.rs"
use http::StatusCode;
use proa::{ComponentRole, DataLoader, SyncHeadOperation, WebContext, WebRenderSync, WriteError};
use proa::html_sync;

pub struct NotFoundPage;

impl<L: DataLoader> WebRenderSync<L> for NotFoundPage {
    const ROLE: ComponentRole = ComponentRole::PAGE;

    fn render_head(&self, cx: &mut WebContext<L>) -> impl SyncHeadOperation {
        if !cx.response_mut().set_status(StatusCode::NOT_FOUND) {
            return Err(WriteError::render("response headers already committed"));
        }
        cx.head_mut().title("Page not found")
    }

    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <main>
                <h1>"Page not found"</h1>
                <p>"The page may have moved or no longer exists."</p>
            </main>
        }
        .render(cx)
    }
}
```

Compose it inside the `RootDocument` from [Layouts and Pages](/docs/framework/layouts-and-pages), then return `RouteResponse::ssr(RootDocument { children: NotFoundPage })`. Enable managed metadata with `FrameworkBuilder::with_head(...)` or the response's `with_head(...)`. This hook works for buffered and streamed documents; the status is decided before the Page body starts.

The same response context also stages headers and cookies.

## Setting headers during render

Components stage response metadata through `cx.response_mut()`:

```rust filename="src/pages/not_found.rs"
use http::{header, HeaderValue, StatusCode};

cx.response_mut().set_status(StatusCode::CREATED);
cx.response_mut().insert_header(
    header::CACHE_CONTROL,
    HeaderValue::from_static("public, max-age=60"),
);
cx.response_mut().append_set_cookie(HeaderValue::from_static("theme=dark; Path=/; SameSite=Lax"));
```

`set_status`, `insert_header`, `append_header`, and `append_set_cookie` return `bool`. Treat `false` as a late mutation.

Late mutations are exactly what streaming makes possible, so streamed routes need a tighter rule.

## Setting status on a streamed route

Set status and headers in the handler when the decision is already known:

```rust filename="src/pages/dashboard.rs"
use axum::http::{header, StatusCode};

(
    StatusCode::OK,
    [(header::CACHE_CONTROL, "private, no-store")],
    RouteResponse::ssr_stream(DashboardPage),
)
```

For managed documents, layout and Page `render_head` hooks can also stage status, headers, and cookies before publication. Put data-dependent HTTP decisions there, before the selected Page body starts. Once the Page metadata is sealed and the head outlet is available, Proa publishes those decisions; `can_mutate_headers()` becomes `false` and later mutations are refused.

Manual streaming documents commit their response head before root rendering, so make their HTTP decisions in the handler. Buffered sync and async routes can stage response metadata until finalization. See [Metadata and streaming](/docs/framework/metadata#metadata-and-streaming).

Redirects avoid the problem entirely: they never enter the render tree.

## Redirecting

Use Axum redirects for moved routes, auth gates, and canonical URLs:

```rust filename="src/routes/legacy.rs"
use axum::response::Redirect;

pub async fn old_docs_path() -> Redirect {
    Redirect::permanent("/docs/framework")
}
```

When a handler may either redirect or render, return `Response`:

```rust filename="src/routes/account.rs"
use axum::response::{IntoResponse, Redirect, Response};
use proa::axum::RouteResponse;

pub async fn account() -> Response {
    if !is_signed_in().await {
        return Redirect::to("/login").into_response();
    }

    RouteResponse::ssr(AccountPage).into_response()
}
```

Your own error types can carry the same decision, once you give them a status code.

## Mapping application errors

Map application errors to explicit status codes. Keep sensitive details in logs, not response bodies:

```rust filename="src/error.rs"
use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
};

pub enum AppError {
    NotFound,
    Unauthorized,
    Upstream,
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        match self {
            Self::NotFound => (StatusCode::NOT_FOUND, "Not found").into_response(),
            Self::Unauthorized => (StatusCode::UNAUTHORIZED, "Unauthorized").into_response(),
            Self::Upstream => (StatusCode::BAD_GATEWAY, "Temporary upstream error").into_response(),
        }
    }
}
```

Then use `Result<Response, AppError>` or `Result<impl IntoResponse, AppError>` in handlers.

Failures below your code, in render or transport, never reach an `AppError`.

## Handling framework errors

The framework protects the response shape for infrastructure failures:

| Source | Response |
|--------|----------|
| Render, bootstrap, or invariant error | `500` with a terse body such as `render error` |
| Encoding error | `500 encoding error` |
| Default request timeout | `408 Request Timeout` |
| Rejected cross-origin unsafe browser request | `403 Forbidden` |
| Missing embedded static asset | `404 Not Found` |

Use `tracing` for the detailed error path and return short public messages to users.

## Checking the error paths

Before shipping:

- Decide in the handler when data is missing before rendering.
- Render a full error page only when it needs the site shell.
- Set streaming HTTP decisions in the handler or, for managed documents, in a layout/Page head hook before publication.
- Check the `bool` returned from response-context mutations in streaming code.
- Use Axum `Redirect` for redirects instead of rendering meta-refresh pages.
- Test `404`, redirect, validation, timeout, and upstream-error paths.

## Next steps

- [Route responses](/docs/framework/responses)
  - Return synchronous, buffered async, or streaming SSR with islands.
- [Data loading and streaming](/docs/framework/data-loading)
  - Load request data, apply cache hints, and stream slow sections with Suspense.
- [Forms and actions](/docs/guides/forms-actions)
  - Handle submissions with Axum and render invalid field state back to the user.
- [Testing](/docs/guides/testing)
  - Unit, snapshot, and integration tests for the paths above.


---

# Docs: Metadata and OG images

URL: /docs/framework/metadata
Description: Add page titles, descriptions, canonical URLs, and social images with render_head.

---
title: Metadata and OG images
sidebar_title: Metadata and OG images
description: Add page titles, descriptions, canonical URLs, and social images with render_head.
---

Set page metadata in `render_head`. Proa turns your `cx.head_mut()` calls into tags at the `{cx.head()}` outlet in your document.

This guide covers setup, request-loaded metadata, layout defaults, and sharing images. For individual setters and their generated HTML, see the [metadata reference](/docs/framework/metadata-reference).

## Add page metadata

Put the hook in the selected Page's `WebRender<L>` implementation. Keep its existing `render(self, cx)` body.

```rust filename="ProductPage"
use proa::{ComponentRole, DataLoader, WebContext, WebRender, WriteError};

impl<L: DataLoader> WebRender<L> for ProductPage {
    const ROLE: ComponentRole = ComponentRole::PAGE;

    async fn render_head(&self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        cx.head_mut().title("Trail Jacket")?;
        cx.head_mut().description("Built for the outdoors.")?;
        Ok(())
    }

    // Keep your existing render(self, cx) implementation.
}
```

```html filename="Generated HTML"
<title>Trail Jacket</title>
<meta name="description" content="Built for the outdoors.">
```

`render_head` is a native async method: mutate `cx` directly and return a `Result`. It needs no attribute or handwritten async block. The examples show the relevant generated tags; other inherited metadata can add more.

For a struct with several fields, use [`cx.head_mut().metadata(HeadMetadata { ... })`](/docs/framework/metadata-reference#apply-a-metadata-object). Omitted fields keep their inherited values.

### Enable managed metadata

Configure a trusted public origin before rendering the document:

```rust filename="Route configuration"
use proa::{HeadConfig, HeadUrlPolicy};
use proa::axum::RouteResponse;

let head = HeadConfig::default()
    .with_urls(HeadUrlPolicy::new("https://shop.example", "/")?);

RouteResponse::ssr_stream(document).with_head(head)
```

Use your configured production or staging origin in place of `https://shop.example`. Proa does not infer it from request headers. The origin resolves canonical, social-image, stylesheet, and module URLs.

To enable metadata for every rendered route, pass the same configuration to the framework builder:

```rust filename="App configuration"
use proa::axum::FrameworkBuilder;

let app = FrameworkBuilder::new()
    .with_head(head)
    .with_dynamic_routes(router)
    .build();
```

Use `.without_head()` on a response that keeps a manual document. Components declaring `ROLE = LAYOUT` or `ROLE = PAGE` must render inside a managed document, even without a head hook. Layouts precede the selected Page and cannot render after sealing or inside Suspense/captures/fallbacks. Use the default `COMPONENT` role for body-only wrappers or manual rendering.

### Place the head outlet

Place `{cx.head()}` where the generated tags belong in your layout's document template:

```rust filename="Document layout"
html! {
    <!DOCTYPE html>
    <html lang="en">
        <head>
            <meta charset="utf-8" />
            <meta name="viewport" content="width=device-width, initial-scale=1" />
            {cx.head()}
        </head>
        <body>{self.page}</body>
    </html>
}
.render(cx)
```

With the Page above, the head contains:

```html filename="Document head"
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Trail Jacket</title>
    <meta name="description" content="Built for the outdoors.">
</head>
```

Charset and viewport come from the template. Proa adds the managed metadata at the outlet; it does not add these manual tags for you. Keep fonts, `<html>` classes, and any other manual tags in the document too. For managed favicons, use [`cx.head_mut().icons(...)`](/docs/framework/metadata-reference#icons).

Each managed document needs exactly one selected Page and one head outlet. Compose the Page through `html!`, `html_sync!`, or framework render helpers. Calling `child.render(cx)` directly calls only its body and skips its hook.

## Load metadata from data

The hook can await the same loader used by the Page body. Here, `ProductPage` has an `id`, `product_key(id)` identifies a product, and the loaded `Product` contains `name` and `summary`.

```rust filename="ProductPage::render_head"
async fn render_head(&self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
    let product = cx.load_typed::<Product>(product_key(self.id)).await?;

    cx.head_mut().title(product.name.clone())?;
    cx.head_mut().description(product.summary.clone())?;
    cx.head_mut().canonical(&format!("/products/{}", self.id))?;
    Ok(())
}
```

For product `42`, named “Trail Jacket” with summary “Built for the outdoors.”:

```html filename="Generated HTML"
<title>Trail Jacket</title>
<meta name="description" content="Built for the outdoors.">
<link rel="canonical" href="https://shop.example/products/42">
```

Head and body share the request, headers, route parameters, and loader. When both need the same value, use a request-scoped `DataResolver` and the same key to reuse one underlying lookup. Request scoping dedupes reads within one request; cache policy beyond that stays with the `DataLoader`. See [Data loading](/docs/framework/data-loading).

## Inherit layout defaults

A layout can supply defaults and a title template. Declare its role as `LAYOUT`:

```rust filename="ShopLayout::render_head"
const ROLE: ComponentRole = ComponentRole::LAYOUT;

async fn render_head(&self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
    cx.head_mut().title("Shop")?;
    cx.head_mut().description("Browse our products.")?;
    cx.head_mut().title_template("%s | Acme")?;
    Ok(())
}
```

The selected Page overrides only the fields it writes:

```rust filename="ProductPage::render_head"
const ROLE: ComponentRole = ComponentRole::PAGE;

async fn render_head(&self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
    cx.head_mut().title("Trail Jacket")?;
    Ok(())
}
```

```html filename="Generated HTML"
<title>Trail Jacket | Acme</title>
<meta name="description" content="Browse our products.">
```

The layout description survives. The Page title replaces the layout title and uses the ancestor's template. Use `absolute_title("Checkout")` to bypass a template, or the [clear methods](/docs/framework/metadata-reference#clear-inherited-metadata) to remove inherited fields.

| Role | Head behavior |
| --- | --- |
| `COMPONENT` (default) | Skips the head method entirely. |
| `LAYOUT` | Runs its hook, then its body; leaves metadata open for the Page. |
| `PAGE` | Runs its hook, seals metadata, then starts its body. |

A Page that only inherits metadata can omit its hook, but it still declares `ROLE = PAGE`. Only the Page establishes the cutoff. Run `cargo proa lint <changed-paths> --deny warnings` to catch async hook overrides with a missing role or an explicit `COMPONENT` role.

### Configure app-wide defaults

Use `with_defaults` for values shared by your routes, then install the configuration using `with_head(...)` on [FrameworkBuilder](/docs/framework/configuration). Here, `routes` is your application's existing Axum router:

```rust filename="App configuration"
use proa::{HeadConfig, HeadUrlPolicy};
use proa::axum::FrameworkBuilder;

let head = HeadConfig::default()
    .with_urls(HeadUrlPolicy::new("https://shop.example", "/")?)
    .with_defaults(|head| {
        head.title_template("%s | Acme")?;
        head.description("Explore the Acme shop.")?;
        Ok(())
    })?;

let app = FrameworkBuilder::new()
    .with_head(head)
    .with_dynamic_routes(routes)
    .build();
```

Page and layout hooks can override these defaults. Call `with_urls` before `with_defaults`: default URLs are resolved when they are configured.

## Add an Open Graph image

Point to an existing image and describe it with `HeadMedia`:

```rust filename="render_head"
use proa::{HeadMedia, OpenGraph};

cx.head_mut().open_graph(
    OpenGraph::new().images([
        HeadMedia::new("/og/trail-jacket.png")
            .mime_type("image/png")
            .alt("Trail Jacket in forest green")
            .dimensions(1200, 630),
    ]),
)?;
```

```html filename="Image tags"
<meta property="og:image" content="https://shop.example/og/trail-jacket.png">
<meta property="og:image:type" content="image/png">
<meta property="og:image:alt" content="Trail Jacket in forest green">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
```

`OpenGraph::new()` enables social metadata. If the document already has a title, description, or canonical URL, Open Graph also emits `og:title`, `og:description`, and `og:url` from those final values. Explicit social values override those fallbacks.

Serve the image through your [static assets](/docs/framework/static-assets) or from any absolute `https` URL. Images do not need `allow_resource_origin`; that allowlist applies to stylesheets and modules. Proa emits the image metadata; it does not generate, resize, or fetch the image. See the reference for [social overrides](/docs/framework/metadata-reference#a-different-social-title), [image replacement](/docs/framework/metadata-reference#replace-inherited-images), and [Twitter cards](/docs/framework/metadata-reference#twitter-cards).

## Metadata and streaming

Proa prepares metadata before starting the selected Page body. It publishes the head when both the Page's sealed metadata and the outlet are available. The outlet records an insertion position; it does not wait for the Page or stop layout rendering.

```text
Layout head → Layout body → Page head → Seal metadata → Page body
```

Do status, redirect, authorization, cookie, and cache decisions before publication. Slow secondary content can stream afterward. A wholly synchronous render cannot yield at publication; expensive body work that needs early delivery belongs in an async component after the outlet.

Page bodies, Suspense children, captures, and loading/error fallbacks cannot add metadata. Late mutations invalidate the managed document even if their `Result` is ignored. An ErrorBoundary can recover within a Page body, but it cannot rewind across head preparation, Page selection, or publication. Cancelled preparation is discarded.

Preparation has a sampled 1 MiB budget and a 30-second streaming deadline. `HeadConfig::with_preparation_limit` adjusts the budget; `ManagedPreparationTimeout` can override the Axum deadline. Serialized head output is limited to 64 KiB. These are cooperative limits, not hard peak-memory guarantees.

## Existing metadata code

`Metadata`, `CascadeValue`, route-spec layouts, and `render_metadata_head` remain available for manual documents. They do not automatically feed the managed head. Move their values into defaults or hooks and replace their emitter with `{cx.head()}`.

The previous `cx.head()` inspection getter is `cx.head_state()`. Managed documents use the checked setters on `cx.head_mut()`; legacy void setters are for manual mode. Existing client-navigation payloads keep their JSON format and resolved title; this API does not add client-side head reconciliation.

## Next steps

- [Layouts and Pages](/docs/framework/layouts-and-pages): role-marked document and page components.
- [Metadata reference](/docs/framework/metadata-reference): mutations with their generated HTML.
- [Data loading](/docs/framework/data-loading): request-scoped loading and reuse.
- [Static assets](/docs/framework/static-assets): serve images, icons, and other files.
- [Headers and CSP](/docs/framework/security-headers): response security policy and nonces.


---

# Docs: Metadata reference

URL: /docs/framework/metadata-reference
Description: See each head mutation and the HTML it generates.

---
title: Metadata reference
description: See each head mutation and the HTML it generates.
---

Use `cx.head_mut()` inside a layout or Page's `render_head` hook. Each example below puts the mutation directly above its generated HTML. See [Metadata and OG images](/docs/framework/metadata) to set up a document.

Examples are independent: they use a fresh managed document, `https://shop.example` as the public origin, `/` as the mount, and no default fields or CSP nonce unless stated otherwise. Output shows only the generated tags, with line breaks added for readability. Charset, viewport, and other manual tags remain in your document template.

## Apply a metadata object

Use `metadata` to set several fields in one call:

```rust filename="render_head"
use proa::HeadMetadata;

cx.head_mut().metadata(HeadMetadata {
    title: "Trail & Travel".into(),
    description: "Built for the outdoors.".into(),
    canonical: "/products/trail-jacket".into(),
    ..Default::default()
})?;
```

```html filename="Generated HTML"
<title>Trail &amp; Travel</title>
<meta name="description" content="Built for the outdoors.">
<link rel="canonical" href="https://shop.example/products/trail-jacket">
```

Every field defaults to `HeadValue::Inherit`. Use `.into()` to set a value and `HeadValue::Clear` to remove an inherited field. The whole patch is validated before any field changes, including URLs and list limits. A normal title uses the nearest ancestor template, just like `title(...)`.

```rust filename="render_head"
use proa::{HeadMetadata, HeadTitle, HeadValue};

cx.head_mut().metadata(HeadMetadata {
    title: HeadTitle::absolute("Checkout").into(),
    description: HeadValue::Clear,
    ..Default::default()
})?;
```

```html filename="Generated HTML"
<title>Checkout</title>
```

This clears any inherited description and bypasses an ancestor title template. Other inherited fields stay in place.

| Field | Value | Inheritance when set |
| --- | --- | --- |
| `title` | `HeadTitle` or a string with `.into()` | Replace; `HeadTitle::absolute` bypasses the template |
| `description`, `title_template`, `canonical` | Text | Replace |
| `open_graph` | `OpenGraph` | Patch individual properties |
| `twitter` | `Twitter` | Patch individual properties |
| `robots`, `googlebot` | `Robots` | Replace the entire directive policy |
| `icons` | `Vec<HeadIcon>` | Replace the entire list |
| `alternates` | `Vec<HeadAlternate>` | Replace the entire list |
| `manifest` | URL text | Replace |
| `authors` | `Vec<HeadAuthor>` | Replace the entire list |
| `application_name`, `creator`, `publisher` | Text | Replace |
| `keywords` | `Vec<Cow<'static, str>>` | Replace the entire list |
| `referrer` | `ReferrerPolicy` | Replace |
| `verification` | `Vec<HeadVerification>` | Replace the entire list |

An empty list removes inherited list entries. Clearing `open_graph` or `twitter` removes the whole inherited object. To suppress one social fallback, use the object's `clear_*` builder method instead. Existing individual setters remain available; migrate old bulk fields such as `title: Some("Shop".into())` to `title: "Shop".into()`.

## Document metadata

### title

Set the document title. Text is escaped when it is written to HTML.

```rust filename="render_head"
cx.head_mut().title("Trail & Travel")?;
```

```html filename="Generated HTML"
<title>Trail &amp; Travel</title>
```

### description

Set the description shown to search engines and link previews.

```rust filename="render_head"
cx.head_mut().description("Lightweight layers for everyday adventures.")?;
```

```html filename="Generated HTML"
<meta name="description" content="Lightweight layers for everyday adventures.">
```

### canonical

Resolve a canonical path against the trusted public origin.

```rust filename="render_head"
cx.head_mut().canonical("/products/trail-jacket")?;
```

```html filename="Generated HTML"
<link rel="canonical" href="https://shop.example/products/trail-jacket">
```

Pass paths relative to the configured public mount. Do not first prefix them with `cx.url(...)`.

### title_template

An ancestor can provide a title template. A descendant supplies the title.

```rust filename="render_head"
// Layout hook
cx.head_mut().title_template("%s | Acme")?;

// Page hook
cx.head_mut().title("Trail Jacket")?;
```

```html filename="Generated HTML"
<title>Trail Jacket | Acme</title>
```

Dynamic routes work the same way: a Page at `/products/:id` or `/blog/:slug` uses `cx.param(...)` to load its display title and passes it to `title(...)` or `metadata(...)`. The template formats that title; it does not infer a title from the URL.

A template must contain exactly one `%s`. The nearest ancestor template applies once. A template set in a hook applies to descendants, not to a title set in that same hook.

### absolute_title

Bypass an inherited title template for this title.

```rust filename="render_head"
// Layout hook
cx.head_mut().title_template("%s | Acme")?;

// Page hook
cx.head_mut().absolute_title("Checkout")?;
```

```html filename="Generated HTML"
<title>Checkout</title>
```

### clear_title_template

Stop a template from being inherited by deeper descendants.

```rust filename="render_head"
// Root layout hook
cx.head_mut().title_template("%s | Acme")?;

// Nested layout hook
cx.head_mut().clear_title_template()?;

// Page hook
cx.head_mut().title("Checkout")?;
```

```html filename="Generated HTML"
<title>Checkout</title>
```

Clearing a template affects descendants. To bypass an ancestor template for a title in the current hook, use `absolute_title`.

## Named meta tags

### meta

Set a named meta tag. Setting the same name again replaces its value; names are matched without case sensitivity.

```rust filename="render_head"
cx.head_mut().meta("robots", "index, follow")?;
cx.head_mut().meta("author", "Acme")?;
```

```html filename="Generated HTML"
<meta name="robots" content="index, follow">
<meta name="author" content="Acme">
```

`description(value)` is shorthand for `meta("description", value)`. Use `open_graph` for Open Graph properties.

### Twitter cards

Use the typed card builder to resolve image URLs and reuse final metadata. These types come from `proa`.

```rust filename="render_head"
cx.head_mut().title("Trail Jacket")?;
cx.head_mut().twitter(
    Twitter::new()
        .card(TwitterCard::SummaryLargeImage)
        .site("@acme")
        .image(HeadMedia::new("/og/trail-jacket.png").alt("Forest green jacket")),
)?;
```

```html filename="Generated HTML"
<title>Trail Jacket</title>
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Trail Jacket">
<meta name="twitter:site" content="@acme">
<meta name="twitter:image" content="https://shop.example/og/trail-jacket.png">
<meta name="twitter:image:alt" content="Forest green jacket">
```

`Twitter::new()` enables a summary card. Title and description fall back to explicit Open Graph values, then the final document values. The image falls back to the first final Open Graph image. Card output is opt-in; Open Graph alone does not enable Twitter tags. `SummaryLargeImage` selects the large image card; this API currently supports summary cards, rather than player or app cards.

Use `.title(...)`, `.description(...)`, `.creator(...)`, `.site_id(...)`, and `.creator_id(...)` to customize the card. `.clear_title()`, `.clear_description()`, and `.clear_image()` suppress fallback values. A descendant patch keeps unspecified parent card properties. `cx.head_mut().clear_twitter()?` removes the whole card.

Named `.meta("twitter:...", value)` overrides the corresponding typed tag without duplication. Named meta values remain text and do not resolve URLs. Setting a typed property again replaces its named override. Overriding `twitter:image` also suppresses the old typed image's alt text.

### Robots directives for a page

Set indexing and preview directives on an individual page:

```rust filename="render_head"
cx.head_mut().robots(Robots {
    index: Some(false),
    follow: Some(true),
    max_image_preview: Some(ImagePreview::Large),
    ..Default::default()
})?;
```

```html filename="Generated HTML"
<meta name="robots" content="noindex, follow, max-image-preview:large">
```

Use `googlebot(Robots { ... })` for a separate `<meta name="googlebot">` policy. Optional directives emit nothing when omitted. `max_snippet` and `max_video_preview` accept `-1` for unlimited or a nonnegative limit. A descendant's policy replaces the parent's entire policy, so directives can be intentionally removed. `clear_robots()` and `clear_googlebot()` remove those tags.

This is separate from `FrameworkBuilder::with_robots(RobotsTxt)`, which serves the site's `/robots.txt`. That file controls which URL paths crawlers may fetch. The HTML meta tag controls indexing and previews for a fetched page. A crawler must be allowed to fetch a page to read its `noindex` tag; disallowing it in `robots.txt` does not guarantee removal from search results. See [Google's page-level directives](https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag) and [robots.txt guide](https://developers.google.com/search/docs/crawling-indexing/robots/intro).

### Icons

Replace the inherited icon list with typed links:

```rust filename="render_head"
cx.head_mut().icons([
    HeadIcon::new("/favicon.svg").sizes("any").mime_type("image/svg+xml"),
    HeadIcon::new("/apple-touch-icon.png").kind(IconKind::AppleTouch).sizes("180x180"),
])?;
```

```html filename="Generated HTML"
<link rel="icon" href="https://shop.example/favicon.svg" sizes="any" type="image/svg+xml">
<link rel="apple-touch-icon" href="https://shop.example/apple-touch-icon.png" sizes="180x180">
```

`IconKind::Mask` emits `rel="mask-icon"`. `.media(...)` and `.color(...)` add optional attributes. Use an empty list or `clear_icons()` to remove inherited icons. URLs are validated and resolved with the trusted public origin and mount.

### Alternate languages and feeds

```rust filename="render_head"
cx.head_mut().alternates([
    HeadAlternate::new("/fr/products/trail-jacket").language("fr"),
    HeadAlternate::new("/products/trail-jacket").language("x-default"),
    HeadAlternate::new("/feed.xml").mime_type("application/rss+xml").title("Shop news"),
])?;
```

```html filename="Generated HTML"
<link rel="alternate" href="https://shop.example/fr/products/trail-jacket" hreflang="fr">
<link rel="alternate" href="https://shop.example/products/trail-jacket" hreflang="x-default">
<link rel="alternate" href="https://shop.example/feed.xml" type="application/rss+xml" title="Shop news">
```

Each alternate can also carry `.media(...)`. Setting alternates replaces the whole inherited list; canonical remains independent. Use `clear_alternates()` to remove the list.

### Manifest

```rust filename="render_head"
cx.head_mut().manifest("/app.webmanifest")?;
```

```html filename="Generated HTML"
<link rel="manifest" href="https://shop.example/app.webmanifest">
```

`clear_manifest()` removes an inherited manifest link.

### Authors, application details, and verification

```rust filename="render_head"
cx.head_mut().metadata(HeadMetadata {
    application_name: "Acme Shop".into(),
    authors: vec![HeadAuthor::new("Alex").url("/authors/alex")].into(),
    referrer: ReferrerPolicy::StrictOriginWhenCrossOrigin.into(),
    verification: vec![HeadVerification::google("verification-token")].into(),
    ..Default::default()
})?;
```

```html filename="Generated HTML"
<meta name="application-name" content="Acme Shop">
<meta name="referrer" content="strict-origin-when-cross-origin">
<meta name="author" content="Alex">
<link rel="author" href="https://shop.example/authors/alex">
<meta name="google-site-verification" content="verification-token">
```

`authors([...])` and `verification([...])` replace their entire inherited lists. Multiple authors and verification tokens emit multiple tags. `HeadVerification::new("msvalidate.01", token)` supports other verification providers; reserved document and Twitter names are rejected. `application_name`, `creator`, `publisher`, `keywords`, and `referrer` also have individual setters. Named `.meta(...)` calls override the corresponding typed author or verification name without duplication; `remove_meta(...)` suppresses it.

### Clear inherited metadata

Clear only the inherited fields you want to remove. Other metadata stays in place.

```rust filename="render_head"
// Layout hook
cx.head_mut().title("Shop")?;
cx.head_mut().description("Browse our products.")?;
cx.head_mut().canonical("/products")?;
cx.head_mut().meta("robots", "noindex")?;
cx.head_mut().meta("author", "Acme")?;

// Page hook
cx.head_mut().clear_title()?;
cx.head_mut().clear_description()?;
cx.head_mut().clear_canonical()?;
cx.head_mut().remove_meta("robots")?;
```

```html filename="Generated HTML"
<meta name="author" content="Acme">
```

`clear_title`, `clear_description`, `clear_canonical`, and `remove_meta` suppress inherited values. Omitting a mutation keeps the inherited value.

## Open Graph

Use `OpenGraph` and `HeadMedia` from `proa` for these builders.

### open_graph

Enable Open Graph and reuse the final document title, description, and canonical URL.

```rust filename="render_head"
cx.head_mut().title("Trail Jacket")?;
cx.head_mut().description("Built for the outdoors.")?;
cx.head_mut().canonical("/products/trail-jacket")?;
cx.head_mut().open_graph(
    OpenGraph::new().kind("product").site_name("Acme"),
)?;
```

```html filename="Generated HTML"
<title>Trail Jacket</title>
<meta name="description" content="Built for the outdoors.">
<link rel="canonical" href="https://shop.example/products/trail-jacket">
<meta property="og:title" content="Trail Jacket">
<meta property="og:description" content="Built for the outdoors.">
<meta property="og:url" content="https://shop.example/products/trail-jacket">
<meta property="og:site_name" content="Acme">
<meta property="og:type" content="product">
```

Open Graph is opt-in. `OpenGraph::new()` enables it. Unspecified title, description, and URL fall back to the final document fields at emission; a templated title includes its template.

### A different social title

Set an Open Graph title without changing the document title.

```rust filename="render_head"
cx.head_mut().title("Trail Jacket")?;
cx.head_mut().open_graph(
    OpenGraph::new().title("Meet your new everyday jacket"),
)?;
```

```html filename="Generated HTML"
<title>Trail Jacket</title>
<meta property="og:title" content="Meet your new everyday jacket">
```

### Open Graph images

Describe an existing image with its URL, alternative text, and dimensions.

```rust filename="render_head"
cx.head_mut().open_graph(
    OpenGraph::new().images([
        HeadMedia::new("/og/trail-jacket.png")
            .mime_type("image/png")
            .alt("Trail Jacket in forest green")
            .dimensions(1200, 630),
    ]),
)?;
```

```html filename="Generated HTML"
<meta property="og:image" content="https://shop.example/og/trail-jacket.png">
<meta property="og:image:type" content="image/png">
<meta property="og:image:alt" content="Trail Jacket in forest green">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
```

Import `HeadMedia` and `OpenGraph` from `proa`. Proa resolves the image URL and emits its metadata; it does not generate or resize the image. `secure_url(...)` adds an optional `og:image:secure_url`.

### Replace inherited images

An images list replaces the whole inherited list.

```rust filename="render_head"
// Layout hook
cx.head_mut().open_graph(
    OpenGraph::new().images([HeadMedia::new("/og/shop.png")]),
)?;

// Page hook
cx.head_mut().open_graph(
    OpenGraph::default().images([HeadMedia::new("/og/trail-jacket.png")]),
)?;
```

```html filename="Generated HTML"
<meta property="og:image" content="https://shop.example/og/trail-jacket.png">
```

`OpenGraph::default()` is a patch: it changes only the supplied fields. It does not enable a previously disabled graph. Use `images([])` to remove inherited images.

### Open Graph locales

Set a primary locale and alternate locales.

```rust filename="render_head"
cx.head_mut().open_graph(
    OpenGraph::new()
        .locale("en_US")
        .alternate_locales(["fr_FR", "es_ES"]),
)?;
```

```html filename="Generated HTML"
<meta property="og:locale" content="en_US">
<meta property="og:locale:alternate" content="fr_FR">
<meta property="og:locale:alternate" content="es_ES">
```

The alternate locale list replaces the whole inherited list. Pass an empty typed list, such as `[] as [&str; 0]`, to clear it.

### Audio and video

Audio and video use the same `HeadMedia` records as images.

```rust filename="render_head"
cx.head_mut().open_graph(
    OpenGraph::new()
        .audio([HeadMedia::new("/media/trail.mp3").mime_type("audio/mpeg")])
        .video([HeadMedia::new("/media/trail.mp4").dimensions(1280, 720)]),
)?;
```

```html filename="Generated HTML"
<meta property="og:audio" content="https://shop.example/media/trail.mp3">
<meta property="og:audio:type" content="audio/mpeg">
<meta property="og:video" content="https://shop.example/media/trail.mp4">
<meta property="og:video:width" content="1280">
<meta property="og:video:height" content="720">
```

Each audio or video list replaces its inherited list. Related properties stay with their media record.

### Clear an Open Graph fallback

Explicitly clear a social field to suppress its fallback while leaving the document field alone.

```rust filename="render_head"
cx.head_mut().title("Trail Jacket")?;
cx.head_mut().description("Built for the outdoors.")?;
cx.head_mut().open_graph(OpenGraph::new().clear_title())?;
```

```html filename="Generated HTML"
<title>Trail Jacket</title>
<meta name="description" content="Built for the outdoors.">
<meta property="og:description" content="Built for the outdoors.">
```

An omitted social field inherits or falls back; a cleared field stays absent. The same pattern applies to `clear_description`, `clear_url`, `clear_site_name`, `clear_determiner`, `clear_kind`, and `clear_locale` on `OpenGraph`.

### Disable Open Graph

Suppress the whole graph without changing ordinary document metadata.

```rust filename="render_head"
cx.head_mut().title("Checkout")?;
cx.head_mut().open_graph(OpenGraph::new().kind("website"))?;
cx.head_mut().open_graph(OpenGraph::default().enabled(false))?;
```

```html filename="Generated HTML"
<title>Checkout</title>
```

### Article metadata

```rust filename="render_head"
cx.head_mut().open_graph(OpenGraph::new().article(ArticleMetadata {
    published_time: Some("2026-10-30T12:00:00Z".into()),
    authors: vec!["/authors/alex".into()],
    tags: vec!["Rust".into(), "Web".into()],
    ..Default::default()
}))?;
```

```html filename="Generated HTML"
<meta property="og:type" content="article">
<meta property="article:published_time" content="2026-10-30T12:00:00Z">
<meta property="article:author" content="https://shop.example/authors/alex">
<meta property="article:tag" content="Rust">
<meta property="article:tag" content="Web">
```

`article(...)` selects `og:type="article"` and replaces the inherited article object. It also accepts `modified_time`, `expiration_time`, and `section`. Author values are profile URLs. Provide valid timestamp text; Proa validates text size and escaping, not timestamp syntax. `clear_article()` removes article properties. Article properties emit only while the final Open Graph type is `article`.

## Stylesheets and scripts

### stylesheet

Register a stylesheet in a typed resource slot.

```rust filename="render_head"
#[derive(PartialEq, Eq)]
enum Style { Theme }

cx.head_mut().stylesheet(Style::Theme, "/styles/theme.css")?;
```

```html filename="Generated HTML"
<link rel="stylesheet" href="https://shop.example/styles/theme.css">
```

### Replace a stylesheet

Writing the same slot again changes its URL without emitting a second tag.

```rust filename="render_head"
#[derive(PartialEq, Eq)]
enum Style { Theme }

cx.head_mut().stylesheet(Style::Theme, "/styles/base.css")?;
cx.head_mut().stylesheet(Style::Theme, "/styles/shop.css")?;
```

```html filename="Generated HTML"
<link rel="stylesheet" href="https://shop.example/styles/shop.css">
```

A slot is identified by its resource family, enum type, and variant. Different slots may intentionally use the same URL.

### module

Register an external module script.

```rust filename="render_head"
#[derive(PartialEq, Eq)]
enum Script { Site }

cx.head_mut().module(Script::Site, "/scripts/site.js")?;
```

```html filename="Generated HTML"
<script type="module" src="https://shop.example/scripts/site.js"></script>
```

When a CSP nonce is installed before managed-head initialization, Proa adds it to resource tags automatically. The output above assumes no nonce.

### Remove a resource

Remove a stylesheet or module by its slot key.

```rust filename="render_head"
#[derive(PartialEq, Eq)]
enum Style { Theme }
#[derive(PartialEq, Eq)]
enum Script { Site }

cx.head_mut().stylesheet(Style::Theme, "/styles/theme.css")?;
cx.head_mut().module(Script::Site, "/scripts/site.js")?;
cx.head_mut().remove_stylesheet(Style::Theme)?;
cx.head_mut().remove_module(Script::Site)?;
cx.head_mut().title("Checkout")?;
```

```html filename="Generated HTML"
<title>Checkout</title>
```

Removal preserves the slot position if a descendant fills it again. Only the title remains in this example.

## URL resolution

### Application URL composition

Use `cx.url(path)` to explicitly apply the application base path to a URL in an HTML attribute or Markdown link. The helper writes the shared prefix and borrowed path directly to the output buffer without creating a concatenated `String`.

```rust filename="Component body"
let product_url = cx.url("/products/42");

html_sync! {
    <a href={product_url}>"View product"</a>
}
.render(cx)
```

With application base path `/shop`, this produces:

```html filename="Generated HTML"
<a href="/shop/products/42">View product</a>
```

Plain URL strings in templates stay unchanged. Absolute URLs, protocol-relative URLs, document-relative paths, queries, and fragments pass through `cx.url(...)` without adding the base path. Pass an unprefixed application path to avoid applying the prefix twice. `cx.request()` remains the accessor for incoming request metadata, including headers, location, and route parameters.

Metadata URL setters currently accept strings and resolve them using the separately configured `HeadUrlPolicy` below. Do not convert a `cx.url(...)` value to a string and then feed it through a metadata policy that applies the same mount again.

### Planned dynamic segments and metadata URLs

Appending dynamic values with `.segment(...)` and passing the resulting typed value directly to `canonical(...)` are proposed and are not yet implemented. `cx.url(path)` itself is available today.

The proposed segment API builds on the context helper. For a dynamic product ID:

```rust filename="Proposed render_head API (not yet implemented)"
let product_url = cx.url("/products").segment(self.id);
cx.head_mut().canonical(product_url)?;
```

With public origin `https://shop.example`, application base path `/shop`, and `self.id = 42`, the expected output is:

```html filename="Expected HTML once implemented"
<link rel="canonical" href="https://shop.example/shop/products/42">
```

`.segment(value)` would append and percent-encode one path segment. For example, `.segment("red/blue")` would append `red%2Fblue`, preserving the slash as part of the slug. Fixed paths would use `cx.url("/products/42")` directly.

The same typed value is intended to work in ordinary URL attributes:

```rust filename="Proposed template API (not yet implemented)"
let product_url = cx.url("/products").segment(self.id);

html_sync! {
    <a href={product_url}>"View product"</a>
}
```

```html filename="Expected HTML once implemented"
<a href="/shop/products/42">View product</a>
```

Dynamic segment composition is intended to preserve the direct-buffer approach, with URL validation, segment encoding, and allocation tests. Metadata retains an owned, validated URL, so its storage can still allocate. A composed application URL would carry its prefix through to metadata without applying the mount a second time.

### URL base and mount

Configure metadata URL resolution once at application startup, then pass the resulting `HeadConfig` to [FrameworkBuilder](/docs/framework/configuration) with `with_head(...)`. The builder makes this policy available to the rendered routes' `cx.head_mut()` setters. Creating the configuration alone does not install it.

In this example, `routes` is your application's Axum `Router`. Both the framework and metadata policy use the same `/shop` mount:

```rust filename="App configuration"
use proa::{HeadConfig, HeadUrlPolicy};
use proa::axum::{BasePath, FrameworkBuilder};

let mount = "/shop";
let head = HeadConfig::default()
    .with_urls(HeadUrlPolicy::new("https://shop.example", mount)?);

let app = FrameworkBuilder::new()
    .with_base_path(BasePath::new(mount)?)
    .with_head(head)
    .with_dynamic_routes(routes)
    .build();
```

Inside a Page or layout's head hook, paths now resolve using that installed policy:

```rust filename="render_head"
cx.head_mut().canonical("/products/trail-jacket")?;
```

```html filename="Generated HTML"
<link rel="canonical" href="https://shop.example/shop/products/trail-jacket">
```

The leading `/` is still relative to the configured mount. Configure `HeadUrlPolicy::new(public_origin, mount)` before `with_defaults`: defaults resolve URLs immediately.

Currently, this mount is configured separately from `FrameworkBuilder::with_base_path(...)`; the builder does not automatically pass its base path into the head URL policy. Keep both configurations aligned for a mounted application. Inside a component, `cx.request().base_path().as_str()` reads the configured application prefix (`""` at the origin root).

### External resource origins

This is also application startup configuration for [FrameworkBuilder](/docs/framework/configuration). Stylesheets and modules registered through `cx.head_mut()` must come from the public origin or an allowed resource origin. Allow a CDN origin in the policy, then install it with `with_head(...)` before serving your routes. `routes` is your application's existing Axum router:

```rust filename="App configuration"
use proa::{HeadConfig, HeadUrlPolicy};
use proa::axum::FrameworkBuilder;

let urls = HeadUrlPolicy::new("https://shop.example", "/")?
    .allow_resource_origin("https://cdn.example")?;
let head = HeadConfig::default().with_urls(urls);

let app = FrameworkBuilder::new()
    .with_head(head)
    .with_dynamic_routes(routes)
    .build();
```

A Page or layout can then register a stylesheet from the allowed CDN:

```rust filename="render_head"
#[derive(PartialEq, Eq)]
enum Style { Theme }

cx.head_mut().stylesheet(Style::Theme, "https://cdn.example/styles/theme.css")?;
```

```html filename="Generated HTML"
<link rel="stylesheet" href="https://cdn.example/styles/theme.css">
```

The allowlist permits registration; it does not register or fetch the resource itself. `RouteResponse::with_head(head)` can install a head configuration for an individual response instead of using app-wide builder configuration.

Images, audio, video, canonical URLs, `og:url`, Twitter images, icons, alternate links, manifests, and author URLs do not use this allowlist. They accept a mount-relative path or any absolute `http` or `https` URL that has a host and carries no credentials.

The public origin comes from trusted application configuration, including staging configuration. It is never inferred from `Host` or forwarded headers. Proa resolves and validates these URLs; it does not fetch resources.

## Other head tags

Keep charset, viewport, fonts, and other manual tags in the document's `html!` or `html_sync!` template, next to `{cx.head()}`. Proa does not parse or deduplicate manual tags. Use the typed icon setters above for managed favicons. There is no automatic favicon or Open Graph image file convention. Do not also emit a manual icon for the same purpose unless you intend both links.

## When mutations are allowed

Set metadata in `render_head` or in `HeadConfig::with_defaults`. A Page declares `ROLE = PAGE` and seals metadata before its body. An ancestor that supplies metadata declares `ROLE = LAYOUT`. Ordinary `COMPONENT` values skip head invocation.

These mutations also work in synchronous hooks returning `impl SyncHeadOperation` on `WebRenderSync`. Send components use `render_head_send` (or `render_head_send_sync` for synchronous rendering); an async Send hook must produce a Send future.

Page bodies, Suspense children, captures, and loading/error fallbacks cannot mutate metadata. A late mutation returns an error and invalidates the managed document, even if its `Result` is ignored. Invalid field values fail atomically and may be handled within a hook.

Each managed document needs one Page and one head outlet. Raw `child.render(cx)` calls render only the body; use template composition or framework render helpers for lifecycle dispatch. Run `cargo proa lint <changed-paths> --deny warnings` to catch async head overrides with missing roles or an explicit `COMPONENT` role. Synchronous hooks also retain a code-generation role assertion.

[Metadata and OG images](/docs/framework/metadata) · [Data loading](/docs/framework/data-loading) · [Headers and CSP](/docs/framework/security-headers)


---

# Docs: Data loading and streaming

URL: /docs/framework/data-loading
Description: Dedupe server loads, seed the browser query cache, apply cache policy, and stream slow page sections with Suspense.

---
title: Data loading and streaming
description: Dedupe server loads, seed the browser query cache, apply cache policy, and stream slow page sections with Suspense.
keywords: [DataLoader, DataResolver, loader]
---

Data loading is simple when a route owns one query. It becomes an architectural problem when a page grows into a tree of independent components: several components may need the same record, parent components start plumbing data they do not use, and uncoordinated fetches create duplicate database work or request waterfalls.

Proa's opinionated model lets components declare data by stable identity while one request-scoped resolver shares repeated reads. Independent `Suspense` boundaries can load concurrently, and origin and cache policy stay behind one `DataLoader` interface.

## Server Data Pipeline

The complete server path fits into four files. Use the file tabs to follow one product request from its stable key to the rendered page:

<CodeExplorer>


<CodeFile name="src/data/loader.rs">


```rust
use std::future::Future;

use bytes::Bytes;
use proa::{DataLoader, LoadError, LoadRequest, LoadValue};

#[derive(Clone)]
pub struct AppLoader {
    // db: sqlx::PgPool,
    // http: reqwest::Client,
}

impl DataLoader for AppLoader {
    fn load(
        &self,
        request: &LoadRequest,
    ) -> impl Future<Output = Result<LoadValue, LoadError>> + Send {
        let key = request.key().to_string();

        async move {
            match key.as_str() {
                "product:sku_1" => {
                    let json = r#"{"title":"Trail Shoe","price_cents":12900}"#;
                    Ok(LoadValue::bytes(Bytes::from_static(json.as_bytes())))
                }
                _ => Err(LoadError::custom(format!("unknown load key: {key}"))),
            }
        }
    }
}
```

</CodeFile>


<CodeFile name="src/data/product.rs">


```rust
use proa::LoadKey;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Product {
    pub title: String,
    pub price_cents: u32,
}

pub fn product_key(id: &str) -> LoadKey {
    LoadKey::named("product", id)
}

pub fn recommendations_key(id: &str) -> LoadKey {
    LoadKey::typed("recommendations", id)
}
```

</CodeFile>


<CodeFile name="src/components/product_page.rs">


```rust
use std::future::Future;

use proa::{
    DataLoader, RenderOutcome, WebContext, WebRender, WriteError,
};
use proa::html;

use crate::data::product::{product_key, Product};

pub struct ProductPage {
    pub id: &'static str,
}

impl<L: DataLoader> WebRender<L> for ProductPage {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let product: Product = cx.load_json(product_key(self.id)).await?;

            html! {
                <main>
                    <h1>{product.title.as_str()}</h1>
                    <p>{proa::text!("{} cents", product.price_cents)}</p>
                </main>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

</CodeFile>


<CodeFile name="src/routes/products.rs">


```rust
use std::sync::Arc;

use proa::axum::RouteResponse;
use proa::stream::DataResolver;

use crate::{
    components::product_page::ProductPage,
    data::loader::AppLoader,
};

pub async fn product_handler() -> impl axum::response::IntoResponse {
    let app_loader = Arc::new(AppLoader {});
    let loader = DataResolver::request_scope(app_loader);

    RouteResponse::ssr_async_with_loader(ProductPage { id: "sku_1" }, loader)
}
```

</CodeFile>


</CodeExplorer>


## Why Keyed Loading

![](/static/images/docs/data-loader-request-dedupe.svg "Three components share one origin load through a stable key and request-scoped DataResolver")

**Prefer keyed loading through `WebContext`.** It keeps data requirements beside the components that own them while preventing repeated database or API work. Loading in the handler remains useful when one fetch has one clear owner and rendering cannot begin without it.

| Pattern | Use it when |
|---------|-------------|
| Keyed load through `WebContext` **(preferred)** | Data may be used by multiple components, should dedupe, or can stream independently. |
| Load in the Axum handler | One fetch has one clear owner and rendering cannot begin without it. |

The model draws from [Haxl's](https://simonmar.github.io/bib/papers/haxl-icfp14.pdf) request-scoped deduplication and [TanStack Query's](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys) keyed browser cache. Proa uses explicit concurrency and does not automatically batch distinct keys.

## How It Works

`LoadKey` identifies a resource, `DataLoader` fetches it and owns cache policy, and `DataResolver` shares repeated same-key loads across every component in one render. Use `LoadKey::named` for string ids or `LoadKey::typed` for values that implement `Hash`; `LoadValue` can carry JSON, raw bytes, or a typed Rust value.

A later request loads the resource again unless the `DataLoader` adds cross-request caching with `StandardDataLoader` or a custom shared cache. `LoadHints` can direct cache policies supported by that loader. Components request values through `WebContext` from inside `WebRender`. See [Data caching](/docs/framework/caching).

## Continue The Data Into The Browser

Server and browser caching are separate layers with an explicit handoff. `LoadKey` and `DataResolver` coordinate work while producing the response. If an interactive island needs to keep observing that data, pass the loaded value to `rsjs::query_with_initial(...)`. RSJS serializes it once into the response's query seed table, then installs it in the page-scoped browser cache under a structural `QueryKey`.

| Phase | Identity and owner | What is shared |
|-------|--------------------|----------------|
| Server render | `LoadKey` through one request-scoped `DataResolver` | Origin work across server components |
| HTML handoff | `query_with_initial(...)` | The server result becomes the browser's initial query value |
| Hydrated page | `QueryKey` through the RSJS query cache | Cached data and one in-flight fetch across islands |
| Browser mutation | Mutation invalidation keys | Fresh data is refetched for every observer of the affected query |

Keep the same logical namespace and id on both sides—for example, `product` plus `sku_1`—but remember that `LoadKey` and `QueryKey` are different types with different lifetimes. Proa does not expose the server loader to the browser. The `query_with_initial(...)` call is the deliberate bridge.

<CodeExplorer>


<CodeFile name="src/components/product_price.rs">


```rust
use std::future::Future;

use proa::{
    DataLoader, RenderOutcome, WebContext, WebRender, WriteError,
};

use crate::data::product::{product_key, Product};

pub struct ProductPrice;

#[rsjs::rsjs(component, client)]
impl<L: DataLoader> WebRender<L> for ProductPrice {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let initial: Product = cx.load_json(product_key("sku_1")).await?;
            let product: rsjs::Query<Product> = rsjs::query_with_initial(
                rsjs::QueryKey::new(("product", "sku_1")),
                initial,
                rsjs::FetchRequest {
                    url: "/api/products/sku_1",
                    apply_base_path: true,
                    response: Some(rsjs::ResponseKind::Json),
                    ..Default::default()
                },
                rsjs::QueryOptions {
                    stale_time_ms: 30_000,
                    refetch_on_focus: true,
                    ..Default::default()
                },
            );

            proa::html! {
                <article aria-live="polite">
                    <h2>{product.data().title}</h2>
                    <p>{product.data().price_cents}" cents"</p>
                    <button
                        type="button"
                        disabled={product.is_refetching()}
                        on_click={|_| product.refetch()}
                    >
                        {if product.is_refetching() { "Refreshing..." } else { "Refresh" }}
                    </button>
                </article>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

</CodeFile>


<CodeFile name="src/components/product_editor.rs">


```rust
use std::future::Future;

use proa::{
    DataLoader, RenderOutcome, WebContext, WebRender, WriteError,
};

pub struct ProductEditor;

#[rsjs::rsjs(component, client)]
impl<L: DataLoader> WebRender<L> for ProductEditor {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let restock = rsjs::mutation::<i64, ()>(
                // Identity of this mutation and its reactive state.
                rsjs::QueryKey::new(("product", "sku_1", "restock")),
                rsjs::FetchRequest {
                    url: "/api/products/sku_1/stock",
                    apply_base_path: true,
                    method: Some(rsjs::HttpMethod::Patch),
                    credentials: Some(rsjs::FetchCredentials::SameOrigin),
                    response: Some(rsjs::ResponseKind::Empty),
                    ..Default::default()
                },
                // Query cache entries to refetch after a successful restock.
                &[rsjs::QueryKey::new(("product", "sku_1"))],
            );

            proa::html! {
                <button
                    type="button"
                    disabled={restock.is_pending()}
                    on_click={|_| restock.run(1_i64)}
                >
                    {if restock.is_pending() { "Saving..." } else { "Add inventory" }}
                </button>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

</CodeFile>


</CodeExplorer>


The mutation key identifies the write operation; the invalidation list names the query keys whose cached data is stale after that write succeeds.

This gives the page several useful properties:

- **Useful HTML immediately.** The first paint contains real data and does not wait for a browser fetch or hydration.
- **No throwaway bootstrap request.** The value loaded for SSR seeds the query cache; the browser refetches according to staleness policy rather than starting from an empty cache.
- **Deduplication in both environments.** Server components share one origin load per `LoadKey`; hydrated islands share one cache entry and one in-flight browser request per `QueryKey`.
- **Local ownership without prop plumbing.** A component can declare the data it needs on the server and the freshness behavior it needs in the browser.
- **Built-in freshness tools.** Queries support staleness windows, retries, polling, focus refetching, manual refetching, and shared invalidation after mutations.
- **Private origins stay private.** The server loader can use a database or internal service directly, while browser refreshes go through an authenticated public HTTP endpoint.
- **JavaScript stays scoped.** Static consumers remain server-only; Proa includes the RSJS query runtime only when rendered browser work actually uses a query or mutation.

The browser endpoint must return the same serialized shape used for the initial value. Mutations should invalidate the structural query keys whose data they changed. See [Queries and mutations](/docs/rsjs/queries-mutations) for retries, polling, progress, streaming text, mutation state, and cache lifetime details.

## JSON, Bytes, And Typed Values

Choose the `WebContext` load helper that matches the value shape:

| Helper | Loader value | Use it for |
|--------|--------------|------------|
| `cx.load_json::<T>(key)` | `LoadValue::bytes(...)` | JSON data that should deserialize into `T`. |
| `cx.load_bytes(key)` | `LoadValue::bytes(...)` | Raw bytes such as pre-rendered fragments or API payloads. |
| `cx.load_typed::<T>(key)` | `LoadValue::typed(value)` | Already-materialized Rust values stored in a loader or cache. |

Typed values return `Arc<T>`, so multiple components can share the same materialized value without cloning a large structure.

## Cache Hints

`LoadHints` carry advisory policy without changing the identity of the data:

```rust
use std::time::Duration;

use proa::{CacheHint, CacheMode, LoadHints, LoadKey};

let product = cx
    .load_json_with::<Product>(
        LoadKey::named("product", "sku_1"),
        LoadHints::new().with_cache(
            CacheHint::ttl(Duration::from_secs(30)).with_mode(CacheMode::Refresh),
        ),
    )
    .await?;
```

Your loader can honor the hints, ignore them, or map them onto its own cache rules. See [Data caching](/docs/framework/caching) for the full cache-boundary model.

## Cross-Request Cache

For a simple in-process cache, wrap an upstream loader with `StandardDataLoader`:

```rust
use std::sync::Arc;
use std::time::Duration;

use proa::StandardDataLoader;

let upstream = AppLoader {};
let cached = Arc::new(StandardDataLoader::new(upstream, Duration::from_secs(30)));
```

`StandardDataLoader` caches by `LoadKey`, applies the request TTL hint when present, and supports manual invalidation with `invalidate(&key)` or `clear()`.

Use a process-local cache only when that matches your deployment model. For horizontally scaled apps, put shared cache policy in Redis, your database, your CDN, or the origin service. See [Data caching](/docs/framework/caching) for loader invalidation and [Page caching](/docs/framework/page-caching) for HTTP header patterns.

## Streaming Slow Sections

Use `RouteResponse::ssr_stream_with_loader` and `Suspense` when a page has a fast shell plus independent slow sections:

```rust
use proa::{html, html_sync};
use proa::stream::Suspense;

pub async fn product_handler() -> impl axum::response::IntoResponse {
    let loader = DataResolver::request_scope(Arc::new(AppLoader {}));

    RouteResponse::ssr_stream_with_loader(
        html! {
            <main>
                <h1>"Product"</h1>
                {Suspense::new(
                    Recommendations { product_id: "sku_1" },
                    html_sync! { <section>"Loading recommendations"</section> },
                )}
            </main>
        },
        loader,
    )
}
```

The fallback renders into the shell immediately. The child renders when its future completes. Streaming responses default to out-of-order chunked rendering.

Out-of-order boundaries can opt into scheduling metadata:

```rust
use std::time::Duration;

use proa::Priority;

let recommendations = Suspense {
    child: Recommendations { product_id: "sku_1" },
    fallback: html_sync! { <section>"Recommendations unavailable"</section> },
    priority: Priority::Optional,
    timeout: Some(Duration::from_millis(750)),
};
```

All boundary futures start concurrently. Priority is a deterministic tie-break when multiple boundaries are ready in the same driver turn: `Critical`, then `Optional`, then `Defer`, with boundary id breaking equal-priority ties. It does not delay lower-priority work.

The timeout starts when the driver admits the boundary after rendering the shell. If it expires, Proa cancels that future, emits `<!--proa:timeout:N-->` for observability, preserves the shell fallback, and continues closing the response. The default framework adapter uses Tokio time. Runtime-independent hosts can drive `proa::stream::driver::out_of_order::OutOfOrderBoundaryDriver::next_deadline()` and `expire(now)` with their own clock; the clockless convenience adapter expires configured timeouts at admission rather than silently allowing an unbounded wait.

Buffered/static HTML, in-order HTML, and Markdown preserve source order and intentionally ignore both options. Cancelling an in-order child after it flushes could otherwise leave partial markup on the wire.

## Streaming Markdown Output

`Suspense` also works in Markdown render trees. Use this when a route or adapter should return generated `text/markdown` for agents, CLI clients, feeds, or high-density text views.

The low-level driver lives in `proa_stream`:

```rust
use std::{rc::Rc, sync::Arc};

use proa::{DataLoader, MdRender, StreamChunkFlusher, WriteError};
use proa::stream::render_md_in_order_to_flusher_with_loader;

pub async fn render_markdown<L: DataLoader, R: MdRender<L>>(
    page: R,
    loader: Arc<L>,
    flusher: Rc<dyn StreamChunkFlusher>,
) -> Result<(), WriteError> {
    render_md_in_order_to_flusher_with_loader(page, loader, flusher).await
}
```

The driver renders the root through `WebContext<L>` in in-order mode with the supplied request-scoped loader, flushes parent Markdown before each streamed `Suspense` boundary, renders the child into the same buffer, then continues the document in order. Markdown-local state such as blank-line tracking is carried across the child boundary so streamed output matches buffered output.

Markdown `Suspense` boundaries preserve document order. The fallback is an HTML shell concern and is not emitted by the Markdown stream driver.

## Preload Known Keys

If you already know which keys a streamed route will need, start them before the component tree reaches each boundary.

On the typed path, wrap the loader explicitly:

```rust
use std::sync::Arc;

use proa::LoadKey;
use proa::stream::{DataResolver, PreparedLoader};

let app_loader = Arc::new(AppLoader {});
let resolver = DataResolver::request_scope(app_loader);
let loader = Arc::new(PreparedLoader::new_typed(
    resolver,
    [
        LoadKey::named("product", "sku_1"),
        LoadKey::named("recommendations", "sku_1"),
    ],
));

RouteResponse::ssr_stream_with_loader(ProductPage { id: "sku_1" }, loader)
```

On the dyn path, use the response helper:

```rust
RouteResponse::ssr_stream_with_loader_dyn(ProductPage { id: "sku_1" }, loader)
    .with_preload_keys([LoadKey::named("product", "sku_1")])
```

Use `with_preload_requests(...)` when a preload needs cache hints.

## Pipeline CPU-Bound Work

`DataLoader` can coordinate expensive computation as well as I/O. If independent components need cryptographic verification, compression, image processing, or similar CPU-heavy results, route that work through a bounded application pipeline instead of running it on Tokio's async worker threads.

The complete pipeline spans five files. Use the tabs to follow a verification request from the component, through `DataLoader`, into the bounded CPU worker pipeline:

<CodeExplorer>


<CodeFile name="src/data/crypto_pipeline.rs">


```rust
use std::sync::Arc;

use tokio::sync::{mpsc, oneshot};
use tokio::task::JoinSet;

#[derive(Debug)]
pub struct Verification {
    pub valid: bool,
}

type CryptoResult = Result<Verification, String>;
type CryptoFn = dyn Fn(Vec<u8>) -> CryptoResult + Send + Sync;

struct CryptoJob {
    input: Vec<u8>,
    reply: oneshot::Sender<CryptoResult>,
}

#[derive(Clone)]
pub struct CryptoPipeline {
    tx: mpsc::Sender<CryptoJob>,
}

impl CryptoPipeline {
    pub fn start<F>(parallelism: usize, work: F) -> Self
    where
        F: Fn(Vec<u8>) -> CryptoResult + Send + Sync + 'static,
    {
        assert!(parallelism > 0);
        let (tx, mut rx) = mpsc::channel::<CryptoJob>(parallelism * 2);
        let work: Arc<CryptoFn> = Arc::new(work);

        tokio::spawn(async move {
            let mut running = JoinSet::new();

            loop {
                tokio::select! {
                    Some(job) = rx.recv(), if running.len() < parallelism => {
                        let work = Arc::clone(&work);
                        running.spawn_blocking(move || {
                            let result = work(job.input);
                            let _ = job.reply.send(result);
                        });
                    }
                    Some(_) = running.join_next(), if !running.is_empty() => {}
                    else => break,
                }
            }

            while running.join_next().await.is_some() {}
        });

        Self { tx }
    }

    pub async fn run(&self, input: Vec<u8>) -> CryptoResult {
        let (reply, result) = oneshot::channel();
        self.tx
            .send(CryptoJob { input, reply })
            .await
            .map_err(|_| "crypto pipeline stopped".to_owned())?;
        result
            .await
            .map_err(|_| "crypto worker stopped".to_owned())?
    }
}
```

</CodeFile>


<CodeFile name="src/data/loader.rs">


```rust
use std::collections::HashMap;
use std::future::Future;
use std::sync::Arc;

use proa::{DataLoader, LoadError, LoadKey, LoadRequest, LoadValue};

use super::crypto_pipeline::CryptoPipeline;

pub fn verification_key(document_id: &str) -> LoadKey {
    LoadKey::named("verification", document_id)
}

#[derive(Clone)]
pub struct AppLoader {
    documents: Arc<HashMap<String, Vec<u8>>>,
    crypto: CryptoPipeline,
}

impl AppLoader {
    pub fn new(documents: HashMap<String, Vec<u8>>, crypto: CryptoPipeline) -> Self {
        Self {
            documents: Arc::new(documents),
            crypto,
        }
    }
}

impl DataLoader for AppLoader {
    fn load(
        &self,
        request: &LoadRequest,
    ) -> impl Future<Output = Result<LoadValue, LoadError>> + Send {
        let documents = Arc::clone(&self.documents);
        let crypto = self.crypto.clone();
        let key = request.key().to_string();

        async move {
            let id = key
                .strip_prefix("verification:")
                .ok_or_else(|| LoadError::custom(format!("unknown load key: {key}")))?;
            let input = documents
                .get(id)
                .cloned()
                .ok_or_else(|| LoadError::custom("document not found"))?;
            let verification = crypto.run(input).await.map_err(LoadError::custom)?;

            Ok(LoadValue::typed(verification))
        }
    }
}
```

</CodeFile>


<CodeFile name="src/components/verification_panel.rs">


```rust
use std::future::Future;
use std::sync::Arc;

use proa::{DataLoader, RenderOutcome, WebContext, WebRender, WriteError};
use proa::html;

use crate::data::crypto_pipeline::Verification;
use crate::data::loader::verification_key;

pub struct VerificationPanel {
    pub document_id: String,
}

impl<L: DataLoader> WebRender<L> for VerificationPanel {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let result: Arc<Verification> =
                cx.load_typed(verification_key(&self.document_id)).await?;

            html! {
                <section aria-label="Signature verification">
                    {if result.valid { "Valid signature" } else { "Invalid signature" }}
                </section>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

</CodeFile>


<CodeFile name="src/routes/documents.rs">


```rust
use std::sync::Arc;

use axum::extract::{Path, State};
use axum::response::IntoResponse;
use proa::axum::RouteResponse;
use proa::stream::DataResolver;

use crate::components::verification_panel::VerificationPanel;
use crate::data::loader::AppLoader;

pub async fn document(
    Path(id): Path<String>,
    State(app_loader): State<Arc<AppLoader>>,
) -> impl IntoResponse {
    let loader = DataResolver::request_scope(app_loader);
    RouteResponse::ssr_async_with_loader(
        VerificationPanel { document_id: id },
        loader,
    )
}
```

</CodeFile>


<CodeFile name="src/app.rs">


```rust
use std::collections::HashMap;
use std::sync::Arc;

use axum::routing::get;
use axum::Router;

use crate::data::crypto_pipeline::{CryptoPipeline, Verification};
use crate::data::loader::AppLoader;
use crate::routes::documents::document;

pub fn router(documents: HashMap<String, Vec<u8>>) -> Router {
    let parallelism =
        std::thread::available_parallelism().map_or(1, |threads| threads.get());
    let crypto = CryptoPipeline::start(parallelism, verify_signature);
    let loader = Arc::new(AppLoader::new(documents, crypto));

    Router::new()
        .route("/documents/:id", get(document))
        .with_state(loader)
}

fn verify_signature(input: Vec<u8>) -> Result<Verification, String> {
    // Replace with the CPU-bound cryptography operation.
    Ok(Verification {
        valid: !input.is_empty(),
    })
}
```

</CodeFile>


</CodeExplorer>


`src/app.rs` creates the pipeline once, while `src/routes/documents.rs` creates a fresh request-local `DataResolver` for each response. `DataResolver` deduplicates identical verification keys within that render; the shared pipeline controls concurrency across distinct jobs and requests. Replace the in-memory document map and `verify_signature` body with the application's storage and cryptography implementation.

Start known jobs with `PreparedLoader`, or place independent consumers in separate `Suspense` boundaries, so computation overlaps with other data loading and rendering instead of beginning only when the page must await its result.

Moving one indivisible calculation to another thread keeps the async runtime responsive, but does not make that calculation finish sooner. To reduce its own latency, split it into independent jobs or use a crypto implementation or CPU pool that parallelizes internally. Tokio recommends `spawn_blocking` for bounded blocking work and a specialized executor such as Rayon for substantial CPU-bound computation. Blocking jobs cannot be aborted after they start, so reject expired work before admission and keep the queue bounded. See [Tokio's CPU-bound task guidance](https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html).


---

# Docs: Databases

URL: /docs/framework/databases
Description: Connect SQLx, Diesel, or Toasty to a Proa DataLoader and render typed rows as components.

---
title: Databases
description: Connect SQLx, Diesel, or Toasty to a Proa DataLoader and render typed rows as components.
---

Proa is database and ORM agnostic. The framework crates ship no driver, no query builder, and no opinion about your data layer. The CLI offers a starting point you can keep or replace: `proa add database` wires SQLite through SQLx and `proa db` runs migrations.

`DataLoader` is the seam. It is a trait you implement, not a driver Proa ships, and its one required method returns a future, so anything you can await composes behind one key: a pool checkout, an ORM query, an HTTP call, a cache read, or all four.

This page connects [SQLx](https://github.com/launchbadge/sqlx), [Diesel](https://diesel.rs), and [Toasty](https://github.com/tokio-rs/toasty) to that trait. Everything above the loader is the same in all three, which is the point; each loader exports the same `Product` and `product_key` interface while its model and connection setup vary. Installing and configuring each library is its own documentation; this page starts once you have a pool.

## The part that does not change

A component asks for what it needs by key. It never learns which library answers:

```rust filename="src/components/product_page.rs"
use std::future::Future;
use std::sync::Arc;

use proa::{DataLoader, RenderOutcome, WebContext, WebRender, WriteError};
use proa::{html, text};

use crate::data::loader::{product_key, Product};

pub struct ProductPage {
    pub id: String,
}

impl<L: DataLoader> WebRender<L> for ProductPage {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let product: Arc<Product> = cx.load_typed(product_key(&self.id)).await?;

            html! {
                <main aria-label="Product details">
                    <article>
                        <h1>{product.name.as_str()}</h1>
                        <p>
                            {text!("${}.{:02}", product.price_cents / 100, product.price_cents % 100)}
                        </p>
                    </article>
                </main>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

`load_typed` pairs with `LoadValue::typed` in the loader, so a database row moves from the query to the component as itself. Nothing is serialized to JSON on the way.

Two details decide whether a loader can answer a key at all:

- **`LoadKey::named("product", id)` renders as `product:42`**, which a loader can parse. `LoadKey::typed` hashes its input into `product#1e9f73…`, so use the named form whenever the loader needs the id back.
- **Request-local dedupe is keyed on that string.** Two components asking for `product:42` in one request produce one query.

Application-wide handles are shared the same way regardless of library. `FrameworkBuilder` is intentionally not generic over an application state type, so the loader goes through the response:

```rust filename="src/app.rs"
use std::sync::Arc;

use axum::{extract::Extension, routing::get, Router};
use proa::axum::FrameworkBuilder;

use crate::{data::loader::AppLoader, db::connect_database};

let db = connect_database().await?;
let loader = Arc::new(AppLoader { db });

let router = Router::new().route("/products/:id", get(product));

let app = FrameworkBuilder::new()
    .with_dynamic_routes(router)
    .build()
    .layer(Extension(loader));
```

See [Route handlers](/docs/framework/route-handlers#sharing-application-state) for the broader state pattern, and [Data loading and streaming](/docs/framework/data-loading) for cache hints, dedupe, and streaming boundaries.

The route keeps the identifier as a string. Each loader parses it into its own key type: an integer for SQLx/Diesel or a UUID for Toasty. This keeps the component and route interface consistent.

These examples focus on data-loading body components. When you enable managed metadata, compose the body inside a role-marked Page and document layout as shown in [Layouts and Pages](/docs/framework/layouts-and-pages).

Everything below differs only in how the pool is built and what the loader runs.

## SQLx

SQLx is an asynchronous SQL toolkit rather than an ORM: connection pooling, migrations, typed row decoding, and optional compile-time query checking for SQLite, PostgreSQL, and MySQL. You write SQL.

<CodeExplorer>


<CodeFile name="src/db.rs">


```rust
use sqlx::{migrate::Migrator, sqlite::SqlitePoolOptions, SqlitePool};

static MIGRATOR: Migrator = sqlx::migrate!();

pub async fn connect_database() -> anyhow::Result<SqlitePool> {
    let database_url = std::env::var("DATABASE_URL")?;
    let db = SqlitePoolOptions::new()
        .max_connections(10)
        .connect(&database_url)
        .await?;

    MIGRATOR.run(&db).await?;
    Ok(db)
}
```

</CodeFile>


<CodeFile name="src/data/loader.rs">


```rust
use std::future::Future;

use proa::{DataLoader, LoadError, LoadKey, LoadRequest, LoadValue};
use sqlx::{FromRow, SqlitePool};

#[derive(Debug, FromRow)]
pub struct Product {
    pub name: String,
    pub price_cents: i64,
}

pub fn product_key(id: &str) -> LoadKey {
    LoadKey::named("product", id)
}

pub struct AppLoader {
    pub db: SqlitePool,
}

impl DataLoader for AppLoader {
    fn load(
        &self,
        request: &LoadRequest,
    ) -> impl Future<Output = Result<LoadValue, LoadError>> + Send {
        let db = self.db.clone();
        let key = request.key().to_string();

        async move {
            let Some(id) = key.strip_prefix("product:") else {
                return Err(LoadError::custom(format!("unknown load key: {key}")));
            };

            let row = sqlx::query_as::<_, Product>(
                "SELECT name, price_cents FROM products WHERE id = ?",
            )
            .bind(id.parse::<i64>().map_err(|error| LoadError::custom(error.to_string()))?)
            .fetch_optional(&db)
            .await
            .map_err(|error| LoadError::custom(error.to_string()))?;

            match row {
                Some(product) => Ok(LoadValue::typed(product)),
                None => Err(LoadError::custom("product not found")),
            }
        }
    }
}
```

</CodeFile>


<CodeFile name="src/routes/products.rs">


```rust
use std::sync::Arc;

use axum::extract::{Extension, Path};
use axum::response::IntoResponse;
use proa::axum::RouteResponse;
use proa::stream::DataResolver;

use crate::{components::product_page::ProductPage, data::loader::AppLoader};

pub async fn product(
    Extension(loader): Extension<Arc<AppLoader>>,
    Path(id): Path<String>,
) -> impl IntoResponse {
    let loader = DataResolver::request_scope(loader);
    RouteResponse::ssr_async_with_loader(ProductPage { id }, loader)
}
```

</CodeFile>


<CodeFile name="src/routes/update_price.rs">


```rust
use sqlx::SqlitePool;

pub async fn update_price(db: &SqlitePool, id: i64, price_cents: i64) -> sqlx::Result<()> {
    let mut transaction = db.begin().await?;

    sqlx::query("UPDATE products SET price_cents = ? WHERE id = ?")
        .bind(price_cents)
        .bind(id)
        .execute(&mut *transaction)
        .await?;

    transaction.commit().await?;
    Ok(())
}
```

</CodeFile>


</CodeExplorer>


**`src/db.rs`** — A SQLx pool is cheap to clone and every clone points at the same shared pool, so the loader holds one by value. Running migrations at startup suits a single instance; in a horizontally scaled deployment run them once as a release command instead of having every replica race.

**`src/data/loader.rs`** — `.bind(...)` sends the id as a query parameter rather than interpolating it into the SQL. `fetch_optional` keeps a missing row distinct from a database failure.

**`src/routes/products.rs`** — The handler wraps the shared loader in a request-scoped `DataResolver`, hands it to the response, and returns. It runs no query itself: the component asks for what it needs while rendering, and two components asking for the same key share one query because the resolver deduplicates within the request. Passing the bare `Arc<AppLoader>` also works, but then each component that asks runs its own query.

**`src/routes/update_price.rs`** — Writes own their transaction and commit before a response is constructed.

## Diesel

Diesel is a query builder and ORM with a typed schema, so a mismatch between schema and query is a compile error rather than a runtime one. Diesel itself is synchronous; [`diesel-async`](https://github.com/weiznich/diesel_async) supplies async connections and pooling for PostgreSQL and MySQL.

<CodeExplorer>


<CodeFile name="src/db.rs">


```rust
use diesel_async::{
    pooled_connection::{bb8, AsyncDieselConnectionManager},
    AsyncPgConnection,
};

pub type Pool = bb8::Pool<AsyncPgConnection>;

pub async fn connect_database() -> anyhow::Result<Pool> {
    let database_url = std::env::var("DATABASE_URL")?;
    let config = AsyncDieselConnectionManager::<AsyncPgConnection>::new(database_url);
    Ok(bb8::Pool::builder().build(config).await?)
}
```

</CodeFile>


<CodeFile name="src/data/schema.rs">


```rust
use diesel::prelude::*;

diesel::table! {
    products (id) {
        id -> BigInt,
        name -> Text,
        price_cents -> BigInt,
    }
}

#[derive(Debug, HasQuery)]
pub struct Product {
    pub name: String,
    pub price_cents: i64,
}
```

</CodeFile>


<CodeFile name="src/data/loader.rs">


```rust
use std::future::Future;

use diesel::prelude::*;
use diesel_async::RunQueryDsl;
use proa::{DataLoader, LoadError, LoadKey, LoadRequest, LoadValue};

use crate::data::schema::products;
pub use crate::data::schema::Product;
use crate::db::Pool;

pub fn product_key(id: &str) -> LoadKey {
    LoadKey::named("product", id)
}

pub struct AppLoader {
    pub db: Pool,
}

impl DataLoader for AppLoader {
    fn load(
        &self,
        request: &LoadRequest,
    ) -> impl Future<Output = Result<LoadValue, LoadError>> + Send {
        let db = self.db.clone();
        let key = request.key().to_string();

        async move {
            let Some(id) = key.strip_prefix("product:") else {
                return Err(LoadError::custom(format!("unknown load key: {key}")));
            };
            let id = id.parse::<i64>().map_err(|error| LoadError::custom(error.to_string()))?;

            let mut conn = db.get().await.map_err(|error| LoadError::custom(error.to_string()))?;
            let row = Product::query()
                .filter(products::id.eq(id))
                .first(&mut conn)
                .await
                .optional()
                .map_err(|error| LoadError::custom(error.to_string()))?;

            match row {
                Some(product) => Ok(LoadValue::typed(product)),
                None => Err(LoadError::custom("product not found")),
            }
        }
    }
}
```

</CodeFile>


<CodeFile name="src/routes/update_price.rs">


```rust
use diesel::prelude::*;
use diesel::result::Error;
use diesel_async::{AsyncConnection, RunQueryDsl};

use crate::data::schema::products;
use crate::db::Pool;

pub async fn update_price(db: &Pool, id: i64, price_cents: i64) -> anyhow::Result<()> {
    let mut conn = db.get().await?;

    conn.transaction::<_, Error, _>(async |conn| {
        diesel::update(products::table.filter(products::id.eq(id)))
            .set(products::price_cents.eq(price_cents))
            .execute(conn)
            .await?;
        Ok(())
    })
    .await?;

    Ok(())
}
```

</CodeFile>


</CodeExplorer>


**`src/db.rs`** — `diesel-async` re-exports its pool backends, so `bb8` comes from `diesel_async::pooled_connection::bb8` rather than a direct dependency.

**`src/data/schema.rs`** — `diesel_cli` normally generates this from your migrations; it is inline here so the example stands alone. `#[derive(HasQuery)]` gives you `Product::query()` and proves the result can be loaded into this type.

**`src/data/loader.rs`** — `.filter(products::id.eq(id))` is a bound parameter, not string interpolation. `.optional()` comes from `OptionalExtension` in `diesel::prelude` and turns a "no rows" error into `Ok(None)`, which keeps a missing row distinct from a failed query.

**`src/routes/update_price.rs`** — `diesel-async` takes an async closure and commits when it returns `Ok`.

## Toasty

[Toasty](https://tokio.rs/blog/2026-04-03-toasty-released) is the Tokio project's async ORM. You define models as plain Rust structs and it infers the schema, generating the query, create, and update builders so you write no SQL. It targets SQLite, PostgreSQL, MySQL, Turso, and DynamoDB from one model definition.

The Toasty examples target 0.11 and require Rust 1.95 or newer, independently
of Proa's minimum Rust version. Enable the driver feature for your database,
such as `sqlite`. Toasty is pre-1.0; pin a minor version and check its migration
guide before upgrading.

<CodeExplorer>


<CodeFile name="src/data/model.rs">


```rust
#[derive(Debug, toasty::Model)]
pub struct Product {
    #[key]
    #[auto]
    pub id: uuid::Uuid,

    pub name: String,
    pub price_cents: i64,
}
```

</CodeFile>


<CodeFile name="src/db.rs">


```rust
pub async fn connect_database() -> toasty::Result<toasty::Db> {
    let url = std::env::var("TOASTY_CONNECTION_URL")
        .unwrap_or_else(|_| "sqlite::memory:".to_string());

    let db = toasty::Db::builder()
        .models(toasty::models!(crate::*))
        .connect(&url)
        .await?;

    Ok(db)
}
```

</CodeFile>


<CodeFile name="src/data/loader.rs">


```rust
use std::future::Future;

use proa::{DataLoader, LoadError, LoadKey, LoadRequest, LoadValue};

pub use crate::data::model::Product;

pub fn product_key(id: &str) -> LoadKey {
    LoadKey::named("product", id)
}

pub struct AppLoader {
    pub db: toasty::Db,
}

impl DataLoader for AppLoader {
    fn load(
        &self,
        request: &LoadRequest,
    ) -> impl Future<Output = Result<LoadValue, LoadError>> + Send {
        // `Db` is cheap to clone and shares its pool, but the executor methods
        // take `&mut self`, so each load works on its own handle.
        let mut db = self.db.clone();
        let key = request.key().to_string();

        async move {
            let Some(id) = key.strip_prefix("product:") else {
                return Err(LoadError::custom(format!("unknown load key: {key}")));
            };
            let id = id.parse::<uuid::Uuid>().map_err(|error| LoadError::custom(error.to_string()))?;

            let row = Product::filter_by_id(id)
                .first()
                .exec(&mut db)
                .await
                .map_err(|error| LoadError::custom(error.to_string()))?;

            match row {
                Some(product) => Ok(LoadValue::typed(product)),
                None => Err(LoadError::custom("product not found")),
            }
        }
    }
}
```

</CodeFile>


<CodeFile name="src/routes/update_price.rs">


```rust
use crate::data::model::Product;

pub async fn update_price(
    db: &mut toasty::Db,
    id: uuid::Uuid,
    new_price: i64,
) -> toasty::Result<()> {
    let mut tx = db.transaction().await?;

    let mut product = Product::get_by_id(&mut tx, &id).await?;
    toasty::update!(product { price_cents: new_price }).exec(&mut tx).await?;

    tx.commit().await?;
    Ok(())
}
```

</CodeFile>


</CodeExplorer>


**`src/data/model.rs`** — `#[key]` marks the primary key and `#[auto]` fills it on insert, which for a `Uuid` means a time-ordered UUID v7. The attributes drive the generated API: `#[unique]` on a field is what makes `Product::get_by_<field>` exist at all.

**`src/db.rs`** — `toasty::models!` discovers every `#[derive(Model)]` in the crate, so models are not listed by hand. A fresh database has no tables; `db.push_schema().await?` creates them straight from the models, which is the quick path for demos and tests. Use migrations for anything with data you care about.

**`src/data/loader.rs`** — `filter_by_*` builds a lazy query and the terminal decides the result shape: `.first().exec(&mut db)` yields `Option`, `.exec(&mut db)` on the unfiltered query yields `Vec`, and `.get(&mut db)` expects exactly one row and errors otherwise.

**`src/routes/update_price.rs`** — An interactive Toasty transaction borrows the
`Db` mutably. Pass `&mut tx` to its queries; dropping it rolls back. This example
requires a SQL backend: DynamoDB does not support interactive transactions.

## Choosing

| | SQLx | Diesel | Toasty |
|---|---|---|---|
| You write | SQL | Typed query builder | Model methods |
| Query checking | Optional, via `query!` and offline metadata | Always, by the Rust type system | Generated from the model |
| Async | Native | Via `diesel-async` | Native |
| Backends | SQLite, PostgreSQL, MySQL | SQLite, PostgreSQL, MySQL | SQLite, PostgreSQL, MySQL, Turso, DynamoDB |
| Maturity | Stable, widely deployed | Stable, widely deployed | Pre-1.0, released April 2026 |

None of this changes anything on the Proa side. Pick on the merits of the data layer.

## Do not hold a transaction across a render

This applies to every library above. Keep a transaction in the handler that owns the mutation, and commit it before constructing the response. Do not place a live transaction inside a component or in shared application state. Its lifetime should be limited to one request operation, and no HTML should be emitted until the write either commits or rolls back.

## When to use `DataLoader`

Do not wrap your database library in a `DataLoader` solely because Proa has one. A handler query followed by a sync component is the shortest and most explicit path for a page that needs one result.

Use a loader when independent components initiate reads, several components may request the same key, or a slow section should participate in `Suspense`. Because `DataLoader::load` is just an async method you write, the loader can own whatever handle your library uses: a cloned `SqlitePool` or `PgPool`, a `bb8::Pool<AsyncPgConnection>`, a `toasty::Db`, or several of them at once behind different key namespaces. Return `LoadValue::typed(record)` for a Rust value or `LoadValue::bytes(..)` for serialized JSON.

See [Data loading and streaming](/docs/framework/data-loading) for that pattern, and [Caching](/docs/framework/caching) before caching database results across requests.

## Next steps

- [Data loading and streaming](/docs/framework/data-loading)
  - Implement a `DataLoader`, key requests, and stream slow sections with `Suspense`.
- [Route handlers](/docs/framework/route-handlers)
  - Build JSON, form, and webhook endpoints, and share application state.
- [Forms and actions](/docs/guides/forms-actions)
  - Accept a write, validate it on the server, and re-render.
- [Caching](/docs/framework/caching)
  - Decide what is safe to cache across requests.


---

# Docs: Data caching

URL: /docs/framework/caching
Description: Deduplicate loads, cache data across requests, and invalidate render dependencies.

---
title: Data caching
description: Deduplicate loads, cache data across requests, and invalidate render dependencies.
---

Proa keeps data cache policy explicit. The framework does not silently cache data fetches for you. Choose the boundary that matches the work:

| Resource | Cache at |
|----------|----------|
| Request-local data | `DataResolver` |
| Cross-request data | application loader, `StandardDataLoader`, Redis, database, or origin service |

For complete HTML responses, HTTP cache headers, ETags, and Cloudflare setup, see [Page caching](/docs/framework/page-caching).

## Cache Boundaries

Request-local dedupe prevents components in one render from loading the same key twice. Cross-request caching reduces origin reads across users or requests. Prefer the narrowest cache that removes real work without sharing user-specific data.

Data caching reduces work when a request reaches the application. A fresh CDN page-cache hit skips the application entirely. Each cache needs its own freshness and invalidation policy.

## Request-Local Dedupe

Wrap your loader with `DataResolver` when multiple components can ask for the same key during one render:

```rust
use std::sync::Arc;

use proa::stream::DataResolver;

pub async fn product_handler() -> impl axum::response::IntoResponse {
    let app_loader = Arc::new(AppLoader::new());
    let loader = DataResolver::request_scope(app_loader);

    RouteResponse::ssr_async_with_loader(ProductPage { id: "sku_1" }, loader)
}
```

This is a per-render optimization. It does not persist values across requests.

## Cross-Request Data Cache

For a process-local cache, wrap an upstream loader with `StandardDataLoader`:

```rust
use std::sync::Arc;
use std::time::Duration;

use proa::StandardDataLoader;

let cached_loader = Arc::new(StandardDataLoader::new(
    AppLoader::new(),
    Duration::from_secs(30),
));
```

`StandardDataLoader` stores `LoadValue` by `LoadKey`, expires entries by TTL, and exposes manual invalidation:

```rust
use proa::LoadKey;

cached_loader.invalidate(&LoadKey::named("product", "sku_1"));
cached_loader.clear();
```

Use a process-local cache only when each instance can safely have its own copy. For horizontally scaled apps, put shared cache state in Redis, your database, your CDN, or the upstream service.

## Load Hints

`LoadHints` carry cache policy without changing the identity of the data:

```rust
use std::time::Duration;

use proa::{CacheHint, CacheMode, LoadHints, LoadKey};

let product = cx
    .load_json_with::<Product>(
        LoadKey::named("product", "sku_1"),
        LoadHints::new().with_cache(
            CacheHint::ttl(Duration::from_secs(60)).with_mode(CacheMode::Refresh),
        ),
    )
    .await?;
```

The built-in cache modes are:

| Mode | Meaning |
|------|---------|
| `UseLoaderDefault` | Let the loader apply its normal policy. |
| `Bypass` | Skip the loader-managed cache and fetch from origin. |
| `Refresh` | Fetch from origin and update the cache entry. |
| `OnlyIfCached` | Return cached data or fail with `LoadError::CacheMiss`. |

Custom loaders may honor hints, ignore them, or map them onto their own cache system. Keep `LoadKey` stable; put freshness policy in `LoadHints`.

## Invalidation

Choose invalidation at the same boundary as the cache:

| Cache | Invalidate by |
|-------|---------------|
| `DataResolver` | end of request |
| `StandardDataLoader` | TTL, `invalidate(&key)`, or `clear()` |
| Redis/database cache | app-specific key, tag, or write transaction |

When data changes through a form or API mutation, invalidate the data cache before redirecting or returning the success response.

If that data appears in cached HTML, invalidate the affected CDN pages too. Clearing a loader cache does not remove an already rendered edge response. See [Page caching](/docs/framework/page-caching#running-deployment-and-invalidation).

```rust
pub async fn update_product(Form(form): Form<ProductForm>) -> Redirect {
    save_product(&form).await;
    cached_loader.invalidate(&LoadKey::named("product", form.id.as_str()));

    Redirect::to("/products")
}
```

## Cache Trace

`WebContext` exposes `cache_trace_mut()` for render-time dependency recording:

```rust
cx.cache_trace_mut().set_ttl(Duration::from_secs(60));
cx.cache_trace_mut().depend_tag("product:sku_1");
cx.cache_trace_mut().depend_path("/products/sku_1");
```

Use this when your application wants to collect dependencies during render and map them to its own invalidation system. Proa records the trace; your app decides how to consume it. Recording a TTL or tag here does not automatically emit CDN headers or call Cloudflare's purge API.

## Production Checklist

- Wrap loaders with `DataResolver` when a render can load the same key repeatedly.
- Use `StandardDataLoader` only when process-local cache state is acceptable.
- Put cross-instance cache state in shared infrastructure.
- Include the relevant user or tenant identity when caching private data across requests.
- Invalidate on mutation before redirecting.
- Invalidate any affected CDN pages separately.

See [Data loading and streaming](/docs/framework/data-loading), [Route handlers](/docs/framework/route-handlers), and [Page caching](/docs/framework/page-caching).


---

# Docs: Forms and actions

URL: /docs/guides/forms-actions
Description: Build and validate HTML forms, handle submissions with Axum, and attach typed actions.

---
title: Forms and actions
description: Build and validate HTML forms, handle submissions with Axum, and attach typed actions.
keywords: [Action, form, CSRF token]
---

Proa keeps server mutations explicit: the browser submits a native HTML form, and an Axum handler validates and writes the data. This page covers [rendering the form](#rendering-a-native-form), [validation with Wellformed](#validating-with-wellformed), [typed client actions](#adding-typed-client-actions), and [choosing a boundary](#choosing-a-boundary).

## Rendering a native form

Use real form controls whenever a browser submit is enough:

```rust filename="src/pages/contact.rs"
use proa::html_sync;

html_sync! {
    <form method="post" action="/contact" class="grid gap-4">
        <label for="email">"Email"</label>
        <input id="email" name="email" type="email" required autocomplete="email" />
        <label for="message">"Message"</label>
        <textarea id="message" name="message" required minlength="10"></textarea>
        <button type="submit">"Send"</button>
    </form>
}
```

This renders useful HTML before any JavaScript loads. The browser owns focus, keyboard submission, autofill, and constraint validation. Those constraints improve the experience, but the server must still validate every submission.

### Form controls

Start with native controls:

| Component | Native element |
|-----------|----------------|
| Text input | `<input type="text">`, `<input type="email">`, `<input type="password">` |
| Text area | `<textarea>` |
| Select | `<select>` |
| Checkbox | `<input type="checkbox">` |
| Radio group | `<input type="radio">` |
| Button | `<button>` |
| Field structure | `<label>`, `<fieldset>`, `<legend>`, help text, error text |

Prefer native names and values for any data that must reach the server. That keeps the submission inspectable and works without JavaScript.

Markup is half the story. The POST needs a server-side validation boundary.

## Validating with Wellformed

Use [Wellformed](https://github.com/hariria/wellformed) to keep normalization, validation rules, generated Rust values, and field errors in one schema:

```bash filename="Terminal"
cargo add wellformed wellformed-macros wellformed-validate serde_json
cargo add serde --features derive
```

Check the serialized schema into the application. This example trims both fields, normalizes the email, and gives every failure a stable code and message:

```json filename="schemas/contact.json"
{
  "version": "1.0.0",
  "id": "contact",
  "title": "Contact",
  "root": {
    "type": "object",
    "unknown_keys": "strict",
    "properties": {
      "email": {
        "type": "string",
        "label": "Email",
        "required": true,
        "transforms": [{ "fn": "trim" }, { "fn": "lower" }],
        "constraints": [
          {
            "pred": { "type": "call", "name": "is_email" },
            "error": {
              "code": "INVALID_EMAIL",
              "message": "Enter a valid email address"
            }
          }
        ]
      },
      "message": {
        "type": "string",
        "label": "Message",
        "required": true,
        "transforms": [{ "fn": "trim" }],
        "constraints": [
          {
            "pred": { "type": "min_len", "len": 10 },
            "error": {
              "code": "MESSAGE_TOO_SHORT",
              "message": "Use at least 10 characters"
            }
          }
        ]
      }
    }
  }
}
```

Generate the typed form facade at compile time:

```rust filename="src/forms/contact.rs"
use wellformed_macros::form_schema;

form_schema!(pub mod contact = "schemas/contact.json");
```

Extract the native form into an untyped map so Wellformed sees the untrusted payload before Serde constructs the generated Rust type:

```rust filename="src/routes/contact.rs"
use std::collections::HashMap;

use axum::{
    extract::Form,
    http::StatusCode,
    response::{IntoResponse, Redirect, Response},
};
use proa::axum::RouteResponse;

use crate::{forms::contact, pages::contact::ContactPage};

pub async fn submit_contact(Form(fields): Form<HashMap<String, String>>) -> Response {
    let submitted = serde_json::to_value(fields)
        .expect("string form fields serialize to JSON");

    let values = match contact::validate_form(submitted) {
        Ok(values) => values,
        Err(errors) => {
            let mut response = RouteResponse::ssr(ContactPage {
                form: contact::state_with_errors(errors),
            })
            .into_response();
            *response.status_mut() = StatusCode::UNPROCESSABLE_ENTITY;
            return response;
        }
    };

    save_contact(values).await;

    Redirect::to("/contact/thanks").into_response()
}
```

`values` is `contact::Values`, generated from the schema after transforms and validation succeed. The redirect follows the post/redirect/get pattern so refreshing the success page does not resubmit the mutation.

Register the route beside the page route:

```rust filename="src/main.rs"
use axum::routing::{get, post};
use axum::Router;

let routes = Router::new()
    .route("/", get(contact_page))
    .route("/contact", post(submit_contact));
```

Use `Route::endpoint` when the endpoint also needs Proa route-specification policy. Component roles and `render_head` control managed page metadata independently of the HTTP method. [Route handlers](/docs/framework/route-handlers) covers JSON endpoints, body limits, shared state, webhooks, and endpoint tests.

### Re-rendering field errors

The generated form state keeps the submitted values and maps validation paths to field accessors:

```rust filename="src/pages/contact.rs"
use crate::forms::contact;

pub struct ContactPage {
    pub form: contact::State,
}
```

Use those accessors to restore values and connect each error to its control:

```rust filename="src/pages/contact.rs"
let email = contact::field_email(&self.form);

html_sync! {
    <input
        id="email"
        name="email"
        type="email"
        required
        autocomplete="email"
        value={email.value_str()}
        aria-invalid={email.invalid()}
        aria-describedby={email.invalid().then_some(email.error_id())}
    />
    {if let Some(error) = email.error_message() {
        html_sync! {
            <p id={email.error_id()} role="alert">{error}</p>
        }
    }}
}
```

Use the same pattern for the message field. `contact::state_with_errors` preserves all submitted values, while `field_email` supplies the stable error id, invalid state, and message needed by accessible HTML.

### Server mutation checklist

Before shipping a form:

- Use `method="post"` for mutations.
- Validate the untyped payload before constructing trusted application values.
- Do not trust hidden inputs for authorization.
- Redirect after successful mutation to avoid duplicate browser resubmits.
- Re-render with field errors on validation failure.
- Keep CSRF and origin policy explicit for browser-issued unsafe methods.
- Use `type="submit"` for submit buttons and `type="button"` for client-only actions.

`FrameworkBuilder` enables cross-origin protection for unsafe browser requests by default. Keep it enabled unless you have a specific trusted-origin deployment requirement. [Deployment](/docs/framework/deployment) covers production hardening.

That covers everything the server owns. Browser-only behavior needs a different mechanism.

## Adding typed client actions

Use typed RSJS handlers, signals, and `bind_value` / `bind_checked` for application browser behavior. See [Islands](/docs/guides/islands) and [Bindings](/docs/rsjs/bindings). Server writes still happen through normal HTTP routes.

The lower-level `proa_actions` interface below is useful when an existing TypeScript integration needs named actions and delegated `data-on*` attributes. It requires generating and loading its own client runtime; adding an action attribute alone does not install a listener.

Use `#[derive(Action)]` when client-side code needs stable, typed action names:

```rust filename="src/actions/product.rs"
use proa::actions::{Action, ActionHandler};

#[derive(Debug, Clone, Action)]
#[action(scope = "product_card")]
pub enum ProductAction {
    Favorite,
    AddToCart { sku: String },
}
```

The derive emits constants and conversion helpers:

```rust filename="src/actions/product.rs"
assert_eq!(
    ProductAction::FAVORITE,
    "product_card.ProductAction.Favorite",
);

let data = ProductAction::AddToCart {
    sku: "sku_1".to_string(),
}
.to_action_data();

let restored = ProductAction::from_action_data(data)?;
```

Use a unique `scope` per page, island, or component family. The scope prevents action-name collisions in generated client code.

### Attaching actions to elements

Render static action identifiers as data attributes:

```rust filename="src/components/product_card.rs"
html_sync! {
    <button type="button" data-onclick={ProductAction::FAVORITE}>"Favorite"</button>
}
```

This renders a `data-onclick` attribute holding the action name. The generated action runtime can delegate browser events from those attributes.

When the handler needs parameters, render explicit `data-param-*` attributes near the action:

```rust filename="src/components/product_card.rs"
html_sync! {
    <button
        type="button"
        data-onclick={ProductAction::ADD_TO_CART}
        data-param-sku={self.sku}
    >
        "Add to cart"
    </button>
}
```

Parameter names **must** be safe attribute-name suffixes: ASCII letters, digits, underscores, and hyphens.

### Generating the client runtime

`proa::actions::codegen` can generate three TypeScript artifacts from action metadata:

| Artifact | Purpose |
|----------|---------|
| Contract | action constants, parameter types, and handler interfaces |
| Runtime | delegated event listeners for `data-onclick`, `data-onblur`, `data-onfocus`, and related event attributes |
| Handler stub | user-owned file where you implement browser behavior |

The runtime parses `data-param-*` attributes as strings and passes them to the registered handler. Convert or validate types in the handler when needed.

Server routes and client actions overlap, so pick the boundary deliberately.

## Choosing a boundary

Start from the need:

| Need | Use |
|------|-----|
| Submit data to the server | Native `<form method="post">` plus an Axum handler. |
| Validate and persist data | Validate with a Wellformed schema, then persist the generated values. |
| Trigger client-only behavior | Typed RSJS event handlers and signals. |
| Keep form UI reactive | RSJS signals with `bind_value` / `bind_checked`. |

Then match the specific situation:

| Situation | Recommended boundary |
|-----------|----------------------|
| Contact form, checkout, account update | Native form plus Axum POST handler. |
| Opening a dialog or toggling local UI | An RSJS island or an existing Proa UI component. |
| Field value drives live browser UI | Controlled `rsjs` component. |
| Data changes server state | Server route, not a client-only action. |
| Static button action with no params | An RSJS `on_click` handler. |
| Dynamic action params | Typed RSJS values or native form fields; use `data-param-*` for an existing delegated action integration. |

## Next steps

- [Route handlers](/docs/framework/route-handlers)
  - Write the POST endpoints, body limits, and endpoint tests.
- [Cross-origin and CSRF](/docs/framework/cross-origin)
  - Configure origin policy for browser-issued unsafe methods.
- [Islands: when and why](/docs/guides/islands)
  - Decide when a form field needs a hydrated component.
- [Accessibility](/docs/guides/accessibility)
  - Label fields and announce validation errors correctly.


---

# Docs: Islands: when and why

URL: /docs/guides/islands
Description: Decide when a page needs browser code, then reach for RSJS.

---
title: 'Islands: when and why'
description: Decide when a page needs browser code, then reach for RSJS.
keywords: [island, hydrate]
---

Most Proa pages should stay server-rendered. Add an island only for UI that must keep state in the browser after the HTML arrives.

| Need | Use |
|------|-----|
| Render data, links, forms, tables, metadata | Normal `WebRenderSync` page/component |
| Submit to the server | Native `<form method="post">` |
| Toggle, filter, validate, open, close, copy, measure, or react to input without a navigation | `#[rsjs(component, client)]` island |
| Fetch browser-visible data after hydration | Async RSJS query/mutation island |

The boundary is explicit: the server renders HTML first, then RSJS hydrates only the marked island.

## First Island

Author the normal render trait, then mark it for RSJS analysis and permission to
originate browser behavior:

```rust
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use rsjs::signal;
use rsjs::rsjs;

pub struct FavoriteButton {
    pub label: &'static str,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for FavoriteButton {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let saved = signal(false);
        let label = self.label;

        html_sync! {
            <button
                type="button"
                aria_pressed={if saved.get() { "true" } else { "false" }}
                on_click={|_| saved.set(!saved.get())}
                class="rounded-md border px-3 py-2 text-sm"
            >
                {if saved.get() {
                    html_sync! { <span>"Saved"</span> }
                } else {
                    html_sync! { <span>{label}</span> }
                }}
            </button>
        }
        .render(cx)
    }
}
```

Two shape rules apply inside an analyzed template, and the compiler reports each as an error: the body must have a single top-level element, so wrap siblings in a containing element, and each branch of a conditional must have an element as its root, which is why the branches above wrap their text in `<span>`.

Use it from any page or component:

```rust
html_sync! {
    <article class="grid gap-3 rounded-lg border p-5">
        <h2>"Atlas Jacket"</h2>
        <p>"Weatherproof shell with a quiet technical finish."</p>
        {FavoriteButton { label: "Save" }}
    </article>
}
```

The server still sends real button HTML. RSJS adds the handler, signal seed, and per-island runtime metadata next to that HTML.

For managed metadata, keep `ROLE = PAGE` and `render_head` on an ordinary SSR Page wrapper around the island. Ancestor metadata layouts declare `LAYOUT`; the analyzed island impl keeps the default component role and contains its render method only. See [Layouts and Pages](/docs/framework/layouts-and-pages).

## What Gets Hydrated

An island emits a small boundary:

```html
<rsjs-island data-rsjs-island-root="favoritebutton_...">
  <button data-rsjs-handler="0" data-rsjs-bind="0">Save</button>
</rsjs-island>
<script type="application/json" data-rsjs-island="favoritebutton_...">
  {"signals":[false]}
</script>
```

Only nodes inside `<rsjs-island>` hydrate. The rest of the page stays static server-rendered HTML.

## Signal Rules

Declare signals near the top of `render`:

```rust
let query = signal(String::new());
let open = signal(false);
let count = signal(0_i64);
```

Read signals in markup:

```rust
html_sync! {
    <div>
        <p>"Count: "{count.get()}</p>
        <section hidden={!open.get()}>"Details"</section>
    </div>
}
```

Write signals inside handlers:

```rust
html_sync! {
    <button type="button" on_click={|_| count.update(|n| n + 1)}>"Increment"</button>
}
```

Avoid writing to signals while the server is rendering the template body. Signal writes belong in browser event handlers.

## Inputs

Use bindings for simple form state:

```rust
pub struct ProductFilter;

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for ProductFilter {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let query = signal(String::new());
        let in_stock = signal(false);

        html_sync! {
            <form class="grid gap-3">
                <label>
                    "Search"
                    <input type="search" bind_value={query} />
                </label>
                <label>
                    <input type="checkbox" bind_checked={in_stock} />
                    "In stock only"
                </label>
                <p>"Query: "{query.get()}</p>
            </form>
        }
        .render(cx)
    }
}
```

Use handlers instead when the update needs validation or normalization:

```rust
html_sync! {
    <input
        type="search"
        value={query.get()}
        on_input={|event| query.set(event.value().trim().to_string())}
    />
}
```

## Server-Rendered Content

Ordinary Rust values stay on the server unless a browser-reachable operation
depends on them. Construct arbitrary non-component renderers in the prelude and
render the resulting local:

```rust
use proa::UnsafeRaw;

let icon = UnsafeRaw(r#"<svg aria-hidden="true"></svg>"#);

html_sync! {
    <button type="button" on_click={|_| open.set(!open.get())}>
        {icon}
        <span>{if open.get() { "Close" } else { "Open" }}</span>
    </button>
}
```

The SVG renders once on the server while the label remains reactive. If an
opaque helper consumes `open.get()`, compilation fails rather than snapshotting
the initial value.

## Child Components

Render a child island component directly when the parent should own state:

```rust
pub struct SearchInput {
    pub value: String,
    pub on_change: rsjs::Handler<String>,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for SearchInput {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <input
                type="search"
                value={self.value}
                on_input={|event| self.on_change.call(event.value())}
            />
        }
        .render(cx)
    }
}

pub struct SearchPanel;

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for SearchPanel {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let query = signal(String::new());
        let on_change = rsjs::handler(|next: String| query.set(next));

        html_sync! {
            <section>
                {SearchInput {
                    value: query.get(),
                    on_change,
                }}
                <p>"Current query: "{query.get()}</p>
            </section>
        }
        .render(cx)
    }
}
```

Use `rsjs::island(...)` only when the child should hydrate as an independent nested island:

```rust
html_sync! {
    <section>{rsjs::island(FavoriteButton { label: "Save" })}</section>
}
```

Parent handlers cannot cross that explicit island boundary. If the child updates parent state, render it directly.

## Hydration Timing

The default strategy hydrates immediately. Defer below-the-fold or optional UI:

```rust
#[rsjs(component, client, strategy = "visible")]
impl<L: DataLoader> WebRenderSync<L> for ReviewsPanel {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let expanded = signal(false);
        html_sync! {
            <section>
                <button type="button" on_click={|_| expanded.set(!expanded.get())}>
                    "Toggle reviews"
                </button>
            </section>
        }
        .render(cx)
    }
}
```

| Strategy | Use for |
|----------|---------|
| default | Buttons, menus, inputs above the fold |
| `visible` | Below-the-fold widgets |
| `idle` | Enhancements that can wait until the browser is idle |
| `interaction:click` | UI that should hydrate on first interaction |
| `media:(min-width: 768px)` | Desktop-only or media-query-gated widgets |

See [Hydration](/docs/rsjs/hydration) for the full behavior.

## Async Islands

Use sync islands for local browser state. Switch to async `WebRender` when the island declares `mutation(...)` or awaits server data before rendering. A `query_with_initial(...)` whose initial value is already available can stay on `WebRenderSync`:

```rust
use proa::{DataLoader, LoadKey, WebContext, WebRender, WriteError};
use proa::html;
use rsjs::rsjs;
use std::future::Future;

#[derive(Clone, serde::Deserialize, serde::Serialize)]
pub struct StockPrice {
    pub symbol: String,
    pub value: f64,
}

pub struct StockTile;

#[rsjs(component, client)]
impl<L: DataLoader> WebRender<L> for StockTile {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> proa::RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        proa::RenderOutcome::pending(async move {
            let initial: StockPrice = cx
                .load_json(LoadKey::named("stock", "AAPL"))
                .await?;
            let price = rsjs::query_with_initial(
                rsjs::QueryKey::new(("stock", "AAPL")),
                initial,
                rsjs::FetchRequest {
                    url: "/api/stock/AAPL",
                    apply_base_path: true,
                    method: Some(rsjs::HttpMethod::Get),
                    ..Default::default()
                },
                rsjs::QueryOptions::default(),
            );

            html! {
                <span>{price.data().value}</span>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

Use [Queries and mutations](/docs/rsjs/queries-mutations) for the full query surface.

## Checklist

Before shipping an island:

- Keep the non-interactive shell server-rendered.
- Keep the island root small and focused.
- Prefer native forms for server mutations.
- Use `WebRenderSync` unless the island actually awaits or declares a mutation.
- Keep signal writes inside event handlers.
- Construct arbitrary server renderers in the prelude and render the local.
- Choose a hydration strategy for below-the-fold or optional UI.
- Run `proa check` and the matching linked `proa test` target; `cargo check` remains useful for provisional type checking.

## Read Next


- [RSJS reference](/docs/rsjs/signals): Signals, handlers, bindings, browser APIs, hydration, queries, mutations, and runtime details.
- [Component props](/docs/rsjs/component-props): Pass on_change and other RSJS callbacks through child structs.
- [Browser APIs](/docs/rsjs/browser-apis): See the typed DOM, observer, storage, URL, clipboard, and network boundary.
- [Forms and actions](/docs/guides/forms-actions): Use native POST routes for server mutations before adding client state.


## Which RSJS primitive

Once you have decided a component needs browser behaviour, this is the map:

| Need | RSJS primitive |
| --- | --- |
| Owner-local browser state | `signal(...)` |
| Read-only derived state | `memo(...)` |
| Typed state shared by independent owners | `SharedStateProvider` and `shared::<T>()` |
| Click, input, keyboard, pointer, document, or window events | `event_handler(...)` and `on_*` attributes |
| Form control state | `bind_value`, `bind_checked`, `bind_selected` |
| Typed child callbacks | `rsjs::Handler<T>` props |
| Portable browser-side calculations | `#[rsjs::client]` functions |
| DOM reads and effects | `node_ref::<T>()` |
| Delayed hydration | `strategy = "visible"`, `idle`, `interaction`, or `media:(...)` |
| Browser fetch work | `query_with_initial(...)` and `mutation(...)` |

Each row links onward from [the RSJS pages](/docs/rsjs/signals) in this section.

## Next steps

- [Signals](/docs/rsjs/signals)
  - Model owner-local and typed cross-owner browser state in RSJS.
- [Event handlers](/docs/rsjs/handlers)
  - Attach named typed browser handlers and component callbacks in RSJS.
- [Hydration strategies](/docs/rsjs/hydration)
  - Defer RSJS island hydration until it matters.
- [Forms and actions](/docs/guides/forms-actions)
  - Build HTML forms, handle submissions with Axum, and attach typed actions.
- [Route responses](/docs/framework/responses)
  - Return synchronous, buffered async, or streaming SSR with islands.


---

# Docs: Signals

URL: /docs/rsjs/signals
Description: Model owner-local and typed cross-owner browser state in RSJS.

---
title: Signals
description: Model owner-local and typed cross-owner browser state in RSJS.
keywords: [signal, derived, effect]
---

Server-rendered HTML stops changing the moment it reaches the browser, so RSJS keeps the live parts in signals. This page covers [declaring a signal](#declaring-a-signal), [the primitives](#which-primitive-do-you-need), [reactive reads](#reading-values-reactively), [initial values](#seeding-initial-values), [inbound fields](#seeding-once-versus-reading-live), and [cross-owner state](#sharing-state-between-independent-owners).

## Declaring a signal

Call `signal(initial)` inside an origin-capable `#[rsjs(component, client)]`
render implementation for state that must keep changing after the server HTML
reaches the browser.

```rust filename="src/components/counter.rs"
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use rsjs::{event_handler, rsjs, signal};

pub struct Counter;

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for Counter {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let count = signal(0_i64);
        let doubled = rsjs::memo(|| count.get() * 2_i64);
        let increment = event_handler(|_: rsjs::MouseEvent<rsjs::elem::Button>| {
            count.update(|value| value + 1_i64);
        });

        html_sync! {
            <div>
                <button type="button" on_click={increment()}>
                    {count.get()}
                </button>
                <output>{doubled.get()}</output>
            </div>
        }
        .render(cx)
    }
}
```

The server renders the initial values. The final linker retains only signals and
memo cells reachable from browser work. The browser runtime rebuilds that
graph during hydration.

For an `i64` seed, the adjacent compiler-owned state is conceptually:

```html filename="counter-response.html"
<script type="application/json" data-rsjs-island="counter_...">
  {"signals":["0"]}
</script>
```

The compiler owns the exact script shape, marker IDs, and `data-rsjs-*`
attributes. `i64` and `u64` values use validated canonical decimal strings, so
values outside JavaScript's safe integer range stay exact.

Four more primitives build on `signal` for derivation and batching.

## Which primitive do you need?

| Primitive | Use |
| --- | --- |
| `signal(initial)` | Declare writable owner-local state. |
| `memo(\|\| expression)` | Cache a read-only value derived from live inputs; dependencies are inferred. |
| `value.get()` | Read the current value in text, attributes, conditions, handlers, or another memo. |
| `value.set(next)` | Replace a writable value from a supported client operation. |
| `value.update(\|old\| next)` | Compute the next value from the previous value. |
| `batch(\|\| { ... })` | Group several synchronous writes into one DOM/subscriber flush. |

Prefer `update` when the next value depends on the old value. Use `memo`
instead of manually synchronizing a second signal.

```rust filename="src/components/toolbar.rs"
let count = signal(0_i64);
let open = signal(false);
let summary = rsjs::memo(|| count.get() * 2_i64);

let update_both = rsjs::event_handler(|_: rsjs::Event| {
    rsjs::batch(|| {
        count.update(|value| value + 1_i64);
        open.update(|value| !value);
    });
});
```

Later reads inside the batch see those writes immediately. RSJS deduplicates
dependent DOM effects and flushes them after the outermost batch completes.
Nested batches coalesce.

Where you call `.get()` decides which DOM the flush touches.

## Memo dependencies and caching

`rsjs::memo(|| expression)` needs no manual dependency array. The compiler
collects and deduplicates the signal reads in the lowered expression and emits
the dependency list for the browser runtime. Both branches of a supported
conditional contribute dependencies, as do live arguments passed to pure
`#[rsjs::client]` helpers.

A memo evaluates at creation and stores one current result. Input writes
schedule recomputation in the microtask flush, and several synchronous writes
coalesce. Reads before the flush return the previous result. Downstream
subscribers run only when the result changes according to `Object.is`; island
teardown removes the input subscriptions.

Use a memo to share a cached derivation across consumers or suppress work when
the derived result stays equal. Inline reactive expressions and supported
reactive prelude aliases also update with their inputs, without creating a
shared cached cell. The memo closure accepts one supported reactive expression;
put intermediate locals in a pure `#[rsjs::client]` helper when needed.

## Reading values reactively

RSJS tracks reads in browser-reachable positions and updates only the affected
binding.

| Position | Example |
| --- | --- |
| Text | `<span>{count.get()}</span>` |
| Attribute | `<button aria_expanded={open.get()}>` |
| Conditional | `{if open.get() { html_sync! { <div>"Open"</div> } }}` |
| Predicate helper | `{if name.is_non_empty() { html_sync! { "Ready" } }}` |
| Derived value | `let total = memo(|| price.get() * quantity.get());` |

Declaring a client primitive does not guarantee that it ships. The final
reachability pass can remove an unused signal, memo, or handler. Surviving
signals retain deterministic declaration order in the owner seed. Never put
required server side effects inside an otherwise unused client declaration.

Whatever survives carries its initial value to the browser as page data.

## Seeding initial values

A signal initializer runs during SSR and becomes a one-time browser seed. A
runtime value that reaches a signal must implement `rsjs::ClientEncode`.

```rust filename="src/components/tab_bar.rs"
let open = signal(false);
let count = signal(0_i64);
let initial_tab = signal(self.initial_tab);
```

The codec requirement is usage-driven: a value rendered only through opaque SSR
does not need a browser codec. Once a value reaches a signal seed, handler
payload, live component prop, query/mutation metadata, or another client-visible
surface, treat it as public page data. Never seed secrets, authorization
capabilities, database handles, or private session data.

Make ambiguous numeric domains explicit with a suffix or turbofish. In
particular, `i64` and `u64` use exact integer semantics and decimal-string wire
encoding rather than JavaScript `Number` approximation.

An inbound field seeds a signal once, but reads differently outside one.

## Seeding once versus reading live

Inbound component fields behave differently depending on how you use them:

```rust filename="src/components/draft_field.rs"
let local_draft = signal(self.value); // SeedOnce

html_sync! {
    <span>{self.label}</span>          // LiveRead
}
```

- `signal(self.value)` samples the inbound value when that child occurrence
  mounts. It creates child-owned state, and later parent writes do not reset it.
- A direct field read such as `{self.label}`, `class={self.class}`, or an exact
  local alias remains a `LiveRead`. When a linked parent supplies a live value,
  the child observes the latest value.
- A `memo` derived only from inbound live values participates in the
  enclosing graph but does not create independent mutable state. A memo that
  reads local state inherits that local origin.

A signal initializer cannot read an earlier client cell:

```rust filename="src/components/doubler.rs"
let count = signal(1_i64);
let doubled = rsjs::memo(|| count.get() * 2_i64); // live derivation
```

RSJS rejects `signal(count.get() * 2_i64)` instead of silently taking a
snapshot.

`rsjs::server_only(...)` and `rsjs::server_attr(...)` are intentional per-render
snapshot boundaries, not a way to bypass this model. If a linked parent tries to
pass a live input across one of those boundaries, linking fails rather than
freezing the value silently.

Independent owners need a different mechanism entirely.

## Sharing state between independent owners

Local `signal(...)` cells belong to one final browser owner. For synchronous UI
state shared by independent owners, derive a typed schema and provide it around
the owning server-rendered region. See [Shared state](/docs/rsjs/shared-state)
for the full lifecycle and provider contract.

```rust filename="src/state/workbench.rs"
#[derive(rsjs::SharedState)]
#[rsjs(type_key = "acme.workbench")]
pub struct WorkbenchState {
    pub mode: String,
    pub selected_node: Option<String>,
}

html_sync! {
    {rsjs::SharedStateProvider {
        state: WorkbenchState {
            mode: "select".into(),
            selected_node: None,
        },
        children: WorkbenchRegion {},
    }}
}
```

The provider is a server-side lexical declaration and renders no DOM wrapper.
It does not itself originate client work. A consumer acquires the nearest
provider inside its own origin-capable component:

```rust filename="src/components/workbench_region.rs"
let workbench = rsjs::shared::<WorkbenchState>();
let mode = workbench.mode();
let editing = rsjs::memo(|| mode.get() == "edit");

let choose_edit = rsjs::event_handler(|_: rsjs::Event| {
    mode.set("edit".to_string());
});
```

Every top-level field is an independent writable cell. All committed owners
under the same provider occurrence acquire the same cells, and nested providers
use nearest-provider semantics. A late-hydrating owner observes the current live
value rather than resetting it to the SSR seed. `rsjs::batch(...)` can group
writes across local signals and shared fields.

In the current provider surface, topology must be statically present. The
`state` field must be a named `SharedState` struct literal, and `children` must
be one direct analyzed component literal. Put richer markup inside that child
component.

Provider initialization stays seed-only. RSJS rejects a seed that reads an
enclosing live value rather than snapshotting it. Use a static server seed, make
SharedState the source of truth, or write to it explicitly from a supported
client operation.

Proa serializes the complete provider schema as public page data, including
fields no current consumer reads. Use
[queries and mutations](/docs/rsjs/queries-mutations) instead when the source of
truth is asynchronous, server-owned, stale, refetchable, or invalidated.

## Which rules apply to signals?

| Rule | Why |
| --- | --- |
| Use `client` when the component originates local or shared browser state | `#[rsjs(component)]` alone is participation-only. |
| Read live values with `.get()` in analyzed positions | Reads register the binding or derived dependency to update. |
| Write from supported handlers or browser operations | Render-time writes would make SSR nondeterministic. |
| Use `memo` for derivation | A second synchronized signal creates unnecessary state and drift. |
| Treat client crossings as public | Proa delivers seeds and payloads to the browser. |
| Use SharedState only for typed synchronous cross-owner UI state | Local signals cannot cross an independent owner boundary. |

## Next steps

- [Event handlers](/docs/rsjs/handlers)
  - Write the typed browser handlers that call `.set` and `.update`.
- [Input bindings](/docs/rsjs/bindings)
  - Bind form controls straight to a writable signal.
- [Shared state](/docs/rsjs/shared-state)
  - Share one typed store across independent owners.
- [Hydration strategies](/docs/rsjs/hydration)
  - Decide when the owner holding these signals activates.
- [Runtime wiring](/docs/rsjs/runtime)
  - See how the seed and runtime tags reach the page.


---

# Docs: Shared state

URL: /docs/rsjs/shared-state
Description: Share typed synchronous browser state across independent RSJS owners.

---
title: Shared state
description: Share typed synchronous browser state across independent RSJS owners.
---

`signal(...)` belongs to one hydrated owner, so two independent owners cannot read the same cell. This page covers [defining a schema](#defining-a-schema), [providing it](#providing-state-to-a-subtree), [acquiring fields](#acquiring-and-using-fields), [provider resolution](#resolving-a-provider), and [the provider grammar](#writing-a-valid-provider).

## Defining a schema

Use typed SharedState when independent owners on the same page must
synchronously read and write the same UI state. Derive `rsjs::SharedState` on an
owned struct with named fields and assign a stable, namespaced protocol key:

```rust filename="src/state/workbench.rs"
#[derive(rsjs::SharedState)]
#[rsjs(type_key = "acme.workbench")]
pub struct WorkbenchState {
    pub mode: String,
    pub button_bg: String,
    pub show_grid: bool,
}
```

> **Good to know**: SharedState is not a server cache and does not persist
> automatically. It holds browser-owned state for one response epoch and
> navigation generation. Use a [query or mutation](/docs/rsjs/queries-mutations)
> when the source of truth is server-owned, asynchronous, stale, refetchable, or
> persistent.

The derive generates typed field accessors, client codecs, and a canonical
schema ABI. The explicit `type_key` is the browser/server identity; a Rust
module path or `TypeId` is not.

Changing a field name, order, type, nested codec, or integer-width rule changes
the schema ABI. Two reachable declarations with the same `type_key` but
different ABIs fail during linking. The runtime also validates the complete page
table before attaching any owner, so mixed schema metadata cannot leave a page
partially activated.

A schema reaches the browser only through a provider, which you place next.

## Providing state to a subtree

`SharedStateProvider` establishes server-side topology. It does not render a DOM
wrapper and is not itself a client origin. A provider that has no reachable
consumer emits no browser state.

```rust filename="src/pages/workbench.rs"
pub struct WorkbenchPage;
// Its `#[rsjs(component)]` WebRenderSync impl renders the consumer components.
pub struct WorkbenchChildren {}

#[rsjs(component)]
impl<L: DataLoader> WebRenderSync<L> for WorkbenchPage {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            {rsjs::SharedStateProvider {
                state: WorkbenchState {
                    mode: "select".to_string(),
                    button_bg: "#3366cc".to_string(),
                    show_grid: true,
                },
                children: WorkbenchChildren {},
            }}
        }
        .render(cx)
    }
}
```

`WorkbenchChildren` can render several consumer components inside its own
analyzed render body. Keeping the provider's direct edge explicit lets the
linker authenticate the provider occurrence and every consumer that resolves
through it.

Each of those consumers reaches the store by acquiring it.

## Acquiring and using fields

Acquisition is the client origin. Call `shared::<T>()` in an origin-capable
`#[rsjs(component, client)]` prelude, then keep field handles in named locals:

```rust filename="src/components/theme_panel.rs"
#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for ThemePanel {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let workbench = rsjs::shared::<WorkbenchState>();
        let mode = workbench.mode();
        let button_bg = workbench.button_bg();
        let show_grid = workbench.show_grid();
        let is_editing = rsjs::memo(|| mode.get() == "edit");
        let choose_edit = rsjs::event_handler(
            |_: rsjs::MouseEvent<rsjs::elem::Button>| {
                rsjs::batch(|| {
                    mode.set("edit".to_string());
                    button_bg.set("#2f6b4f".to_string());
                });
            },
        );

        html_sync! {
            <section>
                <input type="color" bind_value={button_bg} />
                <input type="checkbox" bind_checked={show_grid} />
                <button type="button" on_click={choose_edit()}>
                    {if is_editing.get() { "Editing" } else { "Edit" }}
                </button>
            </section>
        }
        .render(cx)
    }
}
```

Each top-level field is an independently invalidating cell with `.get()`,
`.set(...)`, and `.update(...)`. Field handles work in text, attributes,
conditionals, memo values, handlers, and
[`bind_value` / `bind_checked`](/docs/rsjs/bindings) bindings. Updating one
field does not invalidate consumers of unrelated fields.

The provider declaration remains server topology. `shared::<T>()` is what makes
the consumer and its exact provider seed browser-reachable, so the consumer
requires `client` permission.

With several providers on a page, lexical position decides which store a
consumer gets.

## Resolving a provider

Resolution is lexical during server rendering:

- a consumer uses the nearest enclosing provider for its schema;
- nested providers shadow outer providers;
- sibling providers produce independent stores; and
- separate owners resolved to the same provider share the same field cells.

The linker records the exact provider occurrence, schema ABI, and consumer
binding. The browser does not repeat a nearest-provider search through DOM
ancestry and does not fall back to another provider with the same `type_key`.

An owner that hydrates later observes the store's current browser value. A
replayed identical seed never resets a store that an earlier owner has already
mutated.

Making a provider live also puts its whole value on the page.

## Treating seed data as public

Provider registration and seed exposure are separate. A provider remains
private when no committed or prepared owner can acquire it. Once one reachable
consumer makes the provider live, Proa serializes the complete state value into
the page-level `rsjs-shared-state-seed-table`. That table includes fields the
consumer does not read.

Treat every field as public page data. Never put secrets, authorization policy,
database handles, session internals, or server-only capability values in
SharedState. Browser writes also do not synchronize back to Rust or grant
authority. Persist changes through a validated server mutation.

Once the store is live, group related writes so the page repaints once.

## Batching writes

Use `rsjs::batch(...)` when several synchronous writes form one UI update:

```rust filename="src/components/theme_panel.rs"
rsjs::batch(|| {
    mode.set("edit".to_string());
    button_bg.set("#2f6b4f".to_string());
    show_grid.set(true);
});
```

The batching contract is:

- reads inside the batch see writes immediately;
- nested batches share the outer boundary;
- the scheduler deduplicates subscriber, memo, and DOM work across owners
  into one next-microtask flush after the outer callback returns;
- a thrown error does not roll back writes already made, but the scheduler
  restores its state and rethrows the error; and
- a batch is synchronous and cannot be `async` or return a promise.

Ordinary RSJS signal writes use the same scheduler, so batching can combine
local and SharedState writes when they participate in one interaction.

Those writes survive exactly as long as the page generation that owns them.

## Managing store lifetime

Stores live for the complete response epoch and navigation generation. Removing
one owner or router subtree disposes its subscriptions. It does not destroy a
provider still needed by the shell or by an owner that may hydrate later.

Full page-generation teardown destroys stores, field subscriptions, pending
flushes, and owner references, and invalidates old handles. Query entries follow
the same page-generation boundary but remain a separate async cache with
request, staleness, loading, error, and invalidation semantics.

That deterministic lifetime depends on a provider shape the linker can pin.

## Writing a valid provider

The v1 provider intrinsic is intentionally strict inside an analyzed RSJS
template:

| Rule | Required shape |
|------|----------------|
| State | One named `#[derive(rsjs::SharedState)]` struct literal. The compiler rejects constructor calls, opaque values, nested providers, and struct-update syntax. |
| Children | Exactly one direct component struct literal, such as `children: WorkbenchChildren {}`. Put multi-child markup inside that component. |
| Topology | The provider must be an unconditional static lexical site. RSJS does not support providers inside loops, reactive conditionals, repeated/keyed regions, or deferred boundaries. |
| Seed dependencies | Provider state cannot capture a signal, query, mutation, SharedState handle, node ref, handler, browser value, or live inbound prop. The linker rejects a linked live input instead of sampling it once. |
| Child edge | The direct child receives static server inputs only. It cannot carry enclosing client state or an inbound `self` field through the provider boundary. Acquire SharedState inside the child instead. |

These restrictions make provider occurrence identity deterministic. Move
ordinary server calculations before the template and use their results in the
named state literal. If data must remain synchronized after hydration, make
SharedState the source of truth or update it explicitly from a handler.

## Choosing the state model

| Need | Use |
|------|-----|
| State private to one owner | `signal(...)` |
| Live value/callback through directly composed components | A normal linked prop or `rsjs::Handler<T>` |
| Synchronous UI state shared by independent owners | `SharedStateProvider` + `shared::<T>()` |
| Server-owned async data, refetching, staleness, or loading/error state | `query_with_initial(...)` |
| Persist a browser action and invalidate server data | `mutation(...)` |

## Next steps

- [Signals](/docs/rsjs/signals)
  - Keep state private to one owner with `signal(...)`.
- [Component props](/docs/rsjs/component-props)
  - Pass a live value straight to a directly composed child.
- [Queries and mutations](/docs/rsjs/queries-mutations)
  - Own asynchronous, refetchable, server-backed data instead.
- [Input bindings](/docs/rsjs/bindings)
  - Bind form controls to a SharedState field.
- [Runtime wiring](/docs/rsjs/runtime)
  - See when the page emits the shared-state seed table.


---

# Docs: Event handlers

URL: /docs/rsjs/handlers
Description: Attach named typed browser handlers and component callbacks in RSJS.

---
title: Event handlers
description: Attach named typed browser handlers and component callbacks in RSJS.
keywords: [event_handler, on_click, on_input]
---

RSJS treats every `on_*` attribute as a browser origin, so the render-trait implementation holding one carries `#[rsjs(component, client)]`. This page covers [attaching a handler](#attaching-a-handler), [typing events](#typing-events), [calling event methods](#calling-event-methods), and [passing callbacks to children](#passing-callbacks-to-children).

## Attaching a handler

RSJS analyzes the `WebRenderSync` or `WebRender` method you author. It does not generate an inherent `fn render(self)` shorthand, and it does not invent the method's return type.

A small control can use an inline closure:

```rust filename="src/components/disclosure.rs"
let open = signal(false);

html_sync! {
    <button type="button" on_click={|_| open.update(|value| !value)}>
        {if open.get() { "Close" } else { "Open" }}
    </button>
}
```

For production components, declare a named typed `event_handler(...)` before the template. The template stays readable, Rust tooling can inspect a normal closure, and the event's `currentTarget` capabilities stay explicit.

```rust filename="src/components/shipping_picker.rs"
use rsjs::elem;

let selected = signal("standard".to_string());
let pick = rsjs::event_handler(
    |event: rsjs::MouseEvent<elem::Button>, value: &'static str| {
        event.prevent_default();
        selected.set(value.to_string());
    },
);

html_sync! {
    <div>
        <button type="button" on_click={pick("standard")}>"Standard"</button>
        <button type="button" on_click={pick("express")}>"Express"</button>
    </div>
}
```

The first closure parameter is the browser event. An optional second parameter carries a payload the template supplies. Payloads that reach the browser must satisfy the client encoding contract, and they are public page data. The compiler inlines static payloads such as the labels above into the generated handler module and serializes loop-local payloads into marker attributes it owns; either way they are visible page data, so keep secrets out of them.

To say which element a handler runs on, give its event a type parameter.

## Debouncing a handler

Use `rsjs::debounce(handler, delay_ms)` directly in an event attribute:

```rust filename="src/components/search.rs"
let query = signal(String::new());

html_sync! {
    <div>
        <input on_input={rsjs::debounce(|event| query.set(event.value()), 300)} />
        <output>{query.get()}</output>
    </div>
}
```

The handler runs once after 300 milliseconds without another call, with the
most recent event. This is trailing-edge debounce: it does not run immediately
on the first call. Pending work is canceled when the island is disposed.
The analyzed form requires a closure as the first argument and an integer
literal delay as the second; wrapping a previously declared named handler is
not currently supported.

## Typing events

Event generics describe the handler's `currentTarget`, not the raw bubbling target. Use `rsjs::elem` markers for element-specific helpers. Document handlers use `rsjs::web::dom::Document`; window handlers use `rsjs::web::dom::Window`.

```rust filename="src/components/search_filters.rs"
use rsjs::elem;

let query = signal(String::new());
let enabled = signal(false);

let update_query = rsjs::event_handler(
    |event: rsjs::InputEvent<elem::Input>| {
        query.set(event.current_value());
    },
);

let update_enabled = rsjs::event_handler(
    |event: rsjs::ChangeEvent<elem::Input>| {
        enabled.set(event.current_checked());
    },
);

html_sync! {
    <div>
        <input type="search" value={query.get()} on_input={update_query()} />
        <input type="checkbox" checked={enabled.get()} on_change={update_enabled()} />
    </div>
}
```

Reach for a [binding](/docs/rsjs/bindings) instead when the control maps directly to one writable cell. Do not combine `bind_value={query}` with an `on_input` handler whose only job is to write the same `query` value.

A typed event also unlocks the element-specific methods below.

## Calling event methods

| Method | Use |
| --- | --- |
| `event.prevent_default()` | Stop native submit, link, or drag behavior. |
| `event.stop_propagation()` | Stop the event from bubbling. |
| `event.current_value()` | Read the handler element's current value. |
| `event.current_checked()` | Read the handler element's checked state. |
| `event.closest_attr("data-id")` | Read a static attribute from the event target or an ancestor. |
| `event.key()` / `event.code()` | Read keyboard input. |

Pass a string literal as the attribute name to `closest_attr`, `target_attr`, or `current_target_attr` so RSJS can emit a safe selector.

On local bindings these methods read the element the handler runs on; a callback prop moves the resulting value up to the parent. Exact `Document` and `Window` current targets do not offer element-only reads.

## Passing callbacks to children

Use `rsjs::Handler<T>` when a reusable child owns markup but notifies state its direct parent owns. The child declares the DOM handler, and the parent creates the typed callback edge.

```rust filename="src/components/search_input.rs"
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use rsjs::rsjs;

pub struct SearchInput {
    pub value: String,
    pub on_change: rsjs::Handler<String>,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for SearchInput {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let on_input = rsjs::event_handler(
            |event: rsjs::InputEvent<rsjs::elem::Input>| {
                self.on_change.call(event.current_value());
            },
        );

        html_sync! {
            <input value={self.value} on_input={on_input()} />
        }
        .render(cx)
    }
}
```

The parent creates a callback with `rsjs::handler(...)` and passes it through a direct component literal:

```rust filename="src/pages/search.rs"
let query = signal(String::new());
let on_change = rsjs::handler(|next: String| query.set(next));

html_sync! {
    <div>
        {SearchInput {
            value: query.get(),
            on_change,
        }}
        <p>"Query: "{query.get()}</p>
    </div>
}
```

The linker fuses the live parent/child graph into one owner. `self.value` is a `LiveRead`, so it observes the current parent value. `self.on_change.call(...)` invokes the current callback edge. If the child instead declares `let current = signal(self.value)`, that value is `SeedOnce`. `SeedOnce` state belongs to the child and initializes on mount; a later parent write does not reset it.

Normal Rust imports, renamed imports, and re-exports of `SearchInput` work. rustc resolves a direct struct literal into a component edge, so you do not need to spell a canonical module path.

An explicit `rsjs::island(...)` forces an independent owner boundary. Live parent signals and `Handler` callback props cannot cross it. Use independent state, typed [SharedState](/docs/rsjs/shared-state), [queries](/docs/rsjs/queries-mutations), or another explicit synchronization boundary instead.

Use `Option<rsjs::Handler<T>>` for optional callbacks and call it with `call_if_some(...)` after importing `rsjs::OptionalHandlerExt`. Use `rsjs::noop_handler()` when you construct a child without a real callback.

The table below collects the rules behind these patterns.

## What rules do handlers follow?

| Rule | Why |
| --- | --- |
| Prefer named typed handlers in production | They provide clearer markup, event capabilities, and diagnostics. |
| Keep the event as the first parameter | A second parameter, when present, is the template payload. |
| Treat payloads as public data | Browser handlers can read their encoded payloads. |
| Use `Handler<T>` for direct composed callbacks | It preserves a typed live edge without a global event bus. |
| Use `batch(...)` for one logical multi-cell write | Values update immediately while subscribers flush once. |

## Next steps

- [Signals](/docs/rsjs/signals)
  - Model owner-local and typed cross-owner browser state in RSJS.
- [Input bindings](/docs/rsjs/bindings)
  - Bind form controls to writable RSJS signals and SharedState fields.
- [Component props](/docs/rsjs/component-props)
  - Pass RSJS callbacks and reactive values into child component structs.
- [Hydration strategies](/docs/rsjs/hydration)
  - Defer RSJS island hydration until it matters.


---

# Docs: Input bindings

URL: /docs/rsjs/bindings
Description: Bind form controls to writable RSJS signals and SharedState fields.

---
title: Input bindings
description: Bind form controls to writable RSJS signals and SharedState fields.
keywords: [bind_value, bind_checked, two-way binding]
---

A binding synchronizes one form-control DOM property with one writable RSJS cell. This page covers binding [text inputs](#binding-text-inputs), [checkboxes](#binding-checkboxes), [select values](#binding-select-values), and [SharedState fields](#binding-sharedstate-fields).

## Binding text inputs

Use `bind_value` for an input element's string `value` property. That cell is an owner-local `Signal` or a field handle you acquire from typed [SharedState](/docs/rsjs/shared-state). User edits flow into the cell, and later cell writes flow back to the DOM.

```rust filename="src/components/search_box.rs"
let query = signal(String::new());

html_sync! {
    <div>
        <label class="grid gap-2">
            "Search"
            <input type="search" bind_value={query} />
        </label>
        <p>"Current query: "{query.get()}</p>
    </div>
}
```

For an input, the server output includes its initial value and a hydration marker with a shape similar to:

```html filename="output.html"
<input data-rsjs-input-value="..." value="">
```

The `data-rsjs-*` name and ID are compiler-owned implementation details. Do not author or query them from application code.

> **Good to know**: the runtime binding surface also targets a textarea's `value` property. The current SSR emitter does not yet synthesize the textarea's initial text content from the cell seed. Treat first-paint/no-JS textarea parity as a current limitation.

Use a binding when one DOM property maps directly to one writable cell. Use a named typed [event handler](/docs/rsjs/handlers) when the edit also needs parsing, validation, normalization, or multiple writes. Never use both mechanisms to perform the same write.

Booleans follow the same one-property rule under a different attribute name.

## Formatting reactive text

Use `text!()` to combine labels and live values without allocating an SSR
formatting string:

```rust
let subtotal = quantity.get() * unit_price_cents.get();

html_sync! {
    <p>{text!("Subtotal: ${}.{:02}", subtotal / 100_u32, subtotal % 100_u32)}</p>
}
```

Both signals in this example use the proven `u32` domain. Changes to either
signal update the complete formatted text. Direct `text!` calls also work in
ordinary value attributes, such as `title={text!("Quantity {}", quantity.get())}`.
Static siblings remain intact and dynamic values use normal Proa escaping
during SSR and DOM text/attribute writes after hydration.

Client format specs cover integer display/binary/octal/hex and string display,
including literal width and alignment. Float precision, scientific, debug,
pointer and custom Rust formatting remain server-only; RSJS reports
`rsjs/text-format-unsupported` for those reactive specs.

Typed integer constants can accompany live arguments, for example
`text!("{} {:02}", quantity.get(), 5_u32)`. Conditional string arguments preserve
borrowed signal text and owned string transforms. Bare float placeholders keep
Rust's `inf` and `-inf` spelling, including prop-seeded floats.

Bare native Rust boolean arguments write no bytes in ordinary attributes,
matching Proa's `AttrValue` rules. To show boolean labels, pass a string
conditional such as `if enabled.get() { "true" } else { "false" }`. JSON projections retain their
JSON text spelling. Formatted small integers (`i8` / `i16`) are rejected rather
than widened to 32 bits; use a proven `i32` / `u32` / `i64` / `u64` domain.

## Binding checkboxes

`bind_checked` expects a writable boolean cell and mirrors the control's `checked` property.

```rust filename="src/components/newsletter_optin.rs"
let subscribed = signal(false);

html_sync! {
    <div>
        <label class="inline-flex items-center gap-2">
            <input type="checkbox" bind_checked={subscribed} />
            "Email me updates"
        </label>
        {if subscribed.get() {
            html_sync! { <p>"Subscribed"</p> }
        }}
    </div>
}
```

A `<select>` binds a string rather than a boolean, and it carries one extra name.

## Binding select values

Both `bind_value` and `bind_selected` target the owning `<select>` element's string `value`: the selected option's value.

```rust filename="src/components/plan_picker.rs"
let plan = signal("starter".to_string());

html_sync! {
    <div>
        <label class="grid gap-2">
            "Plan"
            <select bind_selected={plan}>
                <option value="starter">"Starter"</option>
                <option value="team">"Team"</option>
                <option value="enterprise">"Enterprise"</option>
            </select>
        </label>
        <p>"Selected plan: "{plan.get()}</p>
    </div>
}
```

`bind_selected` does **not** bind an individual `<option>` element's boolean `selected` property. Prefer `bind_value` when consistent value-binding syntax across controls is clearer. Use `bind_selected` when the select-specific name communicates intent better.

> **Good to know**: the current SSR emitter writes the bound select seed through a generic `value` attribute. HTML does not use that attribute to choose an option during parsing. If the initial choice is not already the markup's selected or default option, the correct value appears when the owner activates. Exact no-JS first-paint select parity is a current emitter gap.

Each control above binds an owner-local signal; a provider field binds the same way.

## Binding SharedState fields

Bind a writable field from the nearest typed provider directly:

```rust filename="src/components/preferences_search.rs"
let preferences = rsjs::shared::<PreferencesState>();
let search = preferences.search();

html_sync! {
    <input type="search" bind_value={search} />
}
```

Every independent owner under that provider occurrence observes the same field cell. A memo value remains read-only and cannot be a `bind_*` target.

An edit that does more than write one cell needs a handler instead.

## Handling derived state and side effects

Use `on_input` or `on_change` instead of a binding when one edit performs more than direct synchronization.

```rust filename="src/components/search_form.rs"
let query = signal(String::new());
let touched = signal(false);

let update_query = rsjs::event_handler(
    |event: rsjs::InputEvent<rsjs::elem::Input>| {
        query.set(event.current_value());
        touched.set(true);
    },
);

html_sync! {
    <div>
        <label class="grid gap-2">
            "Search"
            <input type="search" value={query.get()} on_input={update_query()} />
        </label>
        {if touched.get() && !query.is_non_empty() {
            html_sync! { <p role="alert">"Enter a search term."</p> }
        }}
    </div>
}
```

For several related writes, wrap the handler work in `rsjs::batch(...)`. All values change synchronously, and DOM and subscriber work flushes once.

For numeric or structured values, keep a local browser input as a string at the boundary. Parse it in a typed handler or on submit. Shared fields with a pinned fixed-width representation validate and coerce their input according to that field's schema.

The next section covers edits that land before the owner activates.

## What happens to edits before hydration?

A user may type, check a box, or choose an option before a delayed owner activates. On the owner's first mount, RSJS compares the live control property with its immutable SSR baseline:

- A dirty control wins. RSJS adopts its current browser value into the writable cell before signal-to-DOM effects run.
- An untouched control takes the cell's current value. This matters when another owner has already updated a SharedState field.
- RSJS skips equal property writes, preserving input cursors, textarea selection and scroll state, select focus, and IME composition where the browser exposes stable state.
- A later lifecycle remount does not re-adopt stale retained DOM state. Fresh `SeedOnce` child state wins for the new occurrence.

Within one owner, all controls reconcile before the first DOM commit. An untouched sibling bound to the same cell therefore cannot immediately overwrite a dirty control.

Reconciled or not, the browser still owns what a native form posts.

## Submitting a form

Bindings pair with native forms. Let the browser own submission when a normal POST is enough, and use RSJS state for optimistic UI or inline validation.

```rust filename="src/components/newsletter_form.rs"
let email = signal(String::new());
let terms = signal(false);
let submitting = signal(false);
let mark_submitting = rsjs::event_handler(
    |_: rsjs::SubmitEvent<rsjs::elem::Form>| submitting.set(true),
);

html_sync! {
    <form method="post" action="/newsletter" on_submit={mark_submitting()}>
        <input type="email" name="email" bind_value={email} required />
        <label>
            <input type="checkbox" name="terms" bind_checked={terms} required />
            "I accept the terms"
        </label>
        <button type="submit" disabled={submitting.get()}>
            {if submitting.get() { "Joining..." } else { "Join" }}
        </button>
    </form>
}
```

Keep `name` attributes on posted fields: RSJS state does not replace native form serialization. Use a hidden input when the server needs a derived value that does not map one-to-one to a visible control.

The table below collects the rules behind these patterns.

## What rules do bindings follow?

| Rule | Reason |
| --- | --- |
| Bind one DOM property to one writable cell per element | Competing bindings create ambiguous ownership. |
| `bind_value` writes strings | Parse or normalize local numeric/structured values in a handler. |
| `bind_checked` writes booleans | It mirrors the control's `checked` property. |
| `bind_selected` writes the select's string value | It does not bind `option.selected`. |
| Keep `name` attributes on posted fields | Native form submission reads the DOM, not RSJS state directly. |
| Use handlers for side effects | Bindings stay direct property synchronization. |

## Next steps

- [Event handlers](/docs/rsjs/handlers)
  - Attach named typed browser handlers and component callbacks in RSJS.
- [Signals](/docs/rsjs/signals)
  - Model owner-local and typed cross-owner browser state in RSJS.
- [Shared state](/docs/rsjs/shared-state)
  - Share typed synchronous browser state across independent RSJS owners.
- [Forms and actions](/docs/guides/forms-actions)
  - Build native HTML forms and handle their submissions with Axum.


---

# Docs: Component props

URL: /docs/rsjs/component-props
Description: Pass RSJS callbacks and reactive values into child component structs.

---
title: Component props
description: Pass RSJS callbacks and reactive values into child component structs.
---

A child component receives parent state through ordinary struct fields, and the linker keeps those fields live across the edge. This page covers [required](#passing-a-required-callback) and [optional](#passing-an-optional-callback) callbacks, [live values and local state](#when-does-a-child-see-live-parent-values), [node refs](#passing-a-node-ref), and [island boundaries](#what-crosses-an-island-boundary).

Include these imports in each component module below:

```rust
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use rsjs::{rsjs, signal};
```

## Passing a required callback

Use callback props when a child component owns markup but the parent owns state.

Child component:

```rust filename="src/components/search_input.rs"
pub struct SearchInput {
    pub label: &'static str,
    pub value: String,
    pub on_change: rsjs::Handler<String>,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for SearchInput {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let on_input = rsjs::event_handler(
            |event: rsjs::InputEvent<rsjs::elem::Input>| {
                self.on_change.call(event.current_value());
            },
        );

        html_sync! {
            <label class="grid gap-2">
                <span>{self.label}</span>
                <input
                    type="search"
                    value={self.value}
                    on_input={on_input()}
                />
            </label>
        }
        .render(cx)
    }
}
```

Parent component:

```rust filename="src/components/search_panel.rs"
pub struct SearchPanel;

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for SearchPanel {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let query = signal(String::new());
        let on_change = rsjs::handler(|next: String| {
            query.set(next);
        });

        html_sync! {
            <section>
                {SearchInput {
                    label: "Search",
                    value: query.get(),
                    on_change,
                }}
                <p>"Current query: "{query.get()}</p>
            </section>
        }
        .render(cx)
    }
}
```

The parent renders `SearchInput` through a direct component edge. The semantic linker resolves the child's real Rust type and imports its linked fragment. It then fuses the two occurrences into one final owner, because a live value and a callback cannot cross an ownership boundary. The callback updates the parent signal without creating an independent island.

That edge does not depend on how you spell the child's name.

## Resolving component names

Direct component syntax uses normal Rust name resolution. Ordinary imports, renamed imports, and re-exports all select the same component ABI:

```rust filename="src/components/status_row.rs"
use crate::ui::StatusBadge as Badge;

html_sync! {
    <div>
        {Badge {
            label: status.get(),
        }}
    </div>
}
```

The authored path spelling is not the component identity. Rust resolves `Badge`, and the linker verifies the selected type's generated component ABI. A direct struct literal in an analyzed template is therefore a component edge. To render an arbitrary non-component renderer, construct it in the prelude and render its local value instead.

Name resolution decides which type renders; the next section decides when that type sees a new value.

## When does a child see live parent values?

A direct inbound read participates in the parent graph without originating browser state:

```rust filename="src/components/status_badge.rs"
pub struct StatusBadge {
    pub label: String,
}

#[rsjs(component)]
impl<L: DataLoader> WebRenderSync<L> for StatusBadge {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <span>{self.label}</span>
        }
        .render(cx)
    }
}
```

When a parent passes `label: status.get()`, the direct `self.label` read observes the current parent value. When you render the component without a live producer, the same template stays ordinary SSR. RSJS does not emit JavaScript for a field that could participate but has no live producer.

Local state has different time semantics. If a child declares `let current = signal(self.value)`, it samples the incoming value once when that child occurrence initializes. Later parent updates do not reset the child-owned signal. A fresh child occurrence samples a fresh seed. Callback props similarly resolve the currently connected parent callback when the browser event fires.

The complete temporal contract is:

| Child use of an inbound value | Semantics |
|-------------------------------|-----------|
| Text, attribute, property, branch, handler read, or exact local alias | `LiveRead`: observes the latest connected parent value. |
| `signal(self.value)` | `SeedOnce`: samples once when that child occurrence initializes; later parent writes do not reset local state. |
| A query key derived from the field | Rebinds the observer from the old cache entry to the entry for the new structural key. It does not mutate the old entry's identity. |
| `rsjs::SharedStateProvider { state: ... }` initialization | RSJS rejects a live parent value. Provider initialization is a server seed, not ongoing synchronization. |
| `rsjs::island(...)` input | RSJS rejects a live value, callback, or client handle, because it would cross an independent-owner cut. |

`rsjs::Handler<T>` follows the same live-edge rule: `self.on_change.call(...)` resolves the callback currently connected to that child occurrence when the event fires. It does not retain a serialized or stale SSR closure.

A child that runs without a parent callback declares that field as optional.

## Passing an optional callback

Use `Option<rsjs::Handler<T>>` when the child can run without a parent callback.

```rust filename="src/components/clear_button.rs"
use rsjs::OptionalHandlerExt;

pub struct ClearButton {
    pub on_clear: Option<rsjs::Handler<()>>,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for ClearButton {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <button type="button" on_click={|_| self.on_clear.call_if_some(())}>"Clear"</button>
        }
        .render(cx)
    }
}
```

```rust filename="src/components/search_panel.rs"
let on_clear = rsjs::handler(|_: ()| query.set(String::new()));

html_sync! {
    <div>{ClearButton { on_clear: Some(on_clear) }}{ClearButton { on_clear: None }}</div>
}
```

When the browser event and a per-node value both matter, build the handler inside the child.

## Combining an event with a payload

Use `rsjs::event_handler(...)` inside the child when the browser event and a per-node payload both matter.

```rust filename="src/components/date_picker.rs"
pub struct DatePicker {
    pub selected: u32,
    pub on_change: rsjs::Handler<u32>,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for DatePicker {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let selected: rsjs::Signal<u32> = signal(self.selected);

        let pick = rsjs::event_handler(|event: rsjs::MouseEvent<rsjs::elem::Button>, day: u32| {
            event.prevent_default();
            selected.set(day);
            self.on_change.call(day);
        });

        html_sync! {
            <div class="grid grid-cols-7 gap-1">
                {for day in 1_u32..=31_u32 {
                    html_sync! {
                        <button
                            type="button"
                            data_selected={selected.get() == day}
                            on_click={pick(day)}
                        >
                            {day}
                        </button>
                    }
                }}
            </div>
        }
        .render(cx)
    }
}
```

Parent:

```rust filename="src/components/booking_panel.rs"
let selected_day = signal(15_u32);
let on_change = rsjs::handler(|day: u32| selected_day.set(day));

html_sync! {
    <div>
        {DatePicker {
            selected: selected_day.get(),
            on_change,
        }}
        <p>"Selected day: "{selected_day.get()}</p>
    </div>
}
```

Callbacks carry values up to the parent; a node ref hands a DOM handle down to the child.

## Passing a node ref

A static direct child can bind a parent-owned `NodeRef<T>`. The child consumes the handle as a participant, so it does not need `client` permission for the ref alone:

```rust filename="src/components/focus_input.rs"
pub struct FocusInput {
    pub input_ref: rsjs::NodeRef<rsjs::HtmlInputElement>,
}

#[rsjs(component)]
impl<L: DataLoader> WebRenderSync<L> for FocusInput {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <input ref={self.input_ref} />
        }
        .render(cx)
    }
}
```

The origin-capable parent creates and uses the same handle:

```rust filename="src/components/account_form.rs"
let input_ref = rsjs::node_ref::<rsjs::HtmlInputElement>();

html_sync! {
    <div>
        {FocusInput { input_ref }}
        <button type="button" on_click={|_| input_ref.focus()}>"Focus"</button>
    </div>
}
```

The linker fuses the direct parent and child into one owner and aliases one browser ref object. There is no serialization or fallback allocation. This first handle shape is **required** and `StaticSingle`. RSJS rejects optional, explicit-island, conditional, repeated, keyed, standalone-child, and multiply-bound crossings.

Every shape above assumes one fused owner; an explicit island creates an independent one instead.

## What crosses an island boundary?

| Shape | Callback can update parent state? |
|-------|-----------------------------------|
| `{Child { on_change }}` | Yes. The linker fuses the child occurrence and the parent into one final owner. |
| `{rsjs::island(Child { on_change: rsjs::noop_handler() })}` | No. Explicit child islands are independent. |
| A child constructed in the prelude as an ordinary SSR value | No live parent edge crosses; the server renders it once. |

Use `rsjs::noop_handler()` for standalone child instances that need a required handler field without calling back into a parent.

An explicit island can receive static server scalars for its own SSR and initial seed. It can also receive one immutable static HTML slot. That slot requires the child's component ABI to carry the slot capability, and the value must be a direct `html_sync!` or `html!` fragment. That fragment carries exactly one root element and entirely static markup. The server renders the slot once, and the browser does not reconstruct it.

Live parent values, callbacks, and query, SharedState, or NodeRef handles cannot cross that independent boundary. Neither can arbitrary or multi-root renderables, reactive slot content, or nested owners. Render the child directly when those values must stay live, or give the independent child its own state and communication channel.

The table below maps each prop kind to the pattern that carries it.

## Choosing a prop shape

| Prop kind | Pattern |
|-----------|---------|
| Parent-owned callback | `pub on_change: rsjs::Handler<T>` plus `self.on_change.call(value)`. |
| Optional callback | `Option<rsjs::Handler<T>>` plus `call_if_some(value)`. |
| Live inbound label or id | Render `self.label` directly; a linked live parent value stays current. |
| Intentional server-only attribute | `href={rsjs::server_attr(self.href)}` takes a per-render snapshot. |
| Child-local reactive value | `let current = signal(self.value)` samples the incoming value once. |
| Required static DOM handle | `pub input_ref: NodeRef<HtmlInputElement>` plus a direct `{FocusInput { input_ref }}` edge aliases the parent's exact ref object. |

Read inbound props directly when they need to stay live. Create a prop-seeded signal only when the child deliberately owns `SeedOnce` state, and emit a callback for parent-owned changes. Do not treat an inbound prop as mutable shared state.

## Next steps

- [Event handlers](/docs/rsjs/handlers)
  - Attach named typed browser handlers and component callbacks in RSJS.
- [Signals](/docs/rsjs/signals)
  - Model owner-local and typed cross-owner browser state in RSJS.
- [Shared state](/docs/rsjs/shared-state)
  - Share typed synchronous browser state across independent RSJS owners.
- [Server-rendered content](/docs/rsjs/server-only)
  - Keep ordinary Rust values and renderables outside an RSJS client graph.


---

# Docs: Client helpers

URL: /docs/rsjs/client-helpers
Description: Compile small pure Rust functions into the RSJS browser graph.

---
title: Client helpers
description: Compile small pure Rust functions into the RSJS browser graph.
---

RSJS evaluates a `#[rsjs::client]` function during the server render, then reruns it in the browser when its result depends on live data. This page covers [annotating a helper](#annotating-a-helper), [path resolution](#calling-helpers-through-ordinary-rust-paths), [purity limits](#keeping-helpers-pure-and-portable), and [the data that crosses](#crossing-data-into-a-helper).

## Annotating a helper

Use `#[rsjs::client]` when a small, portable calculation must produce the same result during SSR and rerun after a browser-visible input changes. Annotate the function definition once. A reachable call creates a symbolic helper edge automatically; the consuming component declares no allowlist.

```rust filename="src/components/results.rs"
mod labels {
    #[rsjs::client]
    pub fn result_label(count: i64) -> String {
        if count == 1_i64 {
            "result".to_string()
        } else {
            "results".to_string()
        }
    }
}

use labels::result_label as label_for_count;
```

Call the helper through an ordinary Rust path inside an analyzed component:

```rust filename="src/components/results.rs"
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use rsjs::{event_handler, rsjs, signal};

pub struct Results;

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for Results {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let count = signal(1_i64);
        let increment = event_handler(|_: rsjs::MouseEvent<rsjs::elem::Button>| {
            count.update(|value| value + 1_i64);
        });

        html_sync! {
            <div>
                <button type="button" on_click={increment()}>"Add"</button>
                <p>{count.get()}" "{label_for_count(count.get())}</p>
            </div>
        }
        .render(cx)
    }
}
```

The helper evaluates for the server render and becomes part of the browser owner because its result depends on `count`. The semantic linker resolves `label_for_count` to its real Rust definition, follows the helper dependency closure, and emits only reachable helpers. The next section covers which path spellings that resolution accepts.

## Calling helpers through ordinary Rust paths

Helper calls may use:

- A same-module function name.
- A normal `use` import.
- A renamed import such as `use labels::result_label as label_for_count`.
- A re-export from a public module.
- A qualified path.
- A helper published by another crate with compatible linked metadata.

Path spelling is not helper identity. Rustc-selected relocation targets give the linker the resolved definition. Authors do not need to replace imported names with canonical paths.

Because the linker resolves identity this way, RSJS removed the component-level `clients(...)` list:

```rust filename="src/components/results.rs"
// Rejected:
#[rsjs(component, client, clients(crate::labels))]
```

The supported form is the annotation alone:

```rust filename="src/pricing.rs"
#[rsjs::client]
pub fn subtotal(price: i64, quantity: i64) -> i64 {
    price * quantity
}
```

Then call `subtotal(...)` through any ordinary resolved Rust path. If that call is unreachable from the final browser graph, neither the function nor its helper dependencies ship. Modules group helpers without changing that rule, as the next section shows.

## Grouping helpers in a module

`#[rsjs::client_module]` remains available for bundling or namespace-level validation. It is optional, and it does not make every function eligible. Each portable helper still carries its own `#[rsjs::client]` annotation.

```rust filename="src/pricing.rs"
#[rsjs::client_module]
pub mod pricing {
    #[rsjs::client]
    pub fn subtotal(price: i64, quantity: i64) -> i64 {
        price * quantity
    }

    #[rsjs::client]
    pub fn discounted(total: i64, enabled: bool) -> i64 {
        if enabled { total - 10_i64 } else { total }
    }
}
```

Grouping changes organization and bundle metadata, not reachability: unused helpers in the module still do not become browser code. Every helper in a module obeys the purity limits below.

## Keeping helpers pure and portable

A **client helper** is an origin-free calculation over its parameters and local values. It may use the Rust expressions, control flow, primitive types, collections, and string operations that the RSJS client IR supports.

It cannot:

- Capture surrounding local state.
- Declare or acquire signals, SharedState, queries, mutations, or node refs.
- Access `WebContext`, loaders, files, environment variables, or server-only
  capabilities.
- Perform network or browser effects.
- Hide unsupported browser globals behind ordinary Rust calls.
- Call an unannotated helper from a browser-reachable path.

Use compiler-known handlers, browser capabilities, queries, and mutations for effects. Unsupported helper syntax fails during analysis or linking instead of silently running only on one side. The values you pass into a pure helper carry their own constraints.

## Crossing data into a helper

Arguments that reach a client helper are browser-visible and must have a supported client representation. Runtime values that cross through a signal, live component prop, or payload use the `rsjs::ClientEncode` contract. Prefer small client-shaped inputs such as fixed-width numbers, booleans, short strings, enum tags, ISO timestamps, or explicit projections.

If a helper needs a server-loaded component field, first make the intended crossing explicit:

```rust filename="src/components/price.rs"
let cents = signal(self.cents);

html_sync! {
    <output>{money::format_cents(cents.get())}</output>
}
```

Do not pass secrets or a large server object to format one label. Keep server-only calculations in ordinary Rust prelude code and render their result through SSR. Some results never need to cross at all.

## When not to use a client helper?

If a result never changes in the browser, use a normal Rust function:

```rust filename="src/components/record_row.rs"
let label = format_server_label(self.record);

html_sync! {
    <span>{label}</span>
}
```

That value remains opaque SSR and adds no helper edge or JavaScript. Reach for `#[rsjs::client]` only when the calculation must rerun from live browser data. The table below collects every rule on this page.

## Rules

| Rule | Why |
| --- | --- |
| Annotate each portable function once with `#[rsjs::client]` | Eligibility belongs to the definition, not every caller. |
| Use ordinary imports, aliases, re-exports, and paths | The linker uses rustc-resolved identity. |
| Do not add `clients(...)` to a component | RSJS removed component allowlists. |
| Keep helpers pure and origin-free | Effects require explicit compiler-known capabilities. |
| Treat arguments as public browser data | RSJS delivers reachable values to client code. |
| Keep server-only formatting as ordinary Rust | Static results do not need a browser helper. |
| Let reachability decide emission | Uncalled and unreachable helpers do not ship. |

## Next steps

- [Browser APIs](/docs/rsjs/browser-apis)
  - Reach events, node refs, storage, and network through the analyzed surface.
- [Server-rendered content](/docs/rsjs/server-only)
  - Keep ordinary Rust values and renderables outside the client graph.
- [Signals](/docs/rsjs/signals)
  - Model the live browser state a helper reads from.
- [Queries and mutations](/docs/rsjs/queries-mutations)
  - Run browser network work through typed capabilities instead of raw `fetch`.


---

# Docs: Browser APIs

URL: /docs/rsjs/browser-apis
Description: Reach browser capabilities through the analyzed RSJS surface.

---
title: Browser APIs
description: Reach browser capabilities through the analyzed RSJS surface.
---

RSJS does not expose raw browser globals, so every browser capability reaches your island through an analyzed, typed surface. This page covers [the surface map](#mapping-browser-apis-to-rsjs-surfaces), [events](#handling-events), [node refs](#using-node-refs), [window and storage](#reading-window-url-and-storage), [observers](#which-observers-can-i-use), and [network calls](#fetching-data-in-the-browser).

## Mapping browser APIs to RSJS surfaces

Use the analyzed surface: event attributes, event accessors, node refs, `rsjs::` helpers, queries, mutations, typed shared state, and timers. A portable `#[rsjs::client]` helper extends pure computation, but it cannot hide DOM access, network I/O, or another browser capability. See [Client helpers](/docs/rsjs/client-helpers) for the one-annotation helper model.

| API family | RSJS surface |
|------------|--------------|
| Events | `on_click`, `on_input`, `on_change`, pointer, touch, drag/drop, keyboard, wheel, animation, transition, document, and window events. |
| DOM nodes | `node_ref::<T>()` plus typed reads/effects such as `value()`, `rect_width()`, `focus()`, `set_attribute(...)`, `show_modal()`, and `show_popover()`. |
| Forms | `bind_value`, `bind_checked`, `bind_selected`, native validity reads/effects, file input metadata, dropped-file reads. |
| Cross-island state | `SharedStateProvider`, `shared::<T>()`, typed field cells, and `batch(...)`. |
| Window and URL | `rsjs::window`, `rsjs::location`, `rsjs::history`, and `rsjs::url` helpers. |
| Storage | `rsjs::local_storage` and `rsjs::session_storage` string/bool/i64/f64 reads plus writes/removes. |
| Clipboard | `write_text(...)`, `read_text_into(&signal)`, `read_text_into_or(&signal, fallback)` inside user-gesture handlers. |
| Fetch | Use `query_with_initial(...)` and `mutation(...)`; RSJS rejects raw `fetch` and XHR. |
| Encoding | `utf8_bytes`, `utf8_string`, `base64_*`, `base64url_*`. |
| Timers | `rsjs::interval(...)` and `rsjs::debounce(...)`; RSJS does not expose raw `setTimeout`. |
| WebAuthn | JSON ceremony helpers: `create_json_into(...)`, `get_json_into(...)`, and fallback variants. |

The rest of this page works through the families in turn, starting with events.

## Handling events

```rust filename="src/components/search_filters.rs"
let query = signal(String::new());
let dropped = signal(String::new());
let update_query = rsjs::event_handler(
    |event: rsjs::InputEvent<rsjs::elem::Input>| {
        query.set(event.current_value());
    },
);
let accept_drop = rsjs::event_handler(|event: rsjs::DragEvent| {
    event.prevent_default();
    dropped.set(event.data_transfer_first_file_name());
});
let allow_drop = rsjs::event_handler(|event: rsjs::DragEvent| {
    event.prevent_default();
});

html_sync! {
    <div>
        <input
            type="search"
            on_input={update_query()}
        />
        <div
            on_drop={accept_drop()}
            on_dragover={allow_drop()}
        >
            {dropped.get()}
        </div>
    </div>
}
```

Common event attributes:

```rust filename="src/components/events.rs"
on_click
on_input
on_change
on_submit
on_keydown
on_keyup
on_pointerdown
on_pointermove
on_pointerup
on_touchstart
on_touchmove
on_touchend
on_dragstart
on_dragover
on_drop
on_wheel
on_scroll
on_document_click
on_document_keydown
on_window_resize
on_window_popstate
on_window_hashchange
on_window_storage
```

Global handlers use exact non-element current targets:

```rust filename="src/components/global_events.rs"
use rsjs::web::dom;

let close_on_escape = rsjs::event_handler(
    |event: rsjs::KeyboardEvent<dom::Document>| {
        if event.key() == "Escape" {
            open.set(false);
        }
    },
);
let measure_on_resize = rsjs::event_handler(
    |_: rsjs::Event<dom::Window>| width.set(panel.rect_width()),
);
```

`current_target()` is the actual `Document` or `Window` for those bindings.
It does not expose element methods; use event target accessors or a typed node
ref when you need an element.

Use `on_mouseover` and `on_mouseout` for delegated hover.

> **Good to know**: RSJS rejects `on_mouseenter` and `on_mouseleave` because those events do not bubble.

When a handler needs one specific element instead of the event target, reach for a node ref.

## Using node refs

Use `node_ref` when a handler needs a specific element.

```rust filename="src/components/checkout_form.rs"
let input = rsjs::node_ref::<rsjs::HtmlInputElement>();
let form = rsjs::node_ref::<rsjs::HtmlFormElement>();
let dialog = rsjs::node_ref::<rsjs::HtmlDialogElement>();
let panel = rsjs::node_ref::<rsjs::HtmlElement>();
let width = signal(0.0_f64);
let submit = rsjs::event_handler(|_: rsjs::MouseEvent<rsjs::elem::Button>| {
    if input.check_validity() {
        form.request_submit();
    } else {
        input.report_validity();
    }
});
let open_dialog = rsjs::event_handler(
    |_: rsjs::MouseEvent<rsjs::elem::Button>| dialog.show_modal(),
);
let measure = rsjs::event_handler(|_: rsjs::Event<rsjs::web::dom::Window>| {
    width.set(panel.rect_width());
});

html_sync! {
    <div>
        <form ref={form}>
            <input ref={input} required />
            <button type="button" on_click={submit()}>"Submit"</button>
        </form>
        <dialog ref={dialog}>"Saved"</dialog>
        <button type="button" on_click={open_dialog()}>"Open dialog"</button>
        <section ref={panel} on_window_resize={measure()}>{width.get()}</section>
    </div>
}
```

Supported ref markers include `Element`, `HtmlElement`, `HtmlInputElement`, `HtmlTextAreaElement`, `HtmlSelectElement`, `HtmlFormElement`, and `HtmlDialogElement`. Handlers reach state outside the document through the window, URL, and storage helpers.

## Reading window, URL, and storage

```rust filename="src/components/filter_bar.rs"
let hash = signal(String::new());
let apply = rsjs::event_handler(|_: rsjs::MouseEvent<rsjs::elem::Button>| {
    hash.set(rsjs::url::search_param_or("filter", "all"));
    rsjs::local_storage::set_item("filter", hash.get());
    rsjs::url::push_search_param("filter", hash.get());
    rsjs::document::dispatch_event_with_detail("filters:changed", hash.get());
});

html_sync! {
    <button type="button" on_click={apply()}>"Apply"</button>
}
```

Useful helpers:

```rust filename="src/components/filter_bar.rs"
rsjs::window::{inner_width, inner_height, scroll_x, scroll_y, scroll_to, scroll_by, print}
rsjs::navigator::language
rsjs::location::{href, origin, pathname, search, hash, set_hash, assign, replace, reload}
rsjs::history::{push_state, replace_state, back, forward, go}
rsjs::url::{search_param, search_param_or, set_search_param, push_search_param, delete_search_param}
rsjs::local_storage::{get_item, get_item_or, get_bool_or, get_i64_or, get_f64_or, set_item, remove_item}
rsjs::session_storage::{get_item, get_item_or, get_bool_or, get_i64_or, get_f64_or, set_item, remove_item}
```

Observers work differently: the runtime drives them, and your handlers never touch them.

## Which observers can I use?

The runtime uses `IntersectionObserver` for visible hydration:

```rust filename="src/components/below_fold_chart.rs"
#[rsjs(component, client, strategy = "visible")]
impl<L: DataLoader> WebRenderSync<L> for BelowFoldChart {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let details = signal(false);
        let show_details = rsjs::event_handler(
            |_: rsjs::MouseEvent<rsjs::elem::Button>| {
                details.set(!details.get());
            },
        );
        html_sync! {
            <section>
                <button type="button" on_click={show_details()}>"Chart details"</button>
                <div hidden={!details.get()}>"Hydrates when visible"</div>
            </section>
        }
        .render(cx)
    }
}
```

`matchMedia` powers `strategy = "media:(...)"`. `MutationObserver` powers detached-island cleanup.

These observer APIs are not public island APIs yet:

| Browser API | Current RSJS status |
|-------------|---------------------|
| `IntersectionObserver` | Internal only via `strategy = "visible"`. |
| `ResizeObserver` | Not exposed. Use `on_window_resize` plus node-ref dimensions; custom observation requires application-owned JavaScript today. |
| `MutationObserver` | Internal cleanup only. Custom observation requires application-owned JavaScript today. |
| `PerformanceObserver` | Not exposed. Use application-owned JavaScript until RSJS has an explicit typed capability. |

Network work has its own typed surface, described next.

## Fetching data in the browser

Use queries and mutations for browser fetch work. A query can stay synchronous when its serializable initial value already exists. Mutations use the async `WebRender` + `html!` surface, even when the browser performs the eventual request:

```rust filename="src/components/cart_updater.rs"
use std::future::Future;

use proa::{
    DataLoader, RenderOutcome, WebContext, WebRender, WriteError,
};
use proa::html;
use rsjs::rsjs;

pub struct CartUpdater;

#[rsjs(component, client)]
impl<L: DataLoader> WebRender<L> for CartUpdater {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let save = rsjs::mutation::<u32, ()>(
                rsjs::QueryKey::new(("cart", "update")),
                rsjs::FetchRequest {
                    url: "/api/cart",
                    apply_base_path: true,
                    method: Some(rsjs::HttpMethod::Patch),
                    credentials: Some(rsjs::FetchCredentials::SameOrigin),
                    response: Some(rsjs::ResponseKind::Empty),
                    ..Default::default()
                },
                &[rsjs::QueryKey::new(("cart", "summary"))],
            );
            let save_quantity = rsjs::event_handler(
                |_: rsjs::MouseEvent<rsjs::elem::Button>| {
                    save.run(2_u32);
                },
            );

            html! {
                <button type="button" on_click={save_quantity()}>"Save"</button>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

Raw `fetch`, `XMLHttpRequest`, `WebSocket`, `EventSource`, IndexedDB, Web Workers, WebCrypto, Geolocation, media capture, Canvas, and WebGL sit outside the analyzed RSJS surface today. Do not hide them in `#[rsjs::client]`: those helpers are origin-free and cannot access raw browser globals. Use the typed query/mutation surface where it applies; otherwise keep the capability in application-owned JavaScript until RSJS exposes an explicit typed helper.

## Next steps

- [Event handlers](/docs/rsjs/handlers)
  - Write typed handlers and read event data through accessors.
- [Input bindings](/docs/rsjs/bindings)
  - Bind form values, checkboxes, and selects to signals.
- [Queries and mutations](/docs/rsjs/queries-mutations)
  - Fetch and write server data with typed keys and invalidation.
- [Hydration strategies](/docs/rsjs/hydration)
  - Choose when an island hydrates, including `visible` and media strategies.


---

# Docs: Server-rendered content

URL: /docs/rsjs/server-only
Description: Keep ordinary Rust values and renderables outside an RSJS client graph.

---
title: Server-rendered content
description: Keep ordinary Rust values and renderables outside an RSJS client graph.
---

Ordinary Rust values remain server-rendered unless a browser obligation depends on them. This page covers [what stays on the server](#keeping-values-out-of-the-client-graph), [trusted static markup](#rendering-trusted-static-markup), [server-only attributes](#setting-server-only-attributes), [child props](#passing-props-to-a-child-component), and [struct literals](#when-is-a-struct-literal-a-component-edge).

## Keeping values out of the client graph

You do not need to annotate every static child in an interactive component. Common cases:

| Need | Pattern |
|------|---------|
| Render a trusted SVG or other ordinary renderable | Construct it in the prelude and render the value |
| Render a compiler-composable child | Use a direct struct literal in the template |
| Render an arbitrary non-component struct | Construct it in the prelude and render the resulting local |
| Render a static-per-request attribute | `rsjs::server_attr(...)` |

An ordinary server renderable may emit zero, one, or many DOM nodes. RSJS keeps reactive addressing correct without parsing or buffering that output. The generated client code takes a fast speculative DOM path and verifies the compiler-owned marker it reached. When opaque output shifts a later target, the code falls back to an owner-scoped marker lookup. You do not need to add a single-element host to stabilize an arbitrary SSR fragment's node count.

Raw HTML is the clearest case of output RSJS never inspects.

## Rendering trusted static markup

You must still trust raw HTML and sanitize it before rendering. That safety boundary is separate from client reachability.

```rust filename="src/components/icon_button.rs"
use proa::{DataLoader, UnsafeRaw, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use rsjs::{rsjs, signal};

pub struct IconButton;

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for IconButton {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let pressed = signal(false);
        let icon =
            UnsafeRaw(r##"<svg aria-hidden="true"><use href="#heart"></use></svg>"##);

        html_sync! {
            <button type="button" on_click={|_| pressed.set(!pressed.get())}>
                {icon}
                {if pressed.get() { "Saved" } else { "Save" }}
            </button>
        }
        .render(cx)
    }
}
```

RSJS hydrates the button and reactive label. The SVG remains ordinary SSR. Attributes take the same server-or-client decision, with an explicit marker for the server side.

## Setting server-only attributes

Use `server_attr(...)` for static-per-render attributes that must **not** update after hydration.

```rust filename="src/components/decorated_button.rs"
pub struct DecoratedButton {
    pub label: &'static str,
    pub class: &'static str,
    pub on_press: rsjs::Handler<()>,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for DecoratedButton {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <button
                type="button"
                class={rsjs::server_attr(self.class)}
                on_click={|_| self.on_press.call(())}
            >
                {self.label}
            </button>
        }
        .render(cx)
    }
}
```

Use a normal dynamic attribute when the value must react to a signal:

```rust filename="src/components/toggle.rs"
let selected = signal(false);

html_sync! {
    <button data_selected={selected.get()}>"Toggle"</button>
}
```

Do not wrap `selected.get()` in `server_attr(...)`. RSJS rejects that capture at compile time because accepting it would silently freeze a reactive value at SSR time. A parent passing props into that component meets the same distinction.

## Passing props to a child component

Descriptor-backed RSJS child components can mix reactive props, callback props, and server-only props.

```rust filename="src/components/parent.rs"
pub struct Parent;

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for Parent {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let pressed = signal(0_i64);
        let on_press = rsjs::handler(|_| pressed.set(1_i64));

        html_sync! {
            <section>
                {DecoratedButton {
                    label: "Press",
                    class: "primary",
                    on_press,
                }}
                <p>{pressed.get()}</p>
            </section>
        }
        .render(cx)
    }
}
```

Both values appear in the server HTML, but their client semantics differ. `self.label` is a live inbound read, so it follows a live parent value whenever a parent connects one. `server_attr(self.class)` deliberately snapshots the class for that server render. A parent may pass a static server value there. Final linking rejects a live parent value rather than silently converting it into a snapshot. The callback's live edge fuses these parent and child occurrences into one final owner, whose owner module imports the child's linked fragment.

If you force an explicit nested island with `rsjs::island(...)`, parent callbacks cannot cross that boundary. Pass independent state or `rsjs::noop_handler()` instead. The child edge above works because of how the template reads a struct literal.

## When is a struct literal a component edge?

A direct struct literal in an analyzed template has a deliberately strong meaning: it is a compiler-composable component edge.

```rust filename="src/components/parent.rs"
html_sync! {
    <div>
        {DecoratedButton {
            label: "Press",
            class: "primary",
            on_press,
        }}
    </div>
}
```

If a struct is only an ordinary server renderer, construct it first:

```rust filename="src/pages/docs.rs"
let rendered_document = DocumentationBody { document };

html_sync! {
    <article>{rendered_document}</article>
}
```

This lets normal Rust imports and aliases work for components. It also preserves an unambiguous escape route for arbitrary renderables.

Renamed imports and re-exports work too because Rust resolves the component type before the linker authenticates its ABI:

```rust filename="src/components/status_row.rs"
use crate::ui::StatusBadge as Badge;

html_sync! {
    <div>{Badge { label: current_label.get() }}</div>
}
```

The alias spelling does not carry component identity. The table below collects every rule on this page.

## Rules

| Rule | Why |
|------|-----|
| Do not read signals inside `server_attr(...)` | RSJS rejects the capture because the attribute would otherwise freeze at SSR time. |
| Do not pass live values into `server_only(...)` or a child snapshot field | Direct captures fail compilation and live parent crossings fail semantic linking. |
| Use normal markup for reactive text and attributes | RSJS needs to emit client bindings for values that update. |
| Construct a non-component struct in the prelude | Direct template struct literals are component edges. |
| Keep `UnsafeRaw` explicit | Client-effect classification does not prove HTML safety. |

`rsjs::server_only(...)` remains a compatibility escape hatch for syntax the tolerant frontend cannot yet classify. It is not the normal authoring path. If a browser-reachable value crosses an opaque operation, compilation fails instead of silently freezing the server value.

## Next steps

- [Component props](/docs/rsjs/component-props)
  - Pass reactive, callback, and server-only props across island boundaries.
- [Client helpers](/docs/rsjs/client-helpers)
  - Compile pure Rust functions into the browser graph on demand.
- [Escaping and raw HTML](/docs/core/escaping)
  - Decide when `UnsafeRaw` is safe and how Proa escapes by default.
- [Hydration strategies](/docs/rsjs/hydration)
  - Control when an island claims its server HTML.


---

# Docs: Hydration strategies

URL: /docs/rsjs/hydration
Description: Defer RSJS island hydration until it matters.

---
title: Hydration strategies
description: Defer RSJS island hydration until it matters.
---

RSJS hydrates every island immediately unless a component asks for a later trigger. This page covers [choosing a strategy](#choosing-a-strategy), [final owner planning](#how-does-the-linker-plan-final-owners), the [interaction](#hydrating-on-interaction) and [media](#hydrating-on-a-media-query) triggers, and [runtime behavior](#how-does-each-trigger-behave-at-runtime).

## Choosing a strategy

The server always sends real HTML first. A **final owner** is the linked unit RSJS activates in the browser. The strategy controls only when that owner attaches client state, event handlers, input bindings, and query/mutation runtime work.

```rust filename="src/components/cart_button.rs"
#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for CartButton {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let count = signal(0_i64);
        html_sync! {
            <button type="button" on_click={|_| count.update(|n| n + 1)}>
                "Cart ("{count.get()}")"
            </button>
        }
        .render(cx)
    }
}
```

Add `strategy = "..."` to the complete component attribute when the final owner can
wait without breaking the first user action.

```rust filename="src/components/below_fold_filters.rs"
#[rsjs(component, client, strategy = "visible")]
impl<L: DataLoader> WebRenderSync<L> for BelowFoldFilters {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let expanded = signal(false);
        html_sync! {
            <aside>
                <button on_click={|_| expanded.set(!expanded.get())}>
                    "Toggle filters"
                </button>
                <div hidden={!expanded.get()}>"Filters"</div>
            </aside>
        }
        .render(cx)
    }
}
```

| Strategy | Use for | Hydrates when |
|----------|---------|---------------|
| `immediate` or no strategy | Above-the-fold controls, nav, search, cart buttons | DOM is ready. |
| `visible` | Below-the-fold filters, related products, large accordions | The final owner root enters the viewport. |
| `idle` | Nice-to-have enhancements that do not block use | The browser has idle time. |
| `interaction` | Widgets that wake on the first click, keydown, or focus | First pointer, keyboard, or focus event on the final owner root. |
| `interaction:click` | Controls where one event is the trigger | The named event fires on the final owner root. |
| `media:(min-width: 768px)` | Desktop-only or media-query-gated UI | The media query matches. |

RSJS accepts `eager` as an alias for `immediate`.

A strategy names a constraint, not an island boundary. The next section covers how the linker turns those constraints into final owners.

## How does the linker plan final owners?

A strategy on `#[rsjs(component, ...)]` contributes a constraint from that
component occurrence. It does not force every component to become a separate
browser island. Once the linker knows client reachability, it partitions the
rendered component graph into final owners:

| Relationship | Owner result |
|--------------|--------------|
| Live prop, live callback, client handle, or parent-reactive lifecycle edge | The connected occurrences must fuse into one owner. |
| Static nesting between disconnected client subgraphs | The subgraphs may remain separate owners and retain separate strategies. |
| `rsjs::island(...)` | Forces an independent-owner cut. A live edge cannot cross it. |
| Different explicit strategies on occurrences that must fuse | Compilation fails with the conflicting strategies and coupling path. |
| One constrained occurrence plus unconstrained fused participants | The final owner uses the constrained strategy. |
| No occurrence in an active owner supplies a constraint | The final owner defaults to eager/immediate hydration. |
| A final `ServerOnly` result with no reachable browser obligation or coupling to one | It forms no owner and ignores any requested strategy. |

A server-only section can therefore contain a visible chart and an
interaction-activated search box without becoming an owner itself. When nothing
connects the two children, each remains its own owner. When a live prop or
callback connects them, they share one owner and must agree on an explicit
activation strategy.

Interaction carries the most runtime nuance of the deferred triggers, so the next section covers it first.

## Hydrating on interaction

Use `interaction` when HTML handles the first paint and a user action activates
the owner.

```rust filename="src/components/search_box.rs"
#[rsjs(component, client, strategy = "interaction:focusin")]
impl<L: DataLoader> WebRenderSync<L> for SearchBox {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let query = signal(String::new());

        html_sync! {
            <label>
                "Search"
                <input type="search" bind_value={query} />
            </label>
        }
        .render(cx)
    }
}
```

Without an explicit event, `interaction` listens for `pointerdown`, `keydown`, and `focusin`.

Interaction owner modules start loading eagerly. The runtime arms capture
listeners only after the module and its dependencies evaluate successfully.
Once armed, the triggering native event initializes the owner during capture.
That event then reaches the real bubble handler exactly once, without synthetic
replay, `preventDefault()`, or propagation suppression.

> **Good to know**: an interaction that happens while the module still loads keeps its normal browser behavior. It cannot invoke an RSJS handler that is not ready yet.

Use `visible`, `idle`, or `media` when you want the framework to delay the owner
module import itself. The next section covers the layout-driven trigger of that set.

## Hydrating on a media query

Use `media:<query>` when the owner only matters in a matching layout.

```rust filename="src/components/desktop_inspector.rs"
#[rsjs(component, client, strategy = "media:(min-width: 1024px)")]
impl<L: DataLoader> WebRenderSync<L> for DesktopInspector {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let open = signal(false);
        html_sync! {
            <aside>
                <button on_click={|_| open.set(!open.get())}>"Inspector"</button>
                <div hidden={!open.get()}>"Desktop tools"</div>
            </aside>
        }
        .render(cx)
    }
}
```

If the query matches immediately, the owner hydrates immediately. If it does
not match, the runtime waits for a media-query change.

Every deferred trigger leaves a window where the user can type first, and the next section covers what happens to those edits.

## Keeping form state before hydration

Deferred hydration does not overwrite edits the user makes before an owner
activates. On the owner's first mount, RSJS compares form controls with their
server defaults. It adopts dirty browser state into the corresponding signal
before committing DOM updates. This covers text inputs and textareas, `checked`
state, select options, and editable text.

Untouched controls take the current signal value. Reconciliation for the whole
owner completes before its first DOM commits. One edited control therefore
updates other untouched controls bound to the same signal, without briefly
restoring the old server seed.

Each strategy reaches these guarantees through a different browser primitive, listed next.

## How does each trigger behave at runtime?

| Strategy | Browser primitive | Fallback |
|----------|-------------------|----------|
| `visible` | `IntersectionObserver` | Hydrates immediately when unavailable. |
| `idle` | `requestIdleCallback` | Uses `setTimeout(..., 0)` when unavailable. |
| `interaction` | Capture-phase DOM listener on the final owner root | Hydrates immediately if the root cannot receive listeners. |
| `media:(...)` | `window.matchMedia(...)` | Hydrates immediately when unavailable or invalid. |

For `visible`, `idle`, and `media`, framework bootstraps can delay importing the
owner module until the trigger fires:

```html filename="index.html"
<script type="module">
  import { hydrate_when_visible, defer_island_module } from "/rsjs-runtime.js";
  defer_island_module(
    "belowfoldfilters_...",
    "/rsjs/island/belowfoldfilters_....js?rsjs-triggered=1",
    hydrate_when_visible,
  );
</script>
```

This is the bootstrap the page runtime plan emits for you; `media` adds the
query as a fourth argument. `defer_island_module` registers the module with
the runtime so the import it performs later is authorized, and the
`?rsjs-triggered=1` flag tells the imported owner module not to wait a second
time. A bare dynamic `import()` inside the trigger callback skips that
registration.

These hydration primitives are runtime internals. Use the strategy attribute in
island code, and pick between the strategies with the table below.

## When to use each strategy?

| Rule | Why |
|------|-----|
| Keep critical controls immediate | Users would otherwise wait for a trigger before primary navigation or form controls work. |
| Use `visible` for below-the-fold UI | It avoids hydration work for content the user never reaches. |
| Use `idle` for optional polish | It yields to initial rendering and input. |
| Use `interaction` for wake-on-use widgets | After its eagerly loaded module is ready, the triggering event reaches the installed handler exactly once. |
| Use `media` for layout-specific islands | It avoids hydrating desktop-only or mobile-only controls on the wrong viewport. |

## Next steps

- [Browser APIs](/docs/rsjs/browser-apis)
  - The public RSJS browser API surface island code calls.
- [Signals](/docs/rsjs/signals)
  - Declare the client state a hydrated owner attaches to.
- [Bindings](/docs/rsjs/bindings)
  - Bind form controls to signals with `bind_value`.
- [Server-only components](/docs/rsjs/server-only)
  - Keep sections out of the browser so they form no owner.
- [Islands](/docs/guides/islands)
  - See how islands fit into a full Proa page.


---

# Docs: Queries and mutations

URL: /docs/rsjs/queries-mutations
Description: Seed browser queries from server-rendered data, refetch them, and run invalidating mutations.

---
title: Queries and mutations
description: Seed browser queries from server-rendered data, refetch them, and run invalidating mutations.
keywords: [query, mutation, fetch]
---

An RSJS query starts from the value the server already rendered, so the first paint and the browser cache agree. This page covers [seeding a query](#seeding-a-query-from-server-data), [awaiting the initial value](#awaiting-the-initial-value), [query keys](#choosing-query-keys), [reads](#reading-query-state), and [mutations](#running-mutations).

Query and mutation URLs use normal browser resolution by default: `/api/items`
targets the origin root even if the app is mounted under `/apps/demo`. For an
endpoint served by the mounted app, set `FetchRequest.apply_base_path: true`;
the runtime then requests `/apps/demo/api/items`. Keep that endpoint's server
route unprefixed. Absolute URLs and already-mounted URLs remain unchanged.
For a simple JSON GET or POST, pass `cx.url("/api/items")` directly as the
query or mutation request argument. Use a literal path in that direct call. It
uses the same mount behavior without a `FetchRequest` descriptor. Use
`FetchRequest` when request options are needed.
This works when the runtime is served with `FrameworkBuilder::with_rsjs_assets()`
and `with_base_path(...)`. Custom runtime handlers configure the source with
`rsjs::runtime_assets::with_base_path`.
See [runtime wiring](/docs/rsjs/runtime#serving-linked-assets-with-axum).

## Seeding a query from server data

Use a **query** when the server renders data first and the browser later
observes, refetches, or invalidates it. Use a **mutation** when a browser action
writes to the server and updates related query entries.

`query_with_initial(...)` does not make rendering asynchronous by itself. If
the initial `serde::Serialize` value is already available, keep the component on
the synchronous fast path:

```rust filename="src/components/stock_tile.rs"
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use rsjs::{event_handler, rsjs, QueryKey};

#[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
pub struct StockPrice {
    pub value: f64,
    pub currency: String,
}

pub struct StockTile {
    pub initial: StockPrice,
}

#[rsjs(component, client)]
impl<L: DataLoader> WebRenderSync<L> for StockTile {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let price: rsjs::Query<StockPrice> = rsjs::query_with_initial(
            QueryKey::new(("stock", "AAPL")),
            self.initial,
            rsjs::FetchRequest {
                url: "/api/stocks/AAPL",
                apply_base_path: true,
                response: Some(rsjs::ResponseKind::Json),
                headers: &[("Accept", "application/json")],
                timeout_ms: Some(1_500),
                ..Default::default()
            },
            rsjs::QueryOptions {
                refetch_on_focus: true,
                stale_time_ms: 2_000,
                ..Default::default()
            },
        );
        let refresh = event_handler(|_: rsjs::MouseEvent<rsjs::elem::Button>| {
            price.refetch();
        });

        html_sync! {
            <article>
                <span>{price.data().value}</span>
                <span>{price.data().currency}</span>
                <button type="button" on_click={refresh()}>"Refresh"</button>
            </article>
        }
        .render(cx)
    }
}
```

The initial value is ordinary server Rust. RSJS serializes it into the
response's page-level query seed table, and the adjacent island metadata names
the effective key. The server-rendered output and browser cache therefore begin
with the same value.

When producing that value needs an `.await`, the component moves to the async path covered next.

## Awaiting the initial value

Use `WebRender` and `html!` only when obtaining the initial value actually needs
`.await`, such as a `DataLoader`, database, or service call. Author the real
render trait and return `RenderOutcome::pending(async move { ... })`. RSJS does
not support `async fn render` shorthand.

```rust filename="src/components/async_stock_tile.rs"
use std::future::Future;

use proa::{
    DataLoader, LoadKey, RenderOutcome, WebContext, WebRender, WriteError,
};
use proa::html;
use rsjs::{rsjs, QueryKey};
use crate::components::stock_tile::StockPrice;

pub struct AsyncStockTile;

#[rsjs(component, client)]
impl<L: DataLoader> WebRender<L> for AsyncStockTile {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let initial: StockPrice = cx.load_json(LoadKey::named("stock", "AAPL")).await?;
            let price: rsjs::Query<StockPrice> = rsjs::query_with_initial(
                QueryKey::new(("stock", "AAPL")),
                initial,
                rsjs::FetchRequest {
                    url: "/api/stocks/AAPL",
                    apply_base_path: true,
                    response: Some(rsjs::ResponseKind::Json),
                    ..Default::default()
                },
                rsjs::QueryOptions::default(),
            );

            html! {
                <span>{price.data().value}</span>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

The important boundary is that the load happens through `cx` before its result
enters `query_with_initial(...)`.

Do not create a query only to fetch SSR data. If the browser will not observe,
refetch, invalidate, or bind the value, load it as ordinary server data and
render it without a query runtime.

Every query, sync or async, reaches its cache entry through a key, which the next section covers.

## Choosing query keys

Use `QueryKey::new((...))` with tuple parts. Tuples support mixed Rust types and
serialize to the same structural array shape used by the browser cache.

```rust filename="src/components/product_reviews.rs"
QueryKey::new(("stock", "AAPL"))
QueryKey::new(("product", product_id, "reviews"))
QueryKey::new(("search", query.get()))
```

The key identifies the cache entry. The `FetchRequest` describes the browser
request and stays static. Keys do not substitute URL parameters or send their
parts to the endpoint. Keep the server seed, cache key, and literal request
descriptor aligned with the same resource; changing only the key does not change
the URL or request body.

When a linked parent supplies a live value used in a child query key, RSJS keeps
the query handle stable. It rebinds the observer to the entry for the new
structural key, and it does not rename or mutate the old cache entry. Existing
subscriptions move to the new entry.

> **Good to know**: a request already in flight stays owned by the old entry.

The next section covers what belongs in the descriptor next to the key.

## Describing fetch requests

`FetchRequest` is the client request descriptor. Keep dynamic state in the key
or mutation payload; keep the endpoint shape in the descriptor.

```rust filename="src/components/stock_tile.rs"
rsjs::FetchRequest {
    url: "/api/stocks/AAPL",
    apply_base_path: true,
    method: Some(rsjs::HttpMethod::Post),
    credentials: Some(rsjs::FetchCredentials::SameOrigin),
    response: Some(rsjs::ResponseKind::Json),
    headers: &[("Accept", "application/json"), ("X-RSJS", "1")],
    body: Some(rsjs::RequestBody::Json(r#"{"symbol":"AAPL"}"#)),
    timeout_ms: Some(1_500),
}
```

Available response decoders are `Json`, `Text`, `Bytes`, and `Empty`.
`QueryOptions` also supports retry, polling, staleness, focus refetching,
download progress, and streaming text for text responses.

Once a query exists, components read it reactively, which the next section shows.

## Reading query state

Query handles are reactive. Use them in text, attributes, conditionals, and
handlers. Use the template macro that matches the component's render trait.

```rust filename="src/components/stock_tile.rs"
let invalidate = event_handler(|_: rsjs::MouseEvent<rsjs::elem::Button>| {
    price.invalidate();
});

html_sync! {
    <div>
        <span>{price.status()}</span>
        <span>{price.data().value}</span>
        <span>{price.download_percent()}</span>
        {if price.is_refetching() {
            html_sync! { <span>"Refreshing"</span> }
        }}
        <button type="button" on_click={invalidate()}>"Invalidate"</button>
    </div>
}
```

Common reads:

| Read | Meaning |
|------|---------|
| `query.data().field` | Project typed JSON data. |
| `query.status()` | Current status string. |
| `query.is_loading()` / `query.is_success()` / `query.is_error()` | Status flags. |
| `query.is_refetching()` / `query.is_stale()` | Cache state flags. |
| `query.error()` | Error value projection. |
| `query.download_loaded()` / `query.download_total()` / `query.download_percent()` | Progress values when enabled. |

Several owners can read one key at the same time, so the next section covers who owns the entry.

## How long do cache entries and observers live?

Declarations with the same structural key share one page-scoped cache entry and
one in-flight request. Options such as `stale_time_ms` remain observer-local.
Active polling observers share the smallest positive interval. Focus refetching
runs when any active observer that requested it considers the entry stale.

Removing an owner disposes its observer and subscriptions, but does not evict
the cache entry. A later owner in the same response epoch and navigation
generation can reuse it. Full page-generation teardown cancels scheduled work
and in-flight query requests, invalidates old handles, and clears the cache.

Writes reach those entries through mutations, which the next section covers.

## Running mutations

Mutations are async-only. Declare them inside the canonical `WebRender` pending
future and render with `html!`. The mutation key identifies the write operation;
the invalidation list names the query keys the runtime refreshes after a
successful run.

```rust filename="src/components/cart_editor.rs"
use std::future::Future;
use proa::{DataLoader, RenderOutcome, WebContext, WebRender, WriteError};
use proa::html;
use rsjs::{rsjs, QueryKey};

pub struct CartEditor;

#[rsjs(component, client)]
impl<L: DataLoader> WebRender<L> for CartEditor {
    fn render(
        self,
        cx: &mut WebContext<L>,
    ) -> RenderOutcome<impl Future<Output = Result<(), WriteError>>> {
        RenderOutcome::pending(async move {
            let draft = rsjs::signal(String::new());
            let save = rsjs::mutation::<String, ()>(
                QueryKey::new(("cart", "update")),
                rsjs::FetchRequest {
                    url: "/api/cart",
                    apply_base_path: true,
                    method: Some(rsjs::HttpMethod::Patch),
                    credentials: Some(rsjs::FetchCredentials::SameOrigin),
                    response: Some(rsjs::ResponseKind::Empty),
                    timeout_ms: Some(2_500),
                    ..Default::default()
                },
                &[QueryKey::new(("cart", "summary"))],
            );
            let update_draft = rsjs::event_handler(
                |event: rsjs::InputEvent<rsjs::elem::Input>| {
                    draft.set(event.current_value());
                },
            );
            let submit = rsjs::event_handler(
                |_: rsjs::MouseEvent<rsjs::elem::Button>| {
                    save.run(draft.get());
                },
            );

            html! {
                <div>
                    <input value={draft.get()} on_input={update_draft()} />
                    <button
                        type="button"
                        disabled={save.is_pending()}
                        on_click={submit()}
                    >
                        {if save.is_pending() { "Saving..." } else { "Save" }}
                    </button>
                </div>
            }
            .render(cx)
            .resolve()
            .await
        })
    }
}
```

`run(args)` sends one JSON value when the request descriptor has no fixed body.
A Rust `String` becomes a JSON string; text containing JSON is not parsed into
an object. Match the endpoint's input type to the payload type. A fixed
`FetchRequest.body` takes precedence over the run argument.

Use `mutation_with_options(...)` when you need retry policy or a different
invalidation strategy.

```rust filename="src/components/cart_editor.rs"
let save = rsjs::mutation_with_options::<String, ()>(
    QueryKey::new(("cart", "update")),
    rsjs::FetchRequest {
        url: "/api/cart",
        apply_base_path: true,
        method: Some(rsjs::HttpMethod::Patch),
        response: Some(rsjs::ResponseKind::Empty),
        ..Default::default()
    },
    &[QueryKey::new(("cart", "summary"))],
    rsjs::MutationOptions {
        retry_count: 1,
        on_success_invalidate_strategy: rsjs::InvalidationStrategy::Refetch,
    },
);
```

The table below condenses these choices into one pass.

## When to use each form?

| Rule | Why |
|------|-----|
| Use `WebRenderSync` when the query initial already exists | Declaring a query does not require an await. |
| Use `WebRender` only for an awaited query initial or a mutation | The render trait reflects actual async work and the current mutation contract. |
| Seed query data on the server | The first paint then matches the hydrated cache. |
| Use tuple query keys | They handle mixed key parts and preserve structural identity. |
| Keep `FetchRequest` static | Runtime request shape belongs to the component definition. |
| Invalidate related query keys after writes | Otherwise the browser cache can show stale data. |

## Next steps

- [Handlers](/docs/rsjs/handlers)
  - Type the events that call `refetch()`, `invalidate()`, and `run()`.
- [Signals](/docs/rsjs/signals)
  - Hold local client state such as a mutation draft.
- [Hydration strategies](/docs/rsjs/hydration)
  - Choose when an owner attaches its query and mutation runtime work.
- [Data loading](/docs/framework/data-loading)
  - Load the initial value on the server through `cx`.
- [Component props](/docs/rsjs/component-props)
  - Pass live values that rebind a child query key.


---

# Docs: Runtime wiring

URL: /docs/rsjs/runtime
Description: Plan, emit, and activate the exact RSJS assets a response rendered.

---
title: Runtime wiring
description: Plan, emit, and activate the exact RSJS assets a response rendered.
---

Proa ships RSJS runtime code only for the owners a response actually rendered. This page covers the [shared runtime layers](#loading-the-runtime-layers), [asset serving](#serving-linked-assets-with-axum), [automatic finalization](#finalizing-a-normal-response), the [response-local plan](#planning-one-response), [hydration semantics](#hydrating-and-disposing-owners), and [custom adapters](#writing-a-custom-adapter).

## Loading the runtime layers

RSJS has two shared runtime layers. The paths below are the origin-root defaults:

| Asset | Loaded when | Purpose |
|-------|-------------|---------|
| `/rsjs-runtime.js` | The response contains at least one hydrated owner | Hydrates signals, handlers, bindings, refs, conditionals, lists, and typed SharedState. |
| `/rsjs-runtime-query.js` | Reachable browser work uses a query or mutation | Adds the page-scoped query cache, observer policies, refetching, mutation state, invalidation, and progress hooks. |

Proa emits the query runtime eagerly only when an immediate or interaction owner
needs it. A visible, idle, or media owner that is the page's only query consumer
keeps that work deferred until its module activates.

Generated island modules, reachable client-helper bundles, and linked component
fragments are separate ES modules. The compiler embeds their sources in the
binary. The response planner selects only the graph needed by owners that
actually rendered.

The finalizer that picks those assets runs on every response without any work
from your page code.

## Serving linked assets with Axum

Install the asset routes when building your application:

```rust filename="src/app.rs"
use proa::axum::FrameworkBuilder;

let app = FrameworkBuilder::new()
    .with_rsjs_assets()
    .with_dynamic_routes_and_metadata(routes, metadata)
    .build();
```

The finalizer emits tags; `with_rsjs_assets()` serves the linked JavaScript those
tags request. It works at the origin root and follows
[`with_base_path(...)`](/docs/framework/configuration#frameworkbuilder-base-paths-and-rsjs-assets)
when configured. Use it in place of custom handlers at the same asset paths.

See [Static assets](/docs/framework/static-assets#serving-linked-island-assets)
for the installed routes and custom-router alternative, and
[URL prefix deployments](/docs/framework/deployment#serving-behind-a-url-path-prefix)
for the proxy configuration example.

The linked core and query runtimes export `app_url(path)` for handwritten
browser code. Query/mutation request URLs use normal browser resolution
unless the request descriptor sets `apply_base_path: true`. In Rust, pass
`cx.url("/api/items")` or set `FetchRequest.apply_base_path: true` to opt in.
Opted-in requests follow the configured mount. Already-mounted browser URLs
and external URLs stay unchanged.
Custom runtime servers can call `rsjs::runtime_assets::with_base_path(source,
&base_path)` before serving either runtime; use the same setting for both.

## Finalizing a normal response

Rendering records `RsjsRenderArtifacts` in the response's `WebContext`.
`proa::axum` snapshots those artifacts after rendering and finalizes the
page automatically across:

- synchronous and asynchronous responses;
- cached-fragment replay;
- in-order streaming; and
- out-of-order streaming.

Normal page and component code only renders the component:

```rust filename="src/pages/dashboard.rs"
html_sync! {
    <main>
        {Counter { initial: 0 }}
    </main>
}
```

Never call `cx.rsjs_islands_used()`, inspect the manifest, or append runtime
tags yourself. The finalizer is the single integration point that sees which
speculative branches committed, which cached artifacts replayed, and which
streamed boundaries became public.

The finalizer turns those artifacts into one plan, described next.

## Planning one response

The finalizer passes the committed rendered-island ids to
`Manifest::page_runtime_plan_with_urls(...)` with the request's public URL
resolver. The resulting `PageRuntimePlan` is one
deterministic description of:

- rendered owner ids and reachable runtime features;
- immediate/interaction modules and visible/idle/media modules;
- reachable `#[rsjs::client]` helper bundles;
- linked component-fragment modules;
- exact eager module preloads;
- base and query runtime URLs; and
- stable tag order.

CSP nonces remain request data; you supply them when the plan writes HTML. You
can select application-owned asset URLs with `page_runtime_plan_with_urls(...)`
and an `RsjsAssetUrlResolver`.

A server-only result records no hydrated owner and therefore emits no RSJS
runtime. A server-only parent may still render an independent hydrated child.
That child records its own artifact, and Proa plans only its reachable graph.

The plan decides which tags reach the browser, shown next.

## What does a hydrated page emit?

The compiler owns the exact output, which depends on reachability and hydration
strategy. An immediate signal owner can produce a shape like this:

```html filename="counter-response.html"
<rsjs-island data-rsjs-island-root="counter_...">
  <button data-rsjs-handler="0">+</button>
  <span data-rsjs-bind="1">0</span>
</rsjs-island>

<script type="application/json" data-rsjs-island="counter_...">
  {"signals":["0"]}
</script>

<script type="module" src="/rsjs-runtime.js"></script>
<link rel="modulepreload" href="/rsjs/island/counter_....js">
<script type="module" src="/rsjs/island/counter_....js"></script>
```

An owner using `query_with_initial(...)` also has adjacent effective-key
metadata. Its server value lives in an inert page-level seed table that Proa
emits before activation:

```html filename="stockticker-response.html"
<script type="application/json" data-rsjs-island-queries="stockticker_...">
  {"0":{"key":["stock","AAPL"]}}
</script>
<script type="application/json" id="rsjs-query-seed-table">
  {"queries":[...]}
</script>
```

A reachable `SharedStateProvider` similarly contributes an inert table:

```html filename="workbench-response.html"
<script type="application/json" id="rsjs-shared-state-seed-table">
  {"abi_version":1,"stores":[...]}
</script>
```

Proa emits the query and SharedState tables only when the committed artifact set
needs them. They appear before the runtime plan can activate a dependent owner.
Proa applies a configured CSP nonce to both inert metadata scripts and
executable module scripts.

Once those tags reach the browser, the runtime activates each owner.

## Hydrating and disposing owners

For each owner, the runtime:

1. Arms the selected immediate, visible, idle, interaction, or media strategy.
2. Locates the exact `<rsjs-island data-rsjs-island-root="...">` occurrence.
3. Validates and installs page-level SharedState/query metadata needed by that owner.
4. Reads its adjacent signal, query, mutation, and provider-binding metadata.
5. Installs generated handlers, bindings, effects, refs, and structural resources as one owner lifetime.

Interaction hydration listens in the capture phase. Successful initialization
installs the generated bubble handler before that same native event reaches the
owner again. The runtime therefore delivers the triggering click, key, or focus
event exactly once, without `preventDefault`, propagation suppression, or
synthetic event replay.

Users may edit a deferred form before it activates. On an owner's first mount,
dirty `value`, `checked`, and `selected` DOM properties win over the SSR seed.
The runtime adopts them into the bound cell, and untouched controls receive the
cell's current value. It skips no-op writes, so text cursors, IME composition,
textarea scroll, and select focus survive.

Activation is atomic from the owner's perspective. If a module fails to load,
SharedState schemas conflict, or an initializer throws, the SSR owner remains
inert. The runtime unwinds partial resources and reports a scoped
`RsjsActivationError`. It never leaves a partially bound owner active.

Removing a reactive range or detached root disposes nested owners, event
listeners, effects, query observers, SharedState subscriptions, node refs,
timers, and pending module gates. Router subtree disposal removes only the
affected owners. Full page-generation disposal also clears page query and
SharedState registries and invalidates old handles.

Streamed and cached responses activate owners the same way, under the ordering
rules below.

## Streaming and replaying cached artifacts

Streaming finalizers retain one `PageRuntimeEmissionState` for the entire
response. Each shell or boundary plan writes only the runtime URLs, preloads,
modules, and deferred instructions that no earlier plan emitted.

Cached fragments carry their complete `RsjsRenderArtifacts`, not just HTML.
Speculative, failed, or cancelled branches do not publish their artifacts. For
in-order streaming, an artifact-aware flush publishes a delta before the first
chunk containing dependent owner markup. For out-of-order streaming, Proa emits
a successful boundary's query/SharedState seed deltas and runtime-plan delta
immediately before its swap frame. That ordering ensures the metadata and
modules exist before the frame dispatches its boundary-ready event.

An adapter outside `proa::axum` reproduces that ordering itself.

## Writing a custom adapter

In a custom adapter, preserve the same sequence:

```rust filename="src/adapter/finalize.rs"
let artifacts = cx.rsjs_artifacts_snapshot();
let plan = rsjs::manifest().page_runtime_plan(
    artifacts.rendered_islands(),
)?;

let query_seeds = artifacts.query_seed_table_json();
let shared_state_seeds = artifacts.shared_state_seed_table_json();
let mut emission = rsjs::PageRuntimeEmissionState::new();

// Emit present inert seed tables here, before executable runtime tags.
plan.write_html_delta(&mut out, &mut emission, nonce)?;
```

Use one `PageRuntimeEmissionState` for every delta in one streaming response.
For hashed, prefixed, or CDN-hosted URLs, build the plan with
`page_runtime_plan_with_urls(...)`. The URL resolver changes response tags. It
does not rewrite static import specifiers inside generated ESM, so the asset
server must also rewrite those imports or preserve canonical aliases.

`Manifest::runtime_with_prefix(...)` remains a coarse compatibility and
diagnostic helper for the complete manifest. It is not a substitute for the
response-local planner. It cannot select island modules, helper dependencies,
component fragments, hydration gates, or preloads.

A correct adapter still needs a correctly linked binary, which the build
contract below guarantees.

## Building a linked binary

Cross-component composition and automatic client-helper discovery require a
deterministic descriptor/link/final-compilation pipeline:

| Command | Contract |
|---------|----------|
| `cargo check` / rust-analyzer | Local Rust typing and provisional descriptor expansion; Proa can defer link-only diagnostics. |
| `cargo proa check` | Descriptor compilation, semantic link, and final Cargo check with cross-component diagnostics. |
| `cargo proa build` | Descriptor compilation, deterministic link, and final deployable compilation. |
| `cargo proa run` | Build one exact linked binary, validate it, then run its immutable snapshot. |
| `cargo proa test` | Build one exact linked test target, then run that harness. |
| `cargo proa dev` | Run the linked development workflow with reusable descriptor/link/final caches. |

Plain local checking is useful, but its provisional output is not a deployable
RSJS artifact. A code-generating build that contains analyzed RSJS components
must have the exact final link plan. Building without it fails closed with an
actionable `cargo proa build` diagnostic rather than emitting a descriptor-pass
binary or silently consuming stale metadata.

When a linked page still misbehaves, work through the checklist below.

## Debugging a page

| Symptom | Check |
|---------|-------|
| Button renders but does nothing | The response recorded the owner and emitted `/rsjs-runtime.js` plus `/rsjs/island/<asset-id>.js`. |
| Signal starts with the wrong value | The adjacent `data-rsjs-island` seed matches the server-rendered text or attribute. |
| Query starts without server data | The page emitted `rsjs-query-seed-table` before activation, and the adjacent effective key matches it. |
| SharedState acquisition fails | The page emitted `rsjs-shared-state-seed-table`, and the provider `type_key` and schema ABI match. |
| A deferred owner never hydrates | Its visible, idle, interaction, or media condition can fire and its managed module load did not fail. |
| Only one repeated instance hydrates | Every wrapper occurrence has the correct `data-rsjs-island-root`; duplicate asset ids across occurrences are normal. |
| A custom adapter works buffered but not streamed | It reuses one `PageRuntimeEmissionState` and publishes seed/plan deltas before boundary markup becomes active. |

## Next steps

- [Hydration strategies](/docs/rsjs/hydration)
  - Choose when each owner activates in the browser.
- [Signals](/docs/rsjs/signals)
  - Declare the client state an activated owner attaches to.
- [Queries and mutations](/docs/rsjs/queries-mutations)
  - Seed the query cache the query runtime layer loads for.
- [Shared state](/docs/rsjs/shared-state)
  - Feed the page-level SharedState seed table from a lexical provider.
- [Streaming SSR](/docs/core/streaming-ssr)
  - Flush the shell first and stream slow sections as they resolve.


---

# Docs: Tailwind

URL: /docs/guides/tailwind-intellisense
Description: Style a Proa app, with autocomplete in Rust files.

---
title: Tailwind
description: Style a Proa app, with autocomplete in Rust files.
---

Proa templates use Tailwind classes inside `class="..."` attributes and `tw_join!()` macros in Rust files. With a few VS Code settings, you get full autocomplete, color swatches, and class linting, the same experience you'd have in a `.tsx` file.

## Prerequisites

- [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension installed in VS Code
- A Tailwind v4 CSS entrypoint, such as `styles/input.css` in generated sites.

## Settings

Add the following to your workspace `.vscode/settings.json`:

```jsonc
{
  // 1. Tell the extension to activate in Rust files.
  //    Maps the "rust" language ID to "html" so it recognises class attributes.
  "tailwindCSS.includeLanguages": {
    "rust": "html"
  },

  // 2. Point to your Tailwind v4 CSS entrypoint.
  "tailwindCSS.experimental.configFile": {
    "styles/input.css": "**/*.rs"
  },

  // 3. Custom regex patterns for Proa idioms.
  "tailwindCSS.experimental.classRegex": [
    // class="..." inside html! macro
    "class=\"([^\"]*?)\"",

    // tw_join!("...", "...") — two-level match:
    //   outer regex captures the contents of tw_join!(...)
    //   inner regex extracts each quoted string
    ["tw_join!\\(([^)]*)\\)", "\"([^\"]*)\""]
  ],

  // 4. Auto-trigger suggestions inside string literals
  //    so you don't have to press Ctrl+Space each time.
  "editor.quickSuggestions": {
    "strings": true
  }
}
```

## What each setting does

### `tailwindCSS.includeLanguages`

The extension only activates for a built-in set of languages (HTML, CSS, JSX, etc.). This setting adds Rust to that list by mapping its VS Code language ID to `html`, which tells the extension to look for HTML-style `class` attributes.

### `tailwindCSS.experimental.configFile`

For Tailwind v4, point the extension at the CSS entrypoint that imports Tailwind and declares the project's sources and theme. The glob `**/*.rs` applies that stylesheet to Rust files throughout the workspace.

### `tailwindCSS.experimental.classRegex`

By default the extension only triggers inside `class` or `className` attributes in markup. This setting adds two patterns:

**Pattern 1**, `class="([^\"]*?)"` matches class attributes in `html!`:

```rust
html! {
    <div class="flex gap-2 items-center">  // autocomplete here
```

**Pattern 2**, the `[container, classlist]` array matches `tw_join!()`:

```rust
pub const BUTTON_BASE: &str = tw_join!(
    "inline-flex",    // autocomplete here
    "items-center",   // and here
    "rounded-md",     // and here
);
```

The outer regex captures everything inside the parentheses; the inner regex then extracts each individual `"..."` string.

### `editor.quickSuggestions`

By default VS Code suppresses auto-suggestions inside string literals. Since every Tailwind class in Proa lives inside a `"..."`, this setting enables inline suggestions so autocomplete appears as you type.

## Verify it works

1. Open any `.rs` file that uses `html!` or `html_sync!` (for example, `src/pages/home.rs`)
2. Place your cursor inside a `class="..."` attribute
3. Start typing a Tailwind class, you should see autocomplete suggestions with color swatches
4. Open a local component recipe file if your app has one
5. Place your cursor inside a `tw_join!("...")` string, autocomplete should work there too
6. Try typing a custom theme color like `bg-primary`, it should appear with your theme's color preview

> **Tip:** If suggestions don't appear, run **Tailwind CSS: Restart IntelliSense Server** from the VS Code command palette (`Cmd+Shift+P`).

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| No suggestions in `.rs` files | Check that `tailwindCSS.includeLanguages` has `"rust": "html"` |
| Suggestions appear but no custom colors | Check that `tailwindCSS.experimental.configFile` points to the correct CSS entrypoint |
| Suggestions in `class=""` but not `tw_join!()` | Check the `classRegex` array has both patterns |
| Have to press `Ctrl+Space` every time | Set `editor.quickSuggestions.strings` to `true` |
| Extension not activating at all | Ensure Tailwind CSS IntelliSense is installed and enabled for the workspace |


---

# Docs: Class composition

URL: /docs/core/class-composition
Description: Compose Tailwind classes with static strings, ClassList, and optional caller classes.

---
title: Class composition
description: Compose Tailwind classes with static strings, ClassList, and optional caller classes.
keywords: [ClassList, tw_join, tw_merge, recipe]
---

Proa composes hot-path classes from static string fragments instead of building a `String` at render time. This page covers [static class constants](#declaring-static-class-constants), [`ClassList`](#composing-with-classlist), [capacity](#choosing-a-capacity), and [the allocation to avoid](#avoiding-hot-path-allocation).

## Declaring static class constants

Keep repeated class sets in constants:

```rust filename="src/components/card/recipe.rs"
pub const CARD_BASE: &str = "rounded-lg border bg-card text-card-foreground shadow-sm";
pub const CARD_COMPACT: &str = "p-3 text-sm";
pub const CARD_SPACIOUS: &str = "p-6";
```

Tailwind-heavy component recipes often use a local `tw_join!` helper. It joins static class fragments at compile time into one `&'static str`.

```rust filename="src/components/button/recipe.rs"
use crate::tw_join;

pub const BUTTON_BASE: &str = tw_join!(
    "inline-flex",
    "items-center",
    "justify-center",
    "rounded-md",
    "text-sm",
    "font-medium",
);
```

Constants cover the fragments you know at compile time. To pick between them per render, combine them with `ClassList`.

## Composing with ClassList

A **`ClassList<N>`** stores references to static class strings and writes them with spaces between segments. It does not allocate a `String`.

```rust filename="src/components/card/recipe.rs"
use proa::ClassList;

pub enum CardDensity {
    Compact,
    Spacious,
}

impl CardDensity {
    pub const fn classes(self) -> &'static str {
        match self {
            Self::Compact => CARD_COMPACT,
            Self::Spacious => CARD_SPACIOUS,
        }
    }
}

pub fn card_classes(density: CardDensity, class: Option<&'static str>) -> ClassList<3> {
    ClassList::new()
        .add(CARD_BASE)
        .add(density.classes())
        .add_opt(class)
}
```

Use the `ClassList` directly in a `class={...}` attribute:

```rust filename="src/components/card/card.rs"
html_sync! {
    <section class={card_classes(self.density, self.class)}>
        {self.children}
    </section>
}
```

One number in that signature carries a hard constraint: the `3`.

## Choosing a capacity

The `N` in `ClassList<N>` is the maximum number of class segments:

```rust filename="src/components/button/button.rs"
ClassList::<4>::new()
    .add("base")
    .add("variant")
    .add_if(disabled, "opacity-50")
    .add_opt(class)
```

If you add more than `N` segments, `ClassList` **panics**. Pick the exact capacity for the call site and count the optional segments too.

Sizing the list correctly matters only if you use it. The alternative costs an allocation on every render.

## Avoiding hot-path allocation

Avoid this in render code:

```rust filename="src/components/card/card.rs"
let classes = format!("{} {}", CARD_BASE, self.density.classes());
```

Prefer `ClassList`:

```rust filename="src/components/card/card.rs"
let classes = ClassList::<3>::new()
    .add(CARD_BASE)
    .add(self.density.classes())
    .add_opt(self.class);
```

If a class string comes from user input or application data, validate or normalize it before rendering. Most component APIs accept `Option<&'static str>` for extension classes, which keeps common render paths static.

## Next steps

- [HTML rendering](/docs/core/html-rendering)
  - Put the composed classes into a `class={...}` attribute.
- [Writing performant pages](/docs/guides/performance)
  - Find the other allocations a render path can hide.
- [Escaping and raw HTML](/docs/core/escaping)
  - See how Proa escapes attribute values it writes.
- [Tailwind](/docs/guides/tailwind-intellisense)
  - Get editor completion for class strings inside Rust constants.


---

# Docs: Fonts

URL: /docs/framework/fonts
Description: Self-host web fonts with metric-matched fallbacks and zero runtime requests, declared in code and vendored by the build.

---
title: Fonts
description: Self-host web fonts with metric-matched fallbacks and zero runtime requests, declared in code and vendored by the build.
keywords: [google_font!, local_font!, font-display]
---

`proa_fonts` brings the valuable part of Next.js' `next/font` to Proa's SSR pipeline: fonts are **self-hosted**, **content-hashed**, **preloaded**, and given **metric-compatible fallbacks**, all at build time, with **no runtime request to a third party** and **no JavaScript**.

Fonts are declared in code, next to the code that uses them. `google_font!` fetches and vendors a family from Google Fonts; `local_font!` vendors font files you already have. Both are driven by an ordinary `build.rs`, and both produce the same self-hosted, metric-matched result, pinned in `proa-fonts.lock` so rebuilds are offline and reproducible.

## Declare fonts in code

Write the font in Rust and let the build vendor it:

```rust
use proa_fonts::Font;
use proa_fonts_macros::{google_font, local_font};

static SANS: Font = google_font!("Geist", subsets = [latin], weights = [400, 700], variable = "--font-sans");
static MONO: Font = google_font!("Geist Mono", variable_font = true, generic = mono, variable = "--font-mono");
static BRAND: Font = local_font!("Brand", files = ["fonts/Brand.woff2"], variable = "--font-brand");
```

The macro performs no I/O; it expands to a reference to a `FONT_<id>` const that the build step generates, and the `static` binding gives it whatever name you like. The macro and the build collector parse the call through the same grammar, so the reference and the generated definition always agree. Identical declarations anywhere in the crate share one const and one set of vendored files; distinct declarations get distinct consts.

## Wire the build

Two pieces of boilerplate. The `origin` site template (`cargo proa new site --template origin`) ships both; the other templates need them added by hand. A `build.rs` that runs the collector:

```rust
// build.rs
fn main() {
    println!("cargo:rerun-if-changed=src");
    println!("cargo:rerun-if-changed=proa-fonts.lock");
    let fonts = proa_fonts_build::collect::CollectOptions::from_build_env()
        .expect("cargo build env");
    if let Err(error) = proa_fonts_build::collect::run(&fonts) {
        panic!("proa fonts: {error}");
    }
}
```

And one line near your crate root wiring the generated file in:

```rust
// somewhere in your crate (once):
mod __proa_fonts_generated {
    include!(concat!(env!("OUT_DIR"), "/proa_fonts.rs"));
}
```

`CollectOptions::from_build_env()` reads the crate root and `OUT_DIR` from the Cargo build environment, vendors into `public/fonts` (served at `/fonts`), and keeps the lock beside `Cargo.toml`. Build the struct by hand to customize those paths; if you do, pass the same values to `cargo proa font sync` via `--fonts-dir` / `--url-prefix`.

Now `cargo build` does everything: the build script scans your source for `google_font!` / `local_font!` calls, fetches Google sources (behind the default-on `fetch` feature of `proa_fonts_build`) or reads local files, and vendors the faces. Google serves already-subset WOFF2 per `unicode-range`, so a subset selection chooses which files to vend, not a glyph-subsetting step.

A build writes three things:

- content-hashed files into `public/fonts/` (served at `/fonts/...`),
- `proa-fonts.lock` beside `Cargo.toml` (the reproducible, checksummed result), and
- a generated module in `OUT_DIR` defining one `pub const FONT_<id>: Font` per declaration.

Commit `public/fonts/` and `proa-fonts.lock`. The `OUT_DIR` module is regenerated by every build and is never committed. The `origin` template serves `public/fonts/` at `/fonts` through a `ServeDir` route; other templates serve `public/` at `/static`, so mount `/fonts` yourself. The filenames are content-hashed, so add a long `Cache-Control: max-age` with `immutable` and browsers can cache them forever.

## Offline and reproducible

Vendoring is gated by `proa-fonts.lock`. A declaration whose lock entry and vendored files are intact (SHA-256 and byte size verified) regenerates from the bytes on disk, touching neither the network nor the vendored files. Only new or changed declarations fetch or read; they vendor their faces and update the lock. If a vendored file goes missing or fails its checksum, an online build re-vendors it and updates the lock, so the repair is visible in git; `cargo proa font sync --offline` fails instead. Declarations you delete get their lock entries dropped and their vendored files deleted (unless another font still references a file). If a source file under `src/` fails to parse mid-edit, the collector preserves the existing lock entries and vendored files instead of treating their declarations as removed.

Once the collector has run, the lock always exists: with zero declarations it is a comment-only stub, and removing your last declaration leaves the stub behind, so `rerun-if-changed=proa-fonts.lock` is sound from the first build. Lock and module writes are skip-if-unchanged, so that directive cannot loop the build.

With the lock and `public/fonts/` committed, a fresh checkout builds fully offline and reproducibly: the lock records each vended file's SHA-256, byte size, and URL, plus the measured metrics and the synthesized fallback overrides.

Offline means two different things in a build and in a sync. During a `cargo build` with `CARGO_NET_OFFLINE=true`, local fonts still vendor (they need no network); only a Google declaration that would need a fetch fails, with an actionable error. `cargo proa font sync --offline` is strictly verify-only for all sources: it performs no writes at all and fails with `proa-fonts.lock is stale` when any declaration, Google or local, is not satisfied by the lock and vendored files, or when the lock content would change (including entries that would be removed), or when any source file under `src/` cannot be parsed (unverifiable declarations fail the gate rather than passing vacuously). Plain `cargo proa font sync` also runs verify-only under `CARGO_NET_OFFLINE=true`. Gate CI with:

```bash
cargo proa font sync --offline   # strict verify, no writes; fails on any drift
```

## Declaration options

Both macros take a family name literal followed by `key = value` options. List entries can be bare words (`latin`) or strings (`"latin-ext"`).

| Key | Meaning |
|-----|---------|
| `subsets = [latin, "latin-ext"]` | Google subsets to vend. Defaults to `[latin]`. The first subset is the primary one for default preloads. |
| `weights = [400, 700]` | Fixed weights to vend. Defaults to `[400]`. |
| `styles = [normal, italic]` | Styles to vend. Defaults to `[normal]`. |
| `variable_font = true` | Treat the source as a variable font spanning weights `100..900`. |
| `variable = "--font-sans"` | CSS custom property defined on `:root`, e.g. for `font-family: var(--font-sans)`. |
| `generic = sans` | `sans`, `serif`, or `mono`: selects the metric-matched fallback and the generic keyword ending the stack. Defaults to `sans`. |
| `display = "swap"` | `font-display` keyword. Defaults to `swap`. |
| `fallback = "Helvetica"` | Override the `local(...)` fallback face used for metric matching. `fallback_local` is an accepted alias. |
| `extra_stack = ["system-ui"]` | Families appended after the fallback, before the generic keyword. |
| `files = ["fonts/Brand.woff2"]` | `local_font!` only, required: files vendored relative to the crate root. Weight and style are inferred from filenames (`-700-`, `Italic`, ...). |
| `preload = ["latin-400-normal"]` | Faces to `<link rel=preload>`. Google entries match `<subset>-<weight>-<style>` tails; local entries match filename stems. Default: the primary subset's upright 400 (or upright variable) face for Google, the upright faces for local files. |
| `license = "OFL-1.1"` | License recorded in `proa-fonts.lock` for auditability. |

## Use it in your layout

A generated `Font` renders everything it needs into the document `<head>` with one call on the static you declared. Assign the font on `<html>` by class name (direct `font-family`) or by referencing its CSS variable:

```rust
use proa::{WebContext, WebRenderSync, WriteError};
use proa_fonts::Font;
use proa_fonts_macros::google_font;
use proa::html_sync;

static SANS: Font = google_font!("Geist", subsets = [latin], weights = [400, 700], variable = "--font-sans");
static MONO: Font = google_font!("Geist Mono", variable_font = true, generic = mono, variable = "--font-mono");

impl WebRenderSync for DocumentHead {
    fn render(self, cx: &mut WebContext) -> Result<(), WriteError> {
        // Preload hints + <style> with @font-face, the metric-matched
        // fallback, and the utility rules.
        SANS.head(cx)?;
        MONO.head(cx)?;
        Ok(())
    }
}
```

```rust
// Apply it on the root element, either as a class:
html_sync! { <html class={SANS.class_name()}> /* ... */ </html> }

// ...or reference the variable the font defines on :root:
//   body { font-family: var(--font-sans); }
```

`head()` is allocation-free, writes into the buffer owned by the context, and
is generic over the loader and output buffer. Render this component inside
the document's `<head>` using the page's context, including when that context
has a loader or a runtime base path. It emits the
stylesheet via `StaticRaw` (developer-controlled generated content), never
re-escaping it.

`Font::head(cx)` writes manual markup during the document layout's body render.
Keep it next to the managed head outlet; `render_head` is for metadata mutations,
not for writing font tags.

## Metric-matched fallbacks

The reason self-hosting alone is not enough is layout shift. While a web font loads, the browser paints a fallback (Arial, Times New Roman, Courier New). If that fallback has different metrics, text reflows when the real font swaps in.

The build pipeline parses the web font's vertical metrics and average character width, then synthesizes a fallback `@font-face` with `ascent-override`, `descent-override`, `line-gap-override`, and a computed `size-adjust` so the fallback occupies the same space as the real font. These overrides reduce metric differences during the font swap. This is the same technique the `fontaine` and `@capsizecss/metrics` projects use, done here at vendor time with no extra dependency.

The generated stylesheet looks like this:

```css
@font-face{font-family:'Geist';font-style:normal;font-weight:400;font-display:swap;src:url(/fonts/geist-latin-400-normal.9f2c1a3b.woff2) format('woff2');unicode-range:U+0000-00FF}
@font-face{font-family:'Geist Fallback';src:local('Arial');ascent-override:95.02%;descent-override:24.02%;line-gap-override:0.00%;size-adjust:101.24%}
.__proa_font_geist_9f2c1a3b{font-family:'Geist','Geist Fallback',sans-serif}
:root{--font-sans:'Geist','Geist Fallback',sans-serif}
```

## Migrating off runtime Google Fonts

A page that injects a Google stylesheet at runtime pays for a render-blocking third-party request and a flash of unstyled text:

```html
<!-- before: runtime request to fonts.googleapis.com, plus JS -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;700&display=swap" rel="stylesheet">
```

Replace both links with a declaration and one head call:

```rust
// after: self-hosted, preloaded, metric-matched, no third-party request
static SANS: Font = google_font!("Geist", subsets = [latin], weights = [400, 500, 700], variable = "--font-sans");

// where you build the head:
SANS.head(cx)?;
```

A hand-written `@font-face` block (naming files you self-host manually) migrates the same way: declare the files with `local_font!`, delete the hand-written CSS and `<link>`s, and call `head(cx)` where you build the head.

### From the removed CLI workflow

Earlier versions vendored fonts with `cargo proa font add` into `proa-fonts.toml` and `src/fonts/<key>.rs`. That workflow is gone; declarations live at the call site now. To migrate:

1. Rewrite each `proa-fonts.toml` entry as a `google_font!` / `local_font!` static and replace `crate::fonts::GEIST`-style imports with your own bindings.
2. Add the `build.rs` call and the `include!` line from [Wire the build](#wire-the-build).
3. Delete `proa-fonts.toml` and `src/fonts/`; keep `public/fonts/` and `proa-fonts.lock` committed.

Lock entries written by the old CLI lack the declaration fingerprint the collector now records, so the first `cargo build` or `cargo proa font sync` re-vendors them once (Google families need the network for that one run). After that, builds are offline again.

## Command reference

`cargo proa font` runs the same collector the build script uses, outside a build. It never emits the `OUT_DIR` module; the next `cargo build` owns that.

## sync

Vendor and lock every font declared in the project's source, right now. Under `CARGO_NET_OFFLINE=true`, `sync` runs verify-only instead of vendoring:

```bash
cargo proa font sync
cargo proa font sync --offline   # strict verify, no writes; fails on any drift (the CI gate)
```

| Flag | Meaning |
|------|---------|
| `--offline` | Strict verify, no writes: exit non-zero with `proa-fonts.lock is stale` when any declaration (Google or local) is not satisfied by the lock and vendored files, or when the lock content would change, including entries that would be removed. |
| `--fonts-dir <DIR>` | Vendored-files directory. Defaults to `public/fonts`; must match the build script's `CollectOptions` when that is customized. |
| `--url-prefix <PREFIX>` | URL prefix referenced by the generated CSS. Defaults to `/fonts`. |
| `--root <DIR>` | Project root. Defaults to the nearest root. |

## list

Show the fonts recorded in `proa-fonts.lock`:

```bash
cargo proa font list
cargo proa font list --json   # stable JSON, includes measured metrics and fallback overrides
```

## Next steps

- [Static assets](/docs/framework/static-assets)
  - Serve static files and embedded assets safely.
- [Images](/docs/framework/images)
  - Serve responsive images from static assets, without a build pipeline.
- [Tailwind](/docs/guides/tailwind-intellisense)
  - Style a Proa app, with autocomplete in Rust files.
- [CI / GitHub Actions](/docs/guides/ci)
  - Gate pull requests with proa check, then deploy from the same pipeline.


---

# Docs: Images

URL: /docs/framework/images
Description: Serve responsive images from static assets, without a build pipeline.

---
title: Images
description: Serve responsive images from static assets, without a build pipeline.
---

Proa has no image optimization pipeline. It renders the `<img>` tag you write, with typed attribute support for `srcset`, `sizes`, `imagesrcset`, and `imagesizes`, and serves the files from your static directory.

```rust filename="src/components/hero.rs"
html_sync! {
    <img
        src="/static/images/hero-800.avif"
        srcset="/static/images/hero-400.avif 400w,
                /static/images/hero-800.avif 800w,
                /static/images/hero-1600.avif 1600w"
        sizes="(max-width: 640px) 100vw, 800px"
        width="800"
        height="450"
        alt="Coastal cliffs at sunrise"
        fetchpriority="high"
        decoding="async"
    />
}
```

That is the whole API. What follows is how to make it fast.

## The four attributes that matter

| Attribute | Why |
|---|---|
| `width` and `height` | Reserve the box before the bytes arrive. Without them the page reflows and your CLS score suffers |
| `loading="lazy"` | Defer offscreen images. Never put it on your largest above-the-fold image |
| `decoding="async"` | Keep decode work off the critical path |
| `srcset` + `sizes` | Let the browser pick a file matching the device, instead of shipping a desktop image to a phone |

`srcset` without `sizes` is a common mistake: the browser assumes the image is viewport-width and often picks a file larger than it needs.

> **Good to know**: For the one image that is your Largest Contentful Paint, add `fetchpriority="high"` and leave `loading` off entirely. Lazy-loading your hero image is a measurable regression.

## Generating the variants

Resizing is a build step you own. Generate the sizes ahead of time and commit them, or produce them in CI before `proa build`:

```bash
for w in 400 800 1600; do
  magick hero.jpg -resize ${w}x -quality 82 public/images/hero-${w}.avif
done
```

Prefer AVIF, then WebP, then JPEG. If you need per-format fallbacks rather than per-width, use `<picture>`:

```rust filename="src/components/hero.rs"
html_sync! {
    <picture>
        <source srcset="/static/images/hero.avif" type="image/avif" />
        <source srcset="/static/images/hero.webp" type="image/webp" />
        <img src="/static/images/hero.jpg" width="800" height="450" alt="Coastal cliffs" />
    </picture>
}
```

## Serving them

Images live under the directory your static service points at, `public/` in scaffolded sites. The framework does not read a `STATIC_DIR` variable; [Environment variables](/docs/framework/environment) shows that as an app-level convention you can adopt. See [Static assets](/docs/framework/static-assets) for mounting and cache headers.

Give generated filenames a content hash and a long `max-age`. Stable names such as `hero.avif` need a revalidation policy or a versioned URL so updates reach browsers.

In MDX content, `MdxImageConfig` rewrites authored paths at build time, so `/images/hero.avif` in a Markdown file can resolve to `/static/images/hero.avif` in the output:

```rust filename="build.rs"
.images(MdxImageConfig::new().rewrite_prefix("/images/", "/static/images/"))
```

## Open Graph images

Social preview images can be shared static files or generated per page. The optional `proa_og` crate can render images with WPE WebKit on Linux and requires its native libraries; it is separate from the metadata API. Metadata points to an existing image URL and does not invoke a renderer. See [Metadata and OG images](/docs/framework/metadata).

## Next steps

- [Static assets](/docs/framework/static-assets)
  - Serve static files and embedded assets safely.
- [Metadata and OG images](/docs/framework/metadata)
  - Compose titles, descriptions, and social preview images.
- [Page caching](/docs/framework/page-caching)
  - Cache public HTML and static assets at browsers and CDNs.
- [Accessibility](/docs/guides/accessibility)
  - How Proa catches common WCAG, WAI-ARIA, and ARIA-in-HTML issues at compile time.


---

# Docs: Static assets

URL: /docs/framework/static-assets
Description: Serve static files and embedded assets safely.

---
title: Static assets
description: Serve static files and embedded assets safely.
---

`FrameworkBuilder` nests your static router at `/static`, and you supply that router, so the service, cache headers, and deployment rules stay yours. This page covers [disk-backed assets](#serving-assets-from-disk), [embedded assets](#embedding-assets-in-the-binary), [linked island assets](#serving-linked-island-assets), [the CSS manifest](#linking-the-css-manifest), and [external apps](#mounting-external-apps).

## Serving assets from disk

Use `tower_http::services::ServeDir` for files built into a directory:

```rust filename="src/app.rs"
use axum::Router;
use tower::ServiceBuilder;
use tower_http::services::ServeDir;
use tower_http::set_header::SetResponseHeaderLayer;
use axum::http::header::{HeaderValue, CACHE_CONTROL, X_CONTENT_TYPE_OPTIONS};

let static_router = Router::new().nest_service(
    "/assets",
    ServiceBuilder::new()
        .layer(SetResponseHeaderLayer::if_not_present(
            CACHE_CONTROL,
            HeaderValue::from_static("public, max-age=31536000, immutable"),
        ))
        .layer(SetResponseHeaderLayer::if_not_present(
            X_CONTENT_TYPE_OPTIONS,
            HeaderValue::from_static("nosniff"),
        ))
        .service(ServeDir::new("frontend/dist/assets")),
);

let app = FrameworkBuilder::new()
    .with_static_service(static_router)
    .build();
```

The final URL for the nested example is `/static/assets/...`. When deployed
under a public prefix, configure `FrameworkBuilder::with_base_path` and use
`cx.url("/static/assets/...")` in templates. The manifest CSS link is
prefixed automatically. See [URL prefix deployments](/docs/framework/deployment#serving-behind-a-url-path-prefix).

When `with_base_path(...)` is configured, the managed service also composes
recognized URLs inside CSS and JS/MJS files. CSS `url(...)`/`image-set(...)`/`@import`, module
imports, and native browser request/worker URL arguments follow the mount.
Ordinary strings and external URLs stay unchanged. Dynamic browser code can
[coverage and examples](/docs/framework/deployment#coverage-and-limitations).

For routers built without `FrameworkBuilder`, wrap the static router explicitly:

```rust
use proa::axum::{base_path_assets, BasePath};

let static_router = base_path_assets(static_router, BasePath::new("/apps/demo")?);
```

Apply compression outside this wrapper. Its parsed output is cached by content;
ETags and HEAD responses describe the transformed representation. Integrity
hashes must be computed from those served bytes.

A single-binary deploy skips the directory entirely and carries the files inside the executable.

## Embedding assets in the binary

Use `EmbeddedStaticService` when `include_dir` compiles assets into the binary.

```rust filename="src/app.rs"
use axum::Router;
use include_dir::{include_dir, Dir};
use proa::axum::EmbeddedStaticService;

static PUBLIC: Dir<'static> = include_dir!("$CARGO_MANIFEST_DIR/public");

let static_router = Router::new().nest_service(
    "/",
    EmbeddedStaticService::new(PUBLIC.clone()),
);
```

`Dir` holds only `'static` slices, so the clone copies references, not file bytes.

The embedded service sets a content type from the extension and adds `X-Content-Type-Options: nosniff`.

Either service can host the stylesheet, but the page still needs a link to it.

## Serving linked island assets

RSJS embeds its runtimes and generated module sources in the linked binary.
Enable their HTTP routes with `with_rsjs_assets()`:

```rust filename="src/app.rs"
use proa::axum::FrameworkBuilder;

let app = FrameworkBuilder::new()
    .with_rsjs_assets()
    .with_dynamic_routes_and_metadata(routes, metadata)
    .build();
```

| Route | Serves |
| --- | --- |
| `/rsjs-runtime.js` | Core browser runtime. |
| `/rsjs-runtime-query.js` | Query and mutation runtime. |
| `/rsjs/island/:file` | Linked island modules, client helpers/classes, and component fragments. |

The response finalizer selects the script tags and preloads each page needs;
these routes serve the corresponding sources. `with_static_service(...)`
continues to serve application files under `/static` independently.

Use these routes in place of custom handlers at the same paths to avoid route
collisions. For a custom Axum router, merge
`proa::axum::rsjs_assets_router(&base_path)` and apply
`RouteContextLayer::with_base_path` with the same setting.

`with_rsjs_assets()` works with the default root or with
[`with_base_path(...)`](/docs/framework/configuration#frameworkbuilder-base-paths-and-rsjs-assets).
With a prefix, it rewrites runtime import URLs once at startup, while incoming
routes remain unprefixed and HTML responses keep streaming. See
[URL prefix deployments](/docs/framework/deployment#serving-behind-a-url-path-prefix)
for proxy setup and [RSJS runtime wiring](/docs/rsjs/runtime) for asset selection
and hydration.

## Linking the application stylesheet

Write the link in the document layout. `cx.url` applies the configured base path:

```rust filename="src/layouts/root.rs"
let stylesheet = cx.url("/static/assets/app.css");
html_sync! {
    <link rel="stylesheet" href={stylesheet} />
}
```

## Mounting external apps

Compose additional static applications with Axum's router APIs. For example,
nest a file service at `/docs`. Configure any SPA fallback explicitly on that
service. Proa does not start other dev servers or provide a reverse proxy.

Every path above serves files straight to the browser, which makes what you put in those directories a security decision.

## Securing served directories

- Serve **only** trusted build output from static directories.
- Do not let untrusted users write files or symlinks into served asset directories.
- Add `nosniff` headers for disk-backed services.
- Prefer immutable cache headers only for fingerprinted asset names.
- Keep uploads behind explicit authenticated handlers instead of a generic static file service.

## Next steps

- [Page caching](/docs/framework/page-caching)
  - How static asset cache headers fit with HTML and endpoint caching.
- [Images](/docs/framework/images)
  - Serve responsive images from static assets, without a build pipeline.
- [Fonts](/docs/framework/fonts)
  - Self-host web fonts with metric-matched fallbacks and zero runtime requests.
- [Configuration](/docs/framework/configuration)
  - Configure FrameworkBuilder, security defaults, static mounts, and response behavior.


---

# Docs: Third-party integrations

URL: /docs/framework/third-party
Description: Add consent-aware Google Analytics, deferred scripts, and click-to-load YouTube embeds to Proa pages.

---
title: Third-party integrations
description: Add consent-aware Google Analytics, deferred scripts, and click-to-load YouTube embeds to Proa pages.
keywords: [analytics, gtag, YouTube, scripts, third-party, consent]
---

Optional third-party components for Proa: deferred external scripts, Google
Analytics 4, and click-to-load YouTube embeds. Components render through
`WebRenderSync<L, B>` and support custom writers. They work in plain SSR apps
without an RSJS runtime. Unrendered integrations emit no browser code.

The browser adapters here are the boundary to external SDKs and iframes;
application state and interactive application components can continue using RSJS.

## Install

Add the optional crate and enable only the providers you need:

```toml
proa_third_party = { version = "0.2.0", default-features = false, features = ["google-analytics", "youtube"] }
```

The default features include both providers. Disable defaults and select just
the providers your application uses. `Script` is available without features.

## Google Analytics

```rust
use proa_third_party::google::GoogleAnalytics;

let analytics = GoogleAnalytics::new("G-XXXXXXXXXX")?;
// Compose {analytics} into your shared html_sync! document layout.
```

In Markdown, `GoogleAnalytics` implements both `MdRenderSync` and `MdRender`
as a no-op. Composing it into `md_sync!` or `md!` emits no text, scripts, or
whitespace.

The default is **consent required**: no Google SDK request and no retained
tracking events until your application's consent UI grants permission. After
the component has rendered, connect the UI to the browser API:

```js
window.proaThirdParty.googleAnalytics.setConsent(true);
// Later, if the visitor withdraws permission:
window.proaThirdParty.googleAnalytics.setConsent(false);
```

The decision applies to all GA measurement IDs rendered in this document.
Applications own consent collection, persistence, and any cookie cleanup. A
revocation disables subsequent tracking and cancels SDK downloads that have
not started; it cannot retract data already sent or unload an existing SDK.
This integration implements a basic loading gate, not a consent-management UI.

If the application has already established permission to collect, render
`GoogleAnalytics::new(id)?.consent(AnalyticsConsent::Granted)` instead, importing
`AnalyticsConsent` from `proa_third_party::google`. Setting `Granted` does not
obtain consent from the visitor. Google Signals and advertising personalization
signals remain disabled; advertising consent states are denied.

The default script strategy waits for `window.load`. Use
`.strategy(ScriptStrategy::Async)` to load earlier or `ScriptStrategy::Idle`
to wait for idle time after load. Longer delays can miss short visits.

Track events after permission is granted:

```js
window.proaThirdParty.googleAnalytics.track("G-XXXXXXXXXX", "sign_up", {
  method: "email",
});
```

Events queue while the SDK downloads. The method returns `false` if that
measurement ID is unregistered or disabled. Do not send personal information.
An existing `window.dataLayer` or `window.gtag` is preserved. Multiple instances
share one SDK; each measurement ID is configured once per document. A repeated
ID uses its first declaration's settings.

By default GA sends an automatic document page view. Use
`.send_page_view(false)` if you send page views yourself, and configure the GA
web stream's enhanced measurement settings accordingly to avoid duplicates.
This crate does not add a second client-router page-view listener.

Environment variables and production-host checks belong to your application.
The component honors `window["ga-disable-" + measurementId] === true` when it
starts, so applications can set the standard GA opt-out flag before rendering
the bootstrap. No API secret, OAuth token, or service-account key is needed.

## YouTube

```rust
use proa_third_party::youtube::YouTubeEmbed;

let video = YouTubeEmbed::new("M7lc1UVf-VE", "YouTube player demonstration")?
    .start_at(10)
    .class("my-video");
// Compose {video} into html_sync! or render it through MdRenderSync.
```

HTML initially contains a lazy thumbnail, a keyboard-operable Play button, and
a persistent link to the video. No player iframe or YouTube player SDK loads
until activation. The iframe uses `youtube-nocookie.com`, preserves a referrer
for player compatibility, and receives focus when inserted. Autoplay is
requested only after activation and remains subject to browser policy.

The default thumbnail comes from `i.ytimg.com`, which can receive a request
before playback. Use `.poster("/images/my-video.webp")?` for a locally hosted
poster and no YouTube request before activation. A privacy-enhanced iframe is
still a third-party connection once the visitor plays the video.

The supplied CSS reserves a 16:9 frame with a minimum height of 200px. It does
not require Tailwind. Styles are inline by default; use `.inline_styles(false)`
and serve `proa_third_party::youtube::YOUTUBE_CSS` as an external `text/css`
asset when your CSP disallows inline styles or you want one cached stylesheet.
Include that stylesheet before the embed to preserve its layout dimensions.

For fully custom styling, combine `.class("my-video").inline_styles(false)`
and style `.my-video` in your app. The internal `data-proa-youtube-frame`,
`data-proa-youtube-play`, and `data-proa-youtube-play-icon` selectors identify
the frame and controls. Your styles should reserve the player's dimensions
before activation. Using `YOUTUBE_CSS` is optional.

Both `MdRenderSync` and `MdRender` produce an escaped title and a normal YouTube
link, with no HTML, scripts, or iframe. The start offset applies to embedded
playback; the fallback and Markdown links point to the video itself.

## Other scripts

```rust
use proa_third_party::{Script, ScriptStrategy};

let widget = Script::new("https://cdn.example.com/widget.js")?
    .strategy(ScriptStrategy::Idle);
```

Only use script URLs whose code you trust. HTTPS and root-relative URLs are
accepted. `.integrity("sha384-...")` enables Subresource Integrity and anonymous
CORS. The loader deduplicates resolved URLs within this API; it does not adopt
unrelated script tags inserted by other libraries. The first declaration's
options win. Failed requests dispatch `proa:script-error`; calling
`window.proaThirdParty.loadScript(url, options)` again explicitly retries them.
The returned promise resolves to the loaded script. There is no automatic
retry loop. Do not initialize GA both here and through a separate tag manager.

## CSP

Install the response nonce on `WebContext`. Components copy it to their inline
bootstrap and any scripts they create. Use a matching nonce-based `script-src`
policy; `strict-dynamic` permits scripts subsequently loaded by the trusted SDK.
Configure `connect-src`/`img-src` for the GA destinations you enable. YouTube
needs `frame-src https://www.youtube-nocookie.com` and, for default posters,
`img-src https://i.ytimg.com`.

Inline YouTube styles carry the same nonce, which must also be permitted by
`style-src`. Alternatively serve `YOUTUBE_CSS` from your own allowed origin.
The crate never relaxes your response's security headers.


---

# Docs: FrameworkBuilder configuration

URL: /docs/framework/configuration
Description: Configure FrameworkBuilder, security defaults, static mounts, and response behavior.

---
title: FrameworkBuilder configuration
description: Configure FrameworkBuilder, security defaults, static mounts, and response behavior.
---

`FrameworkBuilder` turns routes, static services, and hardening layers into the Axum router you run in production.

Use this page when you need the complete setup surface in one place. Use [Routing](/docs/framework/routing), [Responses](/docs/framework/responses), [Static assets](/docs/framework/static-assets), and [Deployment](/docs/framework/deployment) for deeper workflow examples.

## Minimal FrameworkBuilder Setup

```rust
use axum::{routing::get, Router};
use proa::{HeadConfig, HeadUrlPolicy};
use proa::axum::{FrameworkBuilder, RouteResponse};
use crate::{layouts::RootDocument, pages::HomePage};

async fn home() -> RouteResponse {
    RouteResponse::ssr(RootDocument { children: HomePage })
}

let routes = Router::new().route("/", get(home));
let head = HeadConfig::default()
    .with_urls(HeadUrlPolicy::new("https://example.com", "/")?);

let app = FrameworkBuilder::new()
    .with_head(head)
    .with_dynamic_routes(routes)
    .build();
```

`RootDocument` is the `LAYOUT` component containing the document markup and head outlet; `HomePage` declares `ROLE = PAGE`. See [Layouts and Pages](/docs/framework/layouts-and-pages) for complete implementations. Replace the public origin with trusted application configuration.

Use `with_dynamic_routes` for an ordinary Axum router. Route specifications are optional: use `with_dynamic_routes_and_metadata` when you also need their route-mode or other specification metadata. Legacy route titles do not populate the managed head; use `render_head` or app-wide defaults.

The builder returns an Axum router; bind a TCP listener and pass both to `proa::axum::serve()` to run it. See [the complete application example](/docs/framework/sitemaps#run-an-application) for route setup, discovery endpoints, and server startup.

## FrameworkBuilder Methods

| Method | Use it for |
|--------|------------|
| `FrameworkBuilder::new()` | Create the builder with secure defaults. No manifest or configuration is required. |
| `.with_head(head)` | Install app-wide [managed head configuration and defaults](/docs/framework/metadata#configure-app-wide-defaults) for rendered routes. |
| [`.with_base_path(base_path)`](#frameworkbuilder-base-paths-and-rsjs-assets) | Set the public URL prefix for a mounted application. |
| [`.with_public_origin(origin)?`](/docs/framework/sitemaps) | Set the public HTTP(S) origin used by discovery endpoints. |
| [`.with_sitemap(entries)`](/docs/framework/sitemaps) | Serve one sitemap using the final public origin and base path. |
| [`.with_sitemaps(files)`](/docs/framework/sitemaps#multiple-sitemaps) | Serve named sitemap documents plus a sitemap index; accepts results from an awaited async generator. |
| [`.with_robots(robots)`](/docs/framework/robots) | Serve `/robots.txt` from a document or awaited generator result, with bot-specific groups and automatic sitemap/index links. Behind a prefix-stripping proxy, forward origin-root `/robots.txt` to this handler. |
| [`.with_rsjs_assets()`](#frameworkbuilder-base-paths-and-rsjs-assets) | Serve the linked RSJS runtimes and generated modules. |
| `.with_static_service(router)` | Mount a router under `/static`. |
| `.with_dynamic_routes(router)` | Merge an Axum router without a metadata map. |
| `.with_dynamic_routes_and_metadata(router, metadata)` | Merge Proa route specs plus computed route metadata. |
| `.with_body_limit(bytes)` | Override the global request body cap. |
| `.with_cross_origin_protection(bool)` | Toggle browser cross-origin unsafe request protection. |
| `.with_trusted_origin(origin)` | Add an exact trusted origin such as `https://admin.example.com`. |
| `.with_security_headers(config)` | Configure frame policy, HSTS, and CSP. |
| `.with_request_timeout(duration)` | Override the default request timeout. |
| `.without_request_timeout()` | Disable the timeout layer. Prefer raising the timeout first. |
| `.with_concurrency_limit(max)` | Add a global in-flight request cap. |
| `.with_catch_panic(bool)` | Convert panics into plain 500 responses instead of resetting the connection. |
| `.build()` | Produce the final Axum `Router`. |
| `.try_build()?` | Build the router while returning invalid discovery configuration as an error. |

## FrameworkBuilder Base Paths and RSJS Assets

These methods configure separate parts of the application:

- `with_base_path(BasePath)` sets the public mount used by `cx.url(...)`
  and framework-generated URLs. Island query/mutation requests follow it only
  when declared with `cx.url(...)` or `FetchRequest.apply_base_path: true`.
  Managed static CSS/JS URLs follow it too. Its default is the origin root.
- `with_rsjs_assets()` installs routes for the RSJS runtimes and linked modules.
  Enable it when this app serves its own island assets, including at the origin
  root. It is opt-in so applications can supply their own asset handlers.

For an app exposed at `/apps/demo/` by a prefix-stripping proxy:

```rust filename="src/app.rs"
use proa::axum::{BasePath, FrameworkBuilder};

let app = FrameworkBuilder::new()
    .with_base_path(BasePath::new("/apps/demo")?)
    .with_rsjs_assets()
    .with_dynamic_routes_and_metadata(routes, metadata)
    .build();
```

Keep routes such as `/docs/start` and `/static/...` unprefixed. Compose
application links with `cx.url("/docs/start")` and handler redirects
with `app_url("/")`. Pass the original, unprefixed manifest to the builder.

See [linked island asset serving](/docs/framework/static-assets#serving-linked-island-assets)
for the installed routes and custom-router alternative. The
[URL prefix deployment guide](/docs/framework/deployment#serving-behind-a-url-path-prefix)
covers startup environment configuration, proxy behavior, and coverage limits.

## FrameworkBuilder Production Defaults

`build()` applies conservative defaults:

| Default | Value |
|---------|-------|
| Body limit | `1 MiB` through Axum `DefaultBodyLimit`. |
| Request timeout | `30s` for response production. Streaming bodies keep flowing after the response head is produced. |
| Cross-origin protection | On for unsafe browser requests. |
| Security headers | `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, and `Referrer-Policy: strict-origin-when-cross-origin`. |
| Concurrency limit | Off until configured. |
| Panic catching | Off until configured. |

Keep the global body limit small. For uploads, prefer a dedicated nested router with a larger Axum body limit instead of raising the whole app.

## FrameworkBuilder Security

Security defaults live on their own pages, because they are policy decisions rather than configuration plumbing:

| Builder call | Covered in |
|---|---|
| `.with_security_headers(config)`, `.with_strict_csp()`, `.with_csp_policy(policy)` | [Headers and CSP](/docs/framework/security-headers) |
| `.with_trusted_origin(origin)` | [Cross-origin and CSRF](/docs/framework/cross-origin) |

Cross-origin protection, the 1 MiB body limit, and the 30-second request timeout are applied by `build()` without configuration. See [Security](/docs/guides/security) for what Proa hardens and what stays yours.

## FrameworkBuilder Static Services

Mount generated assets under `/static`:

```rust
use tower_http::services::ServeDir;

let static_router = axum::Router::new().nest_service("/", ServeDir::new("public"));

let app = FrameworkBuilder::new()
    .with_static_service(static_router)
    .build();
```

For public directories, keep untrusted writers out of the served tree. `ServeDir` rejects `..` traversal, but deployments should still treat symlinks and generated files deliberately.

## RouteResponse Quick Reference

| Constructor | Use it for |
|-------------|------------|
| `RouteResponse::ssr(component)` | Sync `WebRenderSync` pages. |
| `RouteResponse::ssr_async(component)` | Async pages that do not use a loader. |
| `RouteResponse::ssr_async_with_loader(component, loader)` | Async pages with a typed loader. |
| `RouteResponse::ssr_stream(component)` | Streaming pages without a loader. |
| `RouteResponse::ssr_stream_with_loader(component, loader)` | Streaming pages with a typed loader. |

Response modifiers:

| Modifier | Applies to |
|----------|------------|
| `.with_head(config)` / `.without_head()` | Enable managed metadata for one response, or keep its document in manual mode. |
| `.with_loader(loader)` | Async and streaming responses with typed loaders. |
| `.with_render_mode(mode)` | Async render plans; chunked modes stream, while static and agent modes buffer. |

Use [Responses](/docs/framework/responses) for examples and [Data loading and streaming](/docs/framework/data-loading) for loader and streaming details.


---

# Docs: proa.config.json

URL: /docs/framework/project-config
Description: Configure the dev server, asset build, and component registries.

---
title: proa.config.json
description: Configure the dev server, asset build, and component registries.
---

`proa.config.json` is the CLI lifecycle and component registry config. `proa dev` reads it to build assets, run the server, and watch project files. `proa build` reads it to build assets before compiling the release binary.

It sits at the project root, next to `Cargo.toml`.

Keep local build orchestration and component registry aliases here instead of scattering them through README snippets:

```json
{
  "$schema": "https://proa.so/schema/proa.config.json",
  "paths": {
    "components": "src/components",
    "assets": "public/proa"
  },
  "registries": {
    "@proa": "https://ui.proa.so/r/{name}.json",
    "@proa-pro": "https://console.proa.so/r/{name}.json"
  },
  "dev": {
    "command": ["cargo", "run"],
    "host": "127.0.0.1",
    "port": 3000,
    "watch": ["src", "styles", "Cargo.toml", "build.rs", "proa.config.json"]
  },
  "build": {
    "command": ["cargo", "build", "--release"],
    "assets": [
      {
        "kind": "tailwind",
        "input": "styles/input.css",
        "output": "public/styles.css"
      }
    ]
  }
}
```

`proa.lock.json` is generated next to the config file. It is intentionally separate from Cargo.lock because it tracks vendored UI source files, not Rust crate dependency resolution.

Both individual components and complete blocks install directly beneath
`src/components/<slug>/`. Run `proa config validate` to catch unsafe paths,
missing `{name}` placeholders, and invalid registry URLs before an install.

## Next steps

- [App configuration](/docs/framework/configuration)
  - Configure FrameworkBuilder, security defaults, static mounts, and response behavior.
- [Environment variables](/docs/framework/environment)
  - Configure a deployed Proa app without rebuilding the binary.
- [proa new site](/docs/cli/new-site)
  - Scaffold an opinionated Proa project.


---

# Docs: Environment variables

URL: /docs/framework/environment
Description: Configure a deployed Proa app without rebuilding the binary.

---
title: Environment variables
description: Configure a deployed Proa app without rebuilding the binary.
---

One release binary runs in every environment, and environment variables pick the bind address, static path, log level, and secrets for each one. This page covers the [runtime contract](#defining-the-runtime-contract), [loading config once at startup](#loading-config-once), [handling required secrets](#handling-required-secrets), and [exposing values to the browser](#exposing-values-to-the-browser).

## Defining the runtime contract

Keep the contract small and explicit:

| Variable | Required | Use |
|----------|----------|-----|
| `HOST` | No | Bind host. Use `0.0.0.0` in containers and `127.0.0.1` behind a same-host reverse proxy. Sites from `proa new site` read `PROA_HOST` instead, which is what `proa start --host` sets. |
| `PORT` | No | Bind port. Container platforms often inject this. |
| `STATIC_DIR` | No | Directory the static asset service serves. |
| `RUST_LOG` | No | `tracing_subscriber` filter, usually `info` in production. |
| `PUBLIC_BASE_URL` | Usually | Absolute origin for metadata, canonical URLs, emails, and webhooks. |
| `TRUSTED_ORIGIN` | If needed | Browser origin allowed to send unsafe cross-origin requests. |
| `DATABASE_URL` | If needed | Database connection string or pool configuration input. |

Do not reach for a runtime variable where render code wants a compile-time constant. Pass runtime values through handlers, app state, loaders, or explicit props.

Read every variable in this table once, at startup, rather than scattering `env::var` through the request path.

## Loading config once

Read and validate environment variables during startup:

```rust filename="src/config.rs"
use std::{
    env,
    net::{IpAddr, Ipv4Addr, SocketAddr},
    path::PathBuf,
};

#[derive(Clone, Debug)]
pub struct RuntimeConfig {
    pub bind: SocketAddr,
    pub static_dir: PathBuf,
    pub public_base_url: Option<String>,
    pub trusted_origin: Option<String>,
}

impl RuntimeConfig {
    pub fn from_env() -> anyhow::Result<Self> {
        let host = env::var("HOST").unwrap_or_else(|_| "127.0.0.1".to_string());
        let host = host.parse::<IpAddr>()?;

        let port = env::var("PORT")
            .ok()
            .map(|value| value.parse::<u16>())
            .transpose()?
            .unwrap_or(3000);

        let static_dir = env::var_os("STATIC_DIR")
            .map(PathBuf::from)
            .unwrap_or_else(|| PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("public"));

        Ok(Self {
            bind: SocketAddr::new(host, port),
            static_dir,
            public_base_url: optional_env("PUBLIC_BASE_URL"),
            trusted_origin: optional_env("TRUSTED_ORIGIN"),
        })
    }
}

fn optional_env(name: &str) -> Option<String> {
    env::var(name).ok().filter(|value| !value.trim().is_empty())
}

impl Default for RuntimeConfig {
    fn default() -> Self {
        Self {
            bind: SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 3000),
            static_dir: PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("public"),
            public_base_url: None,
            trusted_origin: None,
        }
    }
}
```

Load it once in `main`:

```rust filename="src/main.rs"
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt::init();

    let config = RuntimeConfig::from_env()?;
    let app = build_app(config.clone())?;

    let listener = tokio::net::TcpListener::bind(config.bind).await?;
    tracing::info!("listening on http://{}", listener.local_addr()?);
    proa::axum::serve(
        listener, app, std::time::Duration::from_secs(30),
    ).await?;

    Ok(())
}
```

That config value then travels to exactly one place: the application boundary.

## Applying config to FrameworkBuilder

Use runtime config where you build the router:

```rust filename="src/app.rs"
use axum::Router;
use proa::axum::FrameworkBuilder;
use tower_http::services::ServeDir;

pub fn build_app(config: RuntimeConfig) -> anyhow::Result<Router> {
    let (routes, metadata) = build_routes();

    let static_router = Router::new().nest_service("/", ServeDir::new(&config.static_dir));

    let mut builder = FrameworkBuilder::new()
        .with_static_service(static_router)
        .with_dynamic_routes_and_metadata(routes, metadata);

    if let Some(origin) = config.trusted_origin.as_deref() {
        builder = builder.with_trusted_origin(origin);
    }

    Ok(builder.build())
}
```

Configure discovery endpoints from these typed startup values:

```rust filename="src/main.rs" {13-14}
use proa::BasePath;
use proa::axum::{FrameworkBuilder, RobotsTxt, SitemapUrl};

let config = RuntimeConfig::from_env()?;
let origin = config.public_base_url.as_deref().unwrap_or("http://localhost:3000");
let base_path = BasePath::new(
    &std::env::var("PROA_BASE_PATH").unwrap_or_default(),
)?;

let app = FrameworkBuilder::new()
    .with_base_path(base_path)
    .with_public_origin(origin)?
    .with_sitemap([SitemapUrl::new("/")?])
    .with_robots(RobotsTxt::new().allow("/")?)
    .try_build()?;
```

Optional values tolerate a fallback like this one. Secrets do not.

## Handling required secrets

Fail fast for required secrets:

```rust filename="src/config.rs"
fn required_env(name: &'static str) -> anyhow::Result<String> {
    let value = env::var(name).map_err(|_| anyhow::anyhow!("{name} must be set"))?;
    anyhow::ensure!(!value.trim().is_empty(), "{name} must not be empty");
    Ok(value)
}

let database_url = required_env("DATABASE_URL")?;
let stripe_secret_key = required_env("STRIPE_SECRET_KEY")?;
```

Read secrets in startup code or request handlers. Do not read them inside `WebRenderSync` implementations, and do not pass secrets into page props.

Some variables never reach the running process at all, because the build consumes them first.

## Separating build-time from runtime

Keep these separate:

| Variable | Phase | Notes |
|----------|-------|-------|
| `PROA_VERSION` | Build | Pins the CLI installed by the Dockerfile or CI installer. Public Proa dependencies require no GitHub credential or registry token. |
| `STATIC_DIR` | Runtime | Points the running server at public assets. |
| `DATABASE_URL` | Runtime | App startup or handlers read it. |
| `PUBLIC_BASE_URL` | Runtime | Safe to expose only if you explicitly render it. |
| `RUST_LOG` | Runtime | Controls logs without rebuilding. |

If a variable changes how Rust code compiles, use Cargo features or build-time configuration. If it changes how one deployed artifact runs, use a runtime environment variable.

Runtime variables stay on the server unless you render them yourself.

## Exposing values to the browser

Proa never copies environment variables into the browser on your behalf. Whitelist values explicitly:

```rust filename="src/layouts/root.rs"
pub struct PublicConfig {
    pub base_url: &'static str,
    pub analytics_enabled: bool,
}

html_sync! {
    <meta name="app-base-url" content={public_config.base_url} />
    <meta
        name="analytics-enabled"
        content={if public_config.analytics_enabled {
        "true"
    } else {
        "false"
    }}
    />
}
```

Render a value only when it can safely appear in page HTML, view source, logs, caches, and browser devtools.

Locally, the same variables come from your shell instead of a platform dashboard.

## Working locally

Use shell exports or a local `.env` loader:

```bash filename="Terminal"
HOST=127.0.0.1 PORT=3000 RUST_LOG=debug proa run
```

```rust filename="src/main.rs"
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    #[cfg(debug_assertions)]
    let _ = dotenvy::dotenv();

    let config = RuntimeConfig::from_env()?;
    // build and serve the app
    Ok(())
}
```

Keep `.env` out of git. Generated Proa projects already ignore `.env`.

> **Good to know**: `dotenvy::dotenv()` sits behind `#[cfg(debug_assertions)]`, so the `.env` loader compiles out of any build with debug assertions off.

In production, the platform supplies the same values through the container or the service unit.

## Setting variables in production

Set runtime variables on the container, not in the image:

```bash filename="Terminal"
docker run --rm \
  -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e STATIC_DIR=/app/public \
  -e RUST_LOG=info \
  -e PUBLIC_BASE_URL=https://example.com \
  hello-proa
```

For Cloud Run and similar platforms, set `HOST=0.0.0.0`, read the injected `PORT`, and configure secrets through the platform secret manager.

A systemd unit carries the same contract:

```ini filename="/etc/systemd/system/hello-proa.service"
[Service]
Environment=HOST=127.0.0.1
Environment=PORT=3000
Environment=STATIC_DIR=/opt/hello-proa/public
Environment=RUST_LOG=info
Environment=PUBLIC_BASE_URL=https://example.com
ExecStart=/opt/hello-proa/bin/hello-proa
```

Use `EnvironmentFile=/etc/hello-proa/env` if you manage variables outside the unit file.

## Next steps

- [Deploy](/docs/framework/deployment)
  - Pick a deployment target, then follow the guide for it.
- [Configuration](/docs/framework/configuration)
  - Configure FrameworkBuilder, security defaults, static mounts, and response behavior.
- [Static assets](/docs/framework/static-assets)
  - Serve the directory `STATIC_DIR` points at, with cache headers and path boundaries.
- [Security](/docs/guides/security)
  - What Proa hardens by default, and what stays your job.


---

# Docs: Security

URL: /docs/guides/security
Description: What Proa hardens by default, the CVE classes its design answers, and what stays your job.

---
title: Security
description: What Proa hardens by default, the CVE classes its design answers, and what stays your job.
---

Proa's security work splits three ways: what the template engine does automatically, what the framework hardens by default, and what remains application logic.

Knowing which bucket a concern falls into is most of the job.

| Concern | Who handles it |
|---|---|
| Escaping dynamic values in HTML | **Proa, automatically.** No opt-in |
| Executable URL schemes in static attributes | **Proa, at compile time.** Hard error |
| Executable URL schemes in dynamic attributes | **Proa, at render time.** Value is neutralized |
| Dynamic values inside `<script>` or `<style>` | **Proa warns at compile time**, and masks tokenizer breakouts at render time |
| Dynamic `on*`, `srcdoc`, and `style` attributes | **Proa warns at compile time.** RSJS rejects them outright |
| Baseline response headers | **Framework, on by default.** `nosniff`, `DENY`, `strict-origin-when-cross-origin` |
| HSTS, frame policy overrides, Content Security Policy | **Framework, opt-in.** `with_security_headers()` / `with_strict_csp()` |
| Cross-origin unsafe requests | **Framework, on by default.** Returns `403` |
| Request body size and timeout | **Framework, on by default.** 1 MiB, 30 seconds |
| Keeping server data out of the browser | **Framework, enforced by the RSJS linker** |
| CSRF tokens, sessions, auth | **Yours.** Axum middleware |
| Input validation, sanitizing user HTML | **Yours.** Before data reaches a template |
| Rate limiting, cookie attributes, CORS, safe redirects | **Yours.** Server middleware |

## What Proa does automatically

Three layers run without configuration: the macro refuses to compile some markup, the escaper encodes per context at render time, and the RSJS client runtime repeats the same guards in the browser.

### Compile time

`html!` and `html_sync!` walk the template AST during macro expansion and run an OWASP-derived validation pass. Errors fail the build. Warnings compile but surface at the call site with the offending expression quoted back.

| Check | Severity | What it catches |
|---|---|---|
| Executable scheme in a static URL attribute | **Error** | `href="javascript:alert(1)"` and every case, whitespace, and entity variant of it |
| Dynamic `{expr}` inside `<script>` or `<style>` | Warning | HTML escaping is the wrong encoder for a JS or CSS context (OWASP Rules #3 and #4) |
| Dynamic `on*` handler (`onclick={expr}`) | Warning | The value lands in a JavaScript execution context, where attribute escaping does nothing |
| Dynamic `srcdoc={expr}` or `style={expr}` | Warning | Second-order contexts: `srcdoc` re-parses as HTML in the iframe, `style` parses as CSS |
| Dynamic `{expr}` in a raw-text element | Warning | `<textarea>`, `<title>`, `<xmp>`, `<noscript>`, `<noframes>` have non-standard parser semantics |
| `UnsafeRaw` inside `<svg>`, `<math>`, or `<foreignObject>` | Warning | Foreign content re-parses in another namespace, the mutation-XSS path |

The static URL error looks like this:

```rust filename="src/components/link.rs"
html_sync! {
    <a href="javascript:alert(1)">"Click me"</a>
}
// error: dangerous URL scheme in `href` attribute. use a safe scheme
// (https:, /, #) or pass data via data-* attributes
// (OWASP XSS Prevention Cheat Sheet, Rule #7)
```

Two details make that check hold up against real bypass techniques rather than only the obvious spelling.

**The attribute set is wide.** Blocking `href`, `src`, `action`, and `formaction` is the common choice and it is not enough. Proa checks `href`, `src`, `action`, `formaction`, `poster`, `ping`, `cite`, `data`, `background`, `longdesc`, `manifest`, and both spellings of `xlink:href`. Each one is a real sink: `poster` fetches `javascript:` on older engines, `ping` is an exfiltration beacon, `data` on `<object>` executes, `manifest` was the AppCache vector. `srcset` is deliberately excluded, because its comma-separated `url descriptor, ...` grammar is not a single URL and a whole-string scheme check would be wrong there.

**The scheme comparison is normalized the way a browser normalizes it.** Two decoding passes happen before a URL reaches the parser, and a naive prefix match misses both:

- The WHATWG URL spec directs browsers to strip ASCII tab, LF, and CR from URL input. So `java&Tab;script:` and `\njavascript:` navigate fine. Proa skips ASCII whitespace and NUL *throughout* the scheme prefix, not just at the leading edge.
- The HTML5 parser decodes numeric character references inside attribute values before URL parsing. So `&#106;avascript:alert(1)` and the zero-padded `&#0000000106;avascript:alert(1)` both work in a browser. Proa runs one pass of numeric-entity decoding with no digit cap, and treats a non-ASCII decoded code point as a non-match, since it cannot spell an ASCII scheme.

The blocked set is `javascript:`, `vbscript:`, and the executable `data:` types: `text/html`, `application/xhtml+xml`, `application/xml`, and `image/svg+xml`. Raster image, audio, video, and font data URLs stay allowed, because they have legitimate inline uses. SVG is blocked even when a particular payload looks inert, because it is an executable XML container.

### Render time

Every dynamic value is escaped for its context before it reaches the output buffer:

```rust filename="src/components/comment.rs"
let user_input = "<script>alert('xss')</script>";

html_sync! {
    <p>{user_input}</p>
}
// <p>&lt;script&gt;alert('xss')&lt;/script&gt;</p>
```

Attribute values are always double-quoted. There is no code path that emits an unquoted attribute.

**Dynamic URL attributes get the same scheme check as static ones.** A compile-time error cannot see `href={user_supplied}`, so the macro routes URL-bearing attributes through a runtime guard using the identical normalization. In debug builds a dangerous value trips a `debug_assert!`, so the mistake fails your test suite. In release builds the attribute renders with an empty value rather than the dangerous URL.

**`<script>` and `<style>` content gets tokenizer masking.** HTML escaping alone does not keep a value inside a raw-text element, because the tokenizer leaves raw-text state on byte sequences that escaping does not touch. Proa masks three of them with a single backslash, which is a no-op for the decoded JavaScript string value:

| Sequence | Masked to | Tokenizer transition it blocks |
|---|---|---|
| `</script` (or `</style`) followed by `>`, whitespace, or `/` | `<\/script` | Closes the raw-text element (HTML5 §13.2.5.17) |
| `<script` followed by `>`, whitespace, or `/` | `<\script` | Enters script-data-escaped state (HTML5 §13.2.5.27) |
| `<!--` | `<\!--` | Opens script-data-escaped state (HTML5 §13.2.5.18) |

`-->` needs no mask of its own: every bare `>` is already escaped to `&gt;`, so the sequence cannot appear in the output, and reaching the `-->` transition requires an unmasked `<!--` first.

This is defense in depth, not permission. The compile-time warning still fires. The masking exists so a value that slips through a suppressed warning cannot escape the element.

**Island hydration payloads are masked too.** RSJS and React islands serialize props into `<script type="application/json">`. That content is raw text and `textContent` does not decode entities, so HTML-escaping it would corrupt the JSON. Instead `</` becomes `<\/` (a valid JSON escape for `/`) so the HTML parser cannot match a closing tag inside the payload, and U+2028 / U+2029 become their six-character escapes, since before ES2019 those acted as line terminators inside inline scripts and allowed breakout from a JSON string literal.

### In the browser

RSJS repeats the server-side guards on the client, because a client-updated attribute is the same sink as a server-rendered one.

- The `#[rsjs(...)]` analyzer rejects dynamic bindings to any `on*` attribute, plus `srcset`, `ping`, `srcdoc`, and `style`. That is a compile error, not a warning.
- Dynamic URL attributes are classified and lowered to a sanitized binding.
- The runtime refuses to install any attribute matching `/^on/i` through `setAttribute`, and warns in dev mode. Reaching that branch means codegen regressed, so it fails closed.
- The runtime carries its own port of the URL scheme check, including the entity-decoding and control-character normalization, and blanks a dangerous value instead of setting it.

> **Good to know**: RSJS enforces a fourth boundary. A value that never reaches a client root never ships to the browser, so secrets held in server-only components stay on the server by construction. See [Server-rendered content](/docs/rsjs/server-only).

## CVE precedents this design answers

These are the published vulnerabilities the escaping and validation layers were reviewed against. Each one is cited in the source next to the code that answers it, so the reasoning survives refactors.

| Precedent | Ecosystem | The bypass | What Proa does |
|---|---|---|---|
| CVE-2023-24538 | Go `html/template` | Script-context escape bypass through template actions in JS contexts | Warns at compile time on any dynamic value inside `<script>`, and masks raw-text breakout sequences at render time |
| CVE-2023-39318 | Go `html/template` | A nested `<script` inside script-data-escaped state changes tokenizer state | `<script` followed by a tag-ending byte is masked to `<\script` |
| CVE-2023-39319 | Go `html/template` | `</script ` with trailing whitespace still closes the element | The close-tag mask matches `</script` followed by `>`, whitespace, *or* `/`, not just `</script>` |
| CVE-2026-32635 | Angular | The `i18n-href` sanitizer allowlist missed a URL attribute, which is a complete XSS bypass | Drove the wide URL-attribute set (11 attributes plus both `xlink:href` spellings) rather than the usual four |
| CVE-2026-39315 | Unhead | `hasDangerousProtocol()` was defeated by HTML-entity padding in the scheme | One pass of numeric-entity decoding with no digit cap runs before the scheme comparison |
| DOMPurify bypass series (2019 to 2020) | DOMPurify | Mutation XSS: HTML-escaped content becomes executable after the browser re-parses it in the SVG or MathML namespace | Warns on `UnsafeRaw` inside `<svg>`, `<math>`, or `<foreignObject>`, and points at a namespace-aware sanitizer |
| OWASP XSS Prevention Rule #7 | Cross-ecosystem | `javascript:` URLs as a reflected XSS path | Compile-time hard error on static values, runtime neutralization on dynamic ones. React adopted the same block in v16.9 |

The `data:text/html` block is worth calling out separately. An allowlist that stops at `javascript:` and `vbscript:` leaves `data:text/html,<script>...</script>` as a working navigation payload, so the executable `data:` MIME types are blocked by the same code path.

## Dependency advisories

Proa's own code is one half of the surface. The other half is the dependency tree, audited against the [RustSec advisory database](https://rustsec.org/).

```bash filename="Terminal"
cargo audit --deny warnings
cargo deny check advisories bans sources licenses
```

The repository's `.cargo/audit.toml` and `deny.toml` record accepted
advisories with their dependency paths and justifications. Read those files and
fresh audit output rather than relying on a fixed advisory list in this guide.
Revisit exceptions when a parent dependency updates, and do not lower the
policy globally to make a new advisory pass.

## What the framework hardens

`FrameworkBuilder::build()` applies the same outer hardening to pages and endpoints:

| Default | Effect |
|---------|--------|
| Baseline response headers | `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`, set only when not already present |
| Cross-origin protection | Browser-issued cross-origin unsafe requests return `403` unless trusted |
| Body limit | Requests capped at 1 MiB unless overridden |
| Request timeout | Handlers must respond within 30 seconds by default |

Frame-policy overrides, HSTS, and Content Security Policy are opt-in, because each deployment needs its own. See [Headers and CSP](/docs/framework/security-headers).

Cross-origin protection follows the pattern Go 1.25 ships as `net/http`'s `CrossOriginProtection`. Rather than synchronizer tokens, it reads the `Sec-Fetch-Site` metadata header that every evergreen browser sends, with an `Origin`-versus-`Host` fallback for older clients. Safe methods always pass. A request carrying neither header passes, because it did not come from a browser and CSRF does not apply to it.

That is **not** a CSRF-token service. It rejects the shape of the request, not a forged token. [Cross-origin and CSRF](/docs/framework/cross-origin) explains the difference and what you still need to add.

## What stays yours

Proa gives you the attribute support these need, `nonce`, `integrity`, `http-equiv`, `sandbox`, `allow`, but the policy is yours:

- **CSRF tokens and sessions.** Configure issuance and validation in Axum middleware. Proa exposes request cookies and can stage `Set-Cookie` headers, but your application owns session management and cookie policy.
- **Input validation.** Do it before data reaches a template, not after.
- **Sanitizing user-authored HTML.** Use an allowlist sanitizer such as [ammonia](https://crates.io/crates/ammonia) before `UnsafeRaw`. Inside SVG or MathML, use a namespace-aware one.
- **Cookie attributes.** `HttpOnly`, `SameSite`, and `Secure` are server configuration.
- **Redirect targets.** There is no safe-redirect helper. Validate a user-supplied `next=` parameter against an allowlist yourself.
- **URL encoding query parameters.** Application logic.
- **Rate limiting.** Server middleware.

Two things no policy can rescue: inline event-handler attributes (`onclick="…"`) never execute under a nonce policy, and a raw `<script>` tag you write by hand needs an explicit `nonce` read from `cx.csp_nonce()`.

Pass browser-visible application data through typed RSJS props and signals. At an external JavaScript integration boundary, use correctly serialized, script-safe JSON in an inert payload and parse it explicitly. HTML escaping does not JSON-encode JavaScript strings. See [Escaping](/docs/core/escaping) for the data-attribute bridge.

## Reporting a vulnerability

Report privately through the **Security** tab of the repository on GitHub, using *Report a vulnerability*. That opens a private advisory visible only to you and the maintainers. Do not open a public issue with exploit details. See [`SECURITY.md`](https://github.com/proa-labs/proa/blob/main/SECURITY.md) for the supported surface and disclosure process.

## Next steps

- [Escaping and raw HTML](/docs/core/escaping)
  - How Proa encodes dynamic values, and the two ways to opt out.
- [Headers and CSP](/docs/framework/security-headers)
  - Set frame policy, HSTS, and a nonce-based Content Security Policy.
- [Cross-origin and CSRF](/docs/framework/cross-origin)
  - Reject forged cross-origin writes, and add the CSRF defense Proa does not.
- [Server-rendered content](/docs/rsjs/server-only)
  - Keep ordinary Rust values and renderables outside an RSJS client graph.
- [Environment variables](/docs/framework/environment)
  - Configure a deployed Proa app without rebuilding the binary.


---

# Docs: Escaping and raw HTML

URL: /docs/core/escaping
Description: How Proa encodes dynamic values, and the two ways to opt out.

---
title: Escaping and raw HTML
description: How Proa encodes dynamic values, and the two ways to opt out.
keywords: [StaticRaw, UnsafeRaw, raw HTML, XSS]
---

Proa's primary security job is output encoding: making sure a dynamic value cannot break out of its HTML context and execute. Every value in `html!` is escaped before it reaches the buffer, with no opt-in.

```rust filename="src/components/comment.rs"
let user_input = "<script>alert('xss')</script>";

html_sync! {
    <p>{user_input}</p>
}
// <p>&lt;script&gt;alert('xss')&lt;/script&gt;</p>
```

## Encoding contexts

Proa escapes per the [OWASP XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html), and the context decides the rule:

| Context | Characters escaped | OWASP rule |
|---------|-------------------|------------|
| Text content | `&`, `<`, `>`, U+00A0, U+0000 | #1 |
| Attribute values | `&`, `<`, `>`, `"`, `'`, U+00A0, U+0000 | #2 |
| `<script>` content | `&`, `<`, `>`, plus `</script`, `<script`, and `<!--` masked with `\` | Tag breakout |
| `<style>` content | `&`, `<`, `>`, plus `</style`, `<style`, and `<!--` masked with `\` | Tag breakout |

All attribute values are always double-quoted. There is no code path that emits an unquoted attribute.

## Dangerous URL schemes

`javascript:` and `vbscript:` execute arbitrary script when navigated to, and so do the executable `data:` types (`text/html`, `application/xhtml+xml`, `application/xml`, `image/svg+xml`). Proa blocks all of them in every URL-bearing attribute: `href`, `src`, `action`, `formaction`, `poster`, `ping`, `cite`, `data`, `background`, `longdesc`, `manifest`, and both spellings of `xlink:href`. The check runs during macro expansion and produces a compile error:

```rust filename="src/components/link.rs"
html_sync! {
    <a href="javascript:alert(1)">"Click me"</a>
}
// error: dangerous URL scheme in `href` attribute.
```

The comparison normalizes the value the way a browser does before parsing it, so the usual evasions fail too. ASCII whitespace and NUL are skipped throughout the scheme (not just at the leading edge), which catches `java&Tab;script:` and `\njavascript:`, and one pass of numeric character reference decoding runs first, which catches `&#106;avascript:alert(1)` and its zero-padded variants.

**Dynamic URLs get the same check at render time.** A compile-time error cannot see `href={user_supplied}`, so URL-bearing attributes route through a runtime guard using the identical normalization. In debug builds a dangerous value trips a `debug_assert!`; in release builds the attribute renders empty rather than dangerous.

That guard is a backstop, not a substitute for validation. It only recognizes executable schemes, so an open redirect or an attacker-chosen host still reaches the page. Validate user-controlled URLs in application code.

Related: when you write `<a target="_blank">`, add `rel="noopener noreferrer"` unless you deliberately want an opener relationship. Without it the opened page can redirect your original tab through `window.opener`, reverse tabnabbing. Modern browsers default to `noopener`, but being explicit preserves behaviour in older clients.

## Dynamic values inside script and style

Proa emits a compile-time warning when a dynamic expression appears inside `<script>` or `<style>`:

```rust filename="src/layouts/root.rs"
html_sync! {
    <script>
        {some_dynamic_value}  // warning: OWASP XSS: dynamic expr in script/style
    </script>
}
```

HTML escaping is **not sufficient** here. JavaScript and CSS are separate encoding contexts needing JS-specific and CSS-specific encoding, which an HTML engine does not provide.

For application browser behavior, pass typed props or query data to an [RSJS island](/docs/guides/islands). RSJS owns the server-to-browser serialization and generated handlers.

For an existing external script that expects a `data-*` bridge, serialize the configuration when constructing the view model, then let the template escape the attribute:

```rust filename="src/layouts/root.rs"
html_sync! {
    <div id="app" data-config={self.config_json.as_str()}></div>
}
```

The external script can parse the DOM attribute as JSON. Attribute escaping keeps the serialized value inside the attribute; it does not make the parsed values safe for arbitrary JavaScript, CSS, URLs, or HTML sinks.

## The two escape hatches

**`StaticRaw`** takes a compile-time constant. No user data can reach it at runtime, so it is inherently safe:

```rust filename="src/components/icon.rs"
use proa::StaticRaw;

StaticRaw("<svg viewBox='0 0 24 24'>...</svg>")
```

**`UnsafeRaw`** takes a dynamic string and escapes nothing. Use it only with content you have already sanitized:

```rust filename="src/pages/article.rs"
use proa::UnsafeRaw;

let sanitized = ammonia::clean(&user_html);
UnsafeRaw(&sanitized)
```

Never wrap request input, CMS strings, or user-authored Markdown in `UnsafeRaw` directly. Sanitize with an allowlist first, [ammonia](https://crates.io/crates/ammonia) on the server, [DOMPurify](https://github.com/cure53/DOMPurify) in the browser.

> **Good to know**: The typed `AttrKey` enum deliberately excludes event-handler attributes such as `onclick`. A nonce-based [Content Security Policy](https://www.w3.org/TR/CSP3/#directive-script-src) does not authorize inline event attributes. Prefer typed RSJS handlers; raw inline handler strings bypass that authoring model.

## Next steps

- [HTML rendering](/docs/core/html-rendering)
  - Render typed Rust values to HTML with render traits and the html! macros.
- [Security](/docs/guides/security)
  - What Proa hardens by default, and what stays your job.
- [Headers and CSP](/docs/framework/security-headers)
  - Set frame policy, HSTS, and a nonce-based Content Security Policy.
- [Writing performant pages](/docs/guides/performance)
  - How to write zero-allocation Proa pages that render in microseconds. Covers format!() avoidance, SafeText, ClassList, numeric rendering, buffer selection, and pre-formatting patterns.


---

# Docs: Headers and CSP

URL: /docs/framework/security-headers
Description: Set frame policy, HSTS, and a nonce-based Content Security Policy.

---
title: Headers and CSP
description: Set frame policy, HSTS, and a nonce-based Content Security Policy.
keywords: [CSP, Content-Security-Policy, nonce, HSTS]
---

Framework responses get baseline hardening headers automatically, including a `DENY` frame policy. HSTS and CSP are configured here but off by default, because each deployment needs its own.

```rust filename="src/main.rs"
use proa::axum::{FrameOptions, SecurityHeadersConfig};

let security = SecurityHeadersConfig::new()
    .with_frame_options(FrameOptions::SameOrigin)
    .with_hsts_max_age_secs(63_072_000);

let app = FrameworkBuilder::new()
    .with_security_headers(security)
    .build();
```

| Setting | Options |
|------|---------|
| `FrameOptions` | `Deny` (default), `SameOrigin`, `Disabled` |
| HSTS | Off by default. Enable only when TLS terminates before the app |
| CSP | Off by default. Each app needs its own script, style, image, and connect policy |

## Use a nonce, not a static policy

A static policy can authorize fixed inline scripts with hashes. Framework-generated scripts can contain response-specific state, so a fresh nonce per response is the convenient policy for RSJS islands, React islands, and out-of-order streaming:

```rust filename="src/main.rs"
let app = FrameworkBuilder::new()
    .with_strict_csp()
    .build();
```

That mints a 128-bit nonce per request and sends:

```text
base-uri 'self'; default-src 'self'; frame-ancestors 'none';
object-src 'none'; script-src 'nonce-…' 'strict-dynamic';
style-src 'self' 'unsafe-inline'
```

Directives are emitted in alphabetical order, so a captured header reads exactly like this.

Proa applies the same nonce to framework-emitted state, import-map, bootstrap, client-shell, and boundary-swap tags. So `script-src` needs no `'unsafe-inline'` and no host allowlist.

Pairing the nonce with `'strict-dynamic'` means a script loaded by an already-trusted script inherits trust. That is what makes bundler-emitted chunks work without enumerating CDN hosts.

Managed module tags registered with `cx.head_mut().module(...)` also receive the installed nonce automatically. Handwritten template tags need the explicit nonce described below.

**Two things the layer cannot do for you.** A raw `<script>` tag you write by hand needs an explicit `nonce` attribute, read from `cx.csp_nonce()` in a component or extracted with `Extension<CspNonce>` in a route handler (the layer stores the nonce in the request extensions). A nonce on a `<script>` does not authorize inline event-handler attributes (`onclick="…"`); use typed RSJS handlers for application behavior.

## Tuning directives

Customize with `CspPolicy`:

```rust filename="src/main.rs"
use proa::axum::CspPolicy;

let app = FrameworkBuilder::new()
    .with_csp_policy(
        CspPolicy::strict()
            .with_directive("img-src", "'self' data: https://cdn.example")
            .with_directive("connect-src", "'self' https://api.example")
            .report_only(true),
    )
    .build();
```

`report_only(true)` sends `Content-Security-Policy-Report-Only`, which is how to roll a strict policy onto a live app. Violations are reported but nothing is blocked. Switch it off once the report stream is clean.

Style policy is separate from script policy. The default keeps `style-src 'unsafe-inline'` because inline `style` attributes are common and cannot execute code. Tighten it to `'self'` once those styles live in classes.

## Conflicts the builder warns about

The layer never overwrites a `Content-Security-Policy` header a handler already set, so a single route can opt out of the global policy.

Two combinations produce a startup warning:

- **`with_strict_csp()` together with `with_security_headers(..with_content_security_policy(..))`.** The static policy wins and the nonce directives are dropped. Pick one.
- **`FrameOptions::SameOrigin` or `FrameOptions::Disabled` while CSP still sends `frame-ancestors 'none'`.** Relaxing `X-Frame-Options` for embedding does nothing if `frame-ancestors` still blocks framing. Replace the directive with one naming the allowed embedders.

## Next steps

- [Security](/docs/guides/security)
  - What Proa hardens by default, and what stays your job.
- [Cross-origin and CSRF](/docs/framework/cross-origin)
  - Reject forged cross-origin writes, and add the CSRF defense Proa does not.
- [App configuration](/docs/framework/configuration)
  - Configure FrameworkBuilder, security defaults, static mounts, and response behavior.
- [Escaping and raw HTML](/docs/core/escaping)
  - How Proa encodes dynamic values, and the two ways to opt out.


---

# Docs: Cross-origin and CSRF

URL: /docs/framework/cross-origin
Description: Reject forged cross-origin writes, and add the CSRF defense Proa does not.

---
title: Cross-origin and CSRF
description: Reject forged cross-origin writes, and add the CSRF defense Proa does not.
---

`FrameworkBuilder::build()` rejects browser-issued unsafe cross-origin requests, POST, PUT, PATCH, DELETE, before they reach a handler. They return `403`.

Safe methods pass. Non-browser clients pass. You do not turn this on.

```rust filename="src/main.rs"
let app = FrameworkBuilder::new()
    .with_trusted_origin("https://admin.example.com")
    .build();
```

Add a trusted origin when a browser on another origin legitimately needs to write to your app.

## What else is on by default

The same outer hardening applies to pages and endpoints alike:

| Default | Effect |
|---------|--------|
| Cross-origin protection | Browser-issued cross-origin unsafe requests return `403` unless trusted |
| Body limit | Requests capped at 1 MiB unless overridden |
| Request timeout | Handlers must respond within 30 seconds by default |
| Security headers | Framework responses get baseline hardening headers |

Raise the body limit deliberately, per route, when a handler accepts file uploads. A global raise removes the protection everywhere.

## This is not a CSRF-token service

The distinction matters and it is easy to miss.

Cross-origin protection rejects a request based on **its shape**, the method and the originating origin. A CSRF token proves the request came from **a form your app rendered**, to a user you authenticated.

| Attack | Blocked by origin checks? |
|---|---|
| A form on `evil.example` POSTs to your app | Yes |
| A `fetch()` from another origin issues a DELETE | Yes |
| A replayed request with a stolen session cookie | **No** |
| A forged request from a same-origin XSS foothold | **No** |

If you migrated from Rails or Django, this is the gap where `csrf_meta_tags` and `{% csrf_token %}` used to sit. Proa does not issue or validate tokens. Configure that in Axum middleware, and keep the token check on every unsafe browser-issued method.

For browser-facing mutations, keep using same-origin forms or same-origin `fetch`. For cross-origin API clients, configure trusted origins deliberately, or mount a separately configured Axum router outside the framework builder.

> **Good to know**: Disable the layer only for a router that implements an equivalent defense. Turning it off to fix a `403` during development usually means an origin needs adding, not that the layer is wrong.

## Next steps

- [Security](/docs/guides/security)
  - What Proa hardens by default, and what stays your job.
- [Headers and CSP](/docs/framework/security-headers)
  - Set frame policy, HSTS, and a nonce-based Content Security Policy.
- [Forms and actions](/docs/guides/forms-actions)
  - Build HTML forms, handle submissions with Axum, and attach typed actions.
- [Route handlers](/docs/framework/route-handlers)
  - Build JSON, form, and webhook endpoints with Route::endpoint.
- [From Rails](/docs/migration/rails)
  - Migrate from Rails ERB templates to Proa, run Proa as a rendering service alongside your Rails app.


---

# Docs: Testing

URL: /docs/guides/testing
Description: Test application behavior and framework regressions without pinning page markup.

---
title: Testing
description: Test application behavior and framework regressions without pinning page markup.
---

Write a test when it protects a behavior that can break independently of an
intentional design or copy change. A component does not need a test merely
because it renders HTML or Markdown.

## Writing unit tests

Keep focused tests for calculations, validation, state transitions, authorization,
and error handling. Exercise different inputs and failure paths. A useful test
should explain what unintended consequence it prevents.

Avoid assertions that repeat the template: headings, footer links, CSS classes,
icon counts, section order, or the presence of a component's own `data-*` marker.
Changing those intentionally should not require editing another copy of the page
inside a test.

Proa's compiler, linter, and renderer tests cover generic template behavior,
escaping, and composition. Application components using those APIs do not need
their own copies of the same tests. Test application-specific handling of
untrusted input when it adds behavior beyond the renderer's guarantees.

## Integration tests

Test boundaries that combine independently changing systems: authentication and
data access, request-scoped loader deduplication, cache invalidation, content
negotiation, HTTP errors, or serving linked browser assets. Prefer a few tests
that exercise complete behavior over a separate render test for every route.

For ordinary library unit tests:

```bash filename="Terminal"
cargo test --lib
```

Application binaries and integration tests that link RSJS islands need the
linked pipeline. Name the relevant target:

```bash filename="Terminal"
proa test -p my_app --test integration
```

A plain `cargo test` integration binary that links RSJS islands fails at link
time because it lacks the compiled JavaScript modules. Library unit tests under
`#[cfg(test)]` are unaffected.

## Writing snapshot tests

Full-page HTML snapshots change whenever the page changes. Do not add them by
default, or build normalization machinery just to keep a changing page snapshot
passing. Use exact-output assertions when the bytes themselves are a stable
contract, such as a serializer or protocol encoder.

## Testing in a browser

Review presentation changes in a browser at the relevant screen sizes. Use
browser automation when it protects a specific workflow, keyboard interaction,
or accessibility behavior that simpler checks cannot exercise. A screenshot or
DOM assertion for every component adds maintenance without necessarily catching
an unintended consequence.

## Catching performance regressions

Measure render and streaming performance with the relevant benchmark on stable
hardware. Keep inputs and workload sizes comparable across runs. A successful
benchmark compilation does not establish that performance stayed the same.

```bash filename="Terminal"
cargo bench -p proa_bench
```

## Organizing tests and CI

Keep unit tests beside the logic they exercise and integration tests under
`tests/`. Add test targets as needed; there is no required suite per component or
page. Group related integration cases when separate linked test binaries would
repeat expensive builds.

Run formatting and Proa's source checks alongside the relevant behavior tests:

```bash filename="Terminal"
cargo fmt --all -- --check
proa check
```

See [CI / GitHub Actions](/docs/guides/ci) for the pinned CLI setup and linked
application build commands.


---

# Docs: Writing performant pages

URL: /docs/guides/performance
Description: Avoid intermediate allocations with direct-buffer text, class composition, numeric rendering, and reusable buffers.

---
title: Writing performant pages
description: Avoid intermediate allocations with direct-buffer text, class composition, numeric rendering, and reusable buffers.
---

Proa's `html!` macro compiles static markup to byte literals at build time. At request time, only dynamic values are rendered. This guide covers how to keep the dynamic path fast.

The core principle: **write authored output directly into the destination buffer instead of building temporary strings.** Use `WebRenderSync` and `html_sync!` by default; the same techniques apply to `WebRender` and `html!` when async work is required.

This describes the template-writing path. Request contexts, loaders, managed metadata preparation, and response ownership have their own costs. Measure the complete request when evaluating an application; eliminating an intermediate formatting string does not make every request allocation-free.

## Avoid format!()

`format!()` allocates a `String` on every call. In a render path that runs hundreds of thousands of times per second, this is the single most common performance mistake.

### In text content, use inline segments

Instead of `format!()`, place string literals and expressions side by side. Each segment writes directly to the output buffer with zero allocation:

```rust
// Bad: allocates a String every render
html! {
    <p>{format!("${} / night", price)}</p>
}
html! {
    <p>{format!("Hello, {}!", name)}</p>
}

// Good: inline segments — zero allocation
html! {
    <p>"$"{price}" / night"</p>
}
html! {
    <p>"Hello, "{name}"!"</p>
}
```

How it works: `"$"` compiles into the static byte run (no runtime formatting), `{price}` renders the integer directly via `itoa_lut` (no `.to_string()`), and `" / night"` compiles into the next static byte run. No intermediate `String` is ever created.

More examples:

```rust
// Bad
html! {
    <span>{format!("{} items in cart", count)}</span>
}
html! {
    <title>{format!("{} - MyApp", page_title)}</title>
}

// Good
html! {
    <span>{count}" items in cart"</span>
}
html! {
    <title>{page_title}" - MyApp"</title>
}
```

### In attributes, use typed values

Use `text!` for formatted text attributes. It writes directly to the output buffer:

```rust
html_sync! {
    <button title={text!("Add {} items", count)}>"Add"</button>
}
```

For URL attributes, use a prepared URL or `cx.url(path)` for explicit application-base-path composition. Placeholder-bearing `text!` is rejected in URLs. Keep resource paths in your data rather than constructing a temporary URL during rendering:

```rust
// Bad: allocates a String every render
html! {
    <img src={format!("/images/{}.webp", product.slug)} />
}

// Good: pre-compute in your data
struct Product {
    image_path: &'static str,  // "/images/alphafly-3.webp"
}

html! {
    <img src={product.image_path} />
}
```

If a dynamic URL needs an owned string, construct it in the handler or view model and move the `String` into the deferred response component. Borrow `as_str()` while rendering it; a borrow of a handler-local string cannot outlive that handler. Computing it on every request still has a per-request cost. See [Linking](/docs/framework/linking) for `cx.url(...)` and mounted paths.

## SafeText

`SafeText<'a>` wraps a `&str` and skips HTML escape scanning. Use it when you know the string contains no HTML-unsafe characters (`<`, `>`, `&`, `"`, `'`).

```rust
use proa::SafeText;
use proa::safe_text;

// Compile-time verified literal
safe_text!("Hello world")

// Runtime: a label whose allowed characters were validated before rendering
SafeText::from_trusted(validated_label)
```

`SafeText` copies verified text directly into the output buffer. Regular `&str` rendering scans every byte with `memchr3` looking for unsafe characters. For strings with a proven safe character set, `SafeText` eliminates that scan. A value is not trusted merely because it came from a database; keep ordinary escaped strings as the default.

**When NOT to use it:** Never wrap user input in `SafeText`. If the string could contain `<script>`, you've created an XSS vulnerability.

## ClassList

`ClassList<N>` composes CSS classes without string concatenation or allocation. All construction methods except `add_opt` are `const fn`.

```rust
use proa::ClassList;

// Compile-time class composition
const fn button_classes(primary: bool) -> ClassList<3> {
    ClassList::new()
        .add("inline-flex items-center rounded-lg px-4 py-2 text-sm font-medium")
        .add_if(primary, "bg-blue-600 text-white")
        .add_if(!primary, "bg-gray-100 text-gray-900")
}

// In your component
html! {
    <button class={button_classes(self.primary)}>{self.label}</button>
}
```

Available methods:
- `add(class)` - always add (const)
- `add_if(condition, class)` - conditional (const)
- `add_non_empty(class)` - skip empty strings (const)
- `add_opt(class)` - `Option<&'static str>` (runtime)

`ClassList` renders by writing each segment directly to the buffer with space separators. No intermediate string is ever built.

## Numeric rendering

Primitive numeric types implement Proa's render traits directly. Integers use a lookup-table algorithm (`itoa_lut`) that formats digits in pairs. Floats use `zmij`, which produces the shortest round-trip representation with Ryu-style exponent spelling. Both write directly to the output buffer.

```rust
// Good: direct numeric rendering, zero allocation
html! {
    <span>{product.price_cents / 100}</span>
    <span>{product.rating}</span>
}

// Bad: format!() for number formatting
html! {
    <span>{format!("${}", product.price_cents / 100)}</span>
}
```

For formatted prices, `text!` writes the currency marker and numeric formatting directly:

```rust
html_sync! {
    <span>{text!("${}.{:02}", price_cents / 100, price_cents % 100)}</span>
}
```

This example uses nonnegative integer cents. For locale-specific currency rules, prepare a display value using the application's formatter.

## Pre-formatting pattern

When your data has values that need formatting, do it once at initialization, not per render.

```rust
// Bad: formats on every render
struct Product {
    price_cents: u32,
    color_hex: &'static str,
}

// In render:
html! {
    <span>{format!("${}", self.price_cents / 100)}</span>
    <div style={format!("background-color:{}", self.color_hex)} />
}

// Good: pre-formatted in static data
struct Product {
    price: &'static str,           // "$205"
    color_style: &'static str,     // "background-color:#26292B"
    image_path: &'static str,      // "/images/air-jordan-14.webp"
    color_count: &'static str,     // "3 Colors"
}

// In render: zero allocation
html! {
    <span>{SafeText::from_trusted(self.price)}</span>
    <div style={SafeText::from_trusted(self.color_style)} />
}
```

The footwear showcase uses preformatted display data. Timing depends on the fixture, build, machine, and buffer ownership; use a pinned benchmark and verify output before comparing results.

## Static consolidation

The `html!` macro automatically merges consecutive static content into single byte literals at compile time. Understand this to write templates that maximize static runs.

```rust
// This entire template is one static byte literal at compile time:
html! {
    <div class="flex items-center gap-4">
        <h1>"Product title"</h1>
        <span class="text-sm text-gray-500">"In stock"</span>
    </div>
}
// Generated: static BYTES: &[u8] = b"<div class=\"flex items-center gap-4\">..."
// Render cost: one memcpy

// Dynamic values break static runs:
html! {
    <div class="flex items-center gap-4">
        <h1>{self.title}</h1>                    // breaks here
        <span class="text-sm text-gray-500">
            {self.stock_label}                    // breaks here
        </span>
    </div>
}
// Generated: 3 static byte literals + 2 dynamic renders
// Still fast, but more work than fully static
```

**Tips for maximizing static runs:**
- Put dynamic values at the leaves, not in wrapper elements
- Use pre-computed strings (SafeText) for values that rarely change
- Static attribute values are consolidated; dynamic ones break the run

## Choosing a buffer

Proa supports multiple buffer types. Most applications should use one of the
standard targets so the compiler does not repeatedly monomorphize the same
component tree for many buffer shapes.

| Buffer | Best for | Allocation |
|--------|----------|------------|
| `RenderBuffer` | Production servers, tests, app-owned buffered renders | 4 KB pages recycled across renders |
| `ZeroCopyBuf` | Custom scatter-gather transport experiments | Static bytes are referenced, dynamic bytes are owned |
| `StreamingZeroCopyBuf` | Streaming responses | Segmented output with flush checkpoints |

Specialized writer variants, contiguous byte-vector buffers, and custom page
sizes are benchmark tools or narrow adapter internals. Avoid copying them into
normal app code; production routes should not depend on guessing an output size.

**For production servers, use `RenderBuffer`:**

```rust
// Create once, reuse across requests
let mut buf = RenderBuffer::new();

// Per request:
buf.render_into(component);  // Clears first, then recycles pages as it renders
```

`RenderBuffer` grows by chaining 4 KB pages. When a page fills, it rotates to a new one. On `clear()`, pages are cached for reuse. Once its reusable capacity covers a workload, the buffer can avoid further page allocations. Components, context state, metadata, and transport finalization can still allocate independently. This low-level helper uses manual rendering and panics on render errors; use framework response helpers for managed documents.

## Attribute rendering

Proa fuses attribute names and delimiters into single static string slices at compile time.

```rust
// The macro generates:
cx.out.extend_static_str(" class=\"")?;  // single pointer, not 3 separate writes
value.render_attr_value(cx)?;
cx.out.extend_static_str("\"")?;
```

For attribute values you control, use `SafeAttr` to skip escape scanning:

```rust
use proa::SafeAttr;

html! {
    <div data-page={SafeAttr("product-detail")} />
}
```

## Loops and iteration

Use the standard Rust `for` pattern inside `html!`. Each iteration writes directly to the output buffer.

```rust
html! {
    <ul class="space-y-2">
        {for product in &self.products {
            html! {
                <li class="flex items-center gap-4">
                    <img src={product.image_path} />
                    <span>{SafeText::from_trusted(product.title)}</span>
                    <span>{SafeText::from_trusted(product.price)}</span>
                </li>
            }
        }}
    </ul>
}
```

**Do not** collect into a `Vec<String>` and then render. Each iteration should write directly.

The macro renders the loop body's final expression automatically. Leave off the
semicolon and `.render(cx)?`; explicit rendering is still needed in ordinary
Rust code outside a template slot.

## Compile-time performance hints

Proa's `html!` macro detects common allocation patterns at compile time and emits compiler warnings. These don't block compilation, they surface mistakes before they reach production.

### What gets flagged

| Pattern | Why | Fix |
|---------|-----|-----|
| `format!()` in `html!` | Allocates a `String` every render | Inline segments for text, pre-compute for attrs |
| `.to_string()` | Unnecessary allocation, primitives render directly | Remove the call: `{count}` not `{count.to_string()}` |
| `.to_owned()` | Clones a `&str` into a `String` for no reason | Use the `&str` directly |
| `String::from()` | Same as above | Use a string literal or `&str` |
| `.join()` | Collects into a `String` | Use a template `for` loop with a renderable final expression |
| `.collect()` | Allocates a `Vec` then iterates | Iterate the original iterator directly |
| `vec![...]` | Heap-allocates a `Vec` | Use `&[...]` (a stack-allocated slice) |
| `{"literal"}` | String literal in braces gets runtime-escaped | Use `"literal"` as a text node (compile-time escaped) |

### Example warnings

```rust
// This produces a compiler warning:
html! {
    <p>{format!("${} / night", price)}</p>
}
```

The hint surfaces as a rustc warning anchored to the offending expression:

```
warning: unused `_perf_format__inside_html_allocates_a_String_on_every_render_0` that must be used
  --> src/pages/room.rs:24:17
   |
   = note: perf: format!() inside html! allocates a String on every render.
           for text content, use inline segments: "$"{price}" / night" — for
           attributes, pre-compute the value before rendering
           (docs/guides/performance). Wrap in perf_ok() to suppress if
           intentional
```

### Silencing a hint with `perf_ok()`

When you intentionally allocate in the render path, wrap the expression in `perf_ok()` to suppress the warning:

```rust
use proa::perf_ok;

// Flagged:
html! {
    <span>{format!("${}", price)}</span>
}

// Silenced — you've acknowledged the allocation:
html! {
    <span>{perf_ok(format!("${}", price))}</span>
}
```

`perf_ok()` is an `#[inline(always)]` identity function, it returns its argument unchanged and compiles away to nothing. It exists only as a signal to the scanner (and to code reviewers) that the allocation is intentional.

**When to use it:**
- Prototyping where speed of development matters more than render performance
- Rare code paths (error pages, admin panels) where allocation cost is negligible
- Complex formatting that can't be pre-computed (e.g., locale-dependent number formatting)

**When NOT to use it:**
- Hot paths (product listings, search results, home pages), pre-compute instead
- Inside `for` loops, N allocations per render, compose typed children directly instead

### Disabling all hints

To disable performance hints project-wide (e.g., during early prototyping):

```toml
[dependencies]
proa = { version = "0.4", features = ["no-perf-hints"] }
```

Remove the feature flag when you're ready to optimize.

## Summary of rules

1. **Avoid temporary formatting strings.** Use plain slots, adjacent text, or `text!` for text and non-URL attributes. Prepare URLs explicitly.
2. **Keep escaping as the default.** Use `SafeText` only for a proven safe character set.
3. **Use `ClassList`** for CSS class composition. It's `const fn` and zero-allocation.
4. **Prepare reusable display data once** where practical. Retain typed numeric values when direct formatting is enough.
5. **Use `RenderBuffer`** in production for buffer reuse across requests.
6. **Maximize static runs** by keeping dynamic values at the leaves of your template.
7. **Never allocate in a loop.** Each iteration should write directly to the output buffer.
8. **Use `perf_ok()`** to silence hints on intentional allocations, not to ignore them.

## Reading the benchmark results

The [current benchmark evidence](https://github.com/Proa-Labs/framework-benchmarks)
separates renderer-only time, complete HTTP responses, streaming, and cold start.
The November 11, 2026 Proa refresh measured commit `bbbc968` on Apple M4 Max;
peer render, HTTP, and cold-start rows retain their October 21 captures.

The renderer-only Proa lane allocates a fresh owned `RenderBuffer` for each
response and keeps that buffer. It does not include flattening it into a
`String`. HTTP captures add the server's request and response path. Streaming
response-end timings need another distinction: Proa sends resolved HTML, while
SvelteKit sends promised data that the browser still has to render. Consult the
[browser-completion results](https://github.com/Proa-Labs/framework-benchmarks/blob/main/sveltekit.md#browser-completion)
when comparing that end-to-end work.

Choose the boundary your application uses and measure it with your own data,
output ownership, host, and request load. The published timings describe the
recorded captures rather than every Proa application.


---

# Docs: Accessibility

URL: /docs/guides/accessibility
Description: How Proa catches common WCAG, WAI-ARIA, and ARIA-in-HTML issues at compile time.

---
title: Accessibility
description: How Proa catches common WCAG, WAI-ARIA, and ARIA-in-HTML issues at compile time.
---

`html_sync!` and `html!` check accessibility rules visible in the authored template at compile time. Invalid roles and required attributes can fail compilation; other findings are warnings. Use `proa check` in CI and browser checks for behavior that static templates cannot prove.

## What Proa Checks

Proa checks a subset of rules from three specifications:

- [WCAG 2.2](https://www.w3.org/TR/WCAG22/), Web Content Accessibility Guidelines (Level A and AA)
- [WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/), Accessible Rich Internet Applications
- [ARIA in HTML](https://www.w3.org/TR/html-aria/), Rules for which ARIA roles and attributes are valid on which HTML elements

### Text Alternatives (WCAG 1.1.1)

Every non-text content element needs a text alternative for screen readers.

```rust
// Warning: <img> without alt
html! {
    <img src="/photo.jpg" />
}
//       ^^^^ missing `alt` attribute — screen readers cannot describe this image.
//            Use alt="description" or alt="" for decorative images.

// OK: descriptive alt
html! {
    <img src="/photo.jpg" alt="Team photo from the company retreat" />
}

// OK: decorative image (empty alt)
html! {
    <img src="/divider.svg" alt="" />
}
```

This also applies to `<input type="image">` (must have `alt`) and `<area>` with `href` (must have `alt`).

### ARIA Role Validation

The `role` attribute must be one of the 82 roles defined in WAI-ARIA 1.2. Abstract roles (like `widget`, `landmark`, `structure`) cannot be used directly.

```rust
// Error: invalid role
html! {
    <div role="buttn">"Click"</div>
}
//                 ^^^^^^ "buttn" is not a valid ARIA role. Did you mean "button"?

// Error: abstract role
html! {
    <div role="widget">"Click"</div>
}
//                 ^^^^^^^ "widget" is an abstract role and cannot be used in content.
//                          Use a concrete role like "button", "checkbox", or "slider".
```

### Required ARIA Attributes

Some roles require specific ARIA attributes to function correctly with assistive technology:

```rust
// Error: role="checkbox" requires aria-checked
html! {
    <div role="checkbox">"Accept terms"</div>
}
//       ^^^^ role="checkbox" requires the `aria-checked` attribute.
//            Add aria-checked="true", aria-checked="false", or aria-checked="mixed".

// OK
html! {
    <div role="checkbox" aria_checked="false">"Accept terms"</div>
}
```

| Role | Required attribute(s) |
|------|-----------------------|
| `checkbox` | `aria-checked` |
| `combobox` | `aria-controls`, `aria-expanded` |
| `heading` | `aria-level` |
| `menuitemcheckbox` | `aria-checked` |
| `menuitemradio` | `aria-checked` |
| `meter` | `aria-valuenow` |
| `option` | `aria-selected` |
| `radio` | `aria-checked` |
| `scrollbar` | `aria-valuenow` |
| `separator` (with `tabindex`) | `aria-valuenow` |
| `slider` | `aria-valuenow` |
| `spinbutton` | `aria-valuenow` |
| `switch` | `aria-checked` |

### ARIA Attribute Validation

ARIA attribute names must be ones the macro recognizes (the 48 defined in WAI-ARIA 1.2, plus the newer braille and description attributes), and enumerated values must be valid:

```rust
// Error: not a real ARIA attribute
html! {
    <div aria_labeledby="title">"content"</div>
}
//            ^^^^^^^^^^^^^^^ "aria-labeledby" is not a valid ARIA attribute.
//                             Did you mean "aria-labelledby"?

// Error: invalid value
html! {
    <div aria_hidden="yes">"content"</div>
}
//                        ^^^^ "yes" is not a valid value for aria-hidden.
//                              Use "true" or "false".
```

### Redundant Roles

HTML elements have implicit ARIA roles. Adding an explicit role that matches is unnecessary noise:

```rust
// Warning: redundant role
html! {
    <button role="button">"Save"</button>
}
//               ^^^^^^^^^^^^^ <button> already has an implicit role of "button".
//                              Remove the role attribute.

// Warning: prefer native element
html! {
    <div role="button" tabindex="0">"Save"</div>
}
//            ^^^^^^^^^^^^^ prefer <button> over <div role="button"> —
//                           native elements provide keyboard support and
//                           accessibility semantics for free.
```

### Tabindex

Positive `tabindex` values disrupt the natural tab order and are almost always wrong:

```rust
// Warning: positive tabindex
html! {
    <input tabindex="5" />
}
//              ^^^^^^^^^^^^^ tabindex="5" overrides the natural document tab order.
//                            Use tabindex="0" to add to natural order, or
//                            tabindex="-1" for programmatic focus only.
```

### Language

Screen readers use the `lang` attribute to determine pronunciation rules:

```rust
// Warning: <html> without lang
html! {
    <html>
        <head>
            <title>"My Page"</title>
        </head>
    </html>
}
// ^^^^^ <html> should have a `lang` attribute (e.g., lang="en").
//       Screen readers use this to select the correct pronunciation rules.
```

## What Proa Cannot Check

These accessibility requirements depend on runtime behavior, computed CSS, or cross-component context that the `html!` macro can't see:

| Concern | Why | What to use |
|---------|-----|-------------|
| Color contrast ratios | Requires computed CSS styles | [axe-core](https://github.com/dequelabs/axe-core), [Lighthouse](https://developer.chrome.com/docs/lighthouse/accessibility/) |
| Keyboard navigation | Requires runtime focus testing | Manual testing, axe-core |
| Focus order | Requires runtime DOM | axe-core |
| Focus visibility | Requires CSS + runtime | Browser DevTools |
| Screen reader announcements | Requires assistive technology | [NVDA](https://www.nvaccess.org/), [VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac) |
| Dynamic ARIA state changes | Requires runtime JS | axe-core |
| Cross-component nesting | Fragments composed at different call sites | [Nu HTML Checker](https://validator.w3.org/nu/) |

Proa's compile-time checks cover what's visible in the HTML output. For the full picture, pair them with axe-core in your integration tests:

```typescript
// Example: axe-core in Playwright
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test("home page is accessible", async ({ page }) => {
  await page.goto("/");
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});
```

## Standards Reference

| Standard | What it covers | Link |
|----------|---------------|------|
| WCAG 2.2 | Success criteria for accessible web content (A, AA, AAA) | [w3.org/TR/WCAG22](https://www.w3.org/TR/WCAG22/) |
| WAI-ARIA 1.2 | Roles, states, and properties for rich UI widgets | [w3.org/TR/wai-aria-1.2](https://www.w3.org/TR/wai-aria-1.2/) |
| ARIA in HTML | Which ARIA is valid on which HTML elements | [w3.org/TR/html-aria](https://www.w3.org/TR/html-aria/) |
| HTML-AAM | How HTML maps to platform accessibility APIs | [w3.org/TR/html-aam-1.0](https://www.w3.org/TR/html-aam-1.0/) |
| Section 508 | US federal accessibility law (references WCAG 2.0 AA) | [section508.gov](https://www.section508.gov/) |
| EN 301 549 | EU accessibility standard (references WCAG 2.1 AA) | [etsi.org](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/) |


---

# Docs: Deploy

URL: /docs/framework/deployment
Description: Pick a deployment target, then follow the guide for it.

---
title: Deploy
description: Pick a deployment target, then follow the guide for it.
---

Proa builds one release binary plus a `public/` directory. Every target below runs that same artifact, usually as a Docker image. The choice is not about Proa. It is about how much of the platform you want to operate yourself.

## Pick a target

| | **Railway** | **Coolify** | **Docker, self-managed** |
|---|---|---|---|
| Who owns the machine | Railway | You, one VPS | You |
| Who compiles Rust | Railway | Your VPS, or GitHub Actions | You |
| Preview URL per pull request | One toggle, domains auto-provisioned, deleted on merge | Yes: wildcard DNS + GitHub App + URL template | Build it yourself |
| TLS certificates | Automatic | Automatic | Caddy or nginx, renewal yours |
| Zero-downtime swap | Health-check gated | Health-check gated | Yours |
| Rollback | One click | One click | Retag and restart |
| Secrets | Service variables | App env + BuildKit secrets | Yours |
| Logs and metrics | Built in | Built in | Ship them yourself |
| Beside an existing Rails or Django app | Awkward | Possible | Native, this is the sidecar shape |
| Floor cost | Usage-based | One VPS | One VPS |
| Escape hatch | It is your Dockerfile | It is your Dockerfile | You are already there |

**Start with [Railway](/docs/framework/railway)** unless you have a reason not to. Rust release builds are heavy, and Railway runs them for you. Coolify source builds run on your own VPS, which is why the [Coolify guide](/docs/framework/coolify) recommends building in GitHub Actions and deploying a prebuilt image instead.

**Choose [Coolify](/docs/framework/coolify)** when you want a fixed monthly bill, data residency on hardware you control, or several apps sharing one box.

**Choose [Docker](/docs/framework/docker)** when you are running Proa as a sidecar next to an existing app, deploying into Kubernetes, Nomad, or ECS, or working somewhere a PaaS is not an option. Read the next section first.

## What self-managed Docker costs you

Plain Docker is the most flexible target and the most expensive one. Flexibility is not the tradeoff. Labour is.

A platform is roughly ten features in a trench coat. Take it away and you own all ten:

| You now build | Because otherwise |
|---|---|
| Reverse proxy and TLS renewal | Nothing terminates HTTPS |
| Zero-downtime container swap | Every deploy drops in-flight requests |
| Health-check gating before cutover | A broken build takes production with it |
| Rollback | Recovery means finding the previous image tag under pressure |
| Secret injection | Tokens end up in a `.env` on the box |
| Log shipping and retention | `docker logs` is your only forensics, until the container is removed |
| Metrics and alerting | You learn about outages from users |
| Restart-on-crash policy | One panic ends the deployment |
| Image garbage collection | The disk fills, quietly, around week six |
| Preview environments | Reviewers test on `main` |

None of these are hard. All of them are yours forever, and they are why a cheap VPS is rarely cheaper than a managed platform once your time is priced in.

Take Docker anyway when the alternative does not exist: the sidecar shape in the [Rails](/docs/migration/rails) and [Django / Flask](/docs/migration/python) migrations puts Proa on the same host as your existing app, routed by your existing proxy. No platform models that well.

## What every target needs

Whatever you pick, the app must:

- Read `PORT` from the environment. Never hardcode it.
- Bind `0.0.0.0`, or `::` for dual-stack traffic, including legacy IPv6-only private networks.
- Serve static assets from `public/` beside the binary (the generated server reads them relative to its working directory).
- Answer `200` on a cheap `/healthz`, with dependency checks on a separate `/readyz`.

Verify these before you deploy anywhere:

```bash
docker run --rm -p 127.0.0.1:3000:3000 -e PORT=3000 my-site
curl -fsS http://127.0.0.1:3000/healthz
curl -fsS http://127.0.0.1:3000/static/styles.css -o /dev/null
```

Build a release binary with `proa build --locked --artifact-out <path>`, which runs the asset build and the linked RSJS pipeline (a plain `cargo build --release` skips the assets and fails at link time on any crate with islands). Public Proa dependencies resolve from crates.io without credentials. The exported binary and `public/` are the deployable artifact.

## Serving behind a URL path prefix

For a proxy that exposes `/apps/demo/` but strips `/apps/demo` before forwarding,
configure the public prefix at startup. Keep your incoming routes at `/`,
`/docs/start`, `/static/...`, and so on:

```rust filename="src/main.rs"
use proa::axum::{BasePath, FrameworkBuilder};

let base_path = BasePath::new(
    &std::env::var("PROA_BASE_PATH").unwrap_or_default(),
)?;
let app = FrameworkBuilder::new()
    .with_base_path(base_path) // <-- new: set the public URL prefix
    .with_rsjs_assets() // <-- new: serve assets with matching runtime imports
    .with_static_service(static_router)
    .with_dynamic_routes(router)
    .build();
```

Set `PROA_BASE_PATH=/apps/demo` when starting the binary. This value is read by
your startup code, so the same build can run at different prefixes. Empty or `/`
keeps origin-root URLs; a trailing slash is normalized away. The framework does
not infer the prefix from forwarded headers.

The APIs are also covered in
[FrameworkBuilder configuration](/docs/framework/configuration#frameworkbuilder-base-paths-and-rsjs-assets)
and [linked island asset serving](/docs/framework/static-assets#serving-linked-island-assets).

`with_rsjs_assets()` installs the linked runtime and generated module routes.
It rewrites runtime imports once at startup. Use it instead of registering your
own `/rsjs-runtime.js`, `/rsjs-runtime-query.js`, and `/rsjs/island/:file` handlers.
Runtime scripts, preloads, query runtime, dependency modules, and deferred island
loading use the same prefix, including islands arriving in streamed boundaries.
HTML responses remain streamed.

For a custom Axum router, merge `rsjs_assets_router(&base_path)` and apply
`RouteContextLayer::new(metadata).with_base_path(base_path)`. Custom
asset pipelines can retain their handlers and call
`rsjs::rewrite_runtime_import_specifiers` with the two public runtime URLs.
Non-Axum adapters can use
`proa::framework::response::append_rsjs_runtime_plan_with_base_path` and
`append_rsjs_runtime_plan_delta_with_base_path` to emit prefixed asset tags.

Application-authored links, forms, images, and redirects opt into URL composition:

```rust filename="src/components/nav.rs"
let start = cx.url("/docs/start");
let logo = cx.url("/static/logo.svg");
html_sync! {
    <nav>
        <a href={start}>"Start"</a>
        <img src={logo} />
    </nav>
}
.render(cx)
```

```rust filename="src/endpoints/redirect.rs"
use axum::response::Redirect;
use proa::axum::app_url;

async fn go_home() -> Redirect {
    Redirect::to(&app_url("/").to_string())
}
```

Pass unprefixed application paths to these helpers. `BasePath::url` produces an
attribute value without allocating an intermediate string. External URLs and
fragment/query-only references pass through. Treat URL input with the same
validation policy you would use without this helper.

The framework's CSS manifest URLs, React manifest URLs, and Markdown alternate
links also follow the configured prefix. The basic Axum site (including its
docs/blog shell), application scaffold, and ORIGIN template read `PROA_BASE_PATH`.

`proa_fonts::Font::head(cx)` uses the request prefix for both preload links and
the generated `@font-face` URLs. It writes CSS segments directly without
allocating a replacement stylesheet; the build-time font files stay unchanged.
Pass the page's context to `head`, rather than caching a rendered font fragment
from a context without the deployment setting.

`proa_docs::DocsShell` uses the request context for its brand, navigation,
section-menu, and pager links. For custom docs handlers, pass the deployment
mount to the adapter (the generated docs/blog handlers already do this):

```rust
proa_docs::adapter::axum::response_with_base_path(&DOCS, "/docs/start", &base_path)
```

The collection's build-time `.base_path("/docs")` remains its internal route.
Non-Axum callers can use `proa_docs::render_with_base_path`. ORIGIN serves linked
islands through the shared asset router and resolves its browser-side lab
request against the URL of its JavaScript module.

### Coverage and limitations

The same setting covers framework assets, fonts, opted-in query/mutation
requests (`cx.url(...)` or `FetchRequest.apply_base_path: true`), docs
navigation and article URL attributes, docs search artifacts, and the ORIGIN
starter. `proa dev` uses a prefixed same-origin event stream when
`PROA_BASE_PATH` is set, so the proxy only needs to expose the app's mount.
The relay accepts both stripped incoming paths and preserved paths when the
application router is nested under that prefix.

`with_static_service(...)` automatically composes recognized URL syntax in
CSS and JavaScript assets when a prefix is configured. This includes CSS
`url(...)`, `image-set(...)`, and `@import`, JavaScript module imports, and native browser `fetch`,
`Request`, `Worker`, `SharedWorker`, `EventSource`, and `WebSocket` URL arguments.
`new URL` arguments also follow the mount when their base is `import.meta.url`
or browser `location`/`location.href`/`location.origin`. Explicit external bases
stay unchanged. Dynamic native URL arguments are composed when evaluated. External URLs,
protocol-relative URLs, relative references, and already-mounted browser URLs
stay unchanged. Comments, ordinary strings, and locally shadowed browser API
names stay unchanged too.

```css
/* Served CSS: /fonts/icon.woff2 becomes /apps/demo/fonts/icon.woff2. */
@font-face { font-family: Icon; src: url(/fonts/icon.woff2); }
```

```javascript
// Served JS: fetches /apps/demo/api/items, including a dynamic URL argument.
const endpoint = "/api/items";
const response = await fetch(endpoint);
```

For handwritten browser code using a custom client library, compose its URL
explicitly with the helper exported by either linked runtime:

```javascript
import { app_url } from "/rsjs-runtime.js";

// The managed asset service prefixes the import above.
client.load(app_url("/api/items")); // /apps/demo/api/items
```

Custom static routers can use `base_path_assets(router, base_path)`; install
compression outside that router. Transformations are cached by content with a
bounded cache. GET and HEAD share the transformed length and ETag; conditional
requests validate those transformed bytes. CSS/JS assets are limited to 32 MiB.
Root deployments retain the original service without parsing or rewriting.

The recognized syntax is the contract. URLs in custom-library arguments,
inline scripts/styles, data files, or external third-party output need explicit
composition or their own pipeline. Subresource integrity hashes must match the
served, transformed bytes. Application templates use `cx.url(...)`;
trusted compiled raw HTML can use `proa::BasePathHtml`. Compiled docs
articles use it automatically for links, images/srcsets, forms, and other URL
attributes, while text and script/style contents remain unchanged.

For example, at `/apps/demo/docs/start`, `/static/styles.css` requests a file
outside the app. The helper generates `/apps/demo/static/styles.css`. Replacing
the URL with `./static/styles.css` would request
`/apps/demo/docs/static/styles.css`, so document-relative URLs are insufficient
for nested routes. The proxy should serve or redirect the mount root to its
trailing-slash form (`/apps/demo/`).

## Next steps

- [Railway](/docs/framework/railway)
  - Deploy a Proa app to Railway from a Dockerfile in about ten minutes.
- [Coolify](/docs/framework/coolify)
  - Deploy a Proa app to Coolify on your own VPS.
- [Docker](/docs/framework/docker)
  - Run the Proa image yourself, and own everything a platform would have done.
- [CI / GitHub Actions](/docs/guides/ci)
  - Gate pull requests with proa check, then deploy from the same pipeline.
- [Environment variables](/docs/framework/environment)
  - Configure a deployed Proa app without rebuilding the binary.
- [Page caching](/docs/framework/page-caching#cloudflare)
  - Cache public SSR pages at the edge and invalidate them after a deploy or content update.


---

# Docs: Railway

URL: /docs/framework/railway
Description: Deploy a Proa app to Railway from a Dockerfile in about ten minutes.

---
title: Railway
description: Deploy a Proa app to Railway from a Dockerfile in about ten minutes.
---

Railway builds your Dockerfile, injects a `PORT`, waits for a health check, then swaps traffic to the new container. Proa apps are ordinary Rust HTTP servers, so nothing about Proa needs special handling: compile the binary in a build stage, run it in a slim runtime stage.

Ten minutes from an existing project to a public URL.

## What Railway needs from your app

Three things. Everything else is default.

| Railway gives you | Your app must |
|---|---|
| A `PORT` environment variable | Read `PORT` at startup. Never hardcode it. |
| An HTTPS edge in front of your container | Bind `0.0.0.0` for public traffic or `::` for dual-stack traffic, never `127.0.0.1` |
| A health check before routing traffic | Return `200` on a cheap path such as `/healthz` |

Scaffolded Proa sites already do all three. If you are wiring a server by hand:

```rust filename="src/main.rs"
use std::net::SocketAddr;

let port: u16 = std::env::var("PORT")
    .ok()
    .map(|value| value.parse::<u16>())
    .transpose()?
    .unwrap_or(3000);

// Railway recommends [::] when the service needs both public and private
// networking. New environments are dual-stack; legacy private networks are
// IPv6-only.
let addr = SocketAddr::from(([0, 0, 0, 0, 0, 0, 0, 0], port));
let listener = tokio::net::TcpListener::bind(addr).await?;
proa::axum::serve(
        listener, app, std::time::Duration::from_secs(30),
    ).await?;
```

## Generate the Dockerfile

Proa's Railway preset writes the Dockerfile and the Railway config for you:

```bash
proa new site my-site --template marketing --deploy railway --tailwind --yes
cd my-site
```

That gives you:

```proa-filetree
Dockerfile
.dockerignore
railway.json
RAILWAY.md
src/main.rs
public/
```

If the generated Dockerfile's pinned binary archive is unavailable, use the
Cargo-based example below. For an existing scaffolded project, add it at the
root beside `proa.lock.json`.

## Adapt the Dockerfile

This Dockerfile reads the CLI version from your project's `proa.lock.json`,
compiles that pinned version from crates.io, and builds the app
through `proa build --locked --artifact-out`. The first CLI compilation takes
several minutes; Docker caches that layer separately from your application
source. The installer handles only Tailwind and verifies its standalone binary's
checksum. Proa dependencies resolve from crates.io without credentials.
Railway's cache mounts reuse downloaded crates and compiled dependencies:

```dockerfile filename="Dockerfile"
FROM rust:1.93-bookworm AS build
WORKDIR /app
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl git jq \
    && rm -rf /var/lib/apt/lists/*

COPY proa.lock.json /tmp/proa.lock.json
RUN --mount=type=cache,id=s/<service-id>-/usr/local/cargo/registry,target=/usr/local/cargo/registry \
    proa_version="$(jq -er '.scaffold.cliVersion' /tmp/proa.lock.json)" \
    && cargo install proa-cli --version "=$proa_version" --locked

# Install the checksum-verified standalone Tailwind CLI.
RUN curl --proto '=https' --tlsv1.2 -fsSL https://proa.so/install.sh \
    | sh -s -- --tailwind-only --to /usr/local/bin --no-modify-path --yes

COPY . .

RUN --mount=type=cache,id=s/<service-id>-/usr/local/cargo/registry,target=/usr/local/cargo/registry \
    --mount=type=cache,id=s/<service-id>-/app/target,target=/app/target \
    proa build --locked --artifact-out /app/my-site

FROM debian:bookworm-slim AS runtime
WORKDIR /app
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=build /app/my-site /usr/local/bin/my-site
COPY --from=build /app/public ./public

ENV PROA_HOST=::
ENV RUST_LOG=info

CMD ["my-site"]
```

The Railway-specific settings are:

- **Cache mounts** reuse Cargo's registry downloads and build output.
- **`PROA_HOST=::`** replaces `PROA_HOST=0.0.0.0`, so private networking works.
- **No `ENV PORT`, no `EXPOSE`.** Railway sets `PORT` and routes to it.

`--artifact-out /app/my-site` matters: cache mounts do not persist into the final layer, so the binary must land outside `/app/target`. The generated server serves `public/` relative to its working directory, so keep `WORKDIR /app` and copy `public/` beside the binary.

Replace every `<service-id>` placeholder with the service ID shown by
`railway status --json`.
Railway requires that literal `s/<service-id>-` cache-key prefix and does not
allow variables in cache-mount IDs.

Railway detects a file named `Dockerfile` at the repository root. For a nested
Dockerfile, set `dockerfilePath` in `railway.json` (or set
`RAILWAY_DOCKERFILE_PATH` in the dashboard).

## Add railway.json

Config as code keeps deploy settings in review instead of in a dashboard. The preset writes this file; `railway.toml` with the same keys also works:

```json filename="railway.json"
{
  "$schema": "https://railway.com/railway.schema.json",
  "deploy": {
    "healthcheckPath": "/readyz",
    "healthcheckTimeout": 120,
    "restartPolicyType": "ON_FAILURE"
  }
}
```

The generated site answers `/healthz` (liveness) and `/readyz` (readiness, which also checks the database when one is configured). Choose a health-check timeout that covers application startup and dependency readiness. This timeout starts after the image is built; increasing it does not extend the image-build deadline.

## Deploy

From the CLI:

```bash
pnpm add -g @railway/cli
railway login
railway link
railway up
```

Or connect the GitHub repository in the Railway dashboard and push. Railway builds on every commit to the linked branch.

Then open **Settings → Networking → Generate Domain** to get a public URL. Without this step the service runs but nothing reaches it.

Under **Variables**, add:

```dotenv
RUST_LOG=info
```

Do not set `PORT` or `PROA_HOST`. Railway manages `PORT`, and the Dockerfile sets `PROA_HOST`.

## Health checks

Railway polls `healthcheckPath` during deployment until it receives a successful `2xx` response, then switches traffic. It does not monitor that endpoint after activation. See [Railway healthchecks](https://docs.railway.com/deployments/healthchecks).

Keep the liveness route cheap:

```rust filename="src/main.rs"
async fn healthz() -> &'static str {
    "ok\n"
}
```

Checking your database here means a slow database fails your deploy. Put dependency checks on a separate `/readyz` route with `proa::axum::Readiness`, which probes fresh on every request and recovers without a restart.

Railway sends the `Host` header `healthcheck.railway.app`. If you add host filtering later, allowlist it.

> **Good to know**: To build an image once and promote it between environments, build and push it to a registry in CI, then deploy that image on Railway. Public Proa dependencies do not require a GitHub token for either build path.

## Verify before you deploy

```bash
docker build -t my-site .
docker run --rm -p 127.0.0.1:3000:3000 -e PORT=3000 my-site
curl -fsS http://127.0.0.1:3000/healthz
curl -fsS http://127.0.0.1:3000/static/styles.css -o /dev/null
```

## When it fails

| Symptom | Cause |
|---|---|
| Health check times out, logs look fine | App bound `127.0.0.1`, or ignored `PORT` |
| Build succeeds, service unreachable | No domain generated under Networking |
| Binary missing in runtime stage | `--artifact-out` pointed inside the cache-mounted `target/` |
| Another service cannot reach this one in a legacy environment | `PROA_HOST=0.0.0.0`; legacy IPv6-only private networking needs `::` |
| Every push rebuilds from scratch | Check the cache-mount IDs and paths, and exclude local `target/` output from the build context |

## Next steps

- [Deploy overview](/docs/framework/deployment)
  - Pick a deployment target, then follow the guide for it.
- [Environment variables](/docs/framework/environment)
  - Configure a deployed Proa app without rebuilding the binary.
- [CI / GitHub Actions](/docs/guides/ci)
  - Gate pull requests with proa check, then deploy from the same pipeline.
- [Coolify](/docs/framework/coolify)
  - Deploy a Proa app to Coolify on your own VPS.


---

# Docs: Coolify

URL: /docs/framework/coolify
Description: Deploy a Proa app to Coolify on your own VPS.

---
title: Coolify
description: Deploy a Proa app to Coolify on your own VPS.
---

A Proa app runs on Coolify as an ordinary Dockerized Rust HTTP server, and Coolify handles TLS, routing, rollbacks, and preview URLs. This page covers [scaffolding the project](#scaffolding-for-coolify), [building the image](#building-the-image), [setting runtime variables](#setting-runtime-variables), and [previewing pull requests](#previewing-pull-requests).

## Scaffolding for Coolify

Generate a site with the Coolify deployment preset:

```bash filename="Terminal"
proa new site my-site --template marketing --deploy coolify --tailwind --yes
cd my-site
```

The preset writes:

```proa-filetree filename="my-site/"
Dockerfile
.dockerignore
coolify.env.example
COOLIFY.md
README.md
src/main.rs
public/
```

The generated server reads `PROA_HOST`, `PORT`, and `RUST_LOG`, and serves `public/` relative to its working directory. The Dockerfile installs a pinned, checksum-verified Proa CLI, builds with `proa build --locked --artifact-out`, sets `PROA_HOST=0.0.0.0`, exposes port `3000`, and copies `public/` beside the binary. Public Proa dependencies resolve from crates.io without credentials.

Coolify needs matching application settings before it can build that image.

## Setting up the application

1. Push the generated project to GitHub.
2. In Coolify, create an Application from the repository.
3. Choose the Dockerfile build pack or Dockerfile deployment type.
4. Set the exposed port to `3000`.
5. Add runtime variables from `coolify.env.example`.
6. Set the health check path to `/healthz` for liveness. The generated `/readyz` also probes the database, so use it as the readiness check when one is configured.
7. Deploy.

## Building the image

Build the generated Dockerfile locally before deploying:

```bash filename="Terminal"
docker build -t my-site .
```

`proa build` runs the asset build and the linked RSJS pipeline; a plain `cargo build --release` would skip the assets and fail at link time on any crate with islands.

For a prebuilt-image deployment, use a GitHub Actions image pipeline:

1. Build the image in GitHub Actions.
2. Push the image to GHCR or another Docker registry.
3. Point Coolify at the prebuilt image.

This is the cleanest production shape because the VPS only needs permission to pull the final image.

Either path produces the same container, and that container reads its configuration from runtime variables.

## Setting runtime variables

Use these runtime variables in Coolify:

```dotenv filename="coolify.env.example"
PORT=3000
PROA_HOST=0.0.0.0
```

Add `RUST_LOG=info` if you want the log filter set from the environment; the generated file lists only the two the server needs.

Preview deployments read their own copy of these variables, so scope the sensitive ones before you turn previews on.

## Previewing pull requests

Coolify supports pull request preview deployments for GitHub repositories. Previews can:

- deploy automatically for new pull requests
- use a unique preview URL template
- post deployment status comments
- keep preview secrets separate from production secrets
- clean up after you merge or close the pull request

Use the GitHub App setup when possible. Automated comments require the GitHub App, and Coolify offers automated preview deployments only for GitHub App based repositories.

For preview domains:

1. Add a wildcard DNS record pointing to the Coolify server, such as `*.preview.example.com`.
2. In Coolify, enable Preview Deployments for the application.
3. Use a URL template such as `{{pr_id}}.preview.example.com`.
4. Keep production secrets in production-only variables.
5. Use preview-scoped variables for disposable databases, API sandboxes, and limited tokens.

Coolify's docs describe the full setup in [GitHub Preview Deploy](https://coolify.io/docs/applications/ci-cd/github/preview-deploy) and the general [Applications](https://coolify.io/docs/applications) settings page.

Every environment, preview or production, needs a route Coolify can poll for liveness.

## Checking health

Generated Axum sites include a cheap liveness route:

```bash filename="Terminal"
curl -fsS https://example.com/healthz
```

Use `/healthz` for Coolify's container health check. If the app needs database readiness, add a separate `/readyz` route and keep `/healthz` cheap.

Where that container gets built, on the VPS or in a pipeline, is the remaining decision.

## When to use prebuilt images?

Use a prebuilt image pipeline when:

- You want the VPS to need only registry pull access rather than source-repository access.
- Builds are too heavy for the production server.
- You need reproducible image promotion from staging to production.
- You want the same image digest in production and preview environments.

Use Coolify source builds when:

- The VPS has enough CPU and memory for Rust release builds.
- You prefer the simplest single-system workflow.

Either way, run the image locally once before you point Coolify at it.

## Verifying before you deploy

Before you deploy:

- `proa build`
- `docker build -t my-site .`
- `docker run --rm -p 127.0.0.1:3000:3000 -e PORT=3000 my-site`
- `curl -fsS http://127.0.0.1:3000/healthz`
- Verify `/static/styles.css` loads.

## Next steps

- [Deploy](/docs/framework/deployment)
  - Pick a deployment target, then follow the guide for it.
- [Environment variables](/docs/framework/environment)
  - Load runtime configuration, secrets, bind addresses, and static paths.
- [Docker](/docs/framework/docker)
  - Run the Proa image yourself, and own everything a platform would have done.
- [CI / GitHub Actions](/docs/guides/ci)
  - Gate pull requests with `proa check`, then deploy from the same pipeline.


---

# Docs: Docker

URL: /docs/framework/docker
Description: Run the Proa image yourself, and own everything a platform would have done.

---
title: Docker
description: Run the Proa image yourself, and own everything a platform would have done.
---

Proa produces one release binary and a `public/` directory. This page packages both into an image and runs it on hardware you control.

Read [what self-managed Docker costs you](/docs/framework/deployment) first. Take this path when you are running Proa beside an existing app, deploying into Kubernetes, Nomad, or ECS, or working somewhere a managed platform is not an option. For a plain public site, [Railway](/docs/framework/railway) or [Coolify](/docs/framework/coolify) does all of this for you.

## Build the image

Multi-stage: install the Proa CLI beside the Rust toolchain, build through the linked pipeline, run from a slim base. Proa dependencies resolve from crates.io without credentials. `proa new site --deploy docker` writes deployment files for you. If its pinned binary archive is unavailable, use the Cargo-based Dockerfile below. It reads the CLI version from the generated `proa.lock.json`, so the build stays pinned to your project's tooling without a version copied from these docs.

```dockerfile filename="Dockerfile"
# syntax=docker/dockerfile:1.7

FROM rust:1.93-bookworm AS build
WORKDIR /app
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl git jq \
    && rm -rf /var/lib/apt/lists/*

# Install the CLI version recorded when this project was scaffolded.
COPY proa.lock.json /tmp/proa.lock.json
RUN --mount=type=cache,target=/usr/local/cargo/registry \
    proa_version="$(jq -er '.scaffold.cliVersion' /tmp/proa.lock.json)" \
    && cargo install proa-cli --version "=$proa_version" --locked

# Install the checksum-verified standalone Tailwind CLI.
RUN curl --proto '=https' --tlsv1.2 -fsSL https://proa.so/install.sh \
    | sh -s -- --tailwind-only --to /usr/local/bin --no-modify-path --yes

COPY . .

RUN --mount=type=cache,target=/usr/local/cargo/registry \
    proa build --locked --artifact-out /tmp/proa-app

FROM debian:bookworm-slim AS runtime
WORKDIR /app
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl \
    && rm -rf /var/lib/apt/lists/*

COPY --from=build /tmp/proa-app /usr/local/bin/my-site
COPY --from=build /app/public ./public

ENV PROA_HOST=0.0.0.0
ENV PORT=3000
ENV RUST_LOG=info

EXPOSE 3000
CMD ["my-site"]
```

The first image build compiles your project's pinned CLI from crates.io, which takes several
minutes. Docker caches that installation layer separately from your application
source. The installer handles only Tailwind and verifies its standalone binary's
checksum. This source-build path also works with the Bookworm base images.

`proa build` runs the configured asset build and the linked RSJS pipeline, then copies the attested binary to `--artifact-out`. A plain `cargo build --release` skips the asset build and fails at link time on any crate with islands. The generated server reads `PROA_HOST` and `PORT` and serves `public/` relative to its working directory, which is why the runtime stage sets `WORKDIR /app` and copies `public/` beside it.

```bash
docker build -t my-site:$(git rev-parse --short HEAD) .
```

**Use commit-qualified tags or image digests**, and retain the previous image for rollback. Tags can be overwritten; a digest identifies the exact image.

Build in CI rather than on the production box. Rust release builds want CPU and RAM that your web server should be spending on requests.

## Run it

```yaml filename="compose.yaml"
services:
  web:
    image: ghcr.io/you/my-site:abc1234
    restart: unless-stopped
    environment:
      PROA_HOST: 0.0.0.0
      PORT: 3000
      RUST_LOG: info
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/healthz"]
      interval: 10s
      timeout: 2s
      retries: 3
      start_period: 5s
    ports:
      - "127.0.0.1:3000:3000"
```

Bind to `127.0.0.1:3000`, not `0.0.0.0:3000`. Publishing to all interfaces bypasses the host firewall on most Docker installs and exposes the app directly.

### Beside an existing app

This is the shape the [Rails](/docs/migration/rails) and [Django / Flask](/docs/migration/python) migrations describe: Proa renders the routes you have moved, your existing app serves the rest, and one proxy routes between them.

```yaml filename="compose.yaml"
services:
  legacy:
    image: ghcr.io/you/legacy-app:def5678
    expose: ["8000"]

  proa:
    image: ghcr.io/you/my-site:abc1234
    expose: ["3000"]
    environment:
      PORT: 3000

  proxy:
    image: caddy:2
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
```

```caddyfile filename="Caddyfile"
example.com {
    handle /rooms/* {
        reverse_proxy proa:3000
    }
    handle {
        reverse_proxy legacy:8000
    }
}
```

Move one path prefix at a time. The proxy config is the migration progress bar.

## TLS and the rest of the platform

Caddy handles certificates and renewal with no configuration, which is why it appears above. nginx works too, with certbot and a renewal timer you now maintain.

Either way, preserve forwarding headers or the app cannot see the real client:

```nginx filename="/etc/nginx/conf.d/my-site.conf"
proxy_set_header Host              $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP         $remote_addr;
```

Do not cache dynamic HTML at the proxy until you have route-level rules. See [Page caching](/docs/framework/page-caching).

Three more things a platform would have handled, in the order they bite:

- **Logs.** `docker logs` vanishes with the container. Ship to a collector before you need it, not after.
- **Disk.** Monitor image storage and prune with a retention policy that preserves the images you need for rollback.
- **Alerting.** A Compose healthcheck marks a container unhealthy; it does not restart it. The restart policy handles process exits. Add monitoring and a recovery policy for a process that stays running but stops responding. See [Docker restart policies](https://docs.docker.com/engine/containers/start-containers-automatically/).

## Ship a new version without downtime

When `docker compose up -d` recreates a single application container, it does
not provide a readiness-gated traffic swap. Use parallel containers and a proxy
cutover when that interruption is unacceptable.

Start the new version alongside, prove it healthy, then move traffic:

```bash
NEW=abc1234
docker run -d --name my-site-$NEW -p 127.0.0.1:3001:3000 \
  -e PORT=3000 -e PROA_HOST=0.0.0.0 ghcr.io/you/my-site:$NEW

healthy=false
for i in $(seq 30); do
  if curl --max-time 2 -fsS http://127.0.0.1:3001/healthz; then
    healthy=true
    break
  fi
  sleep 1
done
if [ "$healthy" != true ]; then
  docker rm -f "my-site-$NEW"
  echo "unhealthy, aborting"
  exit 1
fi

# flip the proxy upstream 3000 -> 3001, reload, then retire the old container
```

Rollback uses the same sequence with the previously retained image tag or digest.

For more than one host, this is the point where Kubernetes, Nomad, or ECS stops being overkill.

## Verify before you deploy

```bash
docker build -t my-site:test .
docker run --rm -p 127.0.0.1:3000:3000 -e PORT=3000 my-site:test
curl -fsS http://127.0.0.1:3000/healthz
curl -fsS http://127.0.0.1:3000/static/styles.css -o /dev/null
docker image inspect my-site:test --format '{{.Size}}'                  # inspect the final image size
```

Inspect the image size and layers to confirm that the runtime stage contains only the application, assets, and runtime dependencies.

## Next steps

- [Deploy overview](/docs/framework/deployment)
  - Pick a deployment target, then follow the guide for it.
- [Railway](/docs/framework/railway)
  - Deploy a Proa app to Railway from a Dockerfile in about ten minutes.
- [Coolify](/docs/framework/coolify)
  - Deploy a Proa app to Coolify on your own VPS.
- [Environment variables](/docs/framework/environment)
  - Configure a deployed Proa app without rebuilding the binary.
- [CI / GitHub Actions](/docs/guides/ci)
  - Gate pull requests with proa check, then deploy from the same pipeline.


---

# Docs: CI / GitHub Actions

URL: /docs/guides/ci
Description: Gate pull requests with proa check, then deploy from the same pipeline.

---
title: CI / GitHub Actions
description: Gate pull requests with proa check, then deploy from the same pipeline.
---

Use `proa check` as the default pull-request gate. It runs `proa fmt --check --verify` and `proa lint`, then fails on formatting differences, errors, or warnings. With explicit paths or Git-selected files it stays source-only; a whole-project `proa check` with no paths also runs the linked RSJS Cargo check.

Install a checksum-verified CLI binary before running the gate. There are two
download flows. The current prebuilt target is 64-bit Ubuntu 24.04+
(`x86_64-unknown-linux-gnu`); compile a pinned published version from crates.io
on other runners.

### Latest CLI From `main`

Inspect the exact commit-qualified snapshot and its available archives:

```bash
curl -fsSL https://proa.so/downloads/cli/main/latest.json | \
  jq '{version, commit, assets}'
```

Install whatever that JSON document currently names. Leave `PROA_VERSION`
unset so the installer resolves it from the main channel:

```bash
curl -fsSL https://proa.so/install.sh | \
  PROA_DOWNLOAD_BASE=https://proa.so/downloads/cli/main \
  PROA_PREBUILT_ONLY=1 \
  PROA_YES=1 sh
```

### A Specific Published CLI Version

The stable metadata names the current published version and every archive that
is available for it:

```bash
curl -fsSL https://proa.so/downloads/cli/latest.json | \
  jq '{version, assets}'
```

Choose a published version from that metadata or your release policy, then pin
it. Versioned stable routes remain available after `latest.json` advances:

```bash
PROA_CLI_VERSION="<published-version>"
curl -fsSL https://proa.so/install.sh | \
  PROA_VERSION="$PROA_CLI_VERSION" \
  PROA_PREBUILT_ONLY=1 \
  PROA_YES=1 sh
```

`PROA_PREBUILT_ONLY=1` makes missing metadata or archives fail immediately
instead of silently recompiling the workspace. Add
`$HOME/.proa/bin` to `PATH`, or set `PROA_INSTALL_DIR` in CI as shown below.

To build it from source instead:

```bash
PROA_CLI_VERSION="<published-version>"
cargo install proa-cli --version "=$PROA_CLI_VERSION" --locked
```

Then confirm CI can resolve the binary:

```bash
proa --help
```

## Minimal Gate

```bash
cargo fmt --all --check
proa test
proa check src
```

`cargo fmt` keeps Rust syntax stable. `proa test` runs the application suite through the linked pipeline, which is what the generated CI workflow does; a plain `cargo test` binary that links RSJS islands fails at link time by design (see [Testing](/docs/guides/testing)). In a workspace with several targets, name one with `-p my_app --bin my_app` or `--test <name>`. `proa check` keeps template macro bodies canonical and catches Proa-specific render, accessibility, composition, performance, and RSJS issues.

## GitHub Actions

Start with a full gate on every pull request. Create a repository or
organization variable named `PROA_CLI_VERSION` and set it to an already
published stable CLI version:

```yaml
name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install Proa CLI
        env:
          PROA_VERSION: ${{ vars.PROA_CLI_VERSION }}
          PROA_INSTALL_DIR: ${{ runner.temp }}/proa-bin
          PROA_NO_MODIFY_PATH: "1"
          PROA_PREBUILT_ONLY: "1"
          PROA_TAILWIND: skip
          PROA_YES: "1"
        run: |
          set -euo pipefail
          : "${PROA_VERSION:?set the PROA_CLI_VERSION repository variable to a published CLI version}"
          curl --proto '=https' --proto-redir '=https' --tlsv1.2 -fsSL https://proa.so/install.sh | sh
          echo "$PROA_INSTALL_DIR" >> "$GITHUB_PATH"

      - name: Rust checks
        run: |
          cargo fmt --all --check
          proa test

      - name: Proa checks
        run: proa check src
```

Generated sites use public crates.io dependencies and need no GitHub credential or Cargo registry token. Commit `Cargo.lock` and use `--locked` in CI to build the same dependency versions as local development. [Installation](/docs) covers CLI setup.

## Changed Files

For faster pull-request checks, run against changed files:

```bash
proa check --changed --base origin/main
```

For pre-commit hooks, run against staged files:

```bash
proa check --staged
```

If no changed Rust files are selected, `check` succeeds without scanning. Do not combine explicit paths with `--changed`, `--staged`, or `--base`; Git-selected mode owns the file list.

In GitHub Actions, changed-file mode needs enough history to diff against the base ref:

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0

- name: Proa changed-file check
  run: proa check --changed --base origin/main
```

## GitHub Annotations

`proa check` is intentionally concise. Use `proa lint --github` when you want inline GitHub Actions annotations:

```bash
proa fmt --check --verify src
proa lint --github --deny-warnings src
```

For a changed-file workflow:

```bash
proa fmt --check --verify src
proa lint --github --deny-warnings --changed --base origin/main
```

`lint --github` emits `error`, `warning`, and `notice` annotations. JSON and GitHub output include info-level diagnostics by default. Use this mode when reviewers need inline file comments; use `proa check` when you want a shorter pass/fail log.

## JSON Diagnostics

Use JSON when integrating with editor tooling or custom CI summaries:

```bash
proa lint --json --min-severity info src > proa-lint.json
proa chunks --json src > proa-chunks.json
proa site check --json > proa-site-check.json
```

The JSON shape includes the path, line, column, severity, diagnostic code, message, and optional help text. That makes it stable enough for custom PR summaries or agent workflows.

## Monorepos

Run Proa checks close to the Rust render code. For a workspace with multiple apps, prefer explicit paths:

```bash
proa check apps/marketing/src apps/admin/src crates/ui/src
```

If each app owns its own generated docs or static routes, include `site check` for each app root:

```bash
proa site check --root apps/marketing
proa site check --root apps/docs
```

## Failure Triage

When CI fails, use the narrow command first:

| Failure | Local command |
| --- | --- |
| Macro formatting differs | `proa fmt src` |
| Verify mode says formatting changed structure | `proa fmt --check --verify src` |
| Lint failed without enough detail | `proa lint --min-severity info src` |
| GitHub annotations are noisy | `proa lint --github --min-severity warning src` |
| Site structure failed | `proa site check --json` |

Keep the full gate on the branch that deploys. Use changed-file mode for fast feedback, not as the only production release check.

## Docker

Use the Dockerfile generated by `proa new site --deploy docker`. After installing the pinned CLI and asset tools, its build stage runs:

```dockerfile
RUN proa build --locked --artifact-out /tmp/proa-app
```

`proa build` runs the linked RSJS pipeline and the configured asset build, then copies the linked executable to the `--artifact-out` path. Copy `public/` separately into the runtime image; a plain `cargo build --release` skips the asset build and fails at link time on any crate with islands. The Dockerfile that `proa new site --deploy docker` writes uses the same command.

Build with:

```bash
docker build .
```

Multi-stage builds keep build tooling and sources out of the final image. [Docker](/docs/framework/docker) shows the full build.

## Other CI Systems

The pattern is the same for any CI:

1. Install a checksum-verified CLI binary (or build it from source) as shown above
2. Run the gate: `cargo fmt --all --check`, `proa test`, `proa check src`

## Next steps

- [proa fmt / lint / check](/docs/cli/format-lint-check)
  - Format macro bodies, run lints, and gate CI.
- [Deploy](/docs/framework/deployment)
  - Pick a deployment target, then follow the guide for it.
- [Testing](/docs/guides/testing)
  - Test application behavior and framework regressions without pinning page markup.
- [Docker](/docs/framework/docker)
  - Run the Proa image yourself, and own everything a platform would have done.


---

# Docs: Agent setup

URL: /docs/agents
Description: Configure coding agents to edit Proa projects with local instructions.

---
title: Agent setup
description: Configure coding agents to edit Proa projects with local instructions.
sidebar_title: Agent setup
---

A coding agent in a Proa repository reads the same files you do: `AGENTS.md`, an optional `SKILL.md`, and per-page docs Markdown. This page covers [writing `AGENTS.md`](#writing-agents-md), [writing a reusable skill](#writing-a-reusable-skill), [which context an agent needs](#which-context-does-an-agent-need), and [fetching page Markdown](#fetching-page-markdown).

## Writing AGENTS.md

`proa new site` scaffolds the file by default (pass `--no-agents-md` to skip it; `--agents-md` is the explicit spelling of the default):

```bash filename="Terminal"
proa new site my-site
```

Keep `AGENTS.md` at the project root. It describes the local project shape, render rules, validation commands, and safe edit boundaries.

````md filename="AGENTS.md"
# AGENTS.md

## Project Shape

- Pages live in `src/pages/`.
- Shared shells live in `src/layouts/`.
- Reusable render components live in `src/components/`.
- Route metadata, navigation, and shared data live in `src/data/`.
- Keep a component next to the route that owns it. Promote it into
  `src/components/` once a second route needs it.
- Keep route handlers, shared components, and content compilation in separate
  modules, and keep request-specific data out of globals.

## Rendering Rules

- Use `WebRenderSync` by default.
- Use `WebRender` only when the render body or `render_head` needs `.await`, or the analyzed component declares RSJS query/mutation state.
- Use `html_sync!` for synchronous render trees and `html!` for async-capable render trees.
- Opaque SSR components use no RSJS attribute. An analyzed component uses
  `#[rsjs(component)]`; add `client` when it originates signals, event
  handlers, queries, mutations, shared-state acquisition, node refs, or
  browser work.
- Always annotate a real render-trait impl. Do not use inherent render
  shorthand, `async fn render` sugar, or component `clients(...)` allowlists.
- A direct inbound read such as `self.label` can remain live when its parent
  supplies a live value. Use `server_only(...)` or `server_attr(...)` only for
  an intentional per-render snapshot.
- Keep hot render paths allocation-clean. Prefer borrowed data, static class strings, and stack-allocated class composition.
- Do not build child HTML strings just to concatenate them into a parent.
- In managed documents, set `const ROLE: ComponentRole = ComponentRole::PAGE` on the route page and `LAYOUT` on its ancestors. Use one head outlet. A head hook requires either role; analyzed RSJS impls stay render-only, with roles and hooks on an ordinary SSR wrapper.

## Validation

Run these before handing work back:

```bash
cargo fmt --all
proa check
proa test
proa site check
```

If a render-path change allocates intentionally, explain why.
````

`AGENTS.md` binds one project. To carry the same rules into every project an agent touches, write a skill.

## Writing a reusable skill

Some agents support reusable `SKILL.md` files. Use one when you want the Proa authoring rules to follow the agent across projects.

The [source repository](https://github.com/Proa-Labs/proa/tree/main/.agents/skills) includes five focused skills:

| Skill | Use it for |
| --- | --- |
| `proa-component` | Typed server-rendered components and allocation-conscious styling |
| `proa-island` | RSJS signals, handlers, and browser islands |
| `proa-perf-review` | Render-path performance checks |
| `proa-markdown` | Typed Markdown and shared HTML/Markdown content |
| `proa-docs-api` | Retrieving current documentation through HTTP or MCP |

Use your agent's skill installer with that repository, or discover the downloadable instructions and integrity hashes in the [public skills index](/.well-known/agent-skills/index.json). The authoring skills use the repository's `docs/agent/` reference; the API skill works without a source checkout. A skill supplements the owning project's instructions.

For a project-specific skill, start with this outline:

```md filename="SKILL.md"
# Proa Site Authoring

Use this skill when adding or changing Proa pages, components, layouts, route handlers, or RSJS islands.

## Rules

- Read the local `AGENTS.md` first.
- Prefer `WebRenderSync` unless the body or head hook must await data, or the component declares RSJS query/mutation state.
- Use `html_sync!` for sync markup and `html!` for async-capable markup.
- Use `#[rsjs(component)]` on an authored render-trait impl for analyzed
  participation. Add `client` when the component originates browser behavior.
  Keep handlers as named locals when they are more than trivial.
- Do not use inherent render shorthand, `async fn render` sugar, or component
  `clients(...)` allowlists.
- Treat direct inbound fields as potentially live. Use explicit server
  boundaries only when the component contract intentionally snapshots them.
- Preserve direct parent-child rendering. Do not render children into intermediate `String`s unless a non-hot-path API explicitly requires it.
- Keep classes static where possible. Prefer compile-time class composition and existing project tokens.
- Managed documents need explicit PAGE/LAYOUT roles and one head outlet; put head hooks on ordinary SSR wrappers, outside analyzed RSJS impls.
- After edits, run the validation commands from `AGENTS.md`.

## Context To Fetch

- `/docs/core/html-rendering.md`
- `/docs/core/components.md`
- `/docs/guides/islands.md`
- `/docs/rsjs/handlers.md`
- `/docs/rsjs/signals.md`
- `/docs/rsjs/queries-mutations.md`
- `/docs/guides/performance.md`

Use `/llms-full.txt` only when the task needs broad recall across the whole docs site.
```

The skill fixes the rules. The next decision is how much documentation to load for a given task.

## Which context does an agent need?

Start small. Add more context only when the task needs it.

| Task | Give the agent |
|------|----------------|
| Create or edit a page | `AGENTS.md`, `/docs/framework/routing.md`, `/docs/core/components.md` |
| Add a reusable component | `AGENTS.md`, `/docs/core/html-rendering.md`, `/docs/guides/performance.md` |
| Add browser interactivity | `AGENTS.md`, `/docs/guides/islands.md`, `/docs/rsjs/handlers.md`, `/docs/rsjs/signals.md` |
| Add async data | `AGENTS.md`, `/docs/framework/data-loading.md`, `/docs/core/html-rendering.md` |
| Debug a compile error | `AGENTS.md`, focused page Markdown, compiler output |
| Answer broad questions | `/llms-full.txt` |

Every row names Markdown files, and every docs route serves one.

## Fetching page Markdown

Every docs route exposes Markdown:

```bash filename="Terminal"
curl https://proa.so/docs/agents.md
curl https://proa.so/docs/core/html-rendering.md
curl https://proa.so/docs/rsjs/handlers.md
```

For persistent project behavior, keep instructions in `AGENTS.md` or `SKILL.md`. For one-off retrieval, use page Markdown or `/llms-full.txt`.

## Next steps

- [AI consumption](/docs/llms)
  - Fetch docs context for an agent that reads but never edits the project.
- [proa new site](/docs/cli/new-site)
  - See where pages, layouts, components, and shared data live.
- [HTML rendering](/docs/core/html-rendering)
  - Learn the render traits and macros the rules above refer to.
- [Writing performant pages](/docs/guides/performance)
  - Keep the render paths an agent edits free of allocation.


---

# Docs: AI consumption

URL: /docs/llms
Description: Serve Proa docs as Markdown context for coding agents.

---
title: AI consumption
description: Serve Proa docs as Markdown context for coding agents.
sidebar_title: AI / LLMs
keywords: [llms.txt, llms-full.txt, Markdown]
---

Proa serves its docs as plain text and Markdown, so a coding agent never executes client JavaScript to read them. This page covers [fetching the full corpus](#fetching-the-full-corpus), [fetching a single page](#fetching-a-single-page), [how much context an agent needs](#how-much-context-does-an-agent-need), and [keeping the corpus stable](#keeping-the-corpus-stable).

## Start with the index

Read [/llms.txt](/llms.txt) for product context and integration links. The focused [/docs/llms.txt](/docs/llms.txt) lists every public documentation page. For programmatic search and retrieval, use the [Proa API and MCP guide](/docs/api). These interfaces are public and read-only.

## Fetching the full corpus

Use `/llms-full.txt` when you want a single plain text file with every docs page:

```bash filename="Terminal"
curl https://proa.so/llms-full.txt > proa-docs.txt
```

The endpoint carries each page title, canonical route, optional description, and the Markdown source the site renders. Feed it to agent context windows, retrieval pipelines, and local search indexes.

The whole corpus is a large amount of context. Most tasks need one page.

## Fetching a single page

Every docs page also exposes its Markdown source:

```bash filename="Terminal"
curl https://proa.so/docs/index.md
curl https://proa.so/docs/proa-docs/configuration.md
```

Use page Markdown when an agent needs focused context. Use the full corpus when the agent answers questions across Core, CLI, Framework, Proa Docs, FFI, Migration, and RSJS.

Which of the two you reach for depends on the task.

## How much context does an agent need?

Start with the smallest useful context:

| Task | Context |
|------|---------|
| Build a page | `/docs/agents.md`, `/docs/index.md`, `/docs/core/components.md`, `/docs/core/html-rendering.md` |
| Fix docs navigation | `/docs/proa-docs/pages-and-routes.md`, `/docs/proa-docs/navigation.md`, `/docs/proa-docs/configuration.md` |
| Wire a server route | `/docs/framework/routing.md`, `/docs/framework/route-handlers.md`, `/docs/framework/responses.md` |
| Review performance | `/docs/guides/performance.md`, `/docs/core/class-composition.md`, `/docs/cli/chunks.md` |

Add `/llms-full.txt` only if the agent needs broad recall across the whole site.

Those routes stay valid because the corpus follows a fixed contract.

## Keeping the corpus stable

Proa generates the text endpoint from compiled docs registries, not from rendered HTML. That keeps the context stable:

- Markdown remains the source of truth.
- Page URLs match the generated routes.
- Descriptions come from frontmatter or inferred content.
- Search-only UI, shell markup, and client scripts stay out of the corpus.

If you publish a new docs collection, add it to the endpoint explicitly so the file stays predictable.

## Next steps

- [Agent setup](/docs/agents)
  - Start here when the agent edits the project instead of only reading docs.
- [Authoring](/docs/proa-docs/pages-and-routes)
  - Write the Markdown pages that feed these endpoints.
- [Markdown pipeline](/docs/proa-docs/markdown)
  - See how Proa compiles Markdown into routes and text endpoints.
- [Quickstart](/docs)
  - Build the site an agent will read the docs for.


---

# Docs: Proa documentation API and MCP

URL: /docs/api
Description: Search and read official Proa documentation over HTTP, MCP, or browser tools without credentials.

---
title: Proa documentation API and MCP
description: Search and read official Proa documentation over HTTP, MCP, or browser tools without credentials.
sidebar_title: API and MCP
keywords: [Proa API, MCP, WebMCP, OpenAPI, authentication, pagination, rate limits, Go SDK]
---

The public Proa documentation API searches and reads the same compiled pages as this website. Use it when a coding agent needs current Rust APIs, render patterns, RSJS instructions, or deployment guidance. All operations are read-only. No account, API key, OAuth token, payment, or signup is required.

Start with [/llms.txt](/llms.txt), the [documentation index](/docs/llms.txt), or the [OpenAPI 3.1 specification](/openapi.json). This service provides documentation; it does not build, host, or deploy your applications.

The OpenAPI definition contains the typed JSON read API for tool generators and SDK clients. HTML, plain-text exports, health checks, and legacy browser search are described separately in the [complete website OpenAPI contract](/openapi/site.json). Those routes remain available.

The [authoring skills index](/.well-known/agent-skills/index.json) follows the draft Agent Skills Discovery 0.2 format. Each entry identifies a `skill-md` artifact and its SHA-256 digest so clients can verify the downloaded instructions. The component, island, performance, and Markdown authoring workflows reference the [Proa source repository](https://github.com/proa-labs/proa); the documentation API skill also works without a checkout. Focused indexes cover [the framework](/docs/framework/llms.txt), [RSJS](/docs/rsjs/llms.txt), and [the ecosystem](/ecosystem/llms.txt).

## Search documentation

```bash
curl 'https://proa.so/api/v1/search?q=streaming&limit=5'
```

`q` is a case-insensitive phrase of 1–256 characters, matched against titles, descriptions, and Markdown. The response contains `results`, `total`, and `next_cursor`. Each result includes `title`, `description`, the canonical `path`, and a direct `markdown_url`.

Pass the returned `next_cursor` as `cursor` with the same query to read the next page. A null cursor means there are no more results. `limit` defaults to 10 and accepts 1–50. Cursors belong to a result set on the current deployment; restart pagination if the documentation changes during retrieval.

## Read and list pages

```bash
curl 'https://proa.so/api/v1/docs/page?path=/docs/core/html-rendering'
curl 'https://proa.so/api/v1/docs?limit=20'
curl 'https://proa.so/docs/core/html-rendering.md'
curl -H 'Accept: text/markdown' 'https://proa.so/'
```

`GET /api/v1/docs/page` returns metadata plus the complete `markdown` field. Its `path` must identify a public documentation page; arbitrary URLs and filesystem paths are rejected. `GET /api/v1/docs` lists all public pages with the same pagination shape as search.

Every documentation page has a `.md` representation. The homepage is also available at `/index.md` and `/?mode=agent`. HTML and negotiated Markdown responses carry `Vary: Accept` so caches can distinguish the representations. Use [/llms-full.txt](/llms-full.txt) only when you need the entire corpus.

The supported JSON operations use GET. JSON POST search, background exports,
and synthetic sandbox endpoints have been retired. Use the reads above for
public documentation and local HTTP fixtures for client tests.

## JavaScript, TypeScript, Python, and Go clients

The repository contains dependency-free [JavaScript/TypeScript](https://github.com/Proa-Labs/proa/tree/main/sdk/javascript) and [Python](https://github.com/Proa-Labs/proa/tree/main/sdk/python) documentation clients. Each includes a `proa-docs` CLI for search, listing, and Markdown retrieval. These clients read documentation; the [Proa build CLI](/docs/cli) scaffolds and builds applications.

The [Python package is available on PyPI](https://pypi.org/project/proa-docs/). Install the library with `pip install proa-docs`, or run its CLI without a source checkout:

```bash
uvx --from proa-docs proa-docs search streaming --limit 5
uvx --from proa-docs proa-docs get /docs/core/html-rendering --markdown
```

The [JavaScript and TypeScript package is available on npm](https://www.npmjs.com/package/@proa-labs/docs). Install the library with `npm install @proa-labs/docs`, or run its CLI with npx:

```bash
npx --yes --package @proa-labs/docs proa-docs search streaming --limit 5
npx --yes --package @proa-labs/docs proa-docs get /docs/core/html-rendering --markdown
```

Both clients can also run from a source checkout:

```bash
node sdk/javascript/cli.mjs search streaming --limit 5
uv run --directory sdk/python proa-docs get /docs/core/html-rendering --markdown
```

JavaScript requires Node.js 22 or newer. Python requires 3.11 or newer. Both clients provide `search`, `list`, `get`, and a paginated `documents` iterator, configurable timeouts and base URLs, typed response definitions, and structured errors with the server's retry delay. They do not retry automatically.

The official [Go SDK on pkg.go.dev](https://pkg.go.dev/github.com/Proa-Labs/proa/sdk/go) requires Go 1.23 or newer and uses only the standard library:

```bash
go get github.com/Proa-Labs/proa/sdk/go@v0.0.0-20261029004544-c75fce01a7f4
```

Import it as `proadocs "github.com/Proa-Labs/proa/sdk/go"`. Create a client with `proadocs.NewClient(proadocs.Options{})`, then call `Search`, `List`, `Get`, or `WalkDocuments` with a Go context. Set `Options.BaseURL` for another deployment and `Options.Timeout` for per-request deadlines. `APIError` preserves the HTTP status, structured problem, and retry delay. The client does not retry automatically. Its [README](https://github.com/Proa-Labs/proa/tree/main/sdk/go) contains a complete example.

The package READMEs contain library examples. Publication and verification steps are in the [SDK release guide](https://github.com/Proa-Labs/proa/tree/main/sdk#releasing).

## Connect through MCP

Configure a Streamable HTTP MCP connection to `https://proa.so/mcp`, with no credentials. The experimental [server card](/mcp/server-card) and [agent resource catalog](/.well-known/ard.json) advertise this endpoint. Public discovery files support cross-origin browser reads; the MCP transport itself accepts browser calls only from this deployment's origin. The service is stateless, so connections do not depend on a particular server instance.

The server is published in the [official MCP Registry as `io.github.proa-web/docs`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proa-web%2Fdocs). Its listing points to this documentation and the same hosted endpoint; no local server installation is required.

The [Proa documentation connector on Glama](https://glama.ai/mcp/connectors/so.proa/proa-documentation) also lists `https://proa.so/mcp`, its public tools, and connection health. Use either directory to find the same service.

- `search_docs` accepts `q`, optional `limit`, and optional `cursor`. It returns the same document list as HTTP search.
- `get_doc` accepts `path` and returns a complete Markdown document with its metadata.
- `resources/list` lists public Markdown resources with names, descriptions, media types, and pagination.
- `resources/read` reads a URI returned by `resources/list`.

For example, initialize a connection using a supported MCP protocol version:

```bash
curl 'https://proa.so/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs-reader","version":"1.0.0"}}}'
```

Use the negotiated protocol version on subsequent requests. Standard MCP clients manage initialization and protocol headers. The server accepts non-browser clients without an Origin header; browser clients must use the deployment's own origin. Requests are limited to 16 KiB. Tool failures return MCP error content and unknown methods return JSON-RPC errors.

## Browser tools

When the browser supports WebMCP, the website registers `search_docs` and `get_doc` through `document.modelContext`, with a compatibility fallback for `navigator.modelContext`. These tools use the same public HTTP endpoints. They do not navigate, submit forms, or alter the page. Browsers without WebMCP continue to use the normal website and search.

## Limits, errors, and retries

The HTTP API and MCP endpoint share a budget of 600 requests per minute per running server instance. It is a shared service budget, not a personal quota. Responses include `RateLimit-Policy`, `RateLimit`, and `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. A 429 response includes `Retry-After` in seconds; wait that long before retrying. These responses use `Cache-Control: no-store` so a cached budget is not mistaken for a current one.

Versioned REST failures use `application/problem+json` with `type`, `title`, `status`, `code`, `detail`, and `documentation`. Codes include `invalid_request` (400), `not_found` (404), `method_not_allowed` (405), and `rate_limited` (429). Correct invalid parameters; use the document index to recover from missing paths. For network failures or temporary 5xx responses, retry with exponential backoff.

Document retrieval and search are synchronous reads and safe to repeat. Even legacy `POST /api/search` only searches documents; it creates no record or side effect. Do not send credentials or personal data in search queries. See [authentication policy](/auth.md).

## Versions and compatibility

The `/api/v1` URL prefix identifies the contract version. Additive response fields may appear within v1; clients should ignore fields they do not use. Breaking changes use a new major URL prefix. Any future removal will first be documented here, with `Deprecation` and `Sunset` headers on the affected routes. No routes are currently scheduled for removal.

The existing `/api/search?q=...` and JSON-string `POST /api/search` remain available for older clients. They return at most eight results and use their original response format. New integrations should use `/api/v1/search` for pagination and typed errors.

## Local development

From the repository root, run the marketing application through the linked development pipeline:

```bash
SITE_URL=http://localhost:5555 PORT=5555 cargo proa run -p proa_marketing --bin proa_marketing
```

The same public read-only operations work locally without credentials. `SITE_URL` sets the absolute discovery URLs and allowed browser origin. For building applications with Proa, use the [CLI quickstart](/docs/cli) and [agent setup guide](/docs/agents).


---

# Docs: Troubleshooting

URL: /docs/guides/troubleshooting
Description: Fix the most common Proa setup, registry, template, component, island, routing, and CI failures.

---
title: Troubleshooting
description: Fix the most common Proa setup, registry, template, component, island, routing, and CI failures.
---

Start with the fastest checks. They separate environment problems from template and runtime problems:

```bash
proa --help
proa check
proa fmt --check --verify src
proa lint --min-severity info src
proa site check
```

If you are working from the Proa repository instead of an installed CLI, use the Cargo wrapper:

```bash
cargo run -p proa-cli --bin proa -- fmt --check --verify src
cargo run -p proa-cli --bin proa -- lint --min-severity info src
```

## `proa: command not found`

Right after an install, the cause is PATH. The installer appends an `export PATH`
line to every shell profile it finds (`~/.bashrc`, `~/.bash_profile`, `~/.zshrc`,
`~/.profile`, and `~/.config/fish/config.fish`), and the shell you are already in
never rereads those files. Open a new terminal, or add the directory to the
current shell by hand:

```bash
export PATH="$HOME/.proa/bin:$PATH"
```

Confirm that the binaries landed where you expect:

```bash
ls "$HOME/.proa/bin"
"$HOME/.proa/bin/proa" --version
```

On Windows, the installer writes the directory into your user PATH and into the
terminal it ran in, so that terminal can run `proa` right away. Every other
process keeps the PATH it started with, so restart any other terminal or editor
before running `proa --version` there. Check the persisted value with:

```powershell
[Environment]::GetEnvironmentVariable("Path", "User")
```

The installer refuses to rewrite a user PATH that contains `%VAR%` references,
because rewriting one would freeze today's expansion. It warns and prints the
line to add when it finds one.

If you ran `cargo install` or the installer fell back to a source build, the
binaries live in `~/.cargo/bin` instead. Point the same `export` line at that
directory.

If you passed `PROA_NO_MODIFY_PATH` or `--no-modify-path`, the installer left
your profiles, and the Windows user PATH, alone by design, and printed the line
to add. Add it yourself, or run the installer again without that flag.

Every run writes a log that lists which profile files the installer examined,
which it changed, and which already had the line. The installer prints the path
as it exits, and it looks like
`/tmp/proa-install-20260813T221500Z-1234.log` (under `%TEMP%` on Windows). Read
that when the PATH change did not land where you expected, and attach it if you
report the problem.

When you are developing inside this repository, run the CLI through Cargo instead:

```bash
cargo run -p proa-cli --bin proa -- --help
```

Then use that same prefix for later commands. See [Install Proa](/docs#1-install-proa) and the [CLI reference](/docs/cli).

## Windows Builds And Executable Launches

Use a current stable Rust toolchain with the MSVC build tools installed, then
run `proa --version` and `cargo proa --version`. Both entry points should
report the installed CLI version. `proa dev`, `proa check`, `proa build`, and
`proa test` coordinate the Cargo passes required for interactive components.
Plain `cargo check` supports Rust type checking and editor feedback; it does
not validate the complete linked browser graph. Plain `cargo build` and
`cargo run` cannot produce a linked application containing RSJS islands.

The release workflow currently publishes a Linux x86_64 CLI archive. Windows
installation falls back to building from source, so installation includes a
Rust dependency build. The first application build also compiles dependencies
for the descriptor and final passes. Later runs reuse those Cargo artifacts.
Keep the same toolchain, target, profile, and features when comparing cold and
warm build times. In PowerShell, enable stage timing before reproducing a slow
build:

```powershell
$env:PROA_BUILD_TIMINGS = '1'
proa build
Remove-Item Env:PROA_BUILD_TIMINGS
```

For `LNK1104` or errors involving a very long artifact path, use a short Cargo
target directory for the same build and dev commands:

```powershell
$env:CARGO_TARGET_DIR = 'C:\pt'
proa dev
```

Proa uses shorter directory labels on Windows while retaining complete cache
identities. Native linkers and dependency build tools can still impose path
limits, so a short target root remains useful for deeply nested checkouts.
The shorter layout requires one cold build when upgrading from the old layout;
Proa leaves the old artifacts in place.
Use a separate target root for unrelated projects if their Cargo builds run
concurrently.

For missing `tailwindcss.exe`, follow the Windows instructions under
[Tailwind prerequisite](/docs/cli/new-site#tailwind-prerequisite).

`proa start` runs an exported executable. To choose its location explicitly:

```powershell
proa build --artifact-out target/release/server.exe
proa start --bin target/release/server.exe
```

If launching or replacing a compiled file fails, preserve the executable path
and numeric OS error from the original diagnostic. A successful retry alone
does not identify which Windows feature caused the failure:

| OS error | Meaning and next check |
| --- | --- |
| `5` | Access denied. Check file permissions and the security event for that exact path; this code alone does not identify antivirus. |
| `32`, `33` | Another process holds a file or region lock. Stop an older server still using that output, or wait for the process holding the lock to release it. |
| `577` | Windows could not verify the file's digital signature. Inspect the Code Integrity events for the named executable or DLL. |

These meanings come from Microsoft's [system error codes 0–499](https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--0-499-)
and [500–999](https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--500-999-).
[Smart App Control](https://learn.microsoft.com/en-us/windows/apps/develop/smart-app-control/overview/)
can also block untrusted unsigned code. Include the Windows version, active
security feature, error code, CLI version, and failing command in a report so
the failure can be distinguished from a compiler error or file-lock race.

## RSJS Unsupported Shapes At Link Time

`unsupported_shapes` means the linked backend cannot represent a client
expression or dependency in the selected component graph. It can appear after
Rust compilation because the graph is only complete at link time. The error
includes a Rust-resolved component name when one is available.

Run `proa lint <component-source.rs>` while editing, then `proa check` for the
whole project. Source lint does not prove every cross-component constraint.
Use explicitly typed state when inference is ambiguous, a named event handler,
and a small reproduction before changing several parts of a mutation at once.
For example, `save.run(draft.get())` passes the current value; browser handlers
cannot implicitly capture arbitrary server-only locals. The exact error and
CLI version are needed to distinguish a compiler limitation from an inference
or server/browser boundary error.

## The Installer Cannot Reach The Download Host

The installer fetches release archives from `https://proa.so/downloads/cli`,
the value of `PROA_DOWNLOAD_BASE`. A connection failure or a `503` from that
host stops the download before there is anything to verify.

A `503` means the release host behind the bridge is unavailable or rate
limited. The response carries `Retry-After: 30`, so wait half a minute and run
the installer again. Check the endpoint yourself:

```bash
curl --proto '=https' --tlsv1.2 -sS -i https://proa.so/downloads/cli/latest.json
```

A `200` with a `version` field means the host is healthy and the problem is
between you and it, usually a proxy or a DNS resolver. If the failure persists,
build the CLI from source instead:

```bash
curl -fsSL https://proa.so/install.sh | PROA_BUILD_FROM_SOURCE=1 sh
```

Or point the installer at another host that serves the same file names:

```bash
curl -fsSL https://proa.so/install.sh | PROA_DOWNLOAD_BASE=https://mirror.example/downloads/cli sh
```

The installer log records the request and what came back. Its path is printed
as the installer exits.

## No Release Is Published Yet

`https://proa.so/downloads/cli/latest.json` answers `404` when no `proa-cli`
release exists. The installer reads that as "there is no version to install"
rather than an archive-download failure, and attempts a Cargo build from
crates.io instead. That requires a published `proa-cli` crate. An unversioned
source build installs the latest published crate; `PROA_VERSION` selects an
exact published version.

The source build puts `proa` and `cargo-proa` in `~/.cargo/bin`, not
`~/.proa/bin`, so look there when the shell cannot find the binary afterwards.

Pinning `PROA_VERSION` does not change this. A version with no published
archives answers `404` on the asset URL too.

## Checksum Verification Failed

The installer compares the downloaded archive against the `SHA256SUMS` file for
that release. A mismatch stops the install before the installer unpacks
anything, and it deletes the temporary directory it downloaded into, so nothing
was installed and no unpacked binary was left behind.

A truncated download, a proxy that rewrote the response, or a stale cache all
produce this. Run the installer again first. If the mismatch survives a retry,
fetch both files and check them yourself:

```bash
VERSION="<published-version>"
TARGET=x86_64-unknown-linux-gnu
BASE="https://proa.so/downloads/cli/$VERSION"
curl --proto '=https' --tlsv1.2 -fLO "$BASE/proa-cli-$VERSION-$TARGET.tar.gz"
curl --proto '=https' --tlsv1.2 -fLO "$BASE/proa-cli-$VERSION-SHA256SUMS"
shasum -a 256 --ignore-missing -c "proa-cli-$VERSION-SHA256SUMS"
```

Use `sha256sum --ignore-missing -c` on Linux. A clean download on a different
network settles the question: if it verifies there, your first download passed
through something that changed it. If it fails there too, do not install the
archive. Open an issue with the version, the target triple, and the digest you
computed, and attach the installer log. It records the URL it fetched, the
expected hash, and the hash it computed. Its path is printed as the installer
exits.

To keep moving in the meantime, build the CLI from source instead:

```bash
curl -fsSL https://proa.so/install.sh | PROA_BUILD_FROM_SOURCE=1 sh
```

## No Prebuilt Binary For This Platform

For now, Proa publishes one native release binary:
`x86_64-unknown-linux-gnu`, built on Ubuntu 24.04. It supports 64-bit Ubuntu
24.04+ and other glibc 2.39+ Linux systems. On anything else, including older
Ubuntu releases, ARM Linux, Alpine and other musl distributions, macOS,
Windows, FreeBSD, and 32-bit hosts, the installer reports that it found no
matching asset and compiles the CLI with Cargo instead. For an official released
version, this fallback builds from crates.io without GitHub credentials:

```bash
cargo install proa-cli --locked
```

Use `--version "=<published-version>"` to pin a release. Main snapshots require
a prebuilt archive. If the snapshot archive is unavailable for your platform,
select a published version instead.

That build takes several minutes and needs Rust 1.93.0 or newer plus a C
toolchain. On Alpine, install the toolchain first:

```bash
apk add build-base
```

Alpine's packaged Rust lags the 1.93.0 minimum on some releases. Run
`rustc --version`, and install the toolchain with
[rustup](https://rustup.rs) when the packaged one is older. The installer
does not install Rust for you: it stops and prints the rustup command
instead. And when the only downloader on the system is BusyBox `wget`,
which cannot enforce HTTPS-only transfers, the installer stops and asks
for curl before downloading anything:

```bash
apk add curl
```

The source build puts `proa` and `cargo-proa` in `~/.cargo/bin`, not
`~/.proa/bin`, so check that directory when the shell cannot find the binary
afterwards.

When the fallback surprises you on a platform that does have a published
binary, read the installer log. It records the raw `uname` output, the libc it
detected and how, the target triple it resolved, and the asset lookup that came
back empty. Attach it if you report the detection as wrong.

## Cargo Cannot Download Proa Crates

Generated projects use public crates.io dependencies. Check network access to
crates.io, the Cargo error, and your project's proxy configuration. No private
`proa` registry or GitHub token is required.

For an older project using Git dependencies, keep all Proa crates on the same
Git URL and revision, and enable `net.git-fetch-with-cli` when you need your Git
credential helper or proxy settings. Migrate dependency declarations together;
see [Upgrading](/docs/guides/upgrading) and [CI](/docs/guides/ci).

## The Page Builds But Styles Are Missing

Generated Tailwind sites write `public/styles.css`. If the page renders unstyled, rebuild the stylesheet with the same command the `proa dev` / `proa build` asset step runs:

```bash
tailwindcss -i styles/input.css -o public/styles.css
```

If `tailwindcss` is not on PATH, install Tailwind CSS CLI v4 with the Proa installer (`curl -fsSL https://proa.so/install.sh | sh -s -- --tailwind-only`) or with Homebrew (`brew install tailwindcss`).

Use `--no-tailwind` when scaffolding if you want to bring your own stylesheet pipeline.

## `html_sync!` Or `html!` Does Not Parse

Run the formatter with structural verification first:

```bash
proa fmt --check --verify src
```

Common causes:

| Symptom | Fix |
|---------|-----|
| A void element has children | Use a self-closing element such as `<input ... />`. |
| Attribute syntax is split by invalid tokens | Keep names like `data-state` and `aria-label` as one attribute token. |
| Dynamic text appears without braces | Use `{value}` for Rust expressions and quoted text for static strings. |
| A generated macro body has odd spacing | Run `proa fmt src`, then `cargo fmt --all`. |

See [The html! Macro](/docs/core/html-rendering) and [Format, Lint, And Check](/docs/cli/format-lint-check).

## A Component Has Trait Errors

Most page and component render paths should implement `WebRenderSync`. Keep the
implementation generic over the data loader; the output defaults to the owned
`RenderBuffer`:

```rust
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};

impl<L: DataLoader> WebRenderSync<L> for MyComponent {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        // ...
        Ok(())
    }
}
```

If you place a sync component inside an async `html!` tree, wrap it with `proa::to_async(...)`. If the component awaits data or uses async loaders, implement `WebRender` and render with `html!`. See [Render traits](/docs/core/html-rendering).

## Classes Disappear Or `ClassList` Fails

`ClassList<N>` has fixed capacity. Count every segment you add, including optional classes:

```rust
let classes = ClassList::<4>::new()
    .add(BASE)
    .add(size.classes())
    .add(variant.classes())
    .add_opt(self.class);
```

Prefer increasing the capacity over building a `String` in the render path. See [Class composition](/docs/core/class-composition).

## An Island Renders But Clicks Do Nothing

Check the browser network panel first. The page should load the rsjs runtime and the island chunk without 404s.

Then confirm:

- The island has a matching server-rendered placeholder.
- The route serves static assets from the same origin during development.
- Event handlers live inside the `#[island]` or
  `#[rsjs(component, client)]` boundary.
- Async query helpers use an async `WebRender` component, not a sync render implementation.

See [RSJS](/docs/guides/islands).

## A New Route Returns 404

Run the site checks:

```bash
proa site routes
proa site check
```

Confirm that the route is registered in the router, the page module is exported, and generated metadata points at the same path. See [Framework routing](/docs/framework/routing) and [Site commands](/docs/cli/site).

## CI Fails But Local Checks Pass

Make CI run the same commands as local development:

```bash
cargo fmt --all --check
proa check --locked
proa test --locked
```

If CI fails before compilation, check access to crates.io and the version requirements in `Cargo.toml`. Generated sites use public registry dependencies and need no GitHub credential or Cargo registry token. Commit `Cargo.lock` and use `--locked` to keep CI on the same resolved dependencies as local development.

For GitHub annotations, run:

```bash
proa lint --github --changed --base origin/main
```

Git selection replaces the path argument: `--changed` and `--base` cannot be combined with explicit paths.

See [CI / GitHub Actions](/docs/guides/ci).

## Still Stuck

Capture the exact failing command and a machine-readable diagnostic:

```bash
proa lint --json --min-severity info src
proa chunks --json src
```

Include the failing route, the rendered HTML snippet if a browser page looks wrong, and the first compiler or CLI diagnostic that points at your code.

For an install that failed, attach the installer log instead. The installer
prints its path on the way out, on success and on failure, and
`PROA_LOG=/path/to/file` writes it where you choose. Rerun with `PROA_VERBOSE=1`
to see the same detail in the terminal while you work.


---

# Docs: Upgrading

URL: /docs/guides/upgrading
Description: Move between Proa versions and find what broke.

---
title: Upgrading
description: Move between Proa versions and find what broke.
---

Proa is pre-1.0. Minor versions carry breaking changes. Each is listed in [`CHANGELOG.md`](https://github.com/proa-labs/proa/blob/main/CHANGELOG.md), with larger ones under a **Breaking** marker and a guide under `docs/migrations/` ([0.3 standalone](https://github.com/proa-labs/proa/blob/main/docs/migrations/0.3-standalone.md), [shared `WebContext`](https://github.com/proa-labs/proa/blob/main/docs/migrations/web-context.md)).

Read the changelog first, then upgrade one minor version at a time:

```bash
cargo update -p proa
cargo proa check
```

`cargo proa check` runs the template lints and the RSJS linker together, which is where most upgrade breakage surfaces. A plain `cargo check` will miss link-time errors.

## Upgrading to 0.4

Applications can replace direct rendering and framework dependencies with the
`proa` facade:

```toml
[dependencies]
proa = { version = "0.4", features = ["axum"] }
```

Import common types and macros from `proa::`, loaders from `proa::stream`, and
Axum integration from `proa::axum`. Add `actions` or `react` only when needed.
RSJS and build-time font dependencies retain their own package versions.
Direct implementation-crate dependencies remain supported for advanced uses.

Managed metadata uses `render_head`, explicit Page/Layout roles, and a head
outlet. Markdown macros use one string body, and `content_part!` wrappers are
removed. Review which outgoing URLs need the application mount and use
`cx.url(path)` for those. See [metadata](/docs/framework/metadata),
[Markdown](/docs/core/markdown), and [rendering responses](/docs/framework/responses).

## Upgrading to 0.3

0.3 was a consolidation release. Six surfaces were removed and one buffer became the standard.

| Change | What to do |
|---|---|
| Standard render buffer | Replace bespoke writers with `RenderBuffer`. See [WriteBuf](/docs/core/write-buf) |
| Component-tree ownership moved | Components take ownership of children rather than borrowing |
| Native-mobile surface removed | No replacement. The crate no longer targets it |
| Runtime-template and `Vm*` surface removed | Templates are compile-time only. Move dynamic templates to data-driven components |
| Documentation-build adapters removed | Use `proa_docs_build`. See [Proa Docs](/docs/proa-docs) |
| Product-specific route codegen removed | Author routes directly. See [Routes and layouts](/docs/framework/routing) |

## Upgrading past 0.3

Breaking changes since 0.3 affect how components are authored and linked, how fonts are declared, and how Markdown components receive their context:

- **`#[proa_component]` is gone**, along with the inherent `#[rsjs(component)]` shorthand and RSJS `async fn render` sugar. Author `WebRenderSync` or the canonical `WebRender` signature directly, then apply `#[rsjs(component)]` for composition or `#[rsjs(component, client)]` when the component originates browser work. See [HTML rendering](/docs/core/html-rendering).
- **Component-level `clients(...)` allowlists are gone.** A reachable call to a `#[rsjs::client]` helper now creates a linker edge automatically. `#[rsjs::client_module]` remains as optional grouping. See [Client helpers](/docs/rsjs/client-helpers).
- **Deployable RSJS binaries require the linked `cargo proa` pipeline.** `cargo check` and rust-analyzer still give provisional type checking, but `cargo build` on an RSJS application now fails at link time with an actionable diagnostic instead of quietly producing a provisional binary.
- **`cargo proa font add` / `font remove` and `proa-fonts.toml` are gone.** Declare fonts in code with `google_font!` / `local_font!`; a `build.rs` collector vendors them and records `proa-fonts.lock`. `cargo proa font sync` runs the same collector outside a build. See [Fonts](/docs/framework/fonts).
- **`MdContext` is gone.** `MdRenderSync` and `MdRender` now take the same `WebContext<L, B>` as the HTML traits, with the loader first and no lifetime parameters, and Markdown helpers are named `md_*` / `write_md_*`. See [Markdown](/docs/core/markdown) and the [migration guide](https://github.com/proa-labs/proa/blob/main/docs/migrations/web-context.md).
- **`RouteResponse` is an opaque deferred-render plan** and `Layout` carries metadata only; the crate is `proa_framework_axum`. See [Responses](/docs/framework/responses) and the changelog for the smaller entries (event-handler parameters, `RenderOptions`, `mdx!`, client IR v3).
- **Managed metadata uses component roles and head hooks.** Select one `ROLE = PAGE`, mark ancestor metadata layouts as `LAYOUT`, and place one `{cx.head()}` outlet in the document. Async hooks use native `async fn render_head(...) -> Result<(), WriteError>`. The former `head()` inspection getter is `head_state()`; mutations go through the checked `head_mut()` writer. Enable managed mode with `FrameworkBuilder::with_head(...)`, or use `.without_head()` while migrating a manual document. See [Metadata](/docs/framework/metadata).
- **`FrameworkBuilder::new()` and `RouteContextLayer::new(metadata)` take no manifest, and the manifest-driven React island bootstrap is gone.** Removed: `IslandManifest` and its entry types, `RouteResponse::with_islands` and `with_bootstrap`, `render_bootstrap_for_islands`, `css_asset_path`, `render_css_link`, and the router's `Extension<Arc<IslandManifest>>`. The finalizers (`finalize_route_response*`, `render_*_html_response`, `into_framework_response`) lose their manifest parameter. Link a stylesheet from the layout with `cx.url(..)`. `proa_react` islands keep rendering through `proa::react::react_bootstrap` directly. `RouteResponse::render_to_bytes` renders a finalized document with no server or runtime. See [Configuration](/docs/framework/configuration) and [Route responses](/docs/framework/responses#rendering-without-a-server).
- **Application URL composition now lives on `cx.url(path)`.** Move outgoing URL construction off `cx.request()`. The helper explicitly applies the configured base path and writes directly into HTML attributes or Markdown links; plain URL strings stay unchanged. See [Linking](/docs/framework/linking).
- **The unused legacy effect IR and fluent expression builder are gone.** Browser effects use RSJS. The `proa_ir` expression/value model, bounded evaluator, reactive bindings, and component trees remain available.
- **The deprecated pool-backed writers are gone.** Replace `SinkWriter`, `SinkPage`, `PagePool`, `MemorySink`, their in-order aliases, and `SinkCheckpoint` with `RenderBuffer` and its checkpoints. Custom transport adapters keep using `StreamChunkFlusher` / `SendStreamChunkFlusher`. See [WriteBuf](/docs/core/write-buf).
- **The file-backed action collision checker is gone.** Remove calls to `proa::actions::check_action_collisions` and `clear_action_registry`, and imports from `collision_check`. The action derive never populated that registry. Scoped action names and the action data/code generation APIs remain available.
- **The standalone `proa_codegen` crate and `proa-codegen` binary are gone.** Component libraries own their metadata-to-TypeScript generation; Proa UI has its own generators. `proa new site` continues to use the CLI's site scaffolder.
- **The old `proa_cli::scaffold::new_site` Rust API is gone.** Use the `proa new site` command, which uses `site_scaffold`. The component, layout, and data generators remain available.
- **Generators no longer add placeholder render or source-text tests.** The page, endpoint, and component generators no longer accept `--no-test`. ORIGIN keeps its loader and runtime integration tests without a full-page HTML snapshot.
- **The unused `ProaConfig` API is gone**, including `PathsConfig`, `CodegenConfig`, `ServerConfig`, and `FrameworkBuilder::{with_config, config}`. Those values did not affect the router. Mount assets with `with_static_service`, configure middleware through the builder, and bind your listener to select the host and port. See [Configuration](/docs/framework/configuration).
- **Unused framework side features are gone:** `ExternalApp`, `ExternalAppStrategy`, `FrameworkBuilder::with_external_app`, the `proxy`, `process_manager`, and `shard` modules, and the `route-export` feature/module. Compose static applications through Axum's router APIs and manage upstream processes and proxies in your deployment. Route `PageCache` and the generic readiness probes remain available.
- **Unused compatibility helpers are gone.** Use `RenderBuffer` instead of `DefaultChainedBumpWriter`, `load_json*` / `load_typed*` instead of the deprecated context `load*` aliases, and `drain_pending_boundaries_with_artifacts` or `drain_pending_boundaries_with_nonce_and_artifacts` for deferred streaming output. Use `[u8; N]` or `SmallBuf<N>` directly instead of the fixed-size aliases in `stack`; construct a `WebContext` with your writer instead of `render_into_vec_with_hint`.

> **Good to know**: The linked-pipeline change is the one most likely to surprise CI. If your pipeline runs `cargo build`, switch it to `cargo proa build`. See [CI / GitHub Actions](/docs/guides/ci).

## When an upgrade breaks the build

Work in this order, because each step rules out the next:

1. **Read the changelog entry** for every version you crossed. Breaking changes are marked.
2. **Run `cargo proa check`**, not `cargo check`. Template lints and linker errors only appear in the former.
3. **Check the RSJS boundary.** Most post-0.3 breakage is a component that used to be implicitly analysed and now needs an explicit `#[rsjs(component)]` or `#[rsjs(component, client)]`.
4. **Check your buffer.** If a custom writer stopped compiling, move to `RenderBuffer`.
5. **Search [Troubleshooting](/docs/guides/troubleshooting)** for the exact diagnostic text.

## Next steps

- [Troubleshooting](/docs/guides/troubleshooting)
  - Fix the most common Proa setup, registry, template, component, island, routing, and CI failures.
- [CI / GitHub Actions](/docs/guides/ci)
  - Gate pull requests with proa check, then deploy from the same pipeline.
- [HTML rendering](/docs/core/html-rendering)
  - Render typed Rust values to HTML with render traits and the html! macros.
- [WriteBuf](/docs/core/write-buf)
  - Pick the buffer a route renders into.
- [proa fmt / lint / check](/docs/cli/format-lint-check)
  - Format macro bodies, run lints, and gate CI.


---

# Docs: From React / Next.js

URL: /docs/migration/react
Description: Migrate from React SSR or Next.js to Proa one route at a time while keeping your existing CSS and DOM contract.

---
title: From React / Next.js
description: Migrate from React SSR or Next.js to Proa one route at a time while keeping your existing CSS and DOM contract.
---

This guide walks through migrating a single Next.js page to Proa. The approach works with any React SSR setup (Remix, Gatsby SSR, custom Express + React).

## Step 1: Convert the Template

### TSX to html_sync!

The surface syntax is intentionally close to HTML. Main differences: static text is quoted, Rust expressions live in `{...}`, and Rust field names use underscores when you create component structs.

This card covers most of what a migration runs into: required and optional
props, a conditionally rendered element, a list, an either/or, and children.

**React (TSX):**
```tsx filename="components/ListingCard.tsx"
type Badge = "superhost" | "guest-favorite";

interface ListingCardProps {
  imageUrl: string;
  title: string;
  location: string;
  price: number;
  amenities: string[];
  rating?: number;
  badge?: Badge;
  children?: React.ReactNode;
}

export function ListingCard({
  imageUrl,
  title,
  location,
  price,
  amenities,
  rating,
  badge,
  children,
}: ListingCardProps) {
  return (
    <div className="flex gap-4 rounded-xl border p-4">
      <img
        src={imageUrl}
        alt={title}
        className="h-48 w-48 rounded-lg object-cover"
      />
      <div className="flex flex-col">
        <h2 className="text-lg font-semibold">{title}</h2>
        {badge && (
          <span className="w-fit rounded bg-accent px-2 py-1 text-xs">
            {badge === "superhost" ? "Superhost" : "Guest favorite"}
          </span>
        )}
        <p className="text-muted-foreground">{location}</p>
        <ul className="flex gap-2 text-sm">
          {amenities.map((amenity) => (
            <li key={amenity}>{amenity}</li>
          ))}
        </ul>
        <p className="text-sm">{rating ? `★ ${rating}` : "New listing"}</p>
        <p className="mt-auto font-semibold">
          ${price} <span className="font-normal">/ night</span>
        </p>
        {children}
      </div>
    </div>
  );
}
```

**Proa (`html_sync!`):**
```rust
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;

#[derive(Clone, Copy)]
pub enum Badge {
    Superhost,
    GuestFavorite,
}

impl Badge {
    pub const fn label(self) -> &'static str {
        match self {
            Self::Superhost => "Superhost",
            Self::GuestFavorite => "Guest favorite",
        }
    }
}

// Props become struct fields. Optional props are `Option<T>`, and children
// ride on a generic parameter defaulting to `()` for the childless case.
pub struct ListingCard<C = ()> {
    pub image_url: &'static str,
    pub title: &'static str,
    pub location: &'static str,
    pub price: u32,
    pub amenities: &'static [&'static str],
    pub rating: Option<f32>,
    pub badge: Option<Badge>,
    pub children: Option<C>,
}

impl<L, C> WebRenderSync<L> for ListingCard<C>
where
    L: DataLoader,
    C: WebRenderSync<L>,
{
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <div class="flex gap-4 rounded-xl border p-4">
                <img
                    src={self.image_url}
                    alt={self.title}
                    class="h-48 w-48 rounded-lg object-cover"
                />
                <div class="flex flex-col">
                    <h2 class="text-lg font-semibold">{self.title}</h2>
                    // `{badge && ...}` becomes an `if` with no `else` branch
                    {if let Some(badge) = self.badge {
                        html_sync! {
                            <span class="w-fit rounded bg-accent px-2 py-1 text-xs">
                                {badge.label()}
                            </span>
                        }
                    }}
                    <p class="text-muted-foreground">{self.location}</p>
                    // `.map(...)` becomes a `for` loop, and no `key` is needed
                    // because there is no virtual DOM to diff
                    <ul class="flex gap-2 text-sm">
                        {for amenity in self.amenities {
                            html_sync! { <li>{*amenity}</li> }
                        }}
                    </ul>
                    // a ternary becomes an ordinary `if`/`else`
                    <p class="text-sm">
                        {if let Some(rating) = self.rating {
                            html_sync! { "★ "{rating} }
                        } else {
                            html_sync! { "New listing" }
                        }}
                    </p>
                    <p class="mt-auto font-semibold">
                        "$"{self.price}" "
                        <span class="font-normal">"/ night"</span>
                    </p>
                    {self.children}
                </div>
            </div>
        }.render(cx)
    }
}
```

Rendering it from a parent is a struct literal in a slot. Add
`#[derive(Default)]` to the struct if you would rather set a few fields and
finish with `..Default::default()`:

```rust
{ListingCard {
    image_url: listing.image_url,
    title: listing.title,
    location: listing.location,
    price: listing.price,
    amenities: &["Wifi", "Kitchen"],
    rating: listing.rating,
    badge: Some(Badge::Superhost),
    children: Some(text("Book now")),
}}
```

## Step 2: Data Loading

In Next.js, you fetch data in `getServerSideProps` or Server Components. In Proa, a handler can load data before rendering, or a component can use keyed loaders through `cx`. See [Data loading](/docs/framework/data-loading) when independent sections should load concurrently.

**Next.js:**
```typescript filename="pages/listings/[id].tsx"
import type { GetServerSideProps } from "next";

export const getServerSideProps: GetServerSideProps = async ({ params }) => {
  const listing = await db.listings.findById(params!.id as string);
  return { props: { listing } };
};

interface ListingPageProps {
  listing: Listing;
}

export default function ListingPage({ listing }: ListingPageProps) {
  return <ListingDetail listing={listing} />;
}
```

**Proa (Axum):**
```rust
async fn listing_page(
    Path(id): Path<String>,
    State(db): State<DbPool>,
) -> Result<impl IntoResponse, StatusCode> {
    let listing = db.listings.find_by_id(&id).await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?
        .ok_or(StatusCode::NOT_FOUND)?;

    let mut cx = WebContext::new();

    ListingDetail {
        title: &listing.title,
        location: &listing.location,
        price: listing.price,
        image_url: &listing.image_url,
    }
    .render(&mut cx)
    .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(Html(cx.into_output().into_string()))
}
```

## Step 3: Interactive Islands

React components that need client-side interactivity become Proa islands. The HTML is rendered server-side by Proa; the JavaScript hydrates only the interactive parts.

**Next.js (a client component):**
```tsx filename="components/SearchFilters.tsx"
"use client";

import { useState } from "react";

interface Filter {
  id: string;
  label: string;
}

interface SearchFiltersProps {
  filters: Filter[];
}

export default function SearchFilters({ filters }: SearchFiltersProps) {
  const [selected, setSelected] = useState<Filter>(filters[0]);
  return (
    <div>
      {filters.map((f) => (
        <button key={f.id} onClick={() => setSelected(f)}>
          {f.label}
        </button>
      ))}
    </div>
  );
}
```

**Proa (only the interactive part ships JS):**
```rust
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;
use rsjs::{event_handler, signal};
use rsjs_macros::rsjs;

pub struct SearchFilters<'a> {
    pub filters: &'a [&'a str],
}

#[rsjs(component, client)]
impl<'a, L: DataLoader> WebRenderSync<L> for SearchFilters<'a> {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        let selected = signal(0_i64);
        let pick = event_handler(|_: rsjs::Event, index: i64| selected.set(index));

        html_sync! {
            <div class="search-filters">
                {for (index, filter) in self.filters.iter().enumerate() {
                    html_sync! {
                        <button
                            type="button"
                            class={if selected.get() == index as i64 { "filter-btn active" } else { "filter-btn" }}
                            on_click={pick(index as i64)}
                        >
                            {filter}
                        </button>
                    }
                }}
            </div>
        }
        .render(cx)
    }
}
```

The `#[rsjs(component, client)]` attribute analyzes the authored render-trait
implementation, records its signals and event handlers, and emits the island
JavaScript that the runtime hydrates in the browser. Static parts of the page
do not hydrate. See [RSJS](/docs/guides/islands) for the runtime wiring and supported
patterns.


## Step 4: Route One Page to Proa

Set up your reverse proxy to route one path to Proa while keeping everything else on Next.js.

**Nginx example:**

```nginx
upstream nextjs {
    server 127.0.0.1:3000;
}

upstream proa {
    server 127.0.0.1:4000;
}

server {
    listen 80;

    # One route goes to Proa
    location /rooms/ {
        proxy_pass http://proa;
        proxy_set_header Host $host;
        proxy_set_header X-Request-Id $request_id;
    }

    # Everything else stays on Next.js
    location / {
        proxy_pass http://nextjs;
        proxy_set_header Host $host;
    }
}
```

**Cloudflare Workers / Vercel Edge:**

```typescript
export default {
  async fetch(request: Request) {
    const url = new URL(request.url);

    if (url.pathname.startsWith("/rooms/")) {
      url.hostname = "proa-origin.example";
      url.protocol = "https:";
      url.port = "";
      return fetch(new Request(url, request));
    }

    // Everything else to Next.js
    return fetch(request);
  },
};
```


## Step 5: Compare in Production

After deploying the Proa version of one route behind the proxy, compare the route against the existing implementation under the same cache policy and data-loading path:

| Metric | How to measure | What to look for |
|--------|---------------|------------------|
| p50 / p95 / p99 latency | Your APM or load test | Lower server render time and flatter tail latency |
| Throughput | `wrk`, `k6`, or production traffic replay | More completed requests per core at the same error rate |
| CPU usage | Container or host metrics | Lower CPU per rendered response |
| Memory | Container or host metrics | Smaller resident set and less GC pressure on the old service |
| Time to First Byte | WebPageTest, Lighthouse, or RUM | Faster uncached server responses |
| Bundle size | Browser DevTools Network tab | Smaller JS on routes that no longer hydrate a React tree |

```bash
# Same route, same data, same cache policy
wrk -t4 -c100 -d30s http://localhost:3000/rooms/12345
wrk -t4 -c100 -d30s http://localhost:4000/rooms/12345
```

## Shared Layout During Transition

During migration, both stacks need to render the same header/footer. Options:

1. **Port the layout first**, migrate the layout to Proa, then render the moved route inside it.
2. **Shared HTML contract**, keep the same class names, IDs, and data attributes so existing CSS and small scripts continue to work.
3. **Proxy-owned shell**, let the edge or load balancer choose which app handles each path while each app renders its own complete document.

Porting the layout first is usually the cleanest path for high-traffic SSR pages because headers, footers, and navigation often contain long static runs that Proa can consolidate at compile time.


---

# Docs: From Rails (ERB)

URL: /docs/migration/rails
Description: Migrate from Rails ERB templates to Proa, run Proa as a rendering service alongside your Rails app.

---
title: From Rails (ERB)
description: Migrate from Rails ERB templates to Proa, run Proa as a rendering service alongside your Rails app.
---

This guide walks through adding Proa to an existing Rails app. Proa runs as a separate service that renders HTML for specific routes, your Rails app continues handling routing, auth, database queries, and everything else.

## Architecture

```
                    ┌─────────────┐
                    │   Nginx /   │
                    │  CDN / LB   │
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │                         │
     /rooms/* │                         │ everything else
              ▼                         ▼
     ┌────────────────┐       ┌────────────────┐
     │  Proa (Axum)   │       │  Rails (Puma)  │
     │  :4000         │       │  :3000         │
     └────────┬───────┘       └────────┬───────┘
              │                         │
              └────────────┬────────────┘
                           │
                    ┌──────┴──────┐
                    │  Database   │
                    └─────────────┘
```

Both services can connect to the same database or service layer. Proa reads the same data Rails does, then renders the moved route from the Rust service.

## Step 1: Route One Page to Proa

**Nginx:**
```nginx
upstream rails {
    server 127.0.0.1:3000;
}

upstream proa {
    server 127.0.0.1:4000;
}

server {
    listen 80;

    location /rooms/ {
        proxy_pass http://proa;
        proxy_set_header Host $host;
        proxy_set_header X-Request-Id $request_id;
        proxy_set_header Cookie $http_cookie;  # pass auth cookies
    }

    location / {
        proxy_pass http://rails;
        proxy_set_header Host $host;
    }
}
```

## Step 2: Convert the Template

### ERB to html_sync!

**Rails (ERB):**
```erb
<%# app/views/listings/show.html.erb %>
<div class="flex gap-4 rounded-xl border p-4">
  <%= image_tag listing.image_url,
      alt: listing.title,
      class: "h-48 w-48 rounded-lg object-cover" %>
  <div class="flex flex-col">
    <h2 class="text-lg font-semibold"><%= listing.title %></h2>
    <p class="text-muted-foreground"><%= listing.location %></p>
    <p class="mt-auto font-semibold">
      $<%= listing.price %> <span class="font-normal">/ night</span>
    </p>
  </div>
</div>
```

**Proa (`html_sync!`):**
```rust
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;

pub struct ListingDetail<'a> {
    pub title: &'a str,
    pub location: &'a str,
    pub price: u32,
    pub image_url: &'a str,
}

impl<'a, L: DataLoader> WebRenderSync<L> for ListingDetail<'a> {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <div class="flex gap-4 rounded-xl border p-4">
                <img
                    src={self.image_url}
                    alt={self.title}
                    class="h-48 w-48 rounded-lg object-cover"
                />
                <div class="flex flex-col">
                    <h2 class="text-lg font-semibold">{self.title}</h2>
                    <p class="text-muted-foreground">{self.location}</p>
                    <p class="mt-auto font-semibold">
                        "$"
                        {self.price}
                        " "
                        <span class="font-normal">"/ night"</span>
                    </p>
                </div>
            </div>
        }.render(cx)
    }
}
```

### Quick Reference

| Rails ERB | Proa | Notes |
|-----------|------|-------|
| `<%= variable %>` | `{variable}` | Auto-escaped in both |
| `<%== raw_html %>` | `{UnsafeRaw(html)}` | Unescaped, same risk |
| `<%= link_to "text", path %>` | `<a href={path}>"text"</a>` | Direct HTML |
| `<%= image_tag src, alt: "..." %>` | `<img src={src} alt="..." />` | Direct HTML |
| `<% if condition %>` | `{if condition { html_sync! { ... } }}` | DOM branches return renderable fragments |
| `<% items.each do \|item\| %>` | `{for item in &items { html_sync! { ... } }}` | Rust for loop |
| `<%= render partial: "card" %>` | `{Card { ... }}` | Component struct |
| `<%= content_for :head %>` | Layout/Page `render_head` hooks | See [Metadata](/docs/framework/metadata) for managed documents |
| `<%= csrf_meta_tags %>` | App-owned Axum middleware | Configure token issuance and validation explicitly; Proa's default cross-origin protection is not a CSRF-token service |

### Partials → Components

Rails partials map to Proa structs:

```erb
<%# Rails: app/views/listings/_card.html.erb %>
<div class="card">
  <h3><%= card.title %></h3>
  <p><%= card.description %></p>
</div>

<%# Usage: %>
<%= render partial: "card", locals: { card: @listing } %>
```

```rust
// Proa: src/components/card.rs
pub struct Card<'a> {
    pub title: &'a str,
    pub description: &'a str,
}

impl<'a, L: DataLoader> WebRenderSync<L> for Card<'a> {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <div class="card">
                <h3>{self.title}</h3>
                <p>{self.description}</p>
            </div>
        }.render(cx)
    }
}

// Usage in another template:
html_sync! {
    {Card { title: listing.title, description: listing.description }}
}
```

### Layouts

Rails layouts (`application.html.erb`) become Proa layout components:

```rust
pub struct AppLayout<'a, C> {
    pub title: &'a str,
    pub children: C,
}

impl<'a, L, C> WebRenderSync<L> for AppLayout<'a, C>
where
    L: DataLoader,
    C: WebRenderSync<L>,
{
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <!DOCTYPE html>
            <html lang="en">
                <head>
                    <meta charset="utf-8" />
                    <title>{self.title}" - MyApp"</title>
                    <link rel="stylesheet" href="/assets/application.css" />
                </head>
                <body>
                    <header class="navbar">"shared navigation"</header>
                    <main>{self.children}</main>
                    <footer>"shared footer"</footer>
                </body>
            </html>
        }.render(cx)
    }
}
```

This example keeps a manual document head. For managed metadata, adopt the
LAYOUT/PAGE roles and head outlet together; see [Layouts and Pages](/docs/framework/layouts-and-pages).

## Step 3: Data Loading

In Rails, the controller loads data and passes it to the view. In Proa, the Axum handler does the same thing.

**Rails:**
```ruby
class ListingsController < ApplicationController
  def show
    @listing = Listing.find(params[:id])
  end
end
```

**Proa (Axum):**
```rust
async fn listing_show(
    Path(id): Path<i64>,
    State(pool): State<PgPool>,
) -> Result<impl IntoResponse, StatusCode> {
    let listing = sqlx::query_as!(Listing, "SELECT * FROM listings WHERE id = $1", id)
        .fetch_optional(&pool)
        .await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?
        .ok_or(StatusCode::NOT_FOUND)?;

    let mut cx = WebContext::new();

    AppLayout {
        title: &listing.title,
        children: ListingDetail {
            title: &listing.title,
            location: &listing.location,
            price: listing.price,
            image_url: &listing.image_url,
        },
    }
    .render(&mut cx)
    .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(Html(cx.into_output().into_string()))
}
```

## Step 4: Auth / Sessions

Rails sessions are typically cookie-based. Pass the cookie through the proxy and validate it in Proa:

```rust
async fn listing_show(
    headers: HeaderMap,
    Path(id): Path<i64>,
    State(state): State<AppState>,
) -> Result<impl IntoResponse, StatusCode> {
    // Extract and validate the Rails session cookie
    let cookie = headers.get("cookie")
        .and_then(|v| v.to_str().ok())
        .ok_or(StatusCode::UNAUTHORIZED)?;

    let user = validate_rails_session(cookie, &state.secret_key_base)
        .ok_or(StatusCode::UNAUTHORIZED)?;

    let listing = state.db.get_listing(id).await
        .map_err(|_| StatusCode::NOT_FOUND)?;

    // Render with user context
    let mut cx = WebContext::new();
    ListingPage { user: &user, listing: &listing }
        .render(&mut cx)
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(Html(cx.into_output().into_string()))
}
```

Alternatively, use a shared auth service (Redis session store, JWT) that both Rails and Proa can validate.

## Step 5: Shared CSS

If you use Tailwind or another utility CSS framework, keep the same class strings in the Proa templates. The moved route can keep using the existing stylesheet.

If you use the Rails asset pipeline with custom CSS:

1. Build your CSS with the asset pipeline as usual
2. Serve the compiled CSS from a shared path (`/assets/application.css`)
3. Reference the same path in Proa's `<link>` tag

Both services serve the same stylesheet, users see no visual difference.

## Step 6: Compare in Production

```bash
# Load test Rails
wrk -t4 -c100 -d30s http://localhost:3000/rooms/12345

# Load test Proa
wrk -t4 -c100 -d30s http://localhost:4000/rooms/12345
```

Measure the same route under the same cache policy before deciding whether to move more paths:

| Metric | Why it matters |
|--------|----------------|
| p50 / p95 / p99 latency | Shows whether render time and tail latency improved. |
| CPU per response | Captures whether native SSR reduces Puma/Ruby work. |
| Resident memory | Shows how much capacity each instance keeps idle. |
| Error rate under load | Prevents throughput wins from hiding overload failures. |
| TTFB | Confirms users see the server-side improvement. |


---

# Docs: From Python (Django / Flask)

URL: /docs/migration/python
Description: Run Proa as a sidecar and migrate Python routes gradually.

---
title: From Python (Django / Flask)
description: Run Proa as a sidecar and migrate Python routes gradually.
---

Proa runs as a separate HTTP service, so a Django or Flask app can hand it one route at a time. This page covers [the sidecar service](#running-proa-as-a-sidecar), [an in-process bridge](#going-in-process), [auth and sessions](#sharing-auth-and-sessions), and [measuring the result](#comparing-in-production).

## Running Proa as a sidecar

The sidecar approach has two halves:

- **Sidecar service**: Proa runs as a separate HTTP service, and your proxy routes selected paths to it.
- **Shared data and auth**: both services read from the same database or service layer, and the proxy forwards the auth context Proa needs.

Your Python app keeps serving every other route while you migrate.

### Architecture

```text filename="Request routing"
                    ┌─────────────┐
                    │   Nginx /   │
                    │  Gunicorn   │
                    └──────┬──────┘
                           │
              ┌────────────┴────────────┐
              │                         │
     /rooms/* │                         │ everything else
              ▼                         ▼
     ┌────────────────┐       ┌──────────────────┐
     │  Proa (Axum)   │       │  Django / Flask   │
     │  :4000         │       │  :8000            │
     └────────┬───────┘       └────────┬──────────┘
              │                         │
              └────────────┬────────────┘
                           │
                    ┌──────┴──────┐
                    │  Database   │
                    └─────────────┘
```

### Nginx config

```nginx filename="/etc/nginx/nginx.conf"
upstream python {
    server 127.0.0.1:8000;
}

upstream proa {
    server 127.0.0.1:4000;
}

server {
    listen 80;

    location /rooms/ {
        proxy_pass http://proa;
        proxy_set_header Host $host;
        proxy_set_header X-Request-Id $request_id;
        proxy_set_header Cookie $http_cookie;
    }

    location / {
        proxy_pass http://python;
        proxy_set_header Host $host;
    }
}
```

### Converting the template

#### Jinja2 to html_sync!

Django with Jinja2:

```html filename="templates/listings/detail.html"
{# templates/listings/detail.html #}
{% extends "base.html" %}
{% block content %}
<div class="flex gap-4 rounded-xl border p-4">
  <img src="{{ listing.image_url }}"
       alt="{{ listing.title }}"
       class="h-48 w-48 rounded-lg object-cover">
  <div class="flex flex-col">
    <h2 class="text-lg font-semibold">{{ listing.title }}</h2>
    <p class="text-muted-foreground">{{ listing.location }}</p>
    <p class="mt-auto font-semibold">
      ${{ listing.price }}
      <span class="font-normal">/ night</span>
    </p>
  </div>
</div>
{% endblock %}
```

The same markup in `html_sync!`:

```rust filename="src/components/listing_detail.rs"
use proa::{DataLoader, WebContext, WebRenderSync, WriteError};
use proa::html_sync;

pub struct ListingDetail<'a> {
    pub title: &'a str,
    pub location: &'a str,
    pub price: u32,
    pub image_url: &'a str,
}

impl<'a, L: DataLoader> WebRenderSync<L> for ListingDetail<'a> {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <div class="flex gap-4 rounded-xl border p-4">
                <img
                    src={self.image_url}
                    alt={self.title}
                    class="h-48 w-48 rounded-lg object-cover"
                />
                <div class="flex flex-col">
                    <h2 class="text-lg font-semibold">{self.title}</h2>
                    <p class="text-muted-foreground">{self.location}</p>
                    <p class="mt-auto font-semibold">
                        "$"
                        {self.price}
                        " "
                        <span class="font-normal">"/ night"</span>
                    </p>
                </div>
            </div>
        }.render(cx)
    }
}
```

### Quick reference

| Jinja2 / Django | Proa | Notes |
|-----------------|------|-------|
| `{{ variable }}` | `{variable}` | Auto-escaped in both |
| `{{ variable\|safe }}` | `{UnsafeRaw(html)}` | Unescaped: same risk |
| `{% if condition %}` | `{if condition { html_sync! { ... } }}` | DOM branches return renderable fragments |
| `{% for item in items %}` | `{for item in &items { html_sync! { ... } }}` | Rust for loop |
| `{% include "partial.html" %}` | `{PartialComponent { ... }}` | Component struct |
| `{% extends "base.html" %}` | Layout component wrapping children | Composition, not inheritance |
| `{% block content %}` | Generic children parameter | `pub children: C` |
| `{{ variable\|truncatewords:30 }}` | Compute before render | Pre-process data in the handler |
| `{% url 'listing_detail' pk=id %}` | Hardcode or use a URL builder | No template-level URL resolution |
| `{% csrf_token %}` | App-owned Axum middleware | Configure token issuance and validation explicitly; Proa's default cross-origin protection is not a CSRF-token service |

### Template inheritance to composition

Jinja2 uses inheritance (`{% extends %}`). Proa uses composition, where a layout component wraps children:

```html filename="templates/base.html"
{# base.html #}
<!DOCTYPE html>
<html lang="en">
<head><title>{% block title %}{% endblock %} - MyApp</title></head>
<body>
  <nav>...</nav>
  {% block content %}{% endblock %}
  <footer>...</footer>
</body>
</html>

{# detail.html #}
{% extends "base.html" %}
{% block title %}{{ listing.title }}{% endblock %}
{% block content %}
  <h1>{{ listing.title }}</h1>
{% endblock %}
```

Proa:

```rust filename="src/layouts/app.rs"
pub struct AppLayout<'a, C> {
    pub title: &'a str,
    pub children: C,
}

impl<'a, L, C> WebRenderSync<L> for AppLayout<'a, C>
where
    L: DataLoader,
    C: WebRenderSync<L>,
{
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <!DOCTYPE html>
            <html lang="en">
                <head>
                    <title>{self.title}" - MyApp"</title>
                </head>
                <body>
                    <nav>"..."</nav>
                    {self.children}
                    <footer>"..."</footer>
                </body>
            </html>
        }.render(cx)
    }
}

// Usage in handler:
AppLayout {
    title: listing.title,
    children: ListingDetail { ... },
}
```

### Loading data

Django:

```python filename="listings/views.py"
def listing_detail(request, listing_id):
    listing = get_object_or_404(Listing, pk=listing_id)
    return render(request, "listings/detail.html", {"listing": listing})
```

Flask:

```python filename="app.py"
@app.route("/rooms/<int:listing_id>")
def listing_detail(listing_id):
    listing = Listing.query.get_or_404(listing_id)
    return render_template("listings/detail.html", listing=listing)
```

Proa with Axum:

```rust filename="src/routes/listings.rs"
async fn listing_detail(
    Path(listing_id): Path<i64>,
    State(pool): State<PgPool>,
) -> Result<impl IntoResponse, StatusCode> {
    let listing = sqlx::query_as!(
        Listing,
        "SELECT * FROM listings WHERE id = $1",
        listing_id
    )
    .fetch_optional(&pool)
    .await
    .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?
    .ok_or(StatusCode::NOT_FOUND)?;

    let mut cx = WebContext::new();

    AppLayout {
        title: &listing.title,
        children: ListingDetail {
            title: &listing.title,
            location: &listing.location,
            price: listing.price,
            image_url: &listing.image_url,
        },
    }
    .render(&mut cx)
    .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(Html(cx.into_output().into_string()))
}
```

The layout above uses a manual head. To adopt managed metadata, follow
[Layouts and Pages](/docs/framework/layouts-and-pages) and migrate roles and
the outlet together.

The sidecar costs one HTTP hop per migrated route. Remove it only when profiling says it matters.

## Going in-process

Start with the sidecar unless the HTTP hop shows up in profiling. A PyO3 extension crate can host Proa in-process, but Proa ships no generic `proa-python` package in this workspace.

Treat that path as application-specific integration work:

- Define a narrow Rust function per migrated render path.
- Render into `RenderBuffer` and convert the bytes to a Python `str` at the boundary.
- Keep auth, database access, and error handling in the Python app.

Either boundary raises the same question: how does Proa learn who the user is?

## Sharing auth and sessions

Django keeps sessions in a database or cache backend. Three options connect Proa to them:

1. **Shared session backend**: point both Django and Proa at the same Redis or PostgreSQL session store.
2. **JWT**: Django issues a JWT on login, and Proa validates it independently.
3. **Proxy header**: Nginx validates the Django session cookie and passes user info as headers to Proa.

Option 3 is simplest for migration:

```nginx filename="/etc/nginx/nginx.conf"
# In the Proa location block:
location /rooms/ {
    # First, authenticate with Django
    auth_request /auth/validate;
    auth_request_set $user_id $upstream_http_x_user_id;

    proxy_pass http://proa;
    proxy_set_header X-User-Id $user_id;
}

location = /auth/validate {
    internal;
    proxy_pass http://python/api/auth/validate;
    proxy_set_header Cookie $http_cookie;
}
```

With one route served and authenticated, measure it against the Python original.

## Comparing in production

```bash filename="Terminal"
# Load test Django/Flask
wrk -t4 -c100 -d30s http://localhost:8000/rooms/12345

# Load test Proa sidecar
wrk -t4 -c100 -d30s http://localhost:4000/rooms/12345
```

Measure the same route under the same cache policy before deciding whether to move more paths:

| Metric | Why it matters |
|--------|----------------|
| p50 / p95 / p99 latency | Shows whether render time and tail latency improved. |
| CPU per response | Captures whether native SSR reduces Python worker time. |
| Resident memory | Shows how much capacity each worker keeps idle. |
| Error rate under load | Prevents throughput wins from hiding overload failures. |
| TTFB | Confirms users see the server-side improvement. |

## Next steps

- [Routes and layouts](/docs/framework/routing)
  - Map the paths your proxy forwards onto Proa routes.
- [HTML rendering](/docs/core/html-rendering)
  - Write the components that replace each template.
- [Cross-origin and CSRF](/docs/framework/cross-origin)
  - Set the origin policy for forms that now post to Proa.
- [Deploy](/docs/framework/deployment)
  - Run the sidecar next to Gunicorn in production.


---

# Docs: All commands

URL: /docs/cli
Description: The main proa subcommands, and where each one is explained.

---
title: All commands
description: The main proa subcommands, and where each one is explained.
---

The Proa CLI is developer tooling for Proa templates and opinionated Proa sites. It scaffolds projects, generates typed Rust modules, formats template macro bodies, runs Proa-specific lints, inspects site structure, and reports how HTML and XML macro bodies consolidate into static byte runs.

## Install

Install the latest stable CLI from crates.io.
[Install Proa](/docs#1-install-proa) walks through the complete setup:

```bash
cargo install proa-cli --locked
```

No GitHub credential or Cargo publishing token is required.

Then confirm the binary is on your path:

```bash
proa --help
```

Cargo installs both `proa` and `cargo-proa`. Select an exact published version
for reproducible installation:

```bash
cargo install proa-cli --version '=0.2.0' --locked --force
```

Generated project builds resolve Proa crates from crates.io and use `Cargo.lock` for reproducibility. Follow [Installation](/docs) if Cargo cannot download dependencies. When working from this repository, use:

```bash
cargo run -p proa-cli --bin proa -- <command>
```

## Update

Update the CLI using the tool that installed it:

```bash
proa update
```

Preview the latest stable version without changing files, or select an exact
stable release:

```bash
proa update --check
proa update --version 0.1.3
proa update --build-from-source
```

`cargo proa update` works too. Proa identifies the installation before updating:

- **Standalone installer:** downloads and runs the official installer. It
  verifies SHA256, checks both binaries, and switches one pointer to a complete
  versioned bundle. Existing processes keep using the previous bundle.
- **Cargo:** lets Cargo update its own installation and records. On Unix,
  Proa hands the process over to Cargo. On Windows, it prints the exact
  PowerShell command to run after Proa exits, then exits without installing.
  This avoids locked executables.
- **Unknown or debug installation:** refuses to overwrite it and provides
  manual upgrade guidance. `--check` remains available in debug builds.

An explicit `--version` can reinstall the same release or downgrade; the
default command never downgrades to an older stable release. Prerelease and
main snapshot versions are rejected; use the installer to select a snapshot.

The updater uses Proa's CLI release metadata and verifies SHA256 checksums
before installing prebuilt binaries. If no archive exists for a standalone
installation, it builds the exact selected release from crates.io in private
staging. This requires Cargo and can take several minutes. Both binaries must
report the requested version before the bundle becomes current.

Checksum verification trusts Proa's HTTPS release channel; it does not yet
verify an independent publisher signature.

Standalone executable staging stays on the installation filesystem to support
hosts where the system temporary directory does not allow execution. Update
logs stay in the installation root after staging is cleaned up. Set `PROA_LOG`
to choose a log path, or `PROA_LOG=off` to disable logging.

Use `--build-from-source` when a prebuilt binary cannot run on your system,
such as a Linux distribution with an older glibc. This bypasses archive
downloads and builds the selected release with your local toolchain.

Older CLIs without `update` need one upgrade through the installer or
`cargo install proa-cli --locked` before this command is available.

New standalone installations keep releases in a sibling directory named
`<bin-directory>.proa`. On Unix, the two public commands are symlinks through
its `current` pointer. On Windows, a dedicated bin directory is a junction
through `current`; shared directories containing other programs are refused.
Previous bundles remain available for processes that are still running.
Older releases without the bundle publisher can still be installed in their
legacy layout; rerun the installer to migrate once a capable release exists.

## Invocation

The installed binary is `proa`:

```bash
proa dev
```

The package also ships `cargo-proa`, so Cargo can invoke the same command as a subcommand:

```bash
cargo proa fmt --check --verify src
```

## Commands

| Command | Purpose |
|---------|---------|
| `proa update` | Update both CLI binaries; use `--check` to preview or `--version` to select a release. |
| `proa init` | Add `proa.config.json` and `proa.lock.json` to an existing project. |
| `proa config validate` | Check `proa.config.json` for unknown keys, empty commands, and invalid asset definitions. |
| `proa config show` | Print the effective configuration with defaults filled in. |
| `proa new site` | Create an opinionated Proa site, including optional deployment presets such as `--deploy coolify`. |
| `proa dev` | Build configured assets, run the app, restart on project changes, and reload open browser tabs. See [Live reload](/docs/cli/new-site#live-reload). |
| `proa build` | Run Proa checks, build configured assets, and compile the app for deployment. |
| `proa run` | Compile and run one exact Proa binary through the linked RSJS pipeline. |
| `proa test` | Compile and execute one exact test target through the linked RSJS pipeline. |
| `proa generate component` | Generate reusable render components under `src/components`. |
| `proa generate layout` | Generate shared page layouts under `src/layouts`. |
| `proa generate data` | Generate typed data modules under `src/static_data`. |
| `proa registry list` | Print configured component registry aliases. |
| `proa ui add` | Install a source component or block from the Proa UI registries. |
| `proa rsjs explain` | Explain why an rsjs impl emitted browser JS or stayed server-only. |
| `proa rsjs crossings` | Print redacted public data crossing records from rsjs strategy sidecars. |
| `proa site check` | Validate the expected site structure. |
| `proa site routes` | Print page routes discovered from `src/pages`. |
| `proa site doctor` | Alias of `site check` with the same diagnostics. |
| `proa fmt` | Format HTML, XML, and raw `md!` / `md_sync!` template bodies. |
| `proa lint` | Run accessibility, format, composition, content coverage, and render-path lints. |
| `proa check` | Run verified format and lint checks and, for a whole project, the linked RSJS Cargo check. |
| `proa chunks` | Inspect static runs, dynamic slots, and consolidation size estimates. |
| `proa font sync` | Vendor and lock every font declared in code, or verify with `--offline`. |
| `proa font list` | List fonts recorded in `proa-fonts.lock`. |
| `proa completions` | Generate shell completions for the `proa` binary. |

## Project Config

Generated sites include `proa.config.json` and `proa.lock.json`. The config drives lifecycle commands and records component registry aliases:

```json
{
  "$schema": "https://proa.so/schema/proa.config.json",
  "paths": {
    "components": "src/components",
    "assets": "public/proa"
  },
  "registries": {
    "@proa": "https://ui.proa.so/r/{name}.json",
    "@proa-pro": "https://console.proa.so/r/{name}.json"
  },
  "dev": {
    "command": ["cargo", "run"],
    "host": "127.0.0.1",
    "port": 3000,
    "watch": ["src", "styles", "Cargo.toml", "build.rs", "proa.config.json"]
  },
  "build": {
    "command": ["cargo", "build", "--release"],
    "assets": [
      {
        "kind": "tailwind",
        "input": "styles/input.css",
        "output": "public/styles.css"
      }
    ]
  }
}
```

`proa.lock.json` records components installed by `proa ui add`: version, registry, installed files, source hashes, and dependencies.

Use the command override when a project needs a custom server binary:

```bash
proa dev -- cargo run --bin my_app
proa build -- cargo build --release --bin my_app
```

## Output Modes

Several commands support machine-readable output:

| Command | Machine Output |
|---------|----------------|
| `init`, `registry list` | `--json` |
| `config validate`, `ui add` | `--json` |
| `rsjs explain`, `rsjs crossings`, `font list` | `--json` |
| `new site` | `--dry-run --json` |
| `generate *` | `--dry-run json` |
| `site check`, `site routes` | `--json` |
| `lint` | `--json` or `--github` |
| `chunks` | `--json` |

## File Selection

`fmt`, `lint`, `check`, and `chunks` can operate on explicit paths or Git-selected paths:

```bash
proa lint src/pages/home.rs
proa lint --changed --base origin/main
proa check --staged
proa chunks --changed --json
```

Do not combine explicit paths with `--changed`, `--staged`, or `--base`.

## Reference Pages

- [Create a site](/docs/cli/new-site)
- [Generators](/docs/cli/generators)
- [Format, lint, and check](/docs/cli/format-lint-check)
- [Site inspection](/docs/cli/site)
- [Static chunk reports](/docs/cli/chunks)
- [CI usage](/docs/guides/ci)


---

# Docs: proa new site

URL: /docs/cli/new-site
Description: Scaffold an opinionated Proa project.

---
title: proa new site
description: 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:

```bash
proa new site my-app --yes
cd my-app && proa 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 your browser once the server accepts connections.

To study a complete production-shaped application, scaffold ORIGIN:

```bash
proa new site origin-atlas --template origin --yes
```

For a Docker-ready deployment:

```bash
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 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:

```bash
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](https://tailwindcss.com/docs/installation/tailwind-cli),
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:

```bash
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:

```proa-filetree
.cargo/
  config.toml
.github/
  workflows/
    ci.yml
.env.example
Cargo.toml
proa.config.json
proa.lock.json
build.rs
rust-toolchain.toml
README.md
AGENTS.md
src/
  components/
  endpoints/
  layouts/
  pages/
  app.rs
  config.rs
  db.rs
  error.rs
  loader.rs
  main.rs
  routes.rs
  static_assets.rs
migrations/
data/
public/
  favicon.svg
  styles.css
styles/
  input.css
tests/
```

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](/docs/framework/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](/docs/framework/fonts)). |

`proa.config.json` controls the `proa dev` and `proa build` lifecycle commands
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. A stylesheet-only change never restarts the
server: the assets are rebuilt and every stylesheet is re-fetched in place, so
scroll position, form values, and open dialogs survive. 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>` | `300` | Quiet window a change must survive before a rebuild starts. Raise it if a formatter or code generator triggers extra cycles. |

The debounce window cannot go below the 100ms file-watch poll interval. `proa dev` reads no `PROA_DEV_*` variables from your shell.

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 only sees stylesheets under a watched path. `dev.watch` defaults
to `src`, `styles`, `Cargo.toml`, `build.rs`, and `proa.config.json`, so a site
whose only stylesheet is `public/styles.css` (what `--no-tailwind` generates)
needs `public` added to `dev.watch` before edits to it are noticed at all.

When `--deploy coolify` is enabled, the generated project also includes `Dockerfile`, `.dockerignore`, `coolify.env.example`, and `COOLIFY.md`. See [Coolify](/docs/framework/coolify) for the deployment flow and pull request preview URL setup.


---

# Docs: proa generate

URL: /docs/cli/generators
Description: Generate components, layouts, and data modules.

---
title: proa generate
description: Generate components, layouts, and data modules.
---

The generator commands write files into an existing Proa project. By default, they locate the nearest parent directory that contains both `Cargo.toml` and `src/`. Pass `--root` when running from outside the project tree.

## Components

```bash
proa generate component pricing/feature-row --children --recipe
```

This creates module entries under `src/components` and writes either a single component file or a component folder. Generators do not add placeholder tests; add a test when the component has behavior worth protecting.

| Flag | Behavior |
|------|----------|
| `--folder` | Use `components/<name>/mod.rs` plus a sibling implementation file. |
| `--recipe` | Generate `recipe.rs` and a folder layout. |
| `--children` | Add generic `children` support. |
| `--root <DIR>` | Use an explicit project root. |
| `--dry-run [text\|json]` | Print the plan without writing. |
| `--force` | Overwrite generated files. |

Names can include folders. `pricing/feature-row` becomes `src/components/pricing/feature_row.rs` or a folder-backed component when `--folder` or `--recipe` is used.

## Layouts

```bash
proa generate layout marketing-shell --section
proa generate layout root-document --document
```

| Flag | Behavior |
|------|----------|
| `--section` | Generate a section-level wrapper. |
| `--document` | Generate a full document shell. |
| `--root <DIR>` | Use an explicit project root. |
| `--dry-run [text\|json]` | Print the plan without writing. |
| `--force` | Overwrite generated files. |

`--document` and `--section` cannot be combined.

Generated wrappers use manual rendering. For a managed document, add the head
outlet to the document shell and declare `ROLE = LAYOUT`; its selected Page
declares `ROLE = PAGE`. Body-only visual wrappers keep the default `COMPONENT`
role. See [Layouts and Pages](/docs/framework/layouts-and-pages).

## Data Modules

```bash
proa generate data pricing-plans
```

Data modules are written under `src/static_data` and registered in the nearest module file.

## Module Updates

Generators append missing `pub mod ...;` lines to parent `mod.rs` files. Existing matching lines are left in place, so repeated dry runs and repeated generation do not duplicate module exports.

## Safety Workflow

Use this pattern when generating into a project with local edits:

```bash
proa generate component pricing/feature-row --children --recipe --dry-run
proa generate component pricing/feature-row --children --recipe
cargo fmt --all
proa test
```

Only use `--force` when you intend to replace generated files.


---

# Docs: proa fmt / lint / check

URL: /docs/cli/format-lint-check
Description: Format macro bodies, run lints, and gate CI.

---
title: proa fmt / lint / check
description: Format macro bodies, run lints, and gate CI.
---

`rustfmt` formats Rust syntax, but it does not understand Proa template macro bodies. Use `proa fmt` for the inside of `html!`, `html_sync!`, `xml!`, `xml_sync!`, `md!`, and `md_sync!`.

## Format

```bash
proa fmt src
proa fmt --check --verify src
```

| Flag | Behavior |
|------|----------|
| `--check` | Do not write files. Print a unified diff and exit non-zero if formatting differs. |
| `--verify` | Reparse formatted output and verify the template tree stayed structurally identical. Always on when writing; this flag adds the pass to `--check` runs. |
| `--no-verify` | Skip the render-preserving verification before rewriting files. |

Use `--check --verify` in CI and before large render-path changes.

For multiline raw Markdown templates, the formatter removes excess common source indentation and places the closing macro brace on its own line at the invocation's indentation:

```rust
md_sync! { r###"
    # {self.title}

    {self.body}
    "###
}
```

`--verify` compares the dedented Markdown semantics before writing, so changing source alignment cannot silently change the rendered document. `proa lint` reports noncanonical raw-template layout as `format/markdown-layout`.

## Lint

```bash
proa lint src
proa lint --deny-warnings src
proa lint --json --min-severity info src
proa lint --github --changed --base origin/main
```

The linter checks template formatting, accessibility-sensitive markup, render-path performance, component composition, content coverage across render targets, and `rsjs` slot restrictions.

| Flag | Behavior |
|------|----------|
| `--deny-warnings` | Exit non-zero when warnings are found. |
| `--deny <LEVEL_OR_CODE>` | `--deny warnings` is the equivalent warning-deny mode; a diagnostic code such as `--deny render/content-coverage` fails the run when that code is found. Repeatable. Denied codes are printed even below `--min-severity`. |
| `--json` | Emit stable JSON diagnostics. |
| `--github` | Emit GitHub Actions annotations. |
| `--min-severity error\|warning\|info` | Control printed diagnostics. Text defaults to warnings and errors. JSON and GitHub output default to all diagnostics. |
| `--include-tests` | Include Rust test files and `#[cfg(test)]` modules. |
| `--content-summary` | Report paired, unpaired, and whole-view-exempt content status as informational diagnostics. Use `--min-severity info` to show them in text output. |
| `--root <PATH>` | Select the project root for content counterpart discovery and RSJS strategy sidecars. Defaults to the nearest Cargo workspace/package or `proa.config.json`. |

### Content coverage

A component can render a field or child in HTML and accidentally leave it out of
Markdown. Both views still compile. Content coverage compares supported rendered
contributions across the component's views and points to the missing content.
Reading a field, constructing a child, or creating an unused template does not
count as rendering it.

The default policy checks HTML → Markdown when both views exist for the same
component. Sync and async implementations belong to the same logical target
family. HTML-only and Markdown-only components are valid; neither needs an
exception. Other targets can be registered through the content-analysis API;
a trait name ending in `Render` does not register it automatically.

Start by showing informational diagnostics and discovery status:

```bash
proa lint src --min-severity info
proa lint src --content-summary --min-severity info
```

The summary distinguishes **paired**, **unpaired**, and **exempt** views.
“Paired” means the views were discovered; it does not certify equivalent content.
An opaque helper or different presence condition can leave a contribution
**unchecked** even when its views are paired.

#### Context and loader usage

Content coverage follows values into the rendered body. It does not require
matching `cx` accesses, loader queries, cache operations, or metadata setup.
Known `proa::WebContext` preparation APIs and supported metadata aliases do
not create content obligations or unchecked-body diagnostics on their own.
An unused fetch does not cover missing content.

Loaded data is compared by its query and payload type, not local variable names.
Rendered helpers are compared by their inputs: `status_badge(self.stock)` and
`status_text(self.stock)` both use `self.stock` and need no markers. Ordinary
`text!()` literals and arguments, shared constants, and dereferences are also
tracked. Passing an input does not prove that the helper displays it; this is a
best-effort check, not a guarantee of equivalent output or repetition. Opaque
output and direct writer calls can remain **unchecked**, reported as information
rather than requiring annotations. Definite omissions still fail the check.
Custom methods merely named `load` are not treated as known Proa preparation.
Response headers, head assets, and telemetry are outside this body-content check.

#### Intentional omissions: put the marker inside the checked view

Import `omit` at file scope in the file containing the view that leaves content
out. Put the invocation **inside its render method, before the template**.
For HTML → Markdown, that is `MdRenderSync::render_md` or `MdRender::render_md`.
If the views live in separate files, edit the file containing the Markdown impl.

This complete `src/components/product.rs` deliberately keeps the image in HTML:

```rust
use proa::{MdRenderSync, WebContext, WebRenderSync, WriteError};
use proa::{html_sync, md_sync, omit};

struct Product<'a> {
    title: &'a str,
    image: &'a str,
}

impl WebRenderSync for Product<'_> {
    fn render(self, cx: &mut WebContext) -> Result<(), WriteError> {
        html_sync! {
            <article data-product>
                <h1>{self.title}</h1>
                <img src={self.image} alt="" />
            </article>
        }
        .render(cx)
    }
}

impl MdRenderSync for Product<'_> {
    fn render_md(self, cx: &mut WebContext) -> Result<(), WriteError> {
        omit!(self.image, "Image is only shown in HTML");
        md_sync! { r###"# {self.title}"### }.render_md(cx)
    }
}
```

The reason is optional. The value must type-check, but the marker does not
evaluate or move it. Future HTML additions still get checked. Bare paths select
child types; use a Rust borrow (`&image`) to select a local value. Put a local's
marker after its declaration and before it is moved. For example,
replace the Markdown impl above with:

```rust
impl MdRenderSync for Product<'_> {
    fn render_md(self, cx: &mut WebContext) -> Result<(), WriteError> {
        let image = self.image;
        omit!(&image, "Image is only shown in HTML");
        md_sync! { r###"# {self.title}"### }.render_md(cx)
    }
}
```

An existing child local works the same way. When the HTML view renders a child
that has no local in Markdown, select its type directly. For a product whose
HTML view renders `RestockNotice`, this could live
in `src/views/product_markdown.rs`, with the types imported from `crate::product`.
That module must expose the product's `title` and the notice type:

```rust
use proa::{MdRenderSync, WebContext, WriteError};
use proa::{md_sync, omit};
use crate::product::{Product, RestockNotice};

impl MdRenderSync for Product<'_> {
    fn render_md(self, cx: &mut WebContext) -> Result<(), WriteError> {
        omit!(RestockNotice<'_>, "Browser-only notice");
        md_sync! { r###"# {self.title}"### }.render_md(cx)
    }
}
```

This is an alternative example for that product, rather than another impl to add
alongside the earlier one. The macro checks the type without constructing a child.
Use `omit!(RestockNotice)` for a type without generic arguments. Lifetime-only child
types can use `'_`. For type/const-generic children, or several occurrences with
different inputs or conditions, use an existing child local to narrow the exception. A field used by several distinct children is ambiguous
and waives none of their contributions.

String selectors select literal copy, for example
`omit!("Loading", "Visual loading indicator")`. Use a field, child type, or
borrowed local for dynamic content. The source renderer needs no labels.

#### Exempt a whole view

To intentionally exclude a whole view, including future additions, put the
attribute **above its impl**:

```rust
#[proa::content(skip, reason = "This view is a brief summary")]
impl MdRenderSync for Product<'_> {
    fn render_md(self, cx: &mut WebContext) -> Result<(), WriteError> {
        proa::md_sync! { r###"# {self.title}"### }.render_md(cx)
    }
}
```

Alternatively, put the attribute **above the render method inside the impl**:

```rust
impl MdRenderSync for Product<'_> {
    #[proa::content(skip)]
    fn render_md(self, cx: &mut WebContext) -> Result<(), WriteError> {
        proa::md_sync! { r###"# {self.title}"### }.render_md(cx)
    }
}
```

Both placements exempt the view's pair checks, including omission-marker checks.
The reason is optional. A parent's exemption does not exempt its child's own
paired views.

HTML-only and Markdown-only components need no exceptions. Content is compared
when both views exist; the linter does not require another render implementation.
Separate representation types can pair explicitly with
`#[proa::content(source = HtmlProduct, from = "html")]` above the Markdown
impl. This explicitly pairs their rendered field names and shared inputs; the
author is responsible for those fields having corresponding meanings.

#### Diagnostics and CI enforcement

Diagnostics name the component and missing contribution, show source frames for
both views, and suggest a repair at the correct location. Omissions are explicit
author decisions; the linter never inserts them automatically.

For example, removing the `omit!` line from the complete product above reports:

```text
error[render/content-coverage]: `Product<'_>`'s Markdown view does not render `self.image` from its HTML view
  --> src/components/product.rs:23:9
    |
 22 |     fn render_md(self, cx: &mut WebContext) -> Result<(), WriteError> {
 23 |         md_sync! { r###"# {self.title}"### }.render_md(cx)
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ this view does not render the contribution
 24 |     }
 25 | }
    |
  ::: src/components/product.rs:14:27
    |
 13 |                 <h1>{self.title}</h1>
 14 |                 <img src={self.image} alt="" />
    |                           ---------- `self.image` rendered in HTML
 15 |             </article>
 16 |         }
    |
   = help: render `self.image` in the Markdown view
   = help: to omit it intentionally, add this inside the render method before its template
           proa::omit!(self.image);
```

| Diagnostic | Meaning and repair |
|------------|--------------------|
| `render/content-coverage` | A supported rendered contribution is missing. Render it in the checked view or acknowledge the intentional omission with `omit!`. |
| `render/content-coverage-unchecked` | Coverage is uncertain. Opaque output is informational; differing presence conditions or ambiguous view discovery remain warnings. |
| `render/content-omit-stale`, `render/content-omit-redundant` | The source no longer contributes the selected content, or the checked view now renders it. Remove the marker. |
| `render/content-omit-ambiguous`, `render/content-omit-unresolved`, `render/content-policy-invalid` | Narrow the selector, fix its resolution, or correct the policy. |

Missing content (`render/content-coverage`) is an error and fails `proa lint`
by default. Opaque output is informational: view it with `--min-severity info`,
`--json`, or `--github`; it does not fail `--deny-warnings`. Different presence
conditions and ambiguous discovery remain warnings. `proa check` and lifecycle
source checks reject errors and warnings; `--allow-warnings` permits warnings
while still rejecting missing content.
Use `omit!` to acknowledge an intentional difference.

```bash
proa lint src/components/product --deny-warnings
```

Paired, unpaired, and exempt discovery status stays informational. The four
omission-marker hygiene codes also remain informational; deny them individually
when enforcing exception hygiene.
Denied codes are printed even at the default warning threshold; `--deny` changes
exit status without changing a diagnostic's printed severity. `--json` includes
related ranges and structured suggestions. `--github` includes counterpart
locations and repair guidance in Actions annotations.

The checker follows supported output contributions, rather than proving
equivalent meaning, order, cardinality, or accessibility across formats. See
the [content coverage authoring reference](https://github.com/Proa-Labs/proa/blob/main/docs/agent/content-coverage.md)
for supported analysis, explicit source pairs, scoped source selectors, and
future target registration.

## Changed Files

`lint` supports Git-based file selection:

```bash
proa lint --changed
proa lint --base origin/main
proa lint --staged
```

`--base <REF>` implies changed-file selection against that ref. `--staged` cannot be combined with `--changed` or `--base`.

For content coverage, selected files determine which pairs are reported; analysis
also loads unchanged counterparts from their enclosing Cargo packages. A pair's
diagnostic is reported when either view is selected. `--staged` reads the selected
paths' working-tree contents, rather than Git index snapshots. Deleted paths are
excluded from Git selection; use a full source scan when the only change deletes
a view.

## Suppressions

For intentional content differences, use the [targeted omission or whole-view
exemption](#intentional-omissions-put-the-marker-inside-the-checked-view) above.

Performance suppressions must include a reason:

```rust
// proa-perf-ok: static SVG is trusted and emitted as raw markup
StaticRaw(ICON_HTML).render(cx)
```

For an item-level suppression, put the scoped marker directly above the item:

```rust
// proa-perf-ok(scope): integration shim allocates outside request render paths
fn render_legacy_fragment(...) { ... }
```

Use suppressions for intentional low-level cases only. Prefer restructuring the component when the lint points to render-path allocation or avoidable copying.

## Check

`proa check` combines `fmt --check --verify` and `lint`, then fails on formatting differences, errors, or warnings (pass `--allow-warnings` to report warnings without failing):

```bash
proa check src
proa check --changed --base origin/main
proa check --staged
```

With explicit paths or Git selection, `check` runs only those source checks. Run with no file selection, it scans the project's `src` and then also runs the linked RSJS Cargo check of the whole project. The Cargo flags (`-p`, `--bin`, `--profile`, `--target`, `--features`, `--all-features`, `--no-default-features`, `--locked`, `--offline`) select the one exact target the linked check compiles; in a multi-package workspace pass `-p` or `--bin` explicitly. Pass `--source-only` to run only the formatter and lints; Cargo flags cannot be combined with file selection or `--source-only`.

Use `check` for local pre-push validation and CI. Use `fmt` or `lint` directly when you need write mode, JSON diagnostics, GitHub annotations, or severity filtering.


---

# Docs: proa site

URL: /docs/cli/site
Description: Validate site structure and print discovered routes.

---
title: proa site
description: 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.

```bash
proa site check
proa site routes
```

## Command Summary

| Command | Use it when | Exit behavior |
|---------|-------------|---------------|
| `proa site check` | You want structural diagnostics for the generated site layout. | Exits non-zero when errors are present. |
| `proa site doctor` | You want the same diagnostics using the diagnostic command name. | Same implementation and exit behavior as `site check`. |
| `proa site routes` | You want the routes the generated site registers, without running it. | Exits zero when route discovery succeeds, even when no routes are found. |

## Check

```bash
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:

```text
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:

```bash
proa site check --json > proa-site-check.json
```

The JSON report has a stable shape:

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

Example failures:

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

## Doctor

```bash
proa site doctor
proa site doctor --json
```

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

## Routes

```bash
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:

```text
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:

```json
[
  {
    "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`:

| File | Route |
|------|-------|
| `src/pages/home.rs` | `/` |
| `src/pages/index.rs` | `/` |
| `src/pages/pricing.rs` | `/pricing` |
| `src/pages/docs/index.rs` | `/docs` |
| `src/pages/docs/getting_started.rs` | `/docs/getting-started` |

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:

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

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

```bash
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:

```bash
cargo fmt --all --check
proa check
proa site check
proa test
```

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

```bash
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.


---

# Docs: proa chunks

URL: /docs/cli/chunks
Description: Inspect static runs and dynamic slots.

---
title: proa chunks
description: Inspect static runs and dynamic slots.
---

`proa chunks` estimates how `html!`, `html_sync!`, `xml!`, and `xml_sync!` macro bodies split into consolidated static byte runs and dynamic slots. Use it when tuning hot SSR routes or reviewing a template that changed unexpectedly.

A leading `<?xml version="1.0" encoding="UTF-8"?>` declaration joins the adjacent static markup; it does not add a dynamic slot.

```bash
proa chunks src/pages/home.rs
proa chunks src/components
proa chunks --json src/pages/home.rs
```

## Report Fields

| Field | Meaning |
|-------|---------|
| `runs` | Number of consolidated static byte runs. |
| `static_bytes` | Estimated bytes across all static runs. |
| `largest_run` | Estimated size of the largest static run. |
| `text_slots` | Dynamic child/text slots such as `{child}`. |
| `attr_slots` | Dynamic attribute slots such as `class={classes}`. |

Dynamic text and attribute slots create run boundaries. Fewer, larger static runs generally render faster because more bytes can be copied as consolidated static segments.

## Example

```bash
proa chunks src/pages/home.rs
```

Text output includes one row per discovered macro body:

```text
macro (file:line)                                runs       static      largest  txt{} attr{}
src/pages/home.rs:18 html_sync!                     4         420B         180B      1      2
```

Use `--json` when feeding the output to scripts or dashboards.

## Changed Files

`chunks` uses the same Git file-selection flags as `lint` and `check`:

```bash
proa chunks --changed --base origin/main
proa chunks --staged --json
```

The report scans HTML and XML macros in Rust files. Markdown and unrelated macro dialects are not included.

## How To Use The Numbers

- Treat byte counts as estimates, not exact macro expansion output.
- Look for templates where small dynamic expressions split large static regions.
- Hoist invariant text and attribute values into literals where practical.
- Keep correctness first when deciding whether to reduce dynamic slots.


---

# Docs: FFI guide

URL: /docs/ffi
Description: Call Proa's SSR engine from Python, Ruby, Go, or any language with C FFI support

---
title: FFI guide
description: Call Proa's SSR engine from Python, Ruby, Go, or any language with C FFI support
---


Proa compiles HTML templates into optimized byte sequences at build time. The playground FFI library exposes selected showcase renders as plain C functions so Python, Ruby, Go, C, and other host runtimes can call them without embedding a JavaScript SSR server.

## What's in the package


```proa-filetree
proa-playground-<target>/
  proa-playground
  run.sh
  ffi/
    libproa_demo.dylib
    proa.h
```


| File | Description |
|------|-------------|
| `proa-playground` | Interactive demo server |
| `run.sh` | Launch script (`run.bat` on Windows) |
| `libproa_demo.dylib` | FFI shared library (`.so` on Linux, `.dll` on Windows) |
| `proa.h` | C header |
| `Dockerfile` | Add the [Packaging example](/docs/ffi/packaging#docker) for a Linux container |

## Docker

Use the **Linux x86_64 download**, even when building on macOS or Windows.
Add the [Dockerfile from Packaging](/docs/ffi/packaging#docker) to the extracted
Linux package; that archive currently omits it. Then run:

```bash
docker build --platform linux/amd64 -t proa/playground .
docker run --rm --platform linux/amd64 -p 127.0.0.1:3001:3001 proa/playground
```

Open `http://localhost:3001`. The image includes Node and Bun for the comparison
engines. A native macOS or Windows executable cannot run in this Linux image.

## API at a glance

Every render function follows one of two patterns.

### Allocating

The library allocates the output buffer. You must free it with `proa_free`.

```c
int32_t render_airbnb_home(uint8_t **out_ptr, uintptr_t *out_len);
void proa_free(uint8_t *ptr, uintptr_t len);
```

Returns `0` on success. The HTML is UTF-8 encoded at `*out_ptr` with length `*out_len`.

### Caller-provided buffer

You provide a pre-allocated output buffer and the library copies the rendered HTML into it.

```c
int32_t render_airbnb_home_into(uint8_t *buf_ptr, uintptr_t buf_cap, uintptr_t *out_len);
```

Returns `0` on success, `-1` if the buffer is too small. When the buffer is too small, `*out_len` receives the required size.

The current demo `_into` functions avoid returning a new FFI-owned allocation, which is useful for host memory management. They are not a guarantee that the demo implementation performs no internal Rust allocation.

### JSON props

Some functions accept custom data as a JSON string:

```c
int32_t render_airbnb_listing_json(
    const uint8_t *json_ptr, uintptr_t json_len,
    uint8_t **out_ptr, uintptr_t *out_len
);
```

Returns `0` on success, `-2` if the JSON is invalid.

### Available functions

| Function | Description |
|----------|-------------|
| `render_airbnb_home` | Airbnb home page |
| `render_airbnb_search` | Airbnb search results |
| `render_airbnb_listing` | Airbnb listing detail |
| `render_airbnb_listing_json` | Airbnb listing with custom props |
| `render_nike_catalog` | Footwear catalog, the Nike showcase |
| `render_nike_catalog_json` | Footwear catalog with custom props |
| `render_nike_pdp` | Footwear product detail, the Nike showcase |
| `render_nike_pdp_json` | Footwear product detail with custom props |
| `render_*_into` | Caller-provided-buffer variants for default-prop pages |
| `proa_free` | Free a buffer from any allocating render |

## Contract Pages

- [Playground](/docs/ffi/playground) covers the interactive demo, load testing UI, package contents, and API endpoints.
- [ABI contract](/docs/ffi/abi) documents exact signatures, return codes, and WASM helpers.
- [Memory ownership](/docs/ffi/memory) explains when to call `proa_free`, how to size buffers, and what the host owns.
- [Deployment](/docs/ffi/packaging) covers shared-library loading, Docker packaging, and build outputs.

## Python

### Minimal example

```python
import ctypes
import time

lib = ctypes.CDLL("./ffi/libproa_demo.dylib")  # .so on Linux, .dll on Windows

lib.render_airbnb_home.restype = ctypes.c_int32
lib.render_airbnb_home.argtypes = [
    ctypes.POINTER(ctypes.POINTER(ctypes.c_uint8)),
    ctypes.POINTER(ctypes.c_size_t),
]
lib.proa_free.restype = None
lib.proa_free.argtypes = [ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t]

ptr = ctypes.POINTER(ctypes.c_uint8)()
length = ctypes.c_size_t(0)

start = time.perf_counter_ns()
rc = lib.render_airbnb_home(ctypes.byref(ptr), ctypes.byref(length))
if rc != 0:
    raise RuntimeError(f"render_airbnb_home failed: {rc}")
elapsed_us = (time.perf_counter_ns() - start) / 1000

try:
    html = ctypes.string_at(ptr, length.value).decode("utf-8")
finally:
    lib.proa_free(ptr, length)

print(f"Rendered {length.value:,} bytes in {elapsed_us:.1f} µs")
```

### Reusable wrapper

```python
import ctypes
import json as json_mod

class Proa:
    """Thin wrapper around the Proa FFI library."""

    def __init__(self, lib_path="./ffi/libproa_demo.dylib"):
        self._lib = ctypes.CDLL(lib_path)
        self._lib.proa_free.restype = None
        self._lib.proa_free.argtypes = [
            ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t
        ]

        # Register allocating render functions
        for name in [
            "render_airbnb_home", "render_airbnb_search",
            "render_airbnb_listing", "render_nike_catalog", "render_nike_pdp",
        ]:
            fn = getattr(self._lib, name)
            fn.restype = ctypes.c_int32
            fn.argtypes = [
                ctypes.POINTER(ctypes.POINTER(ctypes.c_uint8)),
                ctypes.POINTER(ctypes.c_size_t),
            ]

        # Register JSON render functions
        for name in [
            "render_airbnb_listing_json",
            "render_nike_pdp_json",
            "render_nike_catalog_json",
        ]:
            fn = getattr(self._lib, name)
            fn.restype = ctypes.c_int32
            fn.argtypes = [
                ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t,
                ctypes.POINTER(ctypes.POINTER(ctypes.c_uint8)),
                ctypes.POINTER(ctypes.c_size_t),
            ]

    def _render(self, func_name):
        fn = getattr(self._lib, func_name)
        ptr = ctypes.POINTER(ctypes.c_uint8)()
        length = ctypes.c_size_t(0)
        rc = fn(ctypes.byref(ptr), ctypes.byref(length))
        if rc != 0:
            raise RuntimeError(f"{func_name} failed: {rc}")
        try:
            return ctypes.string_at(ptr, length.value).decode("utf-8")
        finally:
            self._lib.proa_free(ptr, length)

    def _render_json(self, func_name, json_str):
        fn = getattr(self._lib, func_name)
        json_bytes = json_str.encode("utf-8")
        json_ptr = (ctypes.c_uint8 * len(json_bytes))(*json_bytes)
        ptr = ctypes.POINTER(ctypes.c_uint8)()
        length = ctypes.c_size_t(0)
        rc = fn(json_ptr, len(json_bytes), ctypes.byref(ptr), ctypes.byref(length))
        if rc == -2:
            raise ValueError("Invalid JSON")
        if rc != 0:
            raise RuntimeError(f"{func_name} failed: {rc}")
        try:
            return ctypes.string_at(ptr, length.value).decode("utf-8")
        finally:
            self._lib.proa_free(ptr, length)

    def airbnb_home(self):
        return self._render("render_airbnb_home")

    def airbnb_search(self):
        return self._render("render_airbnb_search")

    def airbnb_listing(self, json=None):
        if json is not None:
            return self._render_json("render_airbnb_listing_json", json)
        return self._render("render_airbnb_listing")

    def nike_catalog(self, json=None):
        if json is not None:
            return self._render_json("render_nike_catalog_json", json)
        return self._render("render_nike_catalog")

    def nike_pdp(self, json=None):
        if json is not None:
            return self._render_json("render_nike_pdp_json", json)
        return self._render("render_nike_pdp")
```

Usage:

```python
from pathlib import Path

proa = Proa()

# Static render — default props
html = proa.airbnb_home()

# Custom props via JSON
defaults = json_mod.loads(Path("showcase-props.json").read_text())
listing = defaults["listing"].copy()
listing["title"] = "My Beach House"
listing["nightly_rate"] = 350
html = proa.airbnb_listing(json_mod.dumps(listing))
```

### Caller-provided buffer from Python

To avoid accepting an FFI-owned output allocation, pre-allocate a buffer and reuse it across renders:

```python
buf = (ctypes.c_uint8 * (256 * 1024))()  # Starting capacity; handle -1 below
written = ctypes.c_size_t(0)

lib.render_airbnb_home_into.restype = ctypes.c_int32
lib.render_airbnb_home_into.argtypes = [
    ctypes.POINTER(ctypes.c_uint8), ctypes.c_size_t, ctypes.POINTER(ctypes.c_size_t)
]

rc = lib.render_airbnb_home_into(buf, len(buf), ctypes.byref(written))
if rc == 0:
    html = bytes(buf[:written.value]).decode("utf-8")
elif rc == -1:
    print(f"Buffer too small, need {written.value} bytes")
```

## Ruby

```ruby
require 'fiddle'
require 'fiddle/import'

module Proa
  extend Fiddle::Importer
  dlload './ffi/libproa_demo.dylib'  # .so on Linux

  extern 'int render_airbnb_home(void**, size_t*)'
  extern 'void proa_free(void*, size_t)'
end

ptr = Fiddle::Pointer.new(0)
len = [0].pack('J')

ptr_ref = Fiddle::Pointer[ptr.ref]
len_ref = Fiddle::Pointer[len]

start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond)
rc = Proa.render_airbnb_home(ptr_ref, len_ref)
raise "render_airbnb_home failed: #{rc}" unless rc == 0
elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC, :microsecond) - start

size = len.unpack1('J')
output = Fiddle::Pointer.new(ptr_ref.ptr.to_i)
begin
  html = output.to_str(size).force_encoding('UTF-8')
ensure
  Proa.proa_free(output, size)
end

puts "Rendered #{html.bytesize} bytes in #{elapsed} µs"
```

## C

```c
#include <stdio.h>
#include "ffi/proa.h"

int main(void) {
    uint8_t *ptr;
    size_t len;

    // Allocating variant
    if (render_airbnb_home(&ptr, &len) == 0) {
        printf("Rendered %zu bytes\n", len);
        proa_free(ptr, len);
    }

    // Caller-provided buffer variant: reuse a host buffer across requests
    uint8_t buf[256 * 1024];
    size_t written;
    if (render_airbnb_home_into(buf, sizeof(buf), &written) == 0) {
        printf("Rendered %zu bytes into caller buffer\n", written);
    }

    return 0;
}
```

Compile and run:

```bash
# macOS: normalize the current archive's build-machine install name first.
install_name_tool -id @rpath/libproa_demo.dylib ./ffi/libproa_demo.dylib
cc -o demo demo.c -L./ffi -lproa_demo -Wl,-rpath,@loader_path/ffi

# Linux
cc -o demo demo.c -L./ffi -lproa_demo -Wl,-rpath,'$ORIGIN/ffi'
```

## Go

On macOS, run the `install_name_tool` repair in the C example before linking.
The linker paths below resolve from the Go source directory. See
[Dynamic loader paths](/docs/ffi/packaging#dynamic-loader-paths) for details.

```go
package main

/*
#cgo LDFLAGS: -L${SRCDIR}/ffi -lproa_demo
#cgo darwin LDFLAGS: -Wl,-rpath,${SRCDIR}/ffi
#cgo linux LDFLAGS: -Wl,-rpath,${SRCDIR}/ffi
#include "ffi/proa.h"
#include <stdlib.h>
*/
import "C"
import (
    "fmt"
    "time"
    "unsafe"
)

func renderAirbnbHome() (string, error) {
    var ptr *C.uint8_t
    var length C.uintptr_t

    rc := C.render_airbnb_home(&ptr, &length)
    if rc != 0 {
        return "", fmt.Errorf("render_airbnb_home failed: %d", rc)
    }
    defer C.proa_free(ptr, length)

    bytes := unsafe.Slice((*byte)(unsafe.Pointer(ptr)), int(length))
    return string(bytes), nil
}

func main() {
    start := time.Now()
    html, err := renderAirbnbHome()
    if err != nil {
        panic(err)
    }
    elapsed := time.Since(start)

    fmt.Printf("Rendered %d bytes in %v\n", len(html), elapsed)
}
```

## Measuring an integration

Measure your exact library revision, props, build profile, machine, and host runtime. Keep rendering, JSON decoding, FFI calls, output copying, and deallocation visible as separate costs. The Python example times the allocating FFI call with a wall clock; its copy and UTF-8 decode happen afterward.

Verify the output before timing. Compare allocating and caller-buffer exports with the same inputs, warm up the process, and report repeated samples. The demo's `_into` exports reuse host output storage but still render an intermediate Rust `String`, so they do not establish allocation-free rendering.

## JSON prop schemas

The `_json` variants accept JSON matching the structures in `showcase-props.json` (included in the playground download). Full default props for each page:


- [Airbnb Home](/docs/ffi/examples#travel-home): render_airbnb_home
- [Airbnb Search](/docs/ffi/examples#travel-search): render_airbnb_search
- [Airbnb Listing](/docs/ffi/examples#travel-listing): render_airbnb_listing_json
- [Footwear Catalog](/docs/ffi/examples#catalog): render_nike_catalog_json
- [Footwear Product Detail](/docs/ffi/examples#product-detail): render_nike_pdp_json


---

# Docs: Playground

URL: /docs/ffi/playground
Description: Interactive demo with live editing, benchmarks, and three SSR engines side by side

---
title: Playground
description: Interactive demo with live editing, benchmarks, and three SSR engines side by side
---


The Proa Playground is an interactive environment for exploring Proa's SSR engine. Edit JSON props, see renders update instantly, compare performance against React on Node.js and Bun, and run load tests, all from your browser.

## Getting started

### Download and run

Download the package for your platform from the [Ecosystem Apps](/ecosystem/apps#reference-showcases) page, extract it, and run:

```bash
tar xzf proa-playground-*.tar.gz
cd proa-playground-*
./run.sh
```

The server starts at `http://localhost:3001`.

### Docker

Use the **Linux x86_64 download**, even when building on macOS or Windows.
Add the [Dockerfile from Packaging](/docs/ffi/packaging#docker) to the extracted
Linux package; that archive currently omits it. Then run:

```bash
docker build --platform linux/amd64 -t proa/playground .
docker run --rm --platform linux/amd64 -p 127.0.0.1:3001:3001 proa/playground
```

Open `http://localhost:3001`. The image includes Node and Bun for the comparison
engines. A native macOS or Windows executable cannot run in this Linux image.

## Pages

### Playground (`/playground`)

The main interactive UI. It has three panels:

- **JSON Props editor** (left), edit the data passed to the renderer. Changes apply on the next render.
- **Preview** (right), live HTML output rendered by the selected engine.
- **Stats bar** (top), SSR render time, JSON deserialization time, end-to-end time, and HTML size.

Use the breadcrumb at the top to switch between travel and footwear showcases and pages (Home, Search, Listing, Catalog, Product).

### Reference showcases (`/ecosystem/apps#reference-showcases`)

The Apps page includes reference showcase links for every combination of showcase and engine:

| Showcase | Pages | Engines |
|----------|-------|---------|
| Airbnb | Home, Search, Listing | Proa, Node, Bun |
| Nike | Catalog, Product | Proa, Node, Bun |

Each showcase page lives under `/showcase/...` and is a reference implementation rendered with the selected SSR engine. Links within each page stay within the same engine, clicking the Airbnb logo on a Bun page navigates to the Bun home page, not the Proa one.

### API Docs (`/api/docs`)

Interactive API documentation powered by [Scalar](https://scalar.com). Covers all endpoints with full request/response schemas and per-page JSON examples you can send directly from the browser.

## Engines

The playground runs three SSR engines for comparison:

| Engine | How it works |
|--------|-------------|
| **Proa (Rust)** | Templates compiled to byte sequences at build time. Static markup is consolidated; dynamic values are written directly to the output buffer. |
| **React (Node)** | `renderToString()` served by Hono on Node.js 20+. |
| **React (Bun)** | The packaged React/Hono server running on Bun. |

The native Proa engine runs without Node or Bun. Those runtimes are optional
comparison engines.

### Requirements

| Dependency | Required | Minimum version |
|-----------|----------|----------------|
| Proa binary | Yes | Included in package |
| Node.js | Optional | 20+ |
| Bun | Optional | 1.3+ |
| pnpm | Optional | 9.15.2 (for JS dependency installs) |

The `run.sh` script checks versions and attempts to install JavaScript
dependencies on first launch. Current archives contain an obsolete build-machine
path in the comparison-engine launcher. The [Docker example](/docs/ffi/packaging#docker)
starts those engines explicitly; installing Node or Bun alone does not repair
that archived launcher. The native Proa engine remains available.

## Rendering

### Single render

Click **Render** or press `Ctrl/Cmd+Enter` to render the current page with the JSON props in the editor. The stats bar updates with timing:

- **SSR**, pure template-to-bytes render time (measured server-side)
- **JSON deser**, time to deserialize the JSON props
- **E2E**, total server handler time (deser + render + response build)
- **HTML**, response body size in KB

### Engine switching

Use the engine toggle buttons (Proa, React Node, React Bun) to switch which engine renders the page. The preview updates on the next render. The **Open full page** link opens the showcase page in a new tab for the selected engine.

### curl

Click **Copy curl** to copy a ready-to-use `curl` command for the current page and engine. Run it from your terminal for cleaner timing without browser overhead.

## Load testing

Click **Load Test** to run a benchmark across all three engines. Choose a preset:

| Preset | Requests | Concurrency |
|--------|----------|-------------|
| Light | 500 | 10 |
| Medium | 2,000 | 50 |
| Heavy | 5,000 | 100 |
| Stress | 10,000 | 200 |

The test runs each engine sequentially and reports:

- **SSR Render Time**, pure render, no HTTP (Proa is in-process, Node/Bun measured via response headers)
- **HTTP Roundtrip**, full request-to-response via localhost
- **Throughput**, requests per second
- **Failed requests**, requests that returned errors or timed out

### Accuracy note

Treat playground timings as exploratory measurements. The engines share CPU and compete with the server and browser, so scheduling, warm-up, and instrumentation affect both absolute times and ratios. For performance comparisons, pin versions and inputs, verify equivalent output, and run isolated repeated trials as described in [Performance](/docs/guides/performance).

## API endpoints

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/render` | Render a page. Body: `{"page": "listing", "props": {...}}` |
| `POST` | `/api/loadtest` | Run load test. Body: `{"page": "listing", "iterations": 2000, "concurrency": 50}` |
| `GET` | `/api/props` | Default JSON props for all pages |
| `GET` | `/api/openapi.json` | OpenAPI 3.1 spec |
| `GET` | `/api/docs` | Scalar API reference UI |
| `GET` | `/health` | Health check: `{"status": "ok", "engine": "proa"}` |

Full schemas and examples are available at `/api/docs`.

## Package contents


```proa-filetree
proa-playground-{target}/
  proa-playground
  run.sh
  Dockerfile
  README.md
  LICENSE
  showcase-props.json
  ffi/
    libproa_demo.dylib
    proa.h
  public/
    images/
    fonts/
    assets/
  hono-ssr/
    server.ts
    package.json
  react-ssr-shared/
    src/
    package.json
```


| File | Description |
|------|-------------|
| `proa-playground` | Axum HTTP server with embedded playground UI |
| `run.sh` / `run.bat` | Launch script with version checks and dep install |
| `Dockerfile` | Not in every archive; use the [Packaging example](/docs/ffi/packaging#docker) |
| `ffi/` | Shared library + C header for calling renders from any language |
| `public/` | Images, fonts, CSS, JS for the showcase pages |
| `hono-ssr/` | Hono server for React SSR comparison engines |
| `react-ssr-shared/` | React components (same pages rendered by Node/Bun) |
| `showcase-props.json` | Default props for all showcase pages |


---

# Docs: ABI contract

URL: /docs/ffi/abi
Description: Call the playground FFI exports and free their buffers correctly.

---
title: ABI contract
description: Call the playground FFI exports and free their buffers correctly.
---

The playground package ships `ffi/proa.h`, and that header is the source of truth for exported symbols and length types. This page covers [length types](#header-and-length-types), [allocating renders](#allocating-renders), [JSON renders](#json-renders), [caller-provided buffers](#caller-provided-buffers), and [freeing memory](#freeing-memory).

## Header and length types

```c filename="ffi/proa.h"
#include <stddef.h>
#include <stdint.h>
```

All byte lengths use `uintptr_t` in the public header. Host languages can usually map this to their pointer-sized unsigned integer type. In Python `ctypes`, `ctypes.c_size_t` is the practical mapping on supported platforms.

Every export below uses that length type. The first group hands you a buffer Proa allocated.

## Allocating renders

Allocating renders return a newly allocated UTF-8 byte buffer through out-parameters:

```c filename="ffi/proa.h"
int32_t render_airbnb_home(uint8_t **out_ptr, uintptr_t *out_len);
int32_t render_airbnb_search(uint8_t **out_ptr, uintptr_t *out_len);
int32_t render_airbnb_listing(uint8_t **out_ptr, uintptr_t *out_len);
int32_t render_nike_catalog(uint8_t **out_ptr, uintptr_t *out_len);
int32_t render_nike_pdp(uint8_t **out_ptr, uintptr_t *out_len);
```

On success:

- the function returns `0`
- `*out_ptr` points to `*out_len` bytes
- the bytes are UTF-8 HTML
- the bytes are not null-terminated
- the caller **must** eventually call `proa_free(*out_ptr, *out_len)`

The current demo ABI assumes `out_ptr` and `out_len` are valid writable pointers. Invalid pointers are caller bugs, not recoverable error returns.

Those five exports render default props. To pass your own props, use the JSON variants.

## JSON renders

JSON renders accept UTF-8 JSON bytes and return an allocated output buffer:

```c filename="ffi/proa.h"
int32_t render_airbnb_listing_json(
    const uint8_t *json_ptr,
    uintptr_t json_len,
    uint8_t **out_ptr,
    uintptr_t *out_len
);

int32_t render_nike_catalog_json(
    const uint8_t *json_ptr,
    uintptr_t json_len,
    uint8_t **out_ptr,
    uintptr_t *out_len
);

int32_t render_nike_pdp_json(
    const uint8_t *json_ptr,
    uintptr_t json_len,
    uint8_t **out_ptr,
    uintptr_t *out_len
);
```

Return codes:

| Code | Meaning |
|------|---------|
| `0` | Render succeeded. |
| `-2` | `json_ptr` / `json_len` did not decode as valid UTF-8 JSON for the expected props schema. |

There are no `_json_into` functions in the current demo ABI.

Both groups so far allocate. The `_into` group writes into memory you already own.

## Caller-provided buffers

`_into` renders copy default-prop page HTML into a caller-provided buffer:

```c filename="ffi/proa.h"
int32_t render_airbnb_home_into(uint8_t *buf_ptr, uintptr_t buf_cap, uintptr_t *out_len);
int32_t render_airbnb_search_into(uint8_t *buf_ptr, uintptr_t buf_cap, uintptr_t *out_len);
int32_t render_airbnb_listing_into(uint8_t *buf_ptr, uintptr_t buf_cap, uintptr_t *out_len);
int32_t render_nike_catalog_into(uint8_t *buf_ptr, uintptr_t buf_cap, uintptr_t *out_len);
int32_t render_nike_pdp_into(uint8_t *buf_ptr, uintptr_t buf_cap, uintptr_t *out_len);
```

Return codes:

| Code | Meaning |
|------|---------|
| `0` | Render succeeded and `*out_len` is the number of bytes written. |
| `-1` | `buf_cap` was too small and `*out_len` is the required byte count. |

The host owns `buf_ptr`. Do not pass it to `proa_free`.

That leaves one rule to get right: which deallocator matches which pointer.

## Freeing memory

```c filename="ffi/proa.h"
void proa_free(uint8_t *ptr, uintptr_t len);
```

Call `proa_free` exactly once for buffers returned by allocating render functions. The pointer and length must match the pair returned by the library.

### WASM helpers

The same crate exports simple WASM allocator helpers:

```c filename="ffi/proa.h"
uint8_t *wasm_alloc(uintptr_t size);
void wasm_dealloc(uint8_t *ptr, uintptr_t size);
```

Use `wasm_dealloc` only for pointers returned by `wasm_alloc`. Use `proa_free` only for buffers returned by allocating render functions.

## Next steps

- [Memory ownership](/docs/ffi/memory)
  - See the retry, concurrency, and buffer-sizing patterns for these calls.
- [Example payloads](/docs/ffi/examples)
  - Get the JSON props each `_json` export expects.
- [Packaging](/docs/ffi/packaging)
  - Build and distribute the shared library and header.
- [Playground](/docs/ffi/playground)
  - Run the exports without writing a binding first.


---

# Docs: Memory ownership

URL: /docs/ffi/memory
Description: Own, reuse, and free Proa FFI buffers from a host runtime.

---
title: Memory ownership
description: Own, reuse, and free Proa FFI buffers from a host runtime.
---

The FFI boundary has two ownership modes: Proa-owned output for allocating renders, and host-owned output for `_into` renders. This page covers [allocated output](#taking-ownership-of-allocated-output), [reused buffers](#reusing-a-caller-provided-buffer), [JSON inputs](#passing-json-inputs), [concurrency](#calling-concurrently), and [buffer sizing](#choosing-buffer-sizes).

## Taking ownership of allocated output

Allocating functions transfer ownership of an output buffer to the host:

```c filename="examples/render.c"
uint8_t *ptr = NULL;
uintptr_t len = 0;

int32_t rc = render_airbnb_home(&ptr, &len);
if (rc == 0) {
    /* ptr points to len UTF-8 bytes */
    proa_free(ptr, len);
}
```

Rules:

- Read exactly `len` bytes.
- Do not assume null termination.
- Free with `proa_free`, not the host allocator.
- Pass the same pointer and length returned by the render function.
- Call `proa_free` once.

`proa_free(NULL, 0)` is a no-op in the current implementation. Call it only for successful allocated renders.

Use `_into` to reuse host output storage. The current demo exports still allocate their intermediate Rust render output; the ownership contract does not guarantee zero internal allocations.

## Reusing a caller-provided buffer

`_into` functions let the host reuse output storage:

```c filename="examples/render_into.c"
uint8_t buf[256 * 1024];
uintptr_t written = 0;

int32_t rc = render_airbnb_home_into(buf, sizeof(buf), &written);
if (rc == 0) {
    /* buf[0..written] contains the HTML */
}
```

If the buffer is too small, retry with the required size:

```c filename="examples/render_into_retry.c"
uint8_t probe[1];
uintptr_t needed = 0;

int32_t rc = render_airbnb_home_into(probe, sizeof(probe), &needed);
if (rc == -1) {
    uint8_t *buf = malloc(needed);
    rc = render_airbnb_home_into(buf, needed, &needed);
    free(buf);
}
```

The host owns `_into` buffers. Do not pass them to `proa_free`.

Output is one direction. Props travel the other way, and they follow a third rule.

## Passing JSON inputs

JSON render functions borrow the input bytes for the duration of the call:

```c filename="examples/render_json.c"
const uint8_t *json_ptr = ...;
uintptr_t json_len = ...;
uint8_t *out = NULL;
uintptr_t out_len = 0;

int32_t rc = render_nike_pdp_json(json_ptr, json_len, &out, &out_len);
```

The host keeps ownership of `json_ptr`. The input must remain valid until the function returns. On success, ownership of the Proa-allocated output transfers to the caller, which releases it with `proa_free`.

Those rules hold per call. Running calls in parallel adds one more.

## Calling concurrently

Use separate output buffers per concurrent call. Do not share a mutable `_into` buffer between requests unless the host serializes access. Allocating renders return independent buffers per successful call.

How large each of those buffers needs to be depends on the page.

## Choosing buffer sizes

For the current showcase pages, a 256 KiB host buffer covers the default pages in the distributed package. For production bindings, prefer one of these patterns:

- call the allocating function and free the result
- provision a buffer from measured maximum HTML size plus headroom
- retry `_into` calls on `-1` using the required size from `out_len`

## Next steps

- [ABI contract](/docs/ffi/abi)
  - Look up the exact signature and return codes for each export.
- [Example payloads](/docs/ffi/examples)
  - Feed the JSON renders valid props.
- [Packaging](/docs/ffi/packaging)
  - Ship the shared library your host runtime loads.
- [Playground](/docs/ffi/playground)
  - Try the exports before writing a binding.


---

# Docs: Packaging

URL: /docs/ffi/packaging
Description: Build outputs, dynamic library loading, Docker packaging, and runtime integration notes.

---
title: Packaging
description: Build outputs, dynamic library loading, Docker packaging, and runtime integration notes.
---

The playground FFI artifact is a native shared library plus `proa.h`. The host process loads the library and calls exported C ABI functions.

## Build Outputs

Use the matching library and header from a published playground package. A plain `cargo build -p proa_demo --release` does not link, because the demo includes RSJS islands and the linked pipeline currently exposes only binary and example targets, not the cdylib.

Native outputs in the package:

| Platform | Library |
|----------|---------|
| macOS | `ffi/libproa_demo.dylib` |
| Linux | `ffi/libproa_demo.so` |
| Windows | `ffi/proa_demo.dll` |

The downloadable playground package places the library and header under `ffi/`.

## Dynamic Loader Paths

For C programs, set an rpath or configure the platform loader:

```bash
# macOS: normalize the current archive's build-machine install name first.
install_name_tool -id @rpath/libproa_demo.dylib ./ffi/libproa_demo.dylib
cc -o demo demo.c -L./ffi -lproa_demo -Wl,-rpath,@loader_path/ffi

# Linux
cc -o demo demo.c -L./ffi -lproa_demo -Wl,-rpath,'$ORIGIN/ffi'
```

The current Apple Silicon archive embeds an absolute install name from its
build machine. `install_name_tool -id` repairs your local copy before linking;
`otool -D ./ffi/libproa_demo.dylib` should then report
`@rpath/libproa_demo.dylib`. The executable's rpath locates the library beside
it. Rebuild already-linked executables after changing the library identity.

Python and Ruby load the library by its explicit filename. Resolve that path
from the deployed application's directory rather than assuming its working
directory. Go's C bridge also needs linker search paths and an rpath, as shown
in the [Go example](/docs/ffi#go).

## Docker

Use the **x86_64 Linux archive** from [Ecosystem Apps](/ecosystem/apps#reference-showcases),
including when building on macOS or Windows. The image runs Linux executables;
a macOS or Windows download cannot run inside it. The current Linux archive
omits a Dockerfile, so add this one at the extracted package root:

```dockerfile filename="Dockerfile"
FROM oven/bun:1.3.10 AS bun
FROM node:22-bookworm-slim
COPY --from=bun /usr/local/bin/bun /usr/local/bin/bun
WORKDIR /app
COPY . .
RUN npm install --include=dev --prefix hono-ssr \
    && npm install --include=dev --prefix react-ssr-shared \
    && chmod +x proa-playground
ENV PORT=3001
EXPOSE 3001
# The archived binary has an obsolete build-machine path for its companions.
# Start them explicitly from this package, on the ports it expects.
CMD ["sh", "-c", "(cd hono-ssr && PORT=3100 node --import tsx server.ts) & (cd hono-ssr && PORT=3200 bun server.ts) & exec ./proa-playground"]
```

Build and run it for the archive's architecture:

```bash
docker build --platform linux/amd64 -t proa/playground .
docker run --rm --platform linux/amd64 -p 127.0.0.1:3001:3001 proa/playground
```

Open `http://localhost:3001`. Node and Bun provide the comparison engines;
the native Proa server and FFI library come from the Linux archive. The
archived server also contains a build-machine companion path, so this example
starts Node and Bun explicitly from the package directory. Keep dev
dependencies during installation because the packaged Node server uses `tsx`.
This is a showcase package; pin dependency lockfiles and image digests before
using it as a repeatable benchmark baseline.

## Host Integration Checklist

- Load the library once per process when the host runtime supports it.
- Register function signatures explicitly in dynamic FFI systems.
- Treat returned HTML as bytes with an explicit length.
- Free allocated outputs with `proa_free`.
- Keep JSON input buffers alive until the render call returns.
- Avoid sharing mutable `_into` buffers across concurrent requests.
- Log negative return codes before translating them into host exceptions.

## Production Shape

The demo library exports fixed showcase functions. A production integration should expose functions that match the host application's route and props model, then keep the same ownership rules:

```c
int32_t render_product_json(
    const uint8_t *json_ptr,
    uintptr_t json_len,
    uint8_t **out_ptr,
    uintptr_t *out_len
);
```

Keep the ABI narrow. Prefer JSON or another stable byte protocol at the boundary instead of exposing many host-language-specific structs.


---

# Docs: Example payloads

URL: /docs/ffi/examples
Description: JSON prop shapes for the five benchmark render entry points.

---
title: Example payloads
description: JSON prop shapes for the five benchmark render entry points.
---

Each playground benchmark takes a JSON object. The entry points render the playground's showcase recreations of a travel marketplace (the Airbnb home, search, and listing pages) and a footwear store (the Nike catalog and product pages); the checked-in default props in `proa_demo/showcase-props.json` carry that page data. The samples on this page use placeholder names to show the shapes.

| Entry point | Renders |
|---|---|
| `render_airbnb_home` | [Travel home](#travel-home) |
| `render_airbnb_search` | [Travel search](#travel-search) |
| `render_airbnb_listing_json` | [Travel listing](#travel-listing) |
| `render_nike_catalog_json` | [Catalog](#catalog) |
| `render_nike_pdp_json` | [Product detail](#product-detail) |

## Travel home

`render_airbnb_home` renders the dense travel-home benchmark. The default
props under `showcase-props.json > home` are the showcase's listing data.

### Required shape

```ts
type HomeProps = {
  listings: Array<{
    title: string;
    location: string;
    price_per_night: number;
    rating: string;
    property_type: string;
    image: string;
  }>;
  homes_sections: HomeSection[];
  experiences_sections: HomeSection[];
  services_sections: HomeSection[];
};

type HomeSection = {
  title: string;
  subtitle: string;
  listing_indexes: number[];
};
```

Every top-level array is required. Each `listing_indexes` value refers to an
entry in the shared `listings` array, allowing repeated cards without repeating
their source objects.

### Minimal payload

```json
{
  "listings": [{
    "title": "Harbor Point House",
    "location": "Harbor Point, Coast County",
    "price_per_night": 350,
    "rating": "4.92",
    "property_type": "Entire home",
    "image": "/images/synthetic/property-coast.svg"
  }],
  "homes_sections": [{
    "title": "Popular homes in Coast County",
    "subtitle": "",
    "listing_indexes": [0]
  }],
  "experiences_sections": [],
  "services_sections": []
}
```

The full synthetic fixture lives at `proa_demo/showcase-props.json > home`.

## Travel search

`render_airbnb_search` renders the travel search benchmark. The default props
live under `showcase-props.json > search`.

### Required shape

```ts
type SearchProps = {
  title: string;
  subtitle: string;
  stay_info: string;
  filters: string[];
  listings: Array<{
    title: string;
    location: string;
    price_per_night: number;
    rating: string;
    reviews_count: number;
    property_type: string;
    beds: number;
    baths: number;
    image: string;
  }>;
};
```

The map column uses the first few listings for price pins. An empty `listings`
array still renders the page chrome and filters.

```json
{
  "title": "Harbor Point — Fictional Stays",
  "subtitle": "Entire homes and unique stays",
  "stay_info": "Flexible stay · 2 guests",
  "filters": ["Price", "Rooms and beds"],
  "listings": [{
    "title": "Harbor Point House",
    "location": "Harbor Point, Coast County",
    "price_per_night": 350,
    "rating": "4.92",
    "reviews_count": 128,
    "property_type": "Entire home",
    "beds": 3,
    "baths": 2,
    "image": "/images/synthetic/property-coast.svg"
  }]
}
```

The full synthetic fixture lives at `proa_demo/showcase-props.json > search`.

## Travel listing

`render_airbnb_listing_json` renders the travel listing detail page.

The required object contains:

- listing metadata: `title`, `location`, `location_short`, `property_line`,
  `rating`, `review_count`, `overview_summary`, and `description`;
- prices and counts: `nightly_rate`, `cleaning_fee`, `service_fee`, and
  `total_amenity_count`;
- page collections: `photos`, `highlights`, `amenities`,
  `review_distribution`, `reviews`, rules, safety items, cancellation items,
  and nearby links;
- nested `review_scores`, `host`, optional `cohost`, and `booking` objects.

Start with `proa_demo/showcase-props.json > listing`. That file is the canonical
complete example and is validated alongside the demo. Its image paths point at
the showcase's `/images/airbnb/` assets, which the playground package serves.

```json
{
  "title": "Cliffside Coast House",
  "location": "Harbor Point, Coast County",
  "rating": "4.92",
  "photos": [{
    "src": "/images/synthetic/property-coast.svg",
    "alt": "Illustrated coast house exterior"
  }]
}
```

The excerpt shows the primary fields only; use the canonical complete object
when calling the renderer.

## Catalog

`render_nike_catalog_json` renders the footwear catalog benchmark.

```ts
type CatalogProps = {
  title: string;
  products: Array<{
    title: string;
    subtitle: string;
    price: string;
    messaging: string;
    image: string;
    colors: string[];
    color_count: string;
  }>;
};
```

```json
{
  "title": "Footwear & Sneakers",
  "products": [{
    "title": "Stride Supply Pace 001",
    "subtitle": "Road Running Shoes",
    "price": "$145",
    "messaging": "New",
    "image": "/images/synthetic/product-shoe.svg",
    "colors": ["background-color:#26292B", "background-color:#EFBF4D"],
    "color_count": "2 Colors"
  }]
}
```

The full 117-card workload lives at
`proa_demo/showcase-props.json > nike-catalog`.

## Product detail

`render_nike_pdp_json` renders the footwear product detail page.

The object includes product identity and pricing (`title`, `subtitle`,
`current_price`, `original_price`, `discount_pct`, `color_name`, `style_code`,
`description`, `reason_to_buy`, `weight`, `drop`), `benefits`, `whats_new`,
`sizes`, `colorways`, the review summary (`avg_rating`, `review_count`) and
`reviews`, and `recommended` products.

```json
{
  "title": "Stride Supply Velocity One",
  "subtitle": "Unisex Road Racing Shoes",
  "current_price": "$184",
  "original_price": "$220",
  "discount_pct": "16% off",
  "color_name": "Cloud/Ember/Graphite",
  "style_code": "SS-V1-101",
  "avg_rating": "4.5",
  "review_count": "48"
}
```

This excerpt documents the primary scalar fields. Use the complete validated
object at `proa_demo/showcase-props.json > nike-pdp` as a starting point.

## Next steps

- [Playground](/docs/ffi/playground)
  - Interactive demo with live editing, benchmarks, and three SSR engines side by side
- [C ABI contract](/docs/ffi/abi)
  - Call the playground FFI exports and free their buffers correctly.
- [Memory ownership](/docs/ffi/memory)
  - Own, reuse, and free Proa FFI buffers from a host runtime.


---

# Docs: Proa Docs

URL: /docs/proa-docs
Description: A docs framework for Proa sites, compiled at build time.

---
title: Proa Docs
description: A docs framework for Proa sites, compiled at build time.
---

Proa Docs is a docs framework for Proa sites, largely inspired by [fumadocs](https://www.fumadocs.dev/) and [nextra](https://nextra.site/) from JavaScript-land.

Write Markdown, get a documentation site: file-routed pages, a generated sidebar, syntax highlighting, search, a table of contents, and thirteen authoring components.


- [Quickstart](/docs/proa-docs/quickstart): Two crates, a build script, one route.
- [Code block](/docs/proa-docs/code-block): Highlighting, filenames, line marks, and copy controls.


## Everything happens at build time

This is the difference that matters. Markdown is parsed, highlighted, and lowered to escaped static HTML during `build.rs`, then emitted as a static Rust registry your binary includes.

No parser ships to the reader. No syntax highlighter, no math renderer, no client-side router. A docs page is bytes that were computed once.

The practical consequences:

- **Syntax highlighting costs nothing at runtime.** Syntect runs in your build; tokens carry semantic `hl-*` classes your stylesheet colours.
- **Math is MathML.** Where most sites ship KaTeX and a font, Proa compiles TeX during the build and ships markup the browser already renders.
- **Tabs, accordions, and the code explorer need no JavaScript.** They lower to CSS-only patterns.
- **Every page has HTML and Markdown representations** generated from the same source, so browsers, command-line clients, retrieval pipelines, and agents can access the content without a second authoring pipeline.

## Two crates, two jobs

| Crate | Runs | Owns |
|---|---|---|
| `proa_docs_build` | `build.rs` | Parsing, frontmatter schemas, the Markdown pipeline, components, search index, link validation |
| `proa_docs` | request time | The static data model, render primitives, and the default theme |

`proa_docs` is deliberately small. It holds the compiled registry and renders a shell around generated article HTML. It also ships the CSS and JavaScript that make the components work, so a site that links `DocsAssets` from its head is styled on a fresh install.

You can also ignore the default theme entirely and write your own against the [styling contract](/docs/proa-docs/styling-contract). That is the headless path, and it is a supported one.

## What runs in the browser

The article HTML, syntax highlighting, and MathML are generated at build time.
Tabs, accordions, and code explorers use CSS. Copy controls need the optional
default script; search UI and Mermaid rendering need their own integration.
The runtime still selects a page, renders its shell, and serves the response.
See [Customizing the layout](/docs/proa-docs/customizing) for composing a themed
shell and [Mermaid](/docs/proa-docs/mermaid) for its renderer requirement.

## Next


- [Pages and routes](/docs/proa-docs/pages-and-routes): How files become routes.
- [Navigation](/docs/proa-docs/navigation): Order the sidebar with meta.json.
- [Rendering pages](/docs/proa-docs/runtime): Put a docs site inside your Proa app.
- [Configuration](/docs/proa-docs/configuration): Every build option in one reference.


---

# Docs: Quickstart

URL: /docs/proa-docs/quickstart
Description: Build a docs site and start authoring its common components.

---
title: Quickstart
description: Build a docs site and start authoring its common components.
---

Two crates, a build script, and one route.

<Callout type="info">


**Starting from scratch?**

`proa new site my-docs --template docs --yes` scaffolds a site with this
wiring already in place, and `proa new site my-app --template origin --yes`
scaffolds ORIGIN, the full reference application, if you want to study a
complete Proa app (data loading, islands, streamed sections, and Markdown
representations) while you write your docs. The steps below wire `proa_docs`
into an existing site by hand.

</Callout>


<Steps>

<Step>


**Add the dependencies.**

```toml filename="Cargo.toml"
[dependencies]
proa_docs = { version = "0.3.0", features = ["axum"] }

[build-dependencies]
proa_docs_build = "0.3.0"
```

</Step>

<Step>


**Compile your content in `build.rs`.**

```rust filename="build.rs"
use proa_docs_build::{
    CodeHighlight, Config, DocsSource, MarkdownPipeline, MdxConfig,
};

fn main() {
    let markdown = MarkdownPipeline::default()
        .code_highlighting(CodeHighlight::new())
        .mdx(MdxConfig::proa());

    let docs = DocsSource::new("src/docs")
        .out_dir_name("docs")
        .base_path("/docs")
        .site_name("My Docs")
        .markdown(markdown);

    proa_docs_build::compile(Config::new().source(docs));
}
```

</Step>

<Step>


**Write a page.**

```mdx filename="src/docs/index.mdx"
---
title: Introduction
description: What this site is about.
---

Hello from Proa Docs.
```

</Step>

<Step>


**Include the registry and mount a route.**

```rust filename="src/pages/docs.rs"
use axum::{extract::Path, response::IntoResponse, routing::get, Router};
use proa_docs::{include_docs, Docs};

pub fn docs() -> &'static Docs {
    static DOCS: Docs = include_docs!("docs");
    &DOCS
}

async fn docs_page(Path(path): Path<String>) -> impl IntoResponse {
    let path = format!("/docs/{path}");
    proa_docs::adapter::axum::response(docs(), &path)
}

pub fn router() -> Router {
    Router::new()
        .route("/docs", get(|| async { docs_page(Path(String::new())).await }))
        .route("/docs/*path", get(docs_page))
}
```

The adapter needs the `axum` feature on `proa_docs`. [Runtime](/docs/proa-docs/runtime) shows the same handler written by hand.

</Step>

</Steps>


Run it and open `/docs`.

## Styling

`proa_docs` ships a default theme. In a custom document shell, render its assets
inside `<head>`:

```rust filename="src/layouts/root.rs"
use proa_docs::DocsAssets;

html_sync! {
    <head>{DocsAssets::new()}</head>
}
```

The default `DocsShell` used by the adapter above owns its head and has no asset
slot. To install these assets, compose your own document from the primitives in
[Customizing the layout](/docs/proa-docs/customizing); adding a second `<head>`
around `DocsShell` would produce an invalid document.

On a site with many pages, serve `DEFAULT_STYLESHEET` and `DEFAULT_SCRIPT` as static files instead so they cache between navigations.

Theming is 15 CSS custom properties — see [Styling contract](/docs/proa-docs/styling-contract).

## Add components in MDX

Components are authored directly in an `.mdx` page. There are no Rust imports and no runtime registration step. The `MdxConfig::proa()` preset in the build script above also enables the three opt-in helpers: Cards, Files, and Agent Terminal.

### Code blocks and callouts

Fenced code is highlighted during the build. Add `filename` for a header and `{...}` to mark lines. Use a Callout to separate a note or warning from the surrounding prose:

````mdx filename="src/docs/deploy.mdx"
```rust filename="src/main.rs" {2}
fn main() {
    println!("ready");
}
```

<Callout type="warning">
Deploy only after the health check passes.
</Callout>
````

See [Code block](/docs/proa-docs/code-block) and [Callout](/docs/proa-docs/callout) for their complete options.

### Cards

Cards turn a list of destinations into a consistent link list, one entry per card:

```mdx filename="src/docs/index.mdx"
<Cards>
  <Card title="Quickstart" description="Set up the site." href="/docs/quickstart" />
  <Card title="Deploy" description="Ship the site." href="/docs/deploy" />
</Cards>
```

Each Card is self-closing and requires `title` and `href`. See [Cards](/docs/proa-docs/cards).

### Tabs, steps, and accordions

Use Tabs for alternatives, Steps for ordered work, and Accordions for optional detail:

```mdx filename="src/docs/install.mdx"
<Tabs data-items="Cargo|cargo-binstall">
<Tab value="Cargo">
Run `cargo install proa-cli`.
</Tab>
<Tab value="cargo-binstall">
Run `cargo binstall proa-cli`.
</Tab>
</Tabs>

<Steps>
<Step>
Create the docs source directory.
</Step>
<Step>
Mount the generated registry.
</Step>
</Steps>

<Accordions>
<Accordion title="Does this need JavaScript?">
No. The disclosure behavior is CSS-only.
</Accordion>
</Accordions>
```

Read the full [Tabs](/docs/proa-docs/tabs), [Steps](/docs/proa-docs/steps), and [Accordions](/docs/proa-docs/accordions) guides for attributes and constraints.

### Multi-file examples

Code Explorer keeps related files together without stacking every listing down the page:

````mdx filename="src/docs/setup.mdx"
<CodeExplorer>
<CodeFile name="Cargo.toml">
```toml
[build-dependencies]
proa_docs_build = "0.3.0"
```
</CodeFile>
<CodeFile name="build.rs">
```rust
fn main() {
    proa_docs_build::compile(config);
}
```
</CodeFile>
</CodeExplorer>
````

Each Code File requires a unique `name`, and one explorer supports up to eight files. See [Code explorer](/docs/proa-docs/code-explorer).

### File trees

Use Files when the directory structure itself is part of the explanation:

```mdx filename="src/docs/structure.mdx"
<Files>
<Folder name="src">
<Folder name="pages">
<File name="docs.rs" />
</Folder>
<File name="main.rs" />
</Folder>
<File name="build.rs" />
</Files>
```

See [Files](/docs/proa-docs/files). For a quick text-only tree, use a `proa-filetree` code fence instead.

### Generated references, demos, and terminal output

These components are self-closing:

```mdx filename="src/docs/reference.mdx"
<auto-type-table path="src/config.ts" name="DocsConfig" />

<Demo src="/demos/counter" title="Counter demo" height="320" />

<AgentTerminal />
```

- Type Table records a request for a TypeScript type and emits a pending placeholder; the build does not resolve it yet. See [Type table](/docs/proa-docs/type-table).
- Demo embeds a same-origin route and requires an accessible title. See [Demo](/docs/proa-docs/demo).
- Agent Terminal is enabled by `MdxConfig::proa()`. See [Agent terminal](/docs/proa-docs/agent-terminal).

### Math and diagrams

Math and Mermaid are Markdown-pipeline features rather than MDX tags. Enable Math with `.math(MathMode::MathMl)` and write dollar-delimited TeX. Mermaid uses a `mermaid` code fence and needs a renderer supplied by your application.

See [Math](/docs/proa-docs/math) and [Mermaid](/docs/proa-docs/mermaid) for their build configuration.

## What you get without doing anything else

- File-routed pages, with routes derived from paths under your source root
- A sidebar generated from `meta.json`
- Syntax highlighting, compiled at build time
- A table of contents per page, from the heading structure
- HTML and Markdown representations of every page, generated from the same source

## Next


- [Pages and routes](/docs/proa-docs/pages-and-routes): How files become routes, and what frontmatter controls.
- [Code block](/docs/proa-docs/code-block): Highlighting, filenames, line marks, and copy controls.
- [Navigation](/docs/proa-docs/navigation): Order the sidebar with meta.json.


---

# Docs: Pages and routes

URL: /docs/proa-docs/pages-and-routes
Description: How a file becomes a route, and what frontmatter controls.

---
title: Pages and routes
description: How a file becomes a route, and what frontmatter controls.
---

Every `.md` or `.mdx` file under your source root becomes a page. The path is the route; frontmatter is the metadata.

## File routes

Routes come from file paths under the docs source root:

| File | Route |
|------|-------|
| `src/docs/index.mdx` | `/docs` |
| `src/docs/guides/index.mdx` | `/docs/guides` |
| `src/docs/guides/installation.mdx` | `/docs/guides/installation` |
| `src/docs/proa-docs/configuration.mdx` | `/docs/proa-docs/configuration` |

`index.mdx` maps to the folder route. Other file stems map to the final path segment.

## Frontmatter

Supported page fields:

| Field | Type | Runtime effect |
|-------|------|----------------|
| `title` | string | Page title. Falls back to the first `#` heading or file name. |
| `description` | string | Page description, search metadata, and default page meta description. |
| `icon` | string | Stored on `Frontmatter` and copied to the generated `NavItem`. |
| `slug` | string | Overrides the route slug after base path normalization. |
| `sidebar_title` | string | Overrides the label used in navigation. |
| `nav_order` | integer | Fallback ordering when the source root has no `meta.json`. With a root `meta.json`, unlisted pages compile but never enter the nav. |
| `hidden` | boolean | Compiles the page and static Markdown, but omits it from nav. |
| `draft` | boolean | Omits the page unless `include_drafts(true)` is set. |
| `search` | boolean | Includes or excludes the page from generated search documents. |
| `keywords` | list of strings | Extra search terms the page canonically documents (identifiers, API names, synonyms). Emitted to the search documents so a client can boost them. |
| `toc` | boolean | Stores a page-level table-of-contents preference for the app shell. |
| `last_modified` | string | Optional date string for display, plugins, or generated metadata. |

Example:

```markdown
---
title: Route Handlers
description: Build JSON endpoints, form handlers, webhooks, and health checks.
sidebar_title: Handlers
icon: Route
---

# Route Handlers
```

## Laying out a source folder


```proa-filetree
src/docs/
  index.mdx
  meta.json
  guides/
    index.mdx
    installation.mdx
    meta.json
```


Each folder carries its own `meta.json`, which orders that folder's pages. Frontmatter on each file controls how the route presents itself.

## Related

[Navigation](/docs/proa-docs/navigation) · [Markdown](/docs/proa-docs/markdown) · [Configuration](/docs/proa-docs/configuration)


---

# Docs: Navigation

URL: /docs/proa-docs/navigation
Description: Order the sidebar, group pages, and split it into sections.

---
title: Navigation
description: Order the sidebar, group pages, and split it into sections.
---

The sidebar comes from `meta.json` files, one per folder. A source root without one falls back to frontmatter `nav_order`, then alphabetical order; once the root has a `meta.json`, only listed pages appear.

## meta.json

Each folder can include a `meta.json` file:

```json
{
  "title": "Framework",
  "icon": "Route",
  "root": true,
  "pages": [
    "---Start Here---",
    "index",
    "---Request lifecycle---",
    "routing",
    "route-handlers",
    "responses"
  ]
}
```

The compiler supports these `pages` entry types:

| Entry | Meaning |
|-------|---------|
| `"index"` | Page file in the current folder. |
| `"guides"` | Child folder; the child folder's `meta.json` controls its group. |
| `"---Label---"` | Separator item with no path and no children. |
| `{ "separator": "Label", "icon": "Database" }` | Separator with an optional nav icon. Unknown icon names fail the build. |
| `{ "title": "Group", "pages": [...] }` | Inline group using the current folder as its lookup base. |

If a `pages` entry names a folder, the folder must contain `meta.json`. If it names a page, the compiler resolves `.md`, `.mdx`, or `index` by convention.

Set `"root": true` on a child folder to make it an independent navigation root. The generated section menu uses that folder's `title` and `icon`, links to its first page, and shows only its `pages` while one of its pages is active. Root folders appear in the section menu, not as groups inside another root's sidebar. The source-level `meta.json` remains the default root, and its non-root separators, pages, and groups stay visible on pages outside a child root.

## Icons

Pages can set `icon` in frontmatter. Folders can set `icon` in `meta.json`.

The generated runtime stores the value in two places:

- `Frontmatter.icon` on the page.
- `NavItem.icon` on the generated nav item.

`DocsNav` renders a `.proa-docs-nav-icon` span with `data-icon="<name>"`. The default runtime includes a small inline SVG map for common names such as `BookOpen`, `Cpu`, `FileText`, `Settings`, `Brain`, `Layers`, `ArrowRightLeft`, `Route`, `Terminal`, and `Zap`. Unknown names fall back to a file icon, and applications can still target the `data-icon` hook for custom styling or replacement.

## Ordering pages

When a folder contains `meta.json`, its `pages` array controls ordering and grouping:

```json filename="src/docs/meta.json"
{
  "title": "Start Here",
  "pages": ["index", "installation", "security"]
}
```

If a `pages` entry names a folder, `proa_docs_build` reads that folder's `meta.json` and emits a nested nav group. If a `pages` entry names a Markdown file, it emits a page link.

You can also use separator entries in `meta.json` by wrapping the label in `---`:

```json filename="src/docs/meta.json"
{
  "pages": ["index", "---Reference---", "api"]
}
```

Folder `meta.json` files may include an `icon` string. The compiler stores the icon on the generated group:

```json filename="src/docs/reference/meta.json"
{
  "title": "Reference",
  "icon": "BookOpen",
  "pages": ["index", "api"]
}
```

Inside each page, the Markdown parser decides which syntax reaches the rendered HTML.

## Separators

A `"---Label---"` entry renders as a non-clickable group heading:

```json filename="meta.json"
{
  "pages": [
    "---Getting started---",
    "quickstart",
    "---Reference---",
    "configuration"
  ]
}
```

Prefer separators over nested folders. They group without adding a URL segment or an indent level, and a flat sidebar is easier to scan than a deep one.

## Section roots

A folder whose `meta.json` sets `"root": true` becomes its own sidebar. It disappears from the parent nav and appears in the section switcher instead.

```json filename="cli/meta.json"
{
  "title": "CLI",
  "icon": "Terminal",
  "root": true,
  "pages": ["index", "new-site"]
}
```

Use a root for a section a reader enters and stays inside. Entering one replaces the whole sidebar, so a section people cross constantly is better left inline.

## Related

[Pages and routes](/docs/proa-docs/pages-and-routes) · [Rendering pages](/docs/proa-docs/runtime) · [Configuration](/docs/proa-docs/configuration)


---

# Docs: Markdown

URL: /docs/proa-docs/markdown
Description: The syntax a page supports, and what the build does with it.

---
title: Markdown
description: The syntax a page supports, and what the build does with it.
---

Pages are CommonMark plus GitHub tables, strikethrough, and task lists. Everything is parsed once during `build.rs` and emitted as escaped static HTML; no parser reaches the reader.

For anything beyond prose — tabs, code explorers, file trees, diagrams — use the dedicated guides in the Components section of the sidebar.

## What does the default parser enable?

The default parser enables:

- headings with generated IDs
- tables
- strikethrough
- task lists
- fenced code blocks
- links and images
- table-of-contents extraction
- search text extraction

The compiler escapes inline HTML unless it recognizes a supported component tag or a configured type-table directive. It also escapes link and image URLs, and it strips `javascript:` and `vbscript:` URLs before writing HTML.

Headings get one more treatment: a stable id.

## Generating heading IDs and TOC entries

Every Markdown heading gets a deterministic id:

```markdown filename="src/docs/core/html-rendering.mdx"
## Static consolidation
```

renders as `<h2 id="static-consolidation">Static consolidation</h2>`. The id keeps lowercased letters and digits and collapses everything else to single dashes; a repeated heading gets a `-2`, `-3` suffix so anchors stay unique. Every `h2` and deeper also becomes a table-of-contents entry, and every heading id is recorded for [link validation](/docs/proa-docs/link-validation), so a `#fragment` link to a heading that does not exist is reported at build time.

## Serving static Markdown

The generated registry stores the processed Markdown source for each page. For `.md` files this is the original source. For `.mdx` files with `MdxConfig` enabled, this is the lowered Markdown. `render_static` serves it at the page's `.md` route, and the marketing site builds `/llms-full.txt` from the same stored strings.

One authored page therefore produces three useful artifacts:

| Artifact | Purpose |
|----------|---------|
| `page.article_html` | Trusted generated HTML for runtime rendering. |
| `page.markdown` | Source Markdown for `.md` routes and LLM ingestion. |
| `content` in generated search JSON | Search index input. |

Keep the pass predictable, and those three artifacts stay in agreement.

## Related

[Code block](/docs/proa-docs/code-block) · [Pages and routes](/docs/proa-docs/pages-and-routes) · [Search](/docs/proa-docs/search)


---

# Docs: Code block

URL: /docs/proa-docs/code-block
Description: Highlight, title, and annotate a fenced code block.

---
title: Code block
description: Highlight, title, and annotate a fenced code block.
---

Every fenced block is highlighted at build time by Syntect (the `CodeHighlight` toggle in your pipeline, enabled in the quickstart setup). No highlighter ships to the reader.

````mdx filename="content/example.mdx"
```rust filename="src/pages/home.rs" {3,5-7}
use proa::WebRenderSync;
```
````

## Fence metadata

| Metadata | Effect |
|---|---|
| `rust`, `toml`, `bash`, … | Language. Drives highlighting and the file icon |
| `filename="src/main.rs"` | Renders a header above the block with a language icon |
| `{1,3-5}` | Marks those lines with `data-highlighted-line` |
| `proa-filetree` | Renders the block as a file tree instead of code |
| `mermaid` | Marks the block for diagram rendering (opt-in). See [Mermaid](/docs/proa-docs/mermaid) |

For example, this block highlights line 2 and the inclusive range 4–5:

```rust filename="src/main.rs" {2,4-5}
fn main() {
    let message = "Highlighted";

    println!("{message}");
    println!("These ranges are inclusive");
}
```

A filename header adds a copy button. Blocks without one still get the button; only the chrome differs.

## Highlighting is semantic, not inline

Tokens carry `hl-*` classes rather than inline colours, so your stylesheet owns the palette:

```css filename="app.css"
.proa-docs-body .hl-keyword { color: #c678dd; }
.proa-docs-body .hl-string  { color: #98c379; }
```

This is why a Proa docs site can restyle its code blocks without rebuilding content, and why switching themes costs nothing at runtime.

An unrecognized language is not an error. The block renders as escaped plain text with no `hl-*` classes. A recognized language that fails to parse also falls back to escaped text, and that case prints a build warning naming the file and the language.

## File trees

The `proa-filetree` language renders an indented tree:

````mdx
```proa-filetree
Cargo.toml
build.rs
src/
  pages/
  main.rs
```
````

For a tree with folder and file icons and richer structure, use [Files](/docs/proa-docs/files) instead.

> **Good to know**: The copy button is the one component here that needs JavaScript. `proa_docs` ships it in `DEFAULT_SCRIPT`; without it the button renders and does nothing, and the code is still selectable.

## Related

[Code explorer](/docs/proa-docs/code-explorer) · [Files](/docs/proa-docs/files) · [Mermaid](/docs/proa-docs/mermaid) · [Styling contract](/docs/proa-docs/styling-contract)


---

# Docs: Code explorer

URL: /docs/proa-docs/code-explorer
Description: Browse several files of one example in a file switcher.

---
title: Code explorer
description: Browse several files of one example in a file switcher.
---

An explorer groups the files of a single change so a reader can move between them without scrolling past all of them.

````mdx filename="content/setup.mdx"
<CodeExplorer>
<CodeFile name="Cargo.toml">
```toml
[build-dependencies]
proa_docs_build = "0.3.0"
```
</CodeFile>
<CodeFile name="build.rs">
```rust
fn main() { proa_docs_build::compile(config); }
```
</CodeFile>
</CodeExplorer>
````

Use it when the files only make sense together. For one file, a plain [code block](/docs/proa-docs/code-block) with `filename=` is lighter.

## Attributes

| Tag | Attribute | Required | Meaning |
|---|---|---|---|
| `<CodeExplorer>` | — | — | No attributes |
| `<CodeFile>` | `name` | **yes** | Path shown in the switcher. An empty name is rejected |

`name` takes a path, not just a filename. `src/pages/home.rs` renders as a path with the segments styled separately, which is what makes a multi-directory example readable.

## Constraints

**Eight files maximum**, for the same reason as [tabs](/docs/proa-docs/tabs) — the stylesheet addresses panels up to eight, and the build reports an explorer that exceeds it.

**`<CodeFile>` only works inside `<CodeExplorer>`.** Outside one it is not claimed as a component and falls through to the Markdown renderer.

Explorers and tabs share one counter, so their radio groups never collide on a page that uses both.

## Related

[Code block](/docs/proa-docs/code-block) · [Tabs](/docs/proa-docs/tabs) · [Files](/docs/proa-docs/files)


---

# Docs: Tabs

URL: /docs/proa-docs/tabs
Description: Switch between alternative versions of the same content.

---
title: Tabs
description: Switch between alternative versions of the same content.
---

Use tabs to group related instructions or alternatives. Declare the labels once on the container, then one `<Tab>` per label in the same order.

```mdx filename="content/install.mdx"
<Tabs data-items="Install|Build|Test">
<Tab value="Install">
`pnpm install`
</Tab>
<Tab value="Build">
`pnpm run build`
</Tab>
<Tab value="Test">
`pnpm test`
</Tab>
</Tabs>
```

Rendered:

<Tabs data-items="Install|Build|Test">

<Tab value="Install">

Install the project's locked dependencies with pnpm.

</Tab>

<Tab value="Build">

Run the project's build script.

</Tab>

<Tab value="Test">

Run the project's test script.

</Tab>

</Tabs>


## Attributes

| Tag | Attribute | Required | Meaning |
|---|---|---|---|
| `<Tabs>` | `data-items` | yes | Labels, `\|`-separated. Whitespace around each is trimmed |
| `<Tab>` | `value` | no | Accessible label for the panel (`aria-label`). Panels always bind to labels in document order; omit it and the matching `data-items` label is used |

## Constraints

**Eight panels maximum.** The generated stylesheet addresses panels with `nth-of-type` rules up to eight. A ninth panel still renders, but nothing can switch to it — and the build reports the mistake rather than shipping a dead tab.

**Close every container.** An unclosed `<Tabs>` is reported by name at build time.

`<Tab>` outside a `<Tabs>` is not treated as a component at all — it falls through to the Markdown renderer as raw HTML. That is deliberate: it keeps `<Tab>`-shaped text in prose from being captured.

> **Good to know**: Tabs are CSS-only. They lower to a radio group (`input[name="proa-docs-tabs-0"]`) plus sibling panels, so they work with JavaScript disabled. A replacement theme must implement the `:checked` sibling selectors or every panel renders stacked — see [Styling contract](/docs/proa-docs/styling-contract).

## Related

[Code explorer](/docs/proa-docs/code-explorer) · [Accordions](/docs/proa-docs/accordions) · [Styling contract](/docs/proa-docs/styling-contract)


---

# Docs: Steps

URL: /docs/proa-docs/steps
Description: Number a sequence the reader works through in order.

---
title: Steps
description: Number a sequence the reader works through in order.
---

Use steps for a procedure where order matters and each item is a thing the reader does. Numbering is generated, so inserting a step never renumbers the rest by hand.

```mdx filename="content/setup.mdx"
<Steps>
<Step>
Add the dependencies to `Cargo.toml`.
</Step>
<Step>
Write `build.rs` and call `proa_docs_build::compile`.
</Step>
<Step>
Include the registry with `include_docs!` and mount a route.
</Step>
</Steps>
```

Rendered:

<Steps>

<Step>

Add the dependencies to `Cargo.toml`.

</Step>

<Step>

Write `build.rs` and call `proa_docs_build::compile`.

</Step>

<Step>

Include the registry with `include_docs!` and mount a route.

</Step>

</Steps>


Neither tag takes attributes.

Steps nest: an inner `<Steps>` inside a `<Step>` opens its own numbering and closes back to the outer sequence.

## When not to use it

Reach for an ordered list when the items are facts rather than actions. Steps carry visual weight that a three-item list does not earn, and a reader reads them as "do this now."

> **Good to know**: Markdown inside a `<Step>` is rendered normally, so code fences, callouts, and tabs all work inside one.

## Related

[Accordions](/docs/proa-docs/accordions) · [Tabs](/docs/proa-docs/tabs) · [Quickstart](/docs/proa-docs/quickstart)


---

# Docs: Accordions

URL: /docs/proa-docs/accordions
Description: Collapse answers the reader only needs sometimes.

---
title: Accordions
description: Collapse answers the reader only needs sometimes.
---

Use accordions for FAQ blocks and for asides that would interrupt the main flow. Content inside stays in the DOM, so search still indexes it and Ctrl-F still finds it.

```mdx filename="content/faq.mdx"
<Accordions>
<Accordion title="Does it need a runtime parser?">
No. Markdown compiles to escaped static HTML during `build.rs`.
</Accordion>
<Accordion title="Can I use my own CSS?">
Yes. Ship your own theme against the documented markup contract.
</Accordion>
</Accordions>
```

Rendered:

<Accordions>

<Accordion title="Does it need a runtime parser?">

No. Markdown compiles to escaped static HTML during `build.rs`, so no parser ships to the reader.

</Accordion>

<Accordion title="Can I use my own CSS?">

Yes. `proa_docs` ships a default theme, and every hook it targets is documented in the [styling contract](/docs/proa-docs/styling-contract).

</Accordion>

</Accordions>


## Attributes

| Tag | Attribute | Required | Meaning |
|---|---|---|---|
| `<Accordions>` | `type` | no | `multiple` allows several open at once. Anything else, including omitting it, means one at a time |
| `<Accordion>` | `title` | no | The always-visible label. Defaults to empty |
| `<Accordion>` | `id` | no | Stable anchor, so a link can target this item directly |

Exclusive is the default. Pass `type="multiple"` when items are independent:

```mdx
<Accordions type="multiple">
```

## Linking to one item

Give an item an `id` and it becomes addressable:

```mdx
<Accordion title="Registry access" id="registry">
```

`/docs/proa-docs/accordions#registry` then jumps to that item on load.

> **Good to know**: Like tabs, accordions are CSS-only and work without JavaScript.

## Related

[Tabs](/docs/proa-docs/tabs) · [Callout](/docs/proa-docs/callout) · [Steps](/docs/proa-docs/steps)


---

# Docs: Callout

URL: /docs/proa-docs/callout
Description: Mark a note, warning, or error inside the page flow.

---
title: Callout
description: Mark a note, warning, or error inside the page flow.
---

A callout separates a remark from the prose around it without taking the reader out of the page. It renders as an icon beside your Markdown, coloured by the kind of remark it is.

```mdx filename="content/deploy.mdx"
<Callout>
Cross-origin protection is on by default and returns `403` for browser-issued
cross-origin writes.
</Callout>

<Callout type="warning">
`Vary: Accept` fragments CDN caches. Normalize the header at the edge first.
</Callout>
```

Rendered:

<Callout>

Cross-origin protection is on by default and returns `403` for browser-issued cross-origin writes.

</Callout>


<Callout type="info">

The children are ordinary Markdown, so [links](/docs/proa-docs/callout), `code`, and lists all work inside one.

</Callout>


<Callout type="warning">

`Vary: Accept` fragments CDN caches. Normalize the header at the edge first.

</Callout>


<Callout type="error">

A request that fails CSRF validation is rejected before your handler runs.

</Callout>


## Attributes

| Attribute | Required | Default | Meaning |
|---|---|---|---|
| `type` | no | `default` | One of `default`, `info`, `warning`, `error`. Written to `data-type`, which the stylesheet colours |
| `emoji` | no | built-in icon | Replaces the icon with the text you pass |

An unrecognized `type` falls back to `default` rather than dropping the callout, so a typo costs you the colour, not the content.

```mdx filename="content/release.mdx"
<Callout type="warning" emoji="🔥">
This deletes the environment and everything in it.
</Callout>
```

<Callout type="warning" emoji="🔥">

This deletes the environment and everything in it.

</Callout>


## Accessibility

The container carries `role="note"`, so assistive technology announces it as an aside rather than as body copy. The icon is `aria-hidden`, because it repeats what the type and the prose already say; a screen reader that announced it would read decoration.

That means the colour and the icon are never the only carrier of meaning. Write the callout so it still reads correctly in plain text, and the reader who cannot see the treatment loses nothing.

## Use it sparingly

A page with four callouts has no callouts: the reader stops seeing them. If something is required to succeed, it belongs in the prose. Reserve callouts for the thing that is true but would break the sentence you are writing.

## Related

[Accordions](/docs/proa-docs/accordions) · [Styling contract](/docs/proa-docs/styling-contract)


---

# Docs: Cards

URL: /docs/proa-docs/cards
Description: Link onward with a list of cards instead of a paragraph of links.

---
title: Cards
description: Link onward with a list of cards instead of a paragraph of links.
---

<Callout>

Opt-in. Enable it in `build.rs` before use — see [Enabling](#enabling) below.

</Callout>


Cards are how a hub page hands off. They read faster than a "see also" paragraph and they survive scanning.

```mdx filename="content/index.mdx"
<Cards>
  <Card title="Quickstart" description="Running docs site in five minutes." href="/docs/proa-docs/quickstart" />
  <Card title="Code block" description="Highlighting, filenames, line marks, and copy controls." href="/docs/proa-docs/code-block" />
</Cards>
```

Rendered:


- [Quickstart](/docs/proa-docs/quickstart): Running docs site in five minutes.
- [Code block](/docs/proa-docs/code-block): Highlighting, filenames, line marks, and copy controls.


## Attributes

| Attribute | Required | Meaning |
|---|---|---|
| `title` | **yes** | Card heading. Missing title fails the build |
| `href` | **yes** | Destination. Internal links are checked by [link validation](/docs/proa-docs/link-validation) |
| `description` | no | One line under the title |

Each `<Card />` is a single self-closing tag on its own line; any other non-blank line inside `<Cards>` fails the build. Cards have no bodies, so keep the description to a sentence.

## Enabling

The `MdxConfig::proa()` preset enables this along with the other opt-in components. To turn on just this one:

```rust filename="build.rs"
use proa_docs_build::{Config, MarkdownPipeline, MdxConfig};

let markdown = MarkdownPipeline::default().mdx(MdxConfig::new().cards(true));
let config = Config::new().source(source.markdown(markdown));
```

## Where they earn their place

End a hub page with cards rather than prose. Fumadocs does this on every index page and it is the right call: a reader arriving at a section wants the menu, not a paragraph describing the menu.

Do not use them mid-page as a substitute for inline links.

## Related

[Files](/docs/proa-docs/files) · [Navigation](/docs/proa-docs/navigation) · [Link validation](/docs/proa-docs/link-validation)


---

# Docs: Files

URL: /docs/proa-docs/files
Description: Draw a project tree with folder and file icons.

---
title: Files
description: Draw a project tree with folder and file icons.
---

<Callout>

Opt-in. Enable it in `build.rs` before use — see [Enabling](#enabling) below.

</Callout>


```mdx filename="content/structure.mdx"
<Files>
<Folder name="src">
<Folder name="pages">
<File name="home.rs" />
</Folder>
<File name="main.rs" />
</Folder>
<File name="Cargo.toml" />
</Files>
```

## Attributes

| Tag | Attribute | Required | Meaning |
|---|---|---|---|
| `<Folder>` | `name` | **yes** | Folder label. Missing name fails the build |
| `<File>` | `name` | **yes** | File label. Missing name fails the build |

Both render with `data-kind="folder"` or `data-kind="file"`, which is what the stylesheet uses to pick an icon.

## Enabling

The `MdxConfig::proa()` preset enables this along with the other opt-in components. To turn on just this one:

`Files` is off by default. Turn it on in the MDX config:

```rust filename="build.rs"
use proa_docs_build::{Config, DocsSource, MarkdownPipeline, MdxConfig};

let markdown = MarkdownPipeline::default().mdx(MdxConfig::new().files(true));
let config = Config::new().source(DocsSource::new("src/docs").markdown(markdown));
```

Without it, the tags are dropped from the rendered HTML, which is the usual cause of "my file tree renders as nothing."

## Files or a filetree fence?

| Use | When |
|---|---|
| `<Files>` | You want icons, nesting, and a real tree |
| ```` ```proa-filetree ```` | You want a quick indented listing inside a code block |

The fence is faster to write and needs no config. The component looks like a file browser.

## Related

[Code block](/docs/proa-docs/code-block) · [Cards](/docs/proa-docs/cards)


---

# Docs: Type table

URL: /docs/proa-docs/type-table
Description: Render a props or options table from a type definition.

---
title: Type table
description: Render a props or options table from a type definition.
---

A type table documents an API surface as a table rather than prose, so a reader scans for the field they need instead of reading paragraphs.

```mdx filename="content/config.mdx"
<auto-type-table path="src/config.ts" name="DocsConfig" />
```

The tag name is the `component_name` configured on `TypeScriptDocgen`; `auto-type-table` is the default.

## Attributes

| Attribute | Meaning |
|---|---|
| `path` | File to read the type from |
| `name` | Named type inside that file |
| `type` | An inline type literal, instead of `path` + `name` |

The tag is deferred: the build records the request and emits a pending placeholder (`<div data-proa-docs-type-table-pending>`) holding the escaped directive. Nothing replaces that placeholder today: `TypeScriptDocgen::command` is only checked for presence, never run. Enabling docgen without a command fails the build as soon as any page requests a table, so the unconfigured case is never published silently; with a command configured, or with docgen disabled (the default), the placeholder ships as is.

## Current limitation

**Type extraction is TypeScript-shaped and not yet wired.** The directive names a TypeScript file and type, and the build records the request without resolving it, so neither a TypeScript nor a Rust type produces a table today.

For Rust APIs, write the table by hand:

| Field | Type | Default | Meaning |
|---|---|---|---|
| `base_path` | `&'static str` | `"/docs"` | URL prefix the site mounts under |
| `site_name` | `&'static str` | — | Shown in the sidebar header |

Until type extraction is implemented, maintain API tables alongside their
examples and verify field names and defaults against the owning Rust types.

## Related

[Configuration](/docs/proa-docs/configuration) · [Markdown](/docs/proa-docs/markdown)


---

# Docs: Demo

URL: /docs/proa-docs/demo
Description: Embed a live page from your own site inside a doc.

---
title: Demo
description: Embed a live page from your own site inside a doc.
---

A demo frames one of your own routes inside the page, so a reader sees the thing working next to the code that produces it.

```mdx filename="content/islands.mdx"
<Demo src="/demos/counter" title="Counter island" height="320" />
```

## Attributes

| Attribute | Required | Meaning |
|---|---|---|
| `src` | **yes** | Same-origin path. Absolute URLs are rejected |
| `title` | **yes** | Accessible frame title. Also the visible caption |
| `height` | no | Frame height in pixels. Clamped to a sane range |

## Two rules, both enforced at build time

**Same-origin only.** `<Demo src="https://example.com/x" />` is rejected with a reason naming the origin constraint. A docs page cannot frame a third-party site — that is a security decision, not an oversight: an embedded external origin can size, track, and navigate inside your docs.

**A title is required.** `<Demo src="/demos/x" />` with no title is rejected. An untitled iframe is unusable with a screen reader, so the build refuses to emit one.

A rejected demo is **dropped, not rendered broken**, and reported with its `src` and the reason. The page still builds.

## What renders

The frame, plus a plain link to the same path. Readers who cannot use the embed — or who want the demo full-size — get a working route either way.

> **Good to know**: Because the demo is a real route on your own site, it is covered by your own tests and deploys. There is no separate sandbox to keep alive.

## Related

[Code block](/docs/proa-docs/code-block) · [Agent terminal](/docs/proa-docs/agent-terminal)


---

# Docs: Agent terminal

URL: /docs/proa-docs/agent-terminal
Description: Insert the stock agent-fetch block on a page.

---
title: Agent terminal
description: Insert the stock agent-fetch block on a page.
---

<Callout>

Opt-in. Enable it in `build.rs` before use.

</Callout>


Lowers to a fixed text block illustrating how an agent consumes a Proa docs page: fetch the page, receive server-rendered HTML, extract the content with no client JavaScript.

```mdx filename="content/quickstart.mdx"
<AgentTerminal />
```

The tag takes no attributes and is self-closing. Its content is fixed; it is a shorthand for the agent-fetch illustration, not a container for your own transcript. It emits:

```text
Agent fetches page -> receives server-rendered HTML -> extracts content without client JavaScript
```

## Enabling

The `MdxConfig::proa()` preset enables this along with the other opt-in components. To turn on just this one:

```rust filename="build.rs"
use proa_docs_build::{Config, MarkdownPipeline, MdxConfig};

let markdown = MarkdownPipeline::default().mdx(MdxConfig::new().agent_terminal(true));
let config = Config::new().source(source.markdown(markdown));
```

Like [Cards](/docs/proa-docs/cards) and [Files](/docs/proa-docs/files), it is off by default. Left off, the tag is not lowered, and the Markdown renderer drops it like any other block-level raw HTML.

## When to reach for it

The block earns its place where you are making the agent-readability point itself: a quickstart or an agents page, next to the claim that a Proa page needs no client JavaScript to be read. For an actual command session, use a plain `bash` [code block](/docs/proa-docs/code-block) with a copy button: readers copy commands far more often than they watch them.

## Related

[Code block](/docs/proa-docs/code-block) · [Demo](/docs/proa-docs/demo) · [Quickstart](/docs/proa-docs/quickstart)


---

# Docs: Mermaid

URL: /docs/proa-docs/mermaid
Description: Draw flowcharts and sequence diagrams from a code fence.

---
title: Mermaid
description: Draw flowcharts and sequence diagrams from a code fence.
---

Write a `mermaid` fence and the block is marked for diagram rendering instead of syntax highlighting.

````mdx filename="content/pipeline.mdx"
```mermaid
flowchart LR
  MD[Markdown] --> C[compile]
  C --> R[static Rust registry]
  R --> H[HTML]
```
````

## Configuring it

```rust filename="build.rs"
use proa_docs_build::{Config, MermaidConfig};

let config = Config::new().source(source.markdown(pipeline.mermaid(MermaidConfig::new())));
```

| Option | Meaning |
|---|---|
| `enabled` | Turn Mermaid handling on |
| `code_fences` | Treat ```` ```mermaid ```` fences as diagrams |
| `renderer` | Recorded for a future renderer; the emitted markup is the same for every value today |
| `fallback` | What to show when rendering does not happen |

The build emits the diagram source in a hidden `data-proa-docs-mermaid-source` block and an empty output slot in `data-proa-docs-mermaid-output`, then leaves rendering to a script you ship.

<Callout type="warning">

`proa_docs` does not currently ship a Mermaid renderer. The build emits the
source and the slot; supplying a renderer is yours. Until you do, the figure
is blank with scripting on, and the `<noscript>` fallback appears only when
JavaScript is disabled.

</Callout>


## Diagram or picture?

Mermaid is right for anything with a decision or a sequence — it lives in git, needs no design time, and survives refactoring. For a conceptual diagram where the layout *is* the explanation, a hand-authored SVG beats Mermaid's auto-layout every time.

## Related

[Code block](/docs/proa-docs/code-block) · [Math](/docs/proa-docs/math) · [Configuration](/docs/proa-docs/configuration)


---

# Docs: Math

URL: /docs/proa-docs/math
Description: Compile TeX to MathML at build time, with nothing shipped to the browser.

---
title: Math
description: Compile TeX to MathML at build time, with nothing shipped to the browser.
---

Math is off by default. Turn it on and dollar-delimited TeX compiles to MathML during the build:

```rust filename="build.rs"
use proa_docs_build::{Config, MathMode};

let config = Config::new().source(source.markdown(pipeline.math(MathMode::MathMl)));
```

```mdx filename="content/performance.mdx"
Render cost is $O(n)$ in the number of dynamic slots, not in template size.
```

## Why MathML rather than KaTeX

The generated markup renders natively in every modern browser. **No client JavaScript, no stylesheet, no font.**

That is the difference between this and the usual approach. Proa compiles equations during the build and emits MathML. Browser fonts and
MathML support determine their appearance; the page does not need a JavaScript
math renderer.

| Mode | Behaviour |
|---|---|
| `MathMode::Disabled` *(default)* | `$…$` passes through as literal text |
| `MathMode::MathMl` | TeX compiles to MathML during the build |

Leaving it disabled is correct for most sites — prose that never uses math should not pay for a TeX parser in the build.

## Related

[Code block](/docs/proa-docs/code-block) · [Mermaid](/docs/proa-docs/mermaid) · [Configuration](/docs/proa-docs/configuration)


---

# Docs: Rendering pages

URL: /docs/proa-docs/runtime
Description: Put a docs site inside your Proa app.

---
title: Rendering pages
description: Put a docs site inside your Proa app.
---

Your build emits a static registry. This page mounts it: include the registry, add a route, serve the static artifacts, and render a page.

## Including the registry

The build crate handles Markdown parsing, frontmatter resolution, table-of-contents extraction, pager links, search JSON, and generated Rust emission. At runtime your app includes the static `Docs` registry and picks one of two paths:

- call `proa_docs::render` and use the default docs shell
- look up a `DocPage` and render your own shell around the compiled article HTML

```rust filename="src/main.rs"
static DOCS: proa_docs::Docs = proa_docs::include_docs!("docs");
```

The argument **must** match `DocsSource::out_dir_name(...)` from `build.rs`:

```rust filename="build.rs"
// build.rs
let docs = proa_docs_build::DocsSource::new("src/docs")
    .out_dir_name("docs")
    .base_path("/docs")
    .site_name("Proa Docs");
```

`include_docs!("docs")` expands to an `include!` path under `$OUT_DIR/proa_docs/docs/docs.generated.rs`. That generated file holds only static data plus `include_str!` references to generated HTML, Markdown, and search JSON.

Everything your app touches at runtime comes from the handful of types below.

## Reading the registry types

| Type | Purpose |
|------|---------|
| `Docs` | Root registry: config, pages, nav, and optional search artifacts. |
| `DocPage` | One compiled page: route path, title, HTML, Markdown, TOC, prev, next. |
| `NavItem` | Nested sidebar tree item with title, optional icon, optional path, and children. |
| `TocItem` | Heading entry with depth, ID, and title. |
| `DocsResponse` | Runtime response wrapper for HTML, Markdown, JSON, or 404. |
| `DocsNav` | Default nav renderer. |
| `DocsToc` | Default table-of-contents renderer. |
| `DocsPager` | Previous/next page renderer. |

The core data model is inspectable on purpose:

```rust filename="tests/docs_registry.rs"
assert_eq!(DOCS.config.base_path, "/docs");
assert_eq!(DOCS.config.site_name, "Proa Docs");

for page in DOCS.pages {
    println!("{} -> {}", page.slug, page.route_path);
}
```

Routing a request means turning a path into one of those `DocPage` values.

## Finding pages

```rust filename="src/routes/docs.rs"
let page = DOCS.page_for_path("/docs/guides/installation")
    .expect("known docs page");

assert_eq!(page.slug, "guides/installation");
```

`find_page("guides/installation")` looks up by slug. `page_for_path("/docs/guides/installation")` strips the configured base path first. It also normalizes trailing slashes, a trailing `index.html`, and `.md` suffixes.

```rust filename="tests/docs_registry.rs"
assert_eq!(
    DOCS.page_for_path("/docs/guides/installation/")
        .map(|page| page.slug),
    Some("guides/installation"),
);

assert_eq!(
    DOCS.find_page("guides/installation.md")
        .map(|page| page.route_path),
    Some("/docs/guides/installation"),
);
```

You can call `first_page()` for an intentional fallback. Do not use it as a silent 404 replacement in production, unless you want unknown docs URLs to render the first page.

Some requests never reach a page at all, and `render_static` answers those.

## Serving static artifacts

`render_static` handles generated non-page assets:

```rust filename="src/routes/docs.rs"
if let Some(response) = proa_docs::render_static(&DOCS, path) {
    return docs_response_to_axum(response);
}
```

It returns:

- Markdown source for each page at `page.markdown_path`
- search manifest JSON
- search documents JSON

Those responses carry the correct content types:

| Method | Content type |
|--------|--------------|
| `DocsResponse::html` | `text/html; charset=utf-8` |
| `DocsResponse::markdown` | `text/markdown; charset=utf-8` |
| `DocsResponse::json` | `application/json; charset=utf-8` |
| `DocsResponse::not_found` | `text/plain; charset=utf-8` |

The default renderer wires that check together with page lookup for you.

## Rendering with the default shell

`proa_docs::render(&DOCS, path)` returns a `DocsResponse` using the default `DocsShell` renderer:

```rust filename="src/routes/docs.rs"
pub async fn docs_handler(Path(path): Path<String>) -> impl IntoResponse {
    let path = format!("/docs/{path}");
    let response = proa_docs::render(&DOCS, &path);

    (
        StatusCode::from_u16(response.status).unwrap(),
        [(CONTENT_TYPE, response.content_type)],
        response.body.into_owned(),
    )
}
```

`render` checks `render_static` first. If the path is not a static artifact, it renders the matching page. If no page matches, it falls back to `first_page()`, and it returns 404 only when the registry has no pages.

Production sites outgrow that shell, so `proa_docs` exposes the pieces separately.

## Building a custom shell

Production sites want their own shell, header, section picker, search modal, and 404 behavior. Look up the page yourself and render the pieces you want:

```rust filename="src/routes/docs.rs"
use axum::{http::StatusCode, response::{IntoResponse, Response}};

pub fn docs_response(path: &str) -> Response {
    if let Some(response) = proa_docs::render_static(&DOCS, path) {
        return docs_response_to_axum(response);
    }

    let Some(page) = DOCS.page_for_path(path) else {
        return StatusCode::NOT_FOUND.into_response();
    };

    html_response(DocsPageView { docs: &DOCS, page })
}
```

Inside the page view, render the generated article HTML with `BasePathHtml`. The compiler already produced trusted HTML from local Markdown files:

```rust filename="src/routes/docs_page.rs"
use proa::{BasePathHtml, WebContext, WebRenderSync, WriteError};
use proa_docs::{DocPage, Docs, DocsNav, DocsPager, DocsSectionMenu, DocsToc};
use proa::html_sync;

struct DocsPageView {
    docs: &'static Docs,
    page: &'static DocPage,
}

impl<L: proa::DataLoader> WebRenderSync<L> for DocsPageView {
    fn render(self, cx: &mut WebContext<L>) -> Result<(), WriteError> {
        html_sync! {
            <main class="docs-layout">
                <aside>
                    {DocsSectionMenu {
                        docs: self.docs,
                        active_path: self.page.route_path,
                    }}
                    {DocsNav {
                        items: self.docs.nav_items_for_path(self.page.route_path),
                        active_path: self.page.route_path,
                    }}
                </aside>
                <article>{BasePathHtml(self.page.article_html)}</article>
                <aside>{DocsToc { items: self.page.toc }}</aside>
                <footer>{DocsPager { page: self.page }}</footer>
            </main>
        }
        .render(cx)
    }
}
```

Keep `BasePathHtml` scoped to trusted compiled HTML such as `page.article_html`; it composes URL attributes with the deployment prefix without re-escaping the markup. Never use it for request data, CMS data, or user-generated Markdown.

`DocsSectionMenu` and `Docs::nav_items_for_path` live in `proa_docs`, so custom shells share one section picker and one scoped-sidebar behavior. Sections come from folders whose `meta.json` sets `"root": true`, so your app supplies no section list of its own.

A custom shell often fronts more than one registry.

## Including multiple registries

Apps can include more than one generated registry:

```rust filename="src/main.rs"
static DOCS: proa_docs::Docs = proa_docs::include_docs!("docs");
static BLOG: proa_docs::Docs = proa_docs::include_docs!("blog");
```

Route each registry by its configured base path:

```rust filename="src/routes/docs.rs"
if path.starts_with("/blog") {
    return proa_docs::render(&BLOG, path);
}

proa_docs::render(&DOCS, path)
```

Each of those `DocsResponse` values still needs a conversion into your framework's response type.

## Using the Axum adapter

With the `axum` feature enabled, `proa_docs::adapter::axum::response(&DOCS, path)` renders the path and returns an Axum `Response` with the status, content type, and body of the underlying `DocsResponse`.

Use the adapter for a default docs site. Write your own adapter when the app needs custom status handling, metrics, headers, or route-level layout.

Run through the list below before you ship either one.

## Runtime checklist

- Include the registry name that matches `out_dir_name`.
- Call `render_static` before custom page rendering.
- Decide whether unknown paths return 404 or fall back to the first page.
- Render `page.article_html` only as trusted generated HTML.
- Expose `page.markdown_path` if agents or users need source Markdown.
- Keep search JSON routes available when the registry carries `Docs.search`.

## Next steps

- [Configuration](/docs/proa-docs/configuration)
  - Produce the registry this page includes, from `build.rs`, and every builder behind `out_dir_name`, `base_path`, and search.
- [Search](/docs/proa-docs/search)
  - Serve the search manifest and documents JSON to a client UI.
- [Page conventions](/docs/proa-docs/pages-and-routes)
  - Structure the pages your shell renders.


---

# Docs: Customizing the layout

URL: /docs/proa-docs/customizing
Description: Compose the render primitives instead of using the default shell.

---
title: Customizing the layout
description: Compose the render primitives instead of using the default shell.
---

`DocsShell` renders a complete docs page: sidebar, article, table of contents, pager. It emits the whole document, `<head>` included. Most sites never need more.

```rust filename="src/pages/docs.rs"
use proa_docs::DocsShell;

DocsShell { docs, page }.render(cx)?;
```

`DocsShell` writes its own `<head>` (charset, viewport, title, description)
and has no slot for a stylesheet link, so the default theme only applies when
you compose your own head and render `DocsAssets` there, as shown in
[Styling](/docs/proa-docs/quickstart#styling). `DEFAULT_STYLESHEET` and
`DEFAULT_SCRIPT` are the bytes to serve for it.

When you want your own chrome, compose the pieces yourself.

## The primitives

| Component | Renders |
|---|---|
| `DocsShell` | The whole page. Start here |
| `DocsNav` | The sidebar tree for a path |
| `DocsNavItem` | One nav entry, if you are building the tree yourself |
| `DocsSectionMenu` | The section switcher, when any folder is a root |
| `DocsToc` | On-this-page headings |
| `DocsPager` | Previous and next links |
| `TypeTable` | An API table from rows your app supplies; the build does not produce them |
| `nav_icon_svg` | An icon by name, for your own chrome |

Apart from `TypeTable`, each takes data from the compiled `Docs` registry, so they stay in sync with content without threading state.

## Replacing one piece

Keep the primitives, wrap them in your own markup. This is what the Proa site does — its sidebar adds a logo, a search trigger, and a theme toggle around the same `DocsNav` you would use:

```rust filename="src/components/docs/sidebar.rs"
use proa_docs::{DocsNav, DocsSectionMenu};

html_sync! {
    <div class="docs-sidebar-inner">
        <div class="docs-sidebar-header">
            {SearchTrigger { class: Some("docs-sidebar-search") }}
            {DocsSectionMenu { docs, active_path: page.route_path }}
        </div>
        <div class="docs-sidebar-content">
            {DocsNav {
                items: docs.nav_items_for_path(page.route_path),
                active_path: page.route_path,
            }}
        </div>
    </div>
}
```

`proa_marketing/src/components/docs/` in the Proa repository is the full worked example — sidebar, article, and page, each wrapping primitives rather than replacing them.

## Reading the registry directly

For chrome the primitives do not cover, walk the model:

| Type | Holds |
|---|---|
| `Docs` | Config, every page, the nav tree, search artifacts |
| `DocPage` | Slug, route, title, description, article HTML, TOC, prev/next |
| `NavItem` | One nav node: page, group, separator, or root |
| `TocItem` | Depth, id, title |

```rust filename="src/pages/docs.rs"
let page = docs.page_for_path(path)?;
let items = docs.nav_items_for_path(page.route_path);
```

`nav_items_for_path` returns a root section's children when the path is inside one, and the whole tree otherwise. That single call is what makes the section switcher work.

## Styling what you build

The primitives emit stable class and `data-` hooks, all documented in [Styling contract](/docs/proa-docs/styling-contract). Your own wrapper markup is yours to style; the parts you compose keep working with the default theme.

## Related

[Rendering pages](/docs/proa-docs/runtime) · [Styling contract](/docs/proa-docs/styling-contract) · [Navigation](/docs/proa-docs/navigation)


---

# Docs: Styling contract

URL: /docs/proa-docs/styling-contract
Description: Every hook the components emit, and what your CSS must do with it.

---
title: Styling contract
description: Every hook the components emit, and what your CSS must do with it.
---

`proa_docs_build` lowers authored components into HTML carrying stable class and `data-` hooks. `proa_docs` ships a default theme for all of them, so you do not have to write any of this to get a working site.

```rust filename="src/layouts/docs.rs"
use proa_docs::DocsAssets;

html_sync! {
    <head>
        {DocsAssets::new()}
    </head>
}
```

Read on when you want to change how it looks.

## Theming without replacing anything

Every colour in the default theme comes from 15 custom properties scoped to `.proa-docs-body`, the class `DocsShell` puts on its root. Override them and every component follows:

```css filename="app.css"
.proa-docs-body {
  --docs-bg: #fbfbfa;
  --docs-fg: #18181b;
  --docs-accent: #ff6a13;
  --docs-line: rgba(24, 24, 27, 0.12);
}

.dark .proa-docs-body {
  --docs-bg: #0b0b0d;
  --docs-fg: #f4f4f5;
}
```

That is the whole theming API. Reach for the hooks below only when you need to change layout or structure, not colour.

## Replacing the theme

Ship your own CSS instead of `DEFAULT_STYLESHEET` and target the hooks in this page. They are part of the public API: they will not change without a major version.

Two rules make a replacement theme work:

- **Tabs and the code explorer are CSS-only.** They are radio groups — `input[name="proa-docs-tabs-N"]` plus sibling panels. There is no JavaScript fallback, so if your CSS does not implement the `:checked` sibling selectors, every panel renders stacked. Copy that section from the default stylesheet before changing anything else.
- **`data-` attributes carry state, classes carry identity.** Style `[data-copied="true"]`, `[data-highlighted-line]`, and `[data-kind="folder"]`; do not depend on element order.

## What needs JavaScript

Almost nothing. `DEFAULT_SCRIPT` wires two things and both degrade cleanly:

| Hook | Behaviour | Without the script |
|---|---|---|
| `[data-code-copy]` | Copies the enclosing `[data-code-block]` | Button renders, does nothing |
| `[data-docs-copy-markdown]` | Fetches `[data-docs-markdown-src]` and copies it | Button renders, does nothing |

Everything else — tabs, accordions, the code explorer, steps, callouts, file trees — is CSS-only and works with JavaScript disabled.

## Syntax highlighting

Highlighted tokens carry semantic `hl-*` classes rather than inline colours, so your stylesheet owns the palette:

```css filename="app.css"
.proa-docs-body .hl-keyword { color: #c678dd; }
.proa-docs-body .hl-string  { color: #98c379; }
.proa-docs-body .hl-comment { color: #7f848e; font-style: italic; }
```

A block that failed to highlight still renders as escaped source text with no `hl-*` classes, so unknown languages degrade to plain code.

## The hooks

Generated from the component sources. Each is stable within a major version.

### Accordions

| Hook | Kind |
|---|---|
| `.proa-docs-accordion` | class |
| `.proa-docs-accordion-body` | class |
| `.proa-docs-accordion-title` | class |
| `.proa-docs-accordions` | class |

### Callout

| Hook | Kind |
|---|---|
| `.proa-docs-callout` | class |
| `.proa-docs-callout-body` | class |
| `.proa-docs-callout-icon` | class |
| `[data-type]` | attribute |

### Code Block

| Hook | Kind |
|---|---|
| `.proa-docs-code-block` | class |
| `.proa-docs-code-file-icon` | class |
| `.proa-docs-code-filename` | class |
| `.proa-docs-code-header` | class |
| `[data-code-block]` | attribute |
| `[data-code-copy]` | attribute |
| `[data-code-file-icon]` | attribute |
| `[data-code-filename]` | attribute |
| `[data-code-header]` | attribute |
| `[data-code-highlight]` | attribute |
| `[data-code-icon]` | attribute |
| `[data-code-line]` | attribute |
| `[data-code-lines]` | attribute |
| `[data-filename]` | attribute |
| `[data-highlighted-line]` | attribute |
| `[data-lang]` | attribute |
| `[data-proa-docs-mermaid]` | attribute |
| `[data-proa-docs-mermaid-output]` | attribute |
| `[data-proa-docs-mermaid-source]` | attribute |

### Code Explorer

| Hook | Kind |
|---|---|
| `.proa-docs-code-file-icon` | class |
| `.proa-docs-explorer` | class |
| `.proa-docs-explorer-file` | class |
| `.proa-docs-explorer-file-name` | class |
| `.proa-docs-explorer-path` | class |
| `.proa-docs-explorer-path-segment` | class |
| `.proa-docs-explorer-path-separator` | class |
| `.proa-docs-explorer-paths` | class |
| `.proa-docs-tabs` | class |
| `.proa-docs-tabs-list` | class |
| `.proa-docs-tabs-panel` | class |
| `.proa-docs-tabs-panels` | class |
| `.proa-docs-tabs-radio` | class |
| `.proa-docs-tabs-tab` | class |
| `[data-code-file-icon]` | attribute |
| `[data-code-icon]` | attribute |
| `[data-index]` | attribute |
| `[data-proa-docs-explorer]` | attribute |

### Demo

| Hook | Kind |
|---|---|
| `.proa-docs-demo` | class |
| `.proa-docs-demo-frame` | class |
| `.proa-docs-demo-link` | class |
| `[data-proa-docs-demo]` | attribute |

### Files

| Hook | Kind |
|---|---|
| `.proa-docs-filetree` | class |
| `.proa-docs-filetree-icon` | class |
| `.proa-docs-filetree-indent` | class |
| `.proa-docs-filetree-row` | class |
| `[data-kind]` | attribute |
| `[data-proa-docs-filetree]` | attribute |

### Steps

| Hook | Kind |
|---|---|
| `.proa-docs-step` | class |
| `.proa-docs-steps` | class |

### Tabs

| Hook | Kind |
|---|---|
| `.proa-docs-tabs` | class |
| `.proa-docs-tabs-list` | class |
| `.proa-docs-tabs-panel` | class |
| `.proa-docs-tabs-panels` | class |
| `.proa-docs-tabs-radio` | class |
| `.proa-docs-tabs-tab` | class |
| `[data-index]` | attribute |
| `[data-proa-docs-tabs]` | attribute |

### Type Table

| Hook | Kind |
|---|---|
| `[data-proa-docs-type-table-pending]` | attribute |

## Related

[Proa Docs](/docs/proa-docs) · [Customizing the layout](/docs/proa-docs/customizing) · [Configuration](/docs/proa-docs/configuration)


---

# Docs: Search

URL: /docs/proa-docs/search
Description: Generate static search manifests and serve search documents from the Docs registry.

---
title: Search
description: Generate static search manifests and serve search documents from the Docs registry.
---

`proa_docs_build` emits static search artifacts for each docs source, and `proa_docs::render_static` serves them as JSON. This page covers [enabling search](#enabling-search), [the generated artifacts](#reading-the-generated-artifacts), and [serving them to a client](#serving-artifacts-to-a-client).

## Enabling search

`DocsSource::new(...)` defaults to `SearchConfig::orama_client()`, and the generated runtime registry stores the artifacts on `Docs.search`:

```rust filename="build.rs"
let docs = proa_docs_build::DocsSource::new("src/docs")
    .base_path("/docs")
    .search(proa_docs_build::SearchConfig::orama_client());
```

Turn search on for a client search box, a server-side search endpoint, or a custom indexer that never walks Markdown at runtime. Disable search for a source that must not publish index data:

```rust filename="build.rs"
let internal = proa_docs_build::DocsSource::new("src/internal")
    .base_path("/internal")
    .search(proa_docs_build::SearchConfig::disabled());
```

The current compiler treats every non-disabled mode as "emit the JSON artifacts":

| Mode | Behavior |
|------|----------|
| `SearchConfig::disabled()` | Do not emit search artifacts. |
| `SearchConfig::orama_client()` | Emit Orama-shaped client data. This is the default. |
| `SearchConfig::static_client()` | Emit the same data for any static client indexer. |
| `SearchConfig::Server` | Emit the same data and let the app build a server index. |
| `SearchConfig::Custom(String)` | Emit the same data and let the app bind it to a custom search layer. |

### Excluding a page from the index

Pages are searchable by default. Add `search: false` to frontmatter to render a page and keep it out of the search index:

```markdown filename="src/docs/internal/notes.mdx"
---
title: Internal Notes
search: false
---
```

Use this for pages that contain generated noise, internal operations notes, or placeholder docs. Everything else lands in the two artifacts the compiler writes.

## Reading the generated artifacts

With search enabled, the compiler writes these files under `$OUT_DIR/proa_docs/<out_dir_name>/`:

```text filename="$OUT_DIR/proa_docs/docs"
search/manifest.json
search/documents.json
```

The generated Rust embeds both with `include_str!` and exposes public paths based on the source `base_path`:

```rust filename="src/pages/docs.rs"
let search = DOCS.search.expect("search enabled");

assert_eq!(search.manifest_path, "/docs/_search/manifest.json");
assert_eq!(search.documents_path, "/docs/_search/documents.json");
```

### Manifest shape

The manifest is the small file a browser fetches first:

```json filename="/docs/_search/manifest.json"
{
  "version": 1,
  "engine": "orama",
  "basePath": "/docs",
  "hash": "sha256-...",
  "documents": "/docs/_search/documents.json"
}
```

Use `hash` to decide whether to rebuild a cached client index. It is a SHA-256 hash of the generated `documents.json` payload.

### Document shape

`documents.json` contains every searchable page:

```json filename="/docs/_search/documents.json"
{
  "version": 1,
  "documents": [
    {
      "id": "guides/quickstart",
      "url": "/docs/guides/quickstart",
      "title": "Getting Started",
      "description": "Install Proa and render your first page.",
      "section": "Start here",
      "content": "Getting Started Install Proa ...",
      "breadcrumbs": ["Getting Started"],
      "headings": [
        { "id": "install", "depth": 2, "title": "Install" }
      ],
      "keywords": ["html_sync", "html!"],
      "rank": 100
    }
  ]
}
```

The compiler extracts `content` while rendering Markdown. It includes heading text, paragraph text, inline code, and fenced code block text. `description` is the frontmatter description, else the page's first prose line (skipping headings, fences, and rules), else `null`. `section` is the title of the nearest `meta.json` separator above the page in the navigation, or `null` for pages outside a separator. `keywords` is the frontmatter `keywords` list: identifiers and API names the page canonically documents, which a client should boost above body text. The `headings` array mirrors the page table of contents, including heading depth and generated anchor ids. Your app decides how those two files reach the browser.

## Serving artifacts to a client

Route requests through `render_static` before normal page rendering. It handles search JSON and Markdown source routes:

```rust filename="src/pages/docs.rs"
pub fn docs_response(path: &str) -> axum::response::Response {
    if let Some(response) = proa_docs::render_static(&DOCS, path) {
        return docs_response_to_axum(response);
    }

    let Some(page) = DOCS.page_for_path(path) else {
        return axum::response::IntoResponse::into_response(
            axum::http::StatusCode::NOT_FOUND,
        );
    };
    docs_html_response(page)
}
```

> **Good to know**: `proa_docs::render(&DOCS, path)` calls `render_static` first, so a page handler built on `render` already serves these routes.

### Loading in the browser

Load the manifest, compare the hash, then fetch the documents file only when the index changed:

```ts filename="src/client/search.ts"
type SearchManifest = {
  version: 1;
  engine: "orama";
  basePath: string;
  hash: string;
  documents: string;
};

type SearchDocuments = {
  version: 1;
  documents: Array<{
    id: string;
    url: string;
    title: string;
    content: string;
    headings: Array<{ id: string; depth: number; title: string }>;
    rank: number;
  }>;
};

let cached: { hash: string; data: SearchDocuments } | undefined;

// Bridge to an external JavaScript search indexer; use RSJS for application UI.
async function loadSearchData(): Promise<SearchDocuments> {
  const manifestResponse = await fetch("/docs/_search/manifest.json");
  if (!manifestResponse.ok) throw new Error("Search manifest failed");
  const manifest: SearchManifest = await manifestResponse.json();
  if (cached?.hash === manifest.hash) return cached.data;

  const response = await fetch(manifest.documents);
  if (!response.ok) throw new Error("Search documents failed");
  const data: SearchDocuments = await response.json();
  cached = { hash: manifest.hash, data };
  return data;
}
```

After that, feed `documents` into Orama, Fuse, Minisearch, or your own server endpoint. Proa Docs owns the extraction and stable URLs; the app owns ranking and UI. A site with several sources gets one set of artifacts per source.

## Splitting search across sources

Each source owns its own artifacts:

```rust filename="build.rs"
let docs = proa_docs_build::DocsSource::new("src/docs")
    .out_dir_name("docs")
    .base_path("/docs");

let blog = proa_docs_build::DocsSource::new("src/blog")
    .out_dir_name("blog")
    .base_path("/blog");
```

Those sources publish separate search paths:

```text filename="published search routes"
/docs/_search/manifest.json
/docs/_search/documents.json
/blog/_search/manifest.json
/blog/_search/documents.json
```

Keep them separate if the UI has scoped search. Merge their `documents` arrays at app startup when the UI searches across the whole site. One more pass before launch keeps the served JSON honest.

## Shipping to production

- Serve both JSON routes with `application/json; charset=utf-8`.
- Cache `documents.json` by content hash, not by path alone.
- Keep `search: false` on draft-like or generated pages.
- Test one real query against the rendered site, not just the generated JSON.
- Rebuild the index whenever the docs build runs.

## Next steps

- [Runtime](/docs/proa-docs/runtime)
  - Include generated Docs registries, serve static artifacts, and render docs pages.
- [Configuration](/docs/proa-docs/configuration)
  - Configure sources, Markdown processing, schemas, search, link validation, and output paths.
- [Authoring](/docs/proa-docs/pages-and-routes)
  - Structure files with Markdown, frontmatter, and meta.json navigation.


---

# Docs: Link validation

URL: /docs/proa-docs/link-validation
Description: Validate compiled docs routes, heading hashes, and URL-relative links at build time.

---
title: Link validation
description: Validate compiled docs routes, heading hashes, and URL-relative links at build time.
---

`proa_docs_build` records links while it compiles Markdown. The validator checks those links against the compiled page graph, so broken docs links can fail CI before the site ships.

Use it for three common problems:

- a page links to a route that does not exist
- a page links to a heading id that changed
- a relative docs link resolves differently than the author expected

## Strict Mode

Use strict mode in production docs:

```rust
let docs = proa_docs_build::DocsSource::new("src/docs")
    .link_validation(proa_docs_build::LinkValidation::strict());
```

`LinkValidation::strict()` sets `mode` to `Error`. During `try_compile`, broken links print diagnostics and return `CompileError::LinkValidation(count)`. The convenience `compile` wrapper panics on that error, which is usually what you want in `build.rs`.

```text
cargo:warning=docs link validation: src/docs/guides/page.md: unknown internal route `/docs/guides/missing` (./missing)
cargo:warning=docs link validation: src/docs/core.md: unknown hash `#old-heading` on current page (#old-heading)
```

Keep strict mode on for docs that publish with the application. Use softer modes only while migrating a large collection.

## Configure Checks

```rust
use proa_docs_build::{
    ExternalLinkCheck, LinkValidation, LinkValidationMode, RelativePathMode,
};

let validation = LinkValidation::new()
    .mode(LinkValidationMode::Error)
    .check_internal(true)
    .check_hashes(true)
    .check_relative_paths(RelativePathMode::AsUrl)
    .check_external(ExternalLinkCheck::Disabled);
```

| Option | Purpose |
|--------|---------|
| `mode` | `Off`, `Warn`, or `Error`. `Error` is the mode enforced by `compile`. |
| `check_internal` | Verify internal route targets exist. |
| `check_hashes` | Verify `#heading` targets exist on the page. |
| `check_relative_paths` | Treat relative links as ignored, URL-relative, or file-relative. |
| `check_external` | Present in the API; the current validator skips `http://` and `https://` links. |
| `component_attr` | Present in the API for app-specific link extraction; not consumed by the current Markdown validator. |
| `static_root` | Present in the API for static asset roots; not consumed by the current Markdown validator. |

Defaults are intentionally useful for docs:

```rust
let validation = LinkValidation::new();

assert_eq!(validation.mode, LinkValidationMode::Warn);
assert!(validation.check_internal);
assert!(validation.check_hashes);
```

For production builds, prefer:

```rust
let validation = LinkValidation::strict()
    .check_relative_paths(RelativePathMode::AsUrl);
```

`RelativePathMode::AsUrl` resolves `./quickstart` from `/docs/guides/install` to `/docs/guides/quickstart`. `RelativePathMode::Ignore` skips relative links. `RelativePathMode::AsFile` exists in the enum, but currently skips relative links; it does not resolve source-file paths.

## What Gets Checked

The validator ignores empty links, `mailto:`, `tel:`, `http://`, and `https://` links. It checks:

| Link | Check |
|------|-------|
| `/docs/core` | Route exists in the compiled docs graph. |
| `/docs/core#render-traits` | Route exists and that page has the heading id. |
| `#quick-reference` | Current page has the heading id. |
| `./quickstart` | Resolves as a URL when `RelativePathMode::AsUrl` is selected. |

For example, `/docs/core#render-traits` must point to a compiled page and a known heading id on that page.

Heading ids come from Markdown headings after slug generation:

```markdown
## Render Traits

[Jump to render traits](#render-traits)
```

If the heading changes to `## Rendering Traits`, the link now points at a missing hash and strict validation fails.

## Validate Without Emitting

Use `validate_links` when you want a dedicated CI check:

```rust
let report = proa_docs_build::validate_links(
    proa_docs_build::Config::new().source(
        proa_docs_build::DocsSource::new("src/docs")
            .link_validation(proa_docs_build::LinkValidation::strict()),
    ),
)?;

if !report.is_empty() {
    for diagnostic in report.diagnostics {
        eprintln!(
            "{}: {}: {}",
            diagnostic.source_path,
            diagnostic.href,
            diagnostic.message,
        );
    }
}
```

This path is useful for a dedicated CI job because it builds the link graph and returns diagnostics without writing generated docs files.

## CI Pattern

Keep the build and link check separate when you want clearer failure output:

```rust
fn main() {
    let config = proa_docs_build::Config::new().source(
        proa_docs_build::DocsSource::new("src/docs")
            .link_validation(proa_docs_build::LinkValidation::strict()),
    );

    proa_docs_build::compile(config);
}
```

```rust
#[test]
fn docs_links_are_valid() {
    let report = proa_docs_build::validate_links(
        proa_docs_build::Config::new().source(
            proa_docs_build::DocsSource::new("src/docs")
                .link_validation(proa_docs_build::LinkValidation::strict()),
        ),
    )
    .expect("link validation should run");

    assert!(
        report.is_empty(),
        "docs contain broken links: {:#?}",
        report.diagnostics
    );
}
```

Run it with the rest of the docs checks:

```sh
cargo test -p my-site docs_links_are_valid
cargo check -p my-site
```

## Authoring Rules

- Prefer absolute docs links when linking between major sections.
- Use relative links only inside a tight folder, such as `guides/`.
- Link to headings only when the target heading is stable.
- Run strict validation before renaming pages or headings.
- Keep redirects in app routing; the current validator checks compiled page routes, not redirect tables.


---

# Docs: Configuration

URL: /docs/proa-docs/configuration
Description: Set up build.rs, then every option in one place.

---
title: Configuration
description: Set up build.rs, then every option in one place.
---

One `Config` value drives the whole build. Start with the minimal script; the reference below covers every builder.

Proa Docs compiles a Markdown tree in `build.rs`, so a finished site ships as generated Rust with no runtime parser. This page covers [Cargo setup](#adding-the-cargo-dependencies), [a production build script](#writing-a-production-build-script), [schemas](#validating-frontmatter-with-schemas), and [the generated output](#reading-the-generated-output).

## Adding the Cargo dependencies

Add the build crate to `build-dependencies` and the runtime crate to normal dependencies.

```toml filename="Cargo.toml"
[build-dependencies]
proa_docs_build = "0.3.0"

[dependencies]
proa_docs = { version = "0.3.0", features = ["axum"] }
```

These crates.io dependencies work from a standalone application checkout.
Repository contributors can keep using the workspace's in-repository path
dependencies through the root workspace manifest.

The `include_docs!("docs")` argument **must** match the source `out_dir_name("docs")`.

With both crates in place, the build script decides what the compiler produces.

## Writing a production build script

Most apps start from this shape. It turns on code highlighting and search artifacts, and it runs strict link validation in CI. It also prints `cargo:rerun-if-changed` for the docs directory.

```rust filename="build.rs"
use std::{env, path::PathBuf};

fn main() {
    let manifest_dir = PathBuf::from(env::var_os("CARGO_MANIFEST_DIR").unwrap());
    let docs_dir = manifest_dir.join("src/docs");

    println!("cargo:rerun-if-changed=build.rs");
    println!("cargo:rerun-if-changed={}", docs_dir.display());

    let markdown = proa_docs_build::MarkdownPipeline::default()
        .code_highlighting(proa_docs_build::CodeHighlight::new())
        .mdx(proa_docs_build::MdxConfig::proa())
        .mermaid(proa_docs_build::MermaidConfig::new());

    let link_validation = if env::var_os("CI").is_some() {
        proa_docs_build::LinkValidation::strict()
    } else {
        proa_docs_build::LinkValidation::new()
    };

    let docs = proa_docs_build::DocsSource::new(docs_dir)
        .out_dir_name("docs")
        .base_path("/docs")
        .site_name("My Docs")
        .markdown(markdown)
        .search(proa_docs_build::SearchConfig::orama_client())
        .link_validation(link_validation)
        .include_drafts(false);

    proa_docs_build::compile(proa_docs_build::Config::new().source(docs));
}
```

Call `compile(config)` in normal apps. You can call `try_compile(config)` instead when your build script adds custom diagnostics before panicking.

That call writes a registry, which stays inert until your app includes it.

## Including the registry at runtime

Include the generated registry in your app shell or docs route module.

```rust filename="src/main.rs"
static DOCS: proa_docs::Docs = proa_docs::include_docs!("docs");
```

The registry contains:

| Field | What it gives you |
|-------|-------------------|
| `DOCS.config` | `base_path` and `site_name`. |
| `DOCS.pages` | Every compiled page with HTML, Markdown, TOC, pager links, and metadata. |
| `DOCS.nav` | Sidebar tree the compiler generates from files and `meta.json`. |
| `DOCS.search` | Search manifest and document paths when you enable search. |

Use `DOCS.page_for_path(path)` for request routing. Use `DOCS.find_page(slug)` when you already have a slug.

Both lookups lean on `base_path`, one of the defaults the next section lists.

## What defaults does DocsSource start with?

`DocsSource::new(root)` starts with production-oriented defaults:

| Setting | Default |
|---------|---------|
| `out_dir_name` | `docs` |
| `base_path` | `/docs` |
| `site_name` | `Docs` |
| `search` | `SearchConfig::orama_client()` |
| `link_validation` | warn mode, internal links and hashes checked |
| `include_drafts` | `false` |

The compiler normalizes `base_path`. Empty input and `/` become `/`; other values get a leading slash and no trailing slash.

Each source carries its own copy of these settings, so one build can compile several.

## Compiling multiple sources

Compile docs, blog posts, changelogs, or API references in one build by adding more sources. Each source gets its own generated registry.

```rust filename="build.rs"
let markdown = proa_docs_build::MarkdownPipeline::default()
    .code_highlighting(proa_docs_build::CodeHighlight::new())
    .mdx(proa_docs_build::MdxConfig::proa());

let config = proa_docs_build::Config::new()
    .source(
        proa_docs_build::DocsSource::new("src/docs")
            .out_dir_name("docs")
            .base_path("/docs")
            .site_name("Docs")
            .markdown(markdown.clone()),
    )
    .source(
        proa_docs_build::DocsSource::new("src/blog")
            .out_dir_name("blog")
            .base_path("/blog")
            .site_name("Blog")
            .markdown(markdown),
    );

proa_docs_build::compile(config);
```

Runtime includes stay separate:

```rust filename="src/main.rs"
static DOCS: proa_docs::Docs = proa_docs::include_docs!("docs");
static BLOG: proa_docs::Docs = proa_docs::include_docs!("blog");
```

Sources also differ in the frontmatter they demand, which is what schemas describe.

## Validating frontmatter with schemas

Use schemas when a collection needs required or typed metadata.

```rust filename="build.rs"
let page_schema = proa_docs_build::PageSchema::new()
    .required_string("title")
    .optional_string("description")
    .bool_with_default("draft", false)
    .date("last_modified");

let meta_schema = proa_docs_build::MetaSchema::new()
    .optional_string("title")
    .optional_string("icon");

let docs = proa_docs_build::DocsSource::new("src/docs")
    .schema(page_schema)
    .meta_schema(meta_schema);
```

A schema allows unknown frontmatter fields. App-owned metadata passes through, and the compiler still checks the fields you declared.

Once validation passes, the compiler writes its artifacts under `$OUT_DIR`.

## Reading the generated output

The compiler writes generated Rust, article HTML, Markdown source copies, table-of-contents data, pager links, and search JSON under `$OUT_DIR/proa_docs/<out_dir_name>/`. For `out_dir_name("docs")`, the tree looks like this:


```proa-filetree
$OUT_DIR/
  proa_docs/
    docs/
      docs.generated.rs
      pages/
        index.html
        index.md
      search/
        manifest.json
        documents.json
```


`include_docs!("docs")` includes `docs.generated.rs`. The Markdown copies power `.md` routes and copy-for-LLM workflows. The compiler emits the search files when you enable search.

Check those artifacts once, then run the list below before every deploy.

## Shipping a docs site

Before publishing a docs site:

| Check | Why |
|-------|-----|
| Set `base_path` to the mounted route | Links, Markdown routes, and search paths depend on it. |
| Keep `out_dir_name` stable | Runtime `include_docs!(...)` uses it. |
| Enable strict link validation in CI | Broken docs links fail before deploy. |
| Keep `include_drafts(false)` for production | Draft pages never ship by accident. |
| Enable processed Markdown | Copy Markdown and `/llms-full.txt` need source text. |
| Smoke test rendered HTML and `.md` routes | Both human pages and AI/LLM workflows depend on them. |

## Next steps

- [Runtime](/docs/proa-docs/runtime)
  - Include the registry, serve static artifacts, and render your own shell.
- [Markdown pipeline](/docs/proa-docs/markdown)
  - Follow a page through MDX lowering, fences, Mermaid, and search text.
- [Link validation](/docs/proa-docs/link-validation)
  - Fail the build on broken internal routes and heading hashes.

---

# Reference

## Config

`Config` is the top-level build object that you pass to `proa_docs_build::compile(config)`.

```rust filename="build.rs"
let config = proa_docs_build::Config::new()
    .source(docs_source)
    .source(blog_source)
    .plugin(proa_docs_build::plugins::last_modified());
```

| Method | Purpose |
|--------|---------|
| `Config::new()` | Create an empty config. |
| `.source(DocsSource)` | Add a docs-like source that emits a `Docs` registry. |
| `.collection(CollectionSource)` | Add a collection source for future non-doc data pipelines. |
| `.plugin(Plugin)` | Add build plugins. |
| `.sources()` | Read configured docs sources. |
| `.collections()` | Read configured collection sources. |
| `.plugins()` | Read configured plugins. |

Sources do the compiling, and `DocsSource` is the one that produces docs pages.

## DocsSource

`DocsSource::new(root)` compiles one documentation tree.

| Setting | Default | Builder |
|---------|---------|---------|
| `root` | required | `DocsSource::new(root)` |
| `out_dir_name` | `docs` | `.out_dir_name("docs")` |
| `base_path` | `/docs` | `.base_path("/docs")` |
| `site_name` | `Docs` | `.site_name("Proa Docs")` |
| `schema` | empty | `.schema(PageSchema::new())` |
| `meta_schema` | empty | `.meta_schema(MetaSchema::new())` |
| `postprocess` | enabled defaults | `.postprocess(Postprocess::new())` |
| `markdown` | default pipeline | `.markdown(MarkdownPipeline::default())` |
| `search` | `SearchConfig::orama_client()` | `.search(SearchConfig::disabled())` |
| `link_validation` | warn, internal links on | `.link_validation(LinkValidation::strict())` |
| `include_drafts` | `false` | `.include_drafts(true)` |

The compiler normalizes `base_path`. Empty input and `/` become `/`; all other values get a leading slash and no trailing slash.

Two of those settings, `schema` and `meta_schema`, describe the metadata a tree must carry.

## PageSchema

`PageSchema` validates frontmatter fields that your collection requires:

```rust filename="build.rs"
let schema = proa_docs_build::PageSchema::new()
    .required_string("title")
    .optional_string("description")
    .bool_with_default("draft", false)
    .date("last_modified");
```

| Method | Check |
|--------|-------|
| `.required_string(name)` | Field must exist and be a string. |
| `.optional_string(name)` | Field may exist and must be a string. |
| `.bool_with_default(name, default)` | Field may exist and must be a boolean. |
| `.date(name)` | Field may exist and must be a string. The value is not parsed as a date. |

Schema validation checks the fields you configure. The compiler allows unknown fields, so app-specific frontmatter passes through.

Directory metadata lives in `meta.json` files, and `MetaSchema` checks those.

## MetaSchema

`MetaSchema` supports optional string validation:

```rust filename="build.rs"
let meta_schema = proa_docs_build::MetaSchema::new()
    .optional_string("title")
    .optional_string("icon");
```

Use it when a site wants typed checks for custom `meta.json` metadata.

Past validation, `Postprocess` decides which side artifacts the build keeps.

## Postprocess

`Postprocess` controls generated side artifacts.

| Method | Default | Effect |
|--------|---------|--------|
| `.include_processed_markdown(bool)` | `true` | Keep Markdown source copies for static `.md` routes. |
| `.extract_link_references(bool)` | `true` | Record links for validation. |
| `.export_element_ids(bool)` | `true` | Export heading IDs for hash validation and TOC data. |

The current compiler always produces all three artifacts; these flags are configuration surface for opting out in a future release.

The largest artifact, page HTML, comes out of the Markdown pipeline.

## MarkdownPipeline

`MarkdownPipeline` controls the Markdown compiler:

```rust filename="build.rs"
let markdown = proa_docs_build::MarkdownPipeline::default()
    .code_highlighting(proa_docs_build::CodeHighlight::new())
    .mdx(proa_docs_build::MdxConfig::proa())
    .mermaid(proa_docs_build::MermaidConfig::new())
    .math(proa_docs_build::MathMode::MathMl)
    .component_indexing(
        proa_docs_build::ComponentIndexing::new()
            .preserve(["Cards", "Files"])
            .children_only_default(true),
    )
    .typescript(proa_docs_build::TypeScriptDocgen::new().command("pnpm docgen"));
```

| Builder | Purpose |
|---------|---------|
| `.code_highlighting(CodeHighlight)` | Highlight recognized code fences with Syntect during the docs build. |
| `.math(MathMode)` | Configure math handling. |
| `.component_indexing(ComponentIndexing)` | Reserved. Accepted and stored, but nothing reads it yet. |
| `.mdx(MdxConfig)` | Configure deterministic MDX-to-Markdown lowering. |
| `.mermaid(MermaidConfig)` | Turn Mermaid fences into diagram placeholders. |
| `.typescript(TypeScriptDocgen)` | Configure TypeScript type-table extraction. |

Each builder gets its own section below, starting with `CodeHighlight`.

## CodeHighlight

| Constructor | Behavior |
|-------------|----------|
| `CodeHighlight::new()` | Enable highlighting. |
| `CodeHighlight::disabled()` | Disable highlighting. |
| `.enabled(bool)` | Toggle explicitly. |

With highlighting on, Syntect maps recognized-language tokens to stable semantic
`hl-*` classes during the docs build. The site supplies the class colors,
including light and dark themes. Unknown languages fall back to escaped
`<pre><code>`. TypeScript, TSX, and JSX fences highlight through the bundled
JavaScript grammar; TOML is not in the bundled syntax set and falls back to
plain code. Every highlight-enabled block carries `data-code-highlight="syntect"`,
safe fallback blocks included, so client-side highlighters can skip them.

`MathMode` handles the other class of typeset content.

## MathMode

| Mode | Behavior today |
|------|----------------|
| `MathMode::Disabled` | Default. Dollar-delimited text passes through as literal Markdown text. |
| `MathMode::MathMl` | Convert TeX to MathML during the build. Browsers render it natively; no client JavaScript, stylesheet, or font is required. |

MDX lowering, unlike math handling, rewrites the source before the parser sees it.

## MdxConfig

`MdxConfig` is an optional build-time lowering pass for `.mdx` files. It does not execute arbitrary MDX or JavaScript. It rewrites a small configured helper subset to plain Markdown before the normal Markdown compiler runs.

```rust filename="build.rs"
let markdown = proa_docs_build::MarkdownPipeline::default()
    .mdx(proa_docs_build::MdxConfig::proa());
```

| Constructor | Behavior |
|-------------|----------|
| `MdxConfig::disabled()` | Default. The pipeline does not lower `.mdx` files. |
| `MdxConfig::new()` | Enable the lowerer: it normalizes syntax, strips imports, and rejects exports. Helpers stay off until you select them. |
| `MdxConfig::proa()` | Preset used by this site: Cards, Files, AgentTerminal, simple images, simple paragraph tags, layout div removal, class/style normalization, and fence metadata normalization. |

| Builder | Purpose |
|---------|---------|
| `.enabled(bool)` | Toggle the MDX lowering pass. |
| `.strip_imports(bool)` | Remove `import ... from ...` lines. |
| `.strip_comments(bool)` | Remove `` comments, including spans that cross lines. |
| `.reject_exports(bool)` | Fail on `export ...` lines. |
| `.normalize_brace_escapes(bool)` | Convert authored `{ / }` escape helpers back to literal braces. |
| `.normalize_fence_metadata(bool)` | Strip unsupported fence metadata such as `title="main.rs"`; preserve the language, `filename="..."`, and `{2,4-5}` selected-line ranges. |
| `.normalize_class_name(bool)` | Convert `class=` to `class=`. |
| `.normalize_style_objects(bool)` | Convert simple `style=""` objects to string style attributes. |
| `.remove_layout_divs(bool)` | Drop layout-only `<div>` wrappers. |
| `.lower_paragraph_tags(bool)` | Convert simple `<p>`, `<strong>`, and `<code>` HTML to Markdown text. |
| `.cards(bool)` | Lower `<Cards>` with `<Card />` children to Markdown bullet links. |
| `.files(bool)` | Lower `<Files>` with `<Folder>` and `<File>` children to a `proa-filetree` fence. |
| `.agent_terminal(bool)` | Lower `<AgentTerminal />` to a static `text` code fence. |
| `.images(MdxImageConfig)` | Configure simple `<img ... />` lowering. |

The pass writes its processed Markdown into `DocPage::markdown`, which the `.md` routes serve.

Images take enough options to warrant their own config.

## MdxImageConfig

`MdxImageConfig` controls simple image lowering:

```rust filename="build.rs"
let images = proa_docs_build::MdxImageConfig::new()
    .default_alt("Image")
    .rewrite_prefix("/images/", "/static/images/");
```

| Constructor / Builder | Purpose |
|-----------------------|---------|
| `MdxImageConfig::new()` | Enable image lowering. |
| `MdxImageConfig::disabled()` | Disable image lowering. |
| `.enabled(bool)` | Toggle image lowering. |
| `.default_alt(value)` | Alt text used when an authored image omits `alt`. |
| `.rewrite_prefix(from, to)` | Rewrite a source path prefix before emitting Markdown image syntax. |

Diagrams survive lowering as `mermaid` fences, which `MermaidConfig` picks up.

## MermaidConfig

`MermaidConfig::new()` enables Mermaid support.

| Setting | Default | Builder |
|---------|---------|---------|
| `enabled` | `false`, `true` from `new()` | `MermaidConfig::new()` |
| `code_fences` | `true` | `.code_fences(false)` |
| `renderer` | `MermaidRenderer::Client` | `.renderer(...)` |
| `fallback` | `MermaidFallback::CodeBlock` | `.fallback(...)` |

The renderer accepts `Client`, `StaticSvg`, and `Custom`. The current compiler emits client-rendered placeholders for Mermaid fences when you enable them.

Components the lowerer leaves alone can still reach an app-level pass through `ComponentIndexing`.

## ComponentIndexing

| Method | Purpose |
|--------|---------|
| `ComponentIndexing::new()` | Create default config. |
| `.preserve(names)` | Preserve named component directives for app-level processing. |
| `.children_only_default(bool)` | Treat unconfigured components as children-only by default. |

This is reserved configuration surface: the builder is accepted and stored, but no compile step reads `preserve` or `children_only_default` yet. Inline HTML that is not a recognized container tag or type-table directive is always escaped.

## TypeScriptDocgen

`TypeScriptDocgen::new()` enables type-table requests. The default component name is `auto-type-table`.

| Method | Purpose |
|--------|---------|
| `.enabled(bool)` | Toggle TypeScript docgen. |
| `.tsconfig_path(path)` | Select the TypeScript config. |
| `.base_path(path)` | Select the path base used by docgen. |
| `.cache_dir(path)` | Select the cache directory. |
| `.component_name(name)` | Change the directive component name. |
| `.hide_internal(bool)` | Hide internal API items. |
| `.annotation(Annotation)` | Add a JSDoc annotation mapping. |
| `.command(command)` | Record an external docgen command. The build checks that one is set; it does not run it. |

Compilation fails when Markdown requests type tables and you enable TypeScript docgen **without** a command. With a command set, requests still ship as pending placeholders; resolution is not implemented yet.

With the pages compiled, `SearchConfig` decides how readers find them.

## SearchConfig

| Mode | Constructor |
|------|-------------|
| Disabled | `SearchConfig::disabled()` |
| Orama client | `SearchConfig::orama_client()` |
| Static client | `SearchConfig::static_client()` |
| Server-owned search | `SearchConfig::Server` |
| Custom integration | `SearchConfig::Custom(String)` |

Every enabled mode emits a search manifest and documents JSON today. Your app decides whether to load them on the client, serve them through an API, or feed another index.

`LinkValidation` guards the other half of navigation: the links themselves.

## LinkValidation

`LinkValidation::default()` uses `Warn` mode, which `compile` does not act on: no validation runs and nothing is printed. `LinkValidation::strict()` (`Error` mode) validates during `compile` and fails the build, printing each broken link first. To get a report without failing, call `validate_links` yourself.

| Method | Purpose |
|--------|---------|
| `.mode(LinkValidationMode)` | `Off`, `Warn`, or `Error`. |
| `.check_internal(bool)` | Check absolute and relative internal route targets. |
| `.check_hashes(bool)` | Check heading hashes. |
| `.check_relative_paths(RelativePathMode)` | Ignore or URL-resolve relative links. `AsFile` currently skips them. |
| `.check_external(ExternalLinkCheck)` | Store external-link settings; the current validator makes no external requests. |
| `.component_attr(component, attr)` | Reserved setting; the current validator does not read custom component attributes. |
| `.static_root(path)` | Reserved setting; the current validator does not resolve static asset roots. |

See [Link validation](/docs/proa-docs/link-validation) for examples.

Collections reuse the same source shape for data that is not a docs page.

## CollectionSource

`CollectionSource` is available for future collection compilation.

| Method | Purpose |
|--------|---------|
| `CollectionSource::new(root)` | Create a collection source. |
| `.kind(CollectionKind)` | Select `Doc` or `Data`. |
| `.schema(PageSchema)` | Validate collection frontmatter. |
| `.root()` | Read the source root. |
| `.collection_kind()` | Read the configured kind. |

Plugins are the last extension point on `Config`.

## Plugins

`proa_docs_build` exposes two plugin constructors today:

| Plugin | Purpose |
|--------|---------|
| `plugins::json_schema()` | Reserve schema output integration. |
| `plugins::last_modified()` | Reserve last-modified metadata integration. |

The plugin API stays small while docs compilation stabilizes.

## Next steps

- [Markdown pipeline](/docs/proa-docs/markdown)
  - Follow a page through MDX lowering, fences, Mermaid, and search text.
- [Link validation](/docs/proa-docs/link-validation)
  - Fail the build on broken internal routes and heading hashes.
- [Runtime](/docs/proa-docs/runtime)
  - Include the generated registry and render it from your app.

## Related

[Quickstart](/docs/proa-docs/quickstart) · [Rendering pages](/docs/proa-docs/runtime) · [Search](/docs/proa-docs/search) · [Link validation](/docs/proa-docs/link-validation)


---

# Docs: Authoring

URL: /docs/proa-docs/_retired/authoring
Description: This guide has moved; follow the links to the current documentation.

---
search: false
title: Authoring
description: This guide has moved; follow the links to the current documentation.
---

This guide has moved to [Pages and routes](/docs/proa-docs/pages-and-routes). For component syntax, start with the [Proa Docs quickstart](/docs/proa-docs/quickstart).


---

# Docs: Config reference

URL: /docs/proa-docs/_retired/config-reference
Description: This guide has moved; follow the links to the current documentation.

---
search: false
title: Config reference
description: This guide has moved; follow the links to the current documentation.
---

This reference has moved to [Configuration](/docs/proa-docs/configuration), which documents the current builders, defaults, and implementation limits.


---

# Docs: Markdown pipeline

URL: /docs/proa-docs/_retired/markdown-pipeline
Description: This guide has moved; follow the links to the current documentation.

---
search: false
title: Markdown pipeline
description: This guide has moved; follow the links to the current documentation.
---

This guide has moved to [Markdown](/docs/proa-docs/markdown). See [Code block](/docs/proa-docs/code-block) for highlighting, filenames, and selected lines, or [Configuration](/docs/proa-docs/configuration) for pipeline settings.


---

# Docs: Page conventions

URL: /docs/proa-docs/_retired/page-conventions
Description: This guide has moved; follow the links to the current documentation.

---
search: false
title: Page conventions
description: This guide has moved; follow the links to the current documentation.
---

This guide has moved to [Pages and routes](/docs/proa-docs/pages-and-routes). See [Navigation](/docs/proa-docs/navigation) for sidebar ordering and section roots.