Docs

Configuration

Configure FrameworkBuilder, security defaults, static mounts, external apps, and response behavior.

FrameworkBuilder turns routes, manifests, static services, external apps, 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 Builder

use std::collections::HashMap;

use axum::routing::get;
use proa_framework_axum::{
    router_from_spec, FrameworkBuilder, IslandManifest, ManifestAssets, Route, RouteResponse,
};

async fn home() -> RouteResponse {
    RouteResponse::ssr(HomePage)
}

let manifest = IslandManifest {
    islands: HashMap::new(),
    assets: ManifestAssets::default(),
    import_map: HashMap::new(),
    ssr_bundle: None,
};

let (routes, metadata) = router_from_spec(vec![
    Route::page("/", "Home", get(home)),
]);

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

with_dynamic_routes_and_metadata is the common path for page routes because it installs both the Axum router and the precomputed metadata map used by response finalization.

Builder Methods

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.

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.

ProaConfig

ProaConfig contains path, codegen, and server defaults:

use proa_framework_axum::{CodegenConfig, PathsConfig, ProaConfig, ServerConfig};

let config = ProaConfig {
    paths: PathsConfig {
        frontend_root: "./apps/web".into(),
        public_dir: "./apps/web/public".into(),
        build_output: "./apps/web/dist".into(),
        ..Default::default()
    },
    codegen: CodegenConfig {
        routes: true,
        components: true,
        islands: true,
        watch: cfg!(debug_assertions),
    },
    server: ServerConfig {
        host: "0.0.0.0".to_string(),
        port: 3000,
        auto_reload: cfg!(debug_assertions),
    },
};

PathsConfig

CodegenConfig

ServerConfig

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(manifest)
    .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.

External Apps

Use external app mounts when one path is owned by a different frontend or service:

use proa_framework_axum::ExternalApp;

let app = FrameworkBuilder::new(manifest)
    .with_external_app(ExternalApp::static_app("/docs", "./apps/docs/out"))
    .with_external_app(ExternalApp::ssr_app(
        "/admin",
        "http://127.0.0.1:4000".to_string(),
    ))
    .with_external_app(ExternalApp::csr_app(
        "/console",
        "./apps/console/dist",
        Some("http://127.0.0.1:5173".to_string()),
    ))
    .build();

SSR proxy mounts strip hop-by-hop headers, rebuild X-Forwarded-* metadata, reuse a shared HTTP client, and buffer bodies with bounded request and response limits.

Proxy Limits

If you build a ProxyConfig directly, defaults are:

When FrameworkBuilder mounts SSR external apps, it aligns the proxy request cap with the framework body limit.

RouteResponse Quick Reference

Response modifiers:

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