Docs

FrameworkBuilder configuration

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, Responses, Static assets, and Deployment for deeper workflow examples.

Minimal FrameworkBuilder Setup

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 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 for route setup, discovery endpoints, and server startup.

FrameworkBuilder Methods

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:

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 for the installed routes and custom-router alternative. The URL prefix deployment guide covers startup environment configuration, proxy behavior, and coverage limits.

FrameworkBuilder Production Defaults

build() applies conservative defaults:

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:

Cross-origin protection, the 1 MiB body limit, and the 30-second request timeout are applied by build() without configuration. See Security for what Proa hardens and what stays yours.

FrameworkBuilder Static Services

Mount generated assets under /static:

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

Response modifiers:

Use Responses for examples and Data loading and streaming for loader and streaming details.