HTMX and Server-Side Rendering
Relevant source files
The following files were used as context for generating this wiki page:
Loco provides robust support for server-side rendering (SSR) and modern "hypermedia-driven" applications through integration with HTMX and the Tera template engine. By utilizing Loco's core generator scaffolding abilities, developers can generate full CRUD (Create, Read, Update, Delete) views that are powered by HTMX, allowing for dynamic user interfaces without the complexity of a heavy client-side JavaScript framework.
The framework is designed to handle various content types and can match on incoming request formats to serve either JSON for APIs or HTML for browser-based views. This flexibility allows a single controller to serve both a headless API and a full-stack UI app seamlessly.
Sources: docs-site/content/casts/007-htmx.md:5-7, docs-site/content/casts/001-dynamic-responses-and-content-types.md:5-7, docs-site/config.toml:117-124
Architecture and Data Flow
The architecture for HTMX and SSR in Loco revolves around the controller's ability to be "content-aware." Requests are routed to a controller which determines the appropriate response format based on headers or path extensions. When a request for HTML is identified, the controller utilizes the Tera engine to render templates on the server before sending the final HTML fragment or page back to the client.
Request-Response Lifecycle
The following diagram illustrates how Loco handles dynamic content types, switching between JSON and HTMX/HTML responses.
The flow shows the controller acting as the orchestrator, deciding whether to invoke the template engine or return serialized data.
Sources: docs-site/config.toml:104-124, docs-site/content/casts/001-dynamic-responses-and-content-types.md:5-7
Scaffolding and Generation
Loco simplifies the creation of SSR applications through powerful CLI generators. Developers can generate entire modules including models, controllers, migrations, and HTML views with a single command.
HTMX Scaffolding
Loco includes a specific scaffold generator for HTMX-powered views. This generator creates a set of views that use HTMX attributes (like hx-get, hx-post) to perform asynchronous updates to the DOM using server-rendered HTML fragments.
| Component | Description |
|---|---|
| Model | SeaORM entities for database interaction. |
| Controller | Logic to handle requests and route to HTML/HTMX views. |
| Views | Tera templates specifically formatted for HTMX interactions. |
| Migrations | Database schema definitions for the entity. |
Sources: docs-site/content/casts/007-htmx.md:5-7, docs-site/content/casts/003-scaffolding-crud-with-html.md:5-7
Tera View Engine
Loco uses the Tera engine for SSR. This allows for strongly typed data to be passed from Rust into templates using serde_json macros.
// Example of a Tera view engine response
format::render().view(v, "home/hello.html", json!({
"name": "Loco User",
"items": item_list
}))
Sources: docs-site/config.toml:117-133
Content-Type Awareness
Controllers in Loco are built on Axum and are designed to be "content-aware." This means they can inspect the request and respond with different formats.
The RespondTo Mechanism
The RespondTo enum (or similar matching logic) is used within controller functions to toggle behavior:
- HTML View: Invokes
format::render().view(...)for SSR. - JSON: Invokes
format::json(...)for API clients.
Sources: docs-site/config.toml:104-115, docs-site/content/casts/001-dynamic-responses-and-content-types.md:5-7
Static Asset Serving
In addition to dynamic SSR, Loco can be configured to serve static assets (CSS, JS, Images) that support the server-rendered views. This is managed via the static middleware in the application configuration.
Static Middleware Configuration
Configuration options for serving assets alongside SSR:
| Option | Type | Description |
|---|---|---|
enable | Boolean | Activates the static asset middleware. |
must_exist | Boolean | If true, server fails to start if the folder is missing. |
folder.uri | String | The URL prefix for accessing assets (e.g., /static). |
folder.path | String | The local filesystem path to the assets (e.g., assets/static). |
fallback | String | The file to serve if a requested asset is not found (404 page). |
Sources: loco-new/tests/templates/asset.rs:32-41, docs-site/content/blog/frontend-website.md:92-105
Conclusion
HTMX and Server-Side Rendering in Loco provide a "productivity-first" approach for developers who prefer the simplicity of the Rails-like model over modern SPA complexities. By integrating the Tera engine for SSR and specialized HTMX generators, Loco enables the creation of high-performance, interactive full-stack applications while maintaining the safety and speed of Rust.
Sources: docs-site/config.toml:3-5, docs-site/content/casts/007-htmx.md:5-7