Development Environment

Run Rust natively on your host machine. Run backing services (PostgreSQL, Valkey, Restate, RustFS, MailCrab) in Docker containers. This separation keeps your edit-compile-run cycle fast while giving you disposable, reproducible infrastructure.

Rust Toolchain

Install rustup, which manages your Rust compiler, standard library, and development tools.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

The default installation profile includes rustc, cargo, clippy, and rustfmt. Add rust-analyzer (the language server) and rust-src (standard library source, needed for full rust-analyzer functionality) separately:

rustup component add rust-analyzer rust-src

Verify the installation:

rustc --version
cargo --version

Keep everything current with rustup update. Rust releases a new stable version every six weeks.

What each tool does

• rustc compiles Rust source code. You rarely invoke it directly; cargo handles it.
• cargo builds, tests, runs, and manages dependencies. It is the entry point for nearly every Rust workflow.
• clippy is the official linter. Run cargo clippy to catch common mistakes and non-idiomatic patterns.
• rustfmt formats code to a consistent style. Run cargo fmt to format, cargo fmt -- --check to verify without modifying files.
• rust-analyzer provides IDE features (completions, diagnostics, go-to-definition, refactoring) via the Language Server Protocol. Any editor or AI coding agent with LSP support can use it.

Backing Services with Docker Compose

The application depends on five external services during development. Run them in containers so they are disposable and require no host-level installation.

Create compose.yaml at the project root:

services:
  postgres:
    image: postgres:18-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app_dev
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 5s
      retries: 5

  valkey:
    image: valkey/valkey:9-alpine
    ports:
      - "6379:6379"
    volumes:
      - valkeydata:/data

  restate:
    image: docker.restate.dev/restatedev/restate:latest
    ports:
      - "8080:8080"
      - "9070:9070"
      - "9071:9071"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - restatedata:/target

  rustfs:
    image: rustfs/rustfs:latest
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      RUSTFS_ROOT_USER: minioadmin
      RUSTFS_ROOT_PASSWORD: minioadmin
    volumes:
      - rustfsdata:/data

  mailcrab:
    image: marlonb/mailcrab:latest
    ports:
      - "1080:1080"
      - "1025:1025"

volumes:
  pgdata:
  valkeydata:
  restatedata:
  rustfsdata:

Start all services:

docker compose up -d

Stop containers (data persists in named volumes):

docker compose down

Stop and destroy everything, including data:

docker compose down -v

Service notes

Valkey is the BSD-licensed fork of Redis, maintained by the Linux Foundation. It is fully API-compatible with Redis, so any Redis client library works without changes. The guide uses Valkey because its licence is unambiguous.

Restate is a durable execution engine for reliable background work, workflows, and agentic AI. The extra_hosts entry allows Restate (running inside Docker) to reach your application (running on the host) via host.docker.internal. Use this hostname instead of localhost when registering service deployments with the Restate admin API on port 9070.

RustFS is an S3-compatible object storage server written in Rust, licensed under Apache 2.0. It replaces MinIO, which entered maintenance mode in December 2025. RustFS is still in alpha but functional for local development. Its web console is available at http://localhost:9001.

MailCrab captures all email sent to it. Configure your application’s SMTP to point at localhost:1025, then view captured messages at http://localhost:1080. No email leaves your machine.

Docker runtime

Any Docker-compatible runtime works: Docker Desktop, OrbStack (macOS), Colima (macOS/Linux), or Podman. The docker compose commands behave identically across all of them.

cargo xtask

cargo xtask is a convention for writing project automation as a Rust binary inside your workspace. Instead of shell scripts or Makefiles, your build tasks are Rust code: checked by the compiler, cross-platform, and requiring no external tooling beyond cargo.

The pattern works by defining a cargo alias that runs a dedicated crate.

Setup

Create the alias in .cargo/config.toml:

[alias]
xtask = "run --package xtask --"

Add an xtask crate to your workspace. In the root Cargo.toml:

[workspace]
resolver = "2"
members = ["app", "xtask"]
default-members = ["app"]

default-members prevents cargo build and cargo test from compiling the xtask crate unless explicitly requested.

Create xtask/Cargo.toml:

[package]
name = "xtask"
version = "0.1.0"
edition = "2024"
publish = false

[dependencies]
clap = { version = "4", features = ["derive"] }
xshell = "0.2"
anyhow = "1"

xshell provides shell-like command execution without invoking an actual shell. Variable interpolation is safe by construction, preventing injection.

Create xtask/src/main.rs:

use std::process::ExitCode;

use anyhow::Result;
use clap::{Parser, Subcommand};
use xshell::{cmd, Shell};

#[derive(Parser)]
#[command(name = "xtask")]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// Start backing services and the dev server
    Dev,
    /// Run database migrations
    Migrate,
    /// Run all CI checks locally
    Ci,
}

fn main() -> ExitCode {
    let cli = Cli::parse();
    let result = match cli.command {
        Command::Dev => dev(),
        Command::Migrate => migrate(),
        Command::Ci => ci(),
    };
    match result {
        Ok(()) => ExitCode::SUCCESS,
        Err(e) => {
            eprintln!("error: {e:?}");
            ExitCode::FAILURE
        }
    }
}

fn dev() -> Result<()> {
    let sh = Shell::new()?;
    cmd!(sh, "docker compose up -d").run()?;
    cmd!(sh, "bacon run").run()?;
    Ok(())
}

fn migrate() -> Result<()> {
    let sh = Shell::new()?;
    cmd!(sh, "cargo sqlx migrate run").run()?;
    Ok(())
}

fn ci() -> Result<()> {
    let sh = Shell::new()?;
    cmd!(sh, "cargo fmt --all -- --check").run()?;
    cmd!(sh, "cargo clippy --all-targets -- -D warnings").run()?;
    cmd!(sh, "cargo nextest run").run()?;
    Ok(())
}

Run tasks with:

cargo xtask dev       # start services + dev server
cargo xtask migrate   # run database migrations
cargo xtask ci        # fmt check, clippy, tests

Add subcommands as your project grows. Common additions: seed (populate development data), reset (drop and recreate the database), build-css (run lightningcss processing).

Editor Configuration

Any editor with Language Server Protocol support works for Rust development. Install the rust-analyzer extension or plugin for your editor of choice.

The following rust-analyzer settings matter for this stack. Apply them through your editor’s LSP configuration.

{
  "rust-analyzer.check.command": "clippy",
  "rust-analyzer.procMacro.enable": true,
  "rust-analyzer.cargo.buildScripts.enable": true,
  "rust-analyzer.check.allTargets": true
}

check.command: "clippy" runs clippy instead of cargo check on save, giving you lint feedback inline. Slightly slower on large workspaces, but the additional warnings are worth it.

procMacro.enable: true is critical for this stack. Maud’s html! macro, serde’s derive macros, and SQLx’s query! macro are all procedural macros. Without this setting, rust-analyzer cannot expand them, resulting in false errors and missing completions inside macro invocations.

cargo.buildScripts.enable: true ensures build scripts run during analysis. SQLx’s compile-time query checking depends on this.

check.allTargets: true includes tests, examples, and benchmarks in diagnostic checking.

Fast Iteration

bacon

bacon watches your source files and runs cargo commands on every change. It replaces the older cargo-watch, which is no longer actively developed (its maintainer recommends bacon).

Install it:

cargo install --locked bacon

Run it:

bacon           # defaults to cargo check
bacon clippy    # run clippy on every change
bacon test      # run tests on every change
bacon run       # build and run on every change

bacon provides a TUI with sorted, filtered diagnostics. Press t to switch to tests, c to switch to clippy, r to run the application. The full set of keyboard shortcuts is shown in the interface.

For project-specific jobs, create a bacon.toml at the workspace root:

[jobs.run]
command = ["cargo", "run"]
watch = ["src"]

[jobs.test-integration]
command = ["cargo", "nextest", "run", "--test", "integration"]
watch = ["src", "tests"]

Linking

On Linux with Rust 1.90+, the compiler uses lld (the LLVM linker) by default. This is significantly faster than the traditional system linker and requires no configuration.

On macOS, Apple’s default linker is adequate. No special setup is needed.

Incremental compilation

Cargo enables incremental compilation by default for debug builds. After the initial compile, changing a single file typically triggers a rebuild of only the affected crate and its dependents.

Two practices keep incremental rebuilds fast:

• Split your workspace into focused crates. A change in one crate does not recompile unrelated crates. The Project Structure section covers this in detail.
• Keep macro-heavy code in leaf crates. Procedural macro expansion is one of the slower compilation phases. Isolating it limits the rebuild radius.

cargo-nextest

cargo-nextest is a test runner that executes tests in parallel across separate processes. It is noticeably faster than cargo test on projects with more than a handful of tests, and its output is easier to read.

cargo install --locked cargo-nextest
cargo nextest run

Doctests are not supported by nextest. Run them separately with cargo test --doc.

Project Structure

A Cargo workspace groups multiple crates under a single Cargo.lock and shared target/ directory. Each crate has its own Cargo.toml and its own dependency list, which means the compiler enforces boundaries between crates: if crates/domain/Cargo.toml does not list sqlx, no code in that crate can import it. This is not a convention. It is a compilation error.

Splitting a project into workspace crates gives you faster incremental builds (changing one crate does not recompile unrelated ones), enforced dependency boundaries, and a clear map of what depends on what.

Workspace layout

Use a virtual manifest, a root Cargo.toml that contains [workspace] but no [package]. All application crates live under crates/:

my-app/
  Cargo.toml              # virtual manifest (workspace root)
  Cargo.lock
  .cargo/
    config.toml            # cargo aliases (xtask)
  crates/
    server/                # binary: composition root
    web/                   # library: Axum handlers, routing, middleware
    db/                    # library: SQLx queries and database access
    domain/                # library: shared types, business logic
    config/                # library: environment variable parsing
    jobs/                  # library: Restate durable execution handlers
    xtask/                 # binary: build automation (dev, migrate, ci)
  migrations/              # SQLx migration files
  compose.yaml             # backing services (Postgres, Valkey, etc.)
  .env                     # local environment variables

The flat crates/* layout is the simplest approach. Cargo’s crate namespace is flat, so hierarchical folder structures (like crates/libs/ and crates/services/) add visual complexity that does not map to anything Cargo understands. Put everything under crates/ and use the crate names to communicate purpose.

What each crate does

server is the binary crate and the composition root. It depends on every other crate and wires them together at startup: builds the database pool, constructs the Axum router, starts the HTTP listener. This is the only crate that sees the full dependency graph.

web contains Axum handlers, route definitions, middleware configuration, and Maud templates. It depends on domain for shared types and on db for data access. All HTTP-facing code lives here.

db owns all database access. SQLx queries, connection pool management, and result-to-type mappings belong in this crate. It depends on domain for the types that queries return.

domain holds types and logic shared across the application: entity structs, error enums, validation rules, and any business logic that is not tied to a specific framework. This crate should have minimal dependencies. It does not depend on Axum, SQLx, or any infrastructure crate.

config parses environment variables into typed configuration structs at startup. It depends on serde and dotenvy, not on framework crates.

jobs contains Restate service and workflow handlers for durable background work. It depends on domain and db, but not on web. Jobs are triggered by HTTP handlers but execute independently.

xtask is the build automation crate. The Development Environment section covers its setup in detail.

Root Cargo.toml

The workspace root defines shared settings, dependency versions, and lint configuration for all members.

[workspace]
members = ["crates/*"]
resolver = "3"

[workspace.package]
edition = "2024"
version = "0.1.0"
rust-version = "1.85"

[workspace.dependencies]
# Async runtime
tokio = { version = "1", features = ["rt-multi-thread", "macros", "signal"] }

# Web framework
axum = "0.8"
tower = "0.5"
tower-http = { version = "0.6", features = ["trace", "compression-gzip"] }
tower-sessions = "0.14"

# HTML templating
maud = { version = "0.26", features = ["axum"] }

# Serialisation
serde = { version = "1", features = ["derive"] }
serde_json = "1"

# Database
sqlx = { version = "0.8", default-features = false, features = [
  "runtime-tokio", "postgres", "macros", "migrate",
] }

# Error handling
thiserror = "2"
anyhow = "1"

# Observability
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

# Config
dotenvy = "0.15"

# HTTP client
reqwest = { version = "0.12", default-features = false, features = [
  "rustls-tls", "json",
] }

# Internal crates
app-server = { path = "crates/server" }
app-web = { path = "crates/web" }
app-db = { path = "crates/db" }
app-domain = { path = "crates/domain" }
app-config = { path = "crates/config" }
app-jobs = { path = "crates/jobs" }

[workspace.lints.rust]
unsafe_code = "forbid"
rust_2018_idioms = { level = "warn", priority = -1 }
unreachable_pub = "warn"

[workspace.lints.clippy]
enum_glob_use = "warn"
implicit_clone = "warn"
dbg_macro = "warn"

Workspace dependencies

The [workspace.dependencies] table defines dependency versions once. Member crates reference them with workspace = true:

# crates/web/Cargo.toml
[package]
name = "app-web"
edition.workspace = true
version.workspace = true

[lints]
workspace = true

[dependencies]
axum.workspace = true
maud.workspace = true
tower.workspace = true
tower-http.workspace = true
tower-sessions.workspace = true
serde.workspace = true
tracing.workspace = true
app-domain.workspace = true
app-db.workspace = true

Members can add features on top of the workspace definition. Features are additive: you can add but not remove them.

# crates/db/Cargo.toml
[dependencies]
sqlx = { workspace = true, features = ["uuid", "time"] }

Workspace lints

The [workspace.lints] table shares lint configuration across all crates. Each member opts in with [lints] workspace = true. The example above forbids unsafe code project-wide and enables several useful Clippy lints.

Workspace package metadata

[workspace.package] avoids repeating edition, version, and rust-version in every crate. Members inherit with edition.workspace = true, and so on. Only unpublished, internal crates should share a version this way. If you publish crates to crates.io, give them independent version numbers.

The dependency graph

The crate dependency graph for this layout looks like this:

server ──→ web ──→ domain
  │         │
  │         └────→ db ──→ domain
  │
  ├──────→ db
  ├──────→ config
  ├──────→ jobs ──→ domain
  │         │
  │         └────→ db
  └──────→ domain

domain sits at the bottom with no framework dependencies. db depends on domain and sqlx. web depends on domain, db, and axum. server depends on everything and wires it all together.

This graph is enforced by Cargo.toml files. If someone adds an axum import to the domain crate, the compiler rejects it. No linting rules or code review discipline required.

The domain crate

Keep domain lean. It holds types that multiple crates need: entity structs, ID types, error enums, validation logic. It depends on serde for serialisation and thiserror for error types. It does not depend on Axum, SQLx, Maud, or Tokio.

# crates/domain/Cargo.toml
[package]
name = "app-domain"
edition.workspace = true
version.workspace = true

[lints]
workspace = true

[dependencies]
serde.workspace = true
thiserror.workspace = true

A typical domain crate:

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Contact {
    pub id: i64,
    pub name: String,
    pub email: String,
}

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

#[derive(Debug, thiserror::Error)]
pub enum ContactError {
    #[error("contact not found")]
    NotFound,
    #[error("email already exists")]
    DuplicateEmail,
}

Other crates import these types. The db crate maps SQL rows to Contact. The web crate uses CreateContact to deserialise form submissions. Neither crate defines these types itself, so there is a single source of truth.

The server crate

The binary crate has one job: connect everything and start listening.

# crates/server/Cargo.toml
[package]
name = "app-server"
edition.workspace = true
version.workspace = true

[lints]
workspace = true

[dependencies]
tokio.workspace = true
axum.workspace = true
tracing.workspace = true
tracing-subscriber.workspace = true
app-web.workspace = true
app-db.workspace = true
app-config.workspace = true

use anyhow::Result;
use tracing_subscriber::EnvFilter;

#[tokio::main]
async fn main() -> Result<()> {
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::from_default_env())
        .init();

    let config = app_config::load()?;
    let db = app_db::connect(&config.database_url).await?;
    let app = app_web::router(db);

    let listener = tokio::net::TcpListener::bind(&config.listen_addr).await?;
    tracing::info!("listening on {}", config.listen_addr);
    axum::serve(listener, app).await?;

    Ok(())
}

This is deliberately thin. Route definitions, middleware, and handler logic live in the web crate. The server crate only constructs dependencies and passes them in.

default-members

Set default-members in the workspace root to control which crates cargo build and cargo run operate on by default:

[workspace]
members = ["crates/*"]
default-members = ["crates/server"]
resolver = "3"

With this setting, cargo run starts the server without needing -p app-server. The xtask crate and other library crates only compile when explicitly requested or pulled in as dependencies.

When to split into more crates

Start with fewer crates than you think you need. A single lib crate alongside server and xtask is a reasonable starting point. Split when you have a concrete reason:

• Compile times. A change in one module triggers recompilation of unrelated code. Splitting into separate crates isolates the rebuild radius.
• Dependency sprawl. A module pulls in heavy dependencies that most of the codebase does not need. Moving it to its own crate keeps those dependencies contained.
• Independent deployment. A Restate worker or CLI tool needs to share domain types with the web server but should not pull in Axum.
• Team boundaries. Different people or teams own different parts of the system and want clear interfaces between them.

Do not split pre-emptively. Each new crate adds a Cargo.toml to maintain and a boundary to design. Split when the cost of staying in one crate (slow builds, tangled dependencies) exceeds the cost of the boundary.

Feature unification

Cargo unifies features of shared dependencies across all workspace members. If the web crate enables sqlx/postgres and the jobs crate enables sqlx/uuid, both features are active everywhere. Features are additive, so this usually works fine. It becomes a problem only if two crates need genuinely incompatible configurations of the same dependency, which is rare in practice.

Resolver 3 (the default with edition = "2024") already avoids unifying features across different target platforms, which eliminates the most common source of unexpected feature activation.

Why Hypermedia-Driven Architecture

This section makes the case for hypermedia-driven architecture (HDA) as the default approach to building web applications. The arguments here are opinionated but grounded in the original definition of REST, the economics of framework migration, and the structural properties of HTML as a transfer format.

The technical implementation follows in later sections. This one answers the prior question: why build this way at all?

REST was always about hypermedia

Roy Fielding’s 2000 doctoral dissertation, Architectural Styles and the Design of Network-based Software Architectures, defined REST as “an architectural style for distributed hypermedia systems.” The word hypermedia is not incidental. It is the subject of the entire architecture.

Chapter 5 of the dissertation specifies four interface constraints for REST. The fourth is HATEOAS: Hypermedia As The Engine of Application State. Server responses carry both data and navigational controls. The client does not hardcode knowledge of available actions. It discovers them through hypermedia links and forms embedded in the response. HTML is the canonical format that satisfies this constraint: an HTML page contains both content and the controls (links, forms, buttons) that drive state transitions.

JSON carries no native hypermedia controls. A JSON response like {"name": "Alice", "email": "alice@example.com"} contains data but no affordances. The client must know in advance what URLs to call, what HTTP methods to use, and what payloads to send. This requires out-of-band documentation and tight client-server coupling, which is precisely what REST’s uniform interface constraint was designed to prevent.

By 2008, the drift had become bad enough that Fielding wrote a blog post titled “REST APIs must be hypertext-driven”:

I am getting frustrated by the number of people calling any HTTP-based interface a REST API. […] If the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.

The industry ignored him. The Richardson Maturity Model, popularised by Martin Fowler, formalised REST into “levels.” Most developers stopped at Level 2 (HTTP verbs and resource URLs) and never implemented Level 3 (hypermedia controls). When JSON replaced XML as the dominant transfer format, the “REST” label stuck even though the defining constraint had been dropped. What the industry calls a “RESTful API” is, by Fielding’s definition, RPC with nice URLs.

This matters because the original REST architecture was designed to solve real problems: evolvability, loose coupling, and independent deployment of client and server. Those problems did not go away when the industry adopted JSON APIs. The solutions were simply abandoned.

The HDA architecture defined

A hypermedia-driven application (HDA) returns HTML from the server, not JSON. The term comes from Carson Gross, creator of htmx, and is defined in detail in the book Hypermedia Systems and on the htmx website.

The architecture has two constraints:

1. Hypermedia communication. The server responds to HTTP requests with HTML. The client renders it. There is no JSON serialisation layer, no client-side data model, and no mapping between API responses and UI state. The HTML is the interface.

2. Declarative interactivity. HTML-embedded attributes (such as htmx’s hx-get, hx-post, hx-swap) drive dynamic behaviour. The developer declares what should happen in the markup rather than writing imperative JavaScript to manage requests, state, and DOM updates.

The key mechanism is partial page replacement. When the user interacts with an element, the browser sends an HTTP request and receives an HTML fragment. That fragment replaces a targeted region of the DOM. The server controls what the user sees next, because the server produces the HTML. The client is a rendering engine, not an application runtime.

This eliminates an entire layer of software. In a typical SPA, the server serialises data to JSON, the client deserialises it, maps it into a state store, derives a virtual DOM from that state, and diffs it against the real DOM. In HDA, the server renders HTML and the browser displays it. The serialisation, deserialisation, state management, and virtual DOM diffing layers do not exist because they are not needed.

An HDA is not a traditional multi-page application with full page reloads on every click. The partial replacement model provides the same responsiveness that SPAs deliver, but the interactivity logic lives on the server rather than in client-side JavaScript.

The coupling advantage

Each endpoint in an HDA produces self-contained HTML. A handler for GET /contacts/42/edit returns an edit form. That form contains the data, the input fields, the validation rules (via HTML5 attributes), and the submit action (via the form’s action attribute or htmx attributes). Everything the client needs is in the response. There is no shared state to coordinate with.

SPA architectures centralise client-side state. React applications commonly use a global state store (Redux, Zustand, Jotai, or React Context) to hold data that multiple components need. This creates a coupling pattern: when you change the shape of data in the store, every component that reads or writes that data must be updated.

Redux’s single-store design has been criticised for exhibiting the God Object anti-pattern, where a single entity becomes tightly coupled to much of the codebase. Changes intended to benefit one feature create ripple effects in unrelated features. The React-Redux community documented this problem: hooks encourage tight coupling between Redux state shape and component internals, reducing testability and violating the single responsibility principle.

The single-spa project (a framework for combining multiple SPAs) explicitly warns against sharing Redux stores across micro-frontends: “if you find yourself needing constant sharing of UI state, your microfrontends are likely more coupled than they should be.” This is an acknowledgement from within the SPA ecosystem that centralised client state creates coupling problems.

In HDA, the coupling boundary is the HTTP response. Each response is stateless and self-contained. The server can change the HTML structure of one endpoint without affecting any other endpoint, because there is no shared client-side state that binds them together. Two developers can modify two different pages concurrently with zero coordination. This property is structural, not a matter of discipline. It falls out automatically from the architecture.

The framework migration tax

JavaScript framework churn imposes a recurring cost on every project built with a client-side framework.

AngularJS to Angular 2+. React class components to hooks to server components. Vue 2 to Vue 3. Each major transition changes fundamental patterns: how components are defined, how state is managed, how side effects are handled. Code written against the old patterns must be rewritten, not just updated.

A peer-reviewed study by Ferreira, Borges, and Valente (On the (Un-)Adoption of JavaScript Front-end Frameworks, published in Software: Practice and Experience, 2021) examined 12 open-source projects that performed framework migrations. The findings:

• The time spent performing the migration was greater than or equal to the time spent using the old framework in all 12 projects.
• In 5 of the 12 projects, the time spent migrating exceeded the time spent using both the old and new frameworks combined.
• Migration durations ranged from 7 days to 966 days.

AngularJS reached end-of-life on 31 December 2021. Three years later, BuiltWith reports over one million live websites still running AngularJS. WebTechSurvey puts the figure above 500,000. The exact count varies by measurement method, but the order of magnitude is clear: hundreds of thousands of applications remain on a deprecated, unpatched framework because migrating to Angular 2+ requires a near-complete rewrite of the client-side codebase.

This is not a one-time problem. React’s transition from class components to hooks changed every component pattern in the ecosystem. The ongoing shift toward React Server Components is changing the execution model itself, blurring the boundary between server and client in ways that require rethinking application architecture. Each transition resets knowledge, breaks libraries, and forces rewrites.

The migration tax is a structural property of the SPA model: when interactivity logic lives in client-side JavaScript tied to a specific framework’s component model, that logic must be rewritten whenever the framework’s model changes. HDA does not eliminate the need to stay current with server-side tools, but server-side framework transitions (switching from one Rust web framework to another, for example) affect route definitions and middleware, not the fundamental rendering model. The HTML your server produces is the same regardless of which framework generates it.

The backward-compatibility guarantee

No HTML element has ever been removed from the specification in a way that breaks rendering.

The WHATWG HTML Standard, which governs HTML as a living specification, lists obsolete elements including <marquee>, <center>, <font>, <frame>, and <acronym>. Authors are told not to use them. But the specification still mandates that browsers render them. <marquee> has a complete interface specification (HTMLMarqueeElement) with defined behaviour. <acronym> must be treated as equivalent to <abbr> for rendering purposes. These elements work in every modern browser because the spec requires it.

This is not accidental. It is policy. The W3C HTML Design Principles document establishes a priority of constituencies: “In case of conflict, consider users over authors over implementors over specifiers over theoretical purity.” Backward compatibility flows directly from this principle: breaking existing content harms users, so the specification does not break existing content.

The WHATWG’s founding position reinforces this:

Technologies need to be backwards compatible, that specifications and implementations need to match even if this means changing the specification rather than the implementations.

An application built on HTML, CSS, and HTTP in 2026 can reasonably expect its platform foundation to remain stable for decades. The same HTML that rendered in Netscape Navigator still renders in Chrome today. No JavaScript framework has provided, or can provide, a comparable guarantee. React is 12 years old and has undergone three major paradigm shifts. The <form> element is 31 years old and works exactly as it did in 1995, with additional capabilities layered on top.

This is the core durability argument for HDA. Your investment in HTML templates, HTTP handlers, and declarative interactivity attributes is protected by the strongest backward-compatibility commitment in software: the web platform’s refusal to break existing content.

No separate API layer

In HDA, the HTML response is the API. There is no JSON layer to design, version, document, or maintain.

A traditional SPA architecture requires two applications: a client-side app that renders UI, and a server-side API that produces JSON. These are developed, tested, deployed, and versioned as separate artefacts with a contract between them. When the contract changes, both sides must change in coordination.

HDA collapses this into one application. An Axum handler receives a request, queries the database, renders HTML with Maud, and returns it. The browser displays the HTML. There is one codebase, one deployment, one thing to reason about.

This has practical consequences:

• No API versioning. The server controls the HTML. If the data model changes, the server updates the template. There is no external consumer relying on a JSON schema.
• No serialisation code. No serde annotations on response types, no JSON schema validation on the client, no mapping between API responses and component props.
• No CORS configuration. The browser requests HTML from the same origin that served the page. Cross-origin issues do not arise.
• Faster feature delivery. Adding a field to a page means adding it to the query and the template. In an SPA, it means updating the API response, the TypeScript types, the state store, and the component that renders it.

The reduction in moving parts is not incremental. It is categorical. An entire class of bugs (schema mismatches, stale client caches, API versioning conflicts) cannot occur because the architecture does not have the layers where those bugs live.

When you do need a separate API

HDA does not mean you never write JSON endpoints. It means JSON is not the default, and HTML handles the majority of your application’s interface.

There are legitimate cases where a JSON API is the right tool:

• Third-party integrations. External services that call your application (payment webhooks, OAuth callbacks, partner integrations) communicate in JSON. These are not UI interactions; they are machine-to-machine interfaces.
• Mobile applications. If you ship a native mobile app alongside your web application, the mobile client needs a data API. HDA applies to the web interface; the mobile interface has different constraints.
• Public APIs. If your product offers an API as a feature (for customers to build integrations), that API will be JSON and needs the usual API design treatment: versioning, documentation, authentication, rate limiting.
• Islands of rich interactivity. Some UI components genuinely need client-side state: a drag-and-drop kanban board, a collaborative text editor, a real-time data visualisation. These components can fetch JSON from dedicated endpoints while the rest of the application uses HDA. This is the islands pattern, covered in When to Use HDA.

The principle is straightforward: use HTML for the interface, JSON for integrations. Most web applications are overwhelmingly interface. The JSON endpoints, when needed, are a small surface area alongside the HDA core, not a parallel architecture that doubles the codebase.

The Web Platform Has Caught Up

Between 2022 and 2026, the web platform crossed a capability threshold. Native CSS and HTML features now provide the functionality that historically justified adopting a CSS preprocessor, a utility framework, a CSS-in-JS library, or a JavaScript UI component system. No single feature is transformative. The cumulative effect is that the problems requiring these tools in 2020 can be solved with the platform itself in 2026.

This section catalogues what changed and why it matters for the architectural choice described in Why Hypermedia-Driven Architecture. The HDA model depends on the platform being capable enough that server-rendered HTML, plain CSS, and minimal JavaScript can deliver a production-quality experience. That dependency is now met.

The Interop Project

Cross-browser inconsistency was a primary driver of framework and preprocessor adoption. Developers reached for jQuery, Sass, Autoprefixer, and eventually React because writing to the platform directly meant writing to four different platforms with different bugs. The Interop Project has largely eliminated this rationale.

Interop is a joint initiative of Apple, Google, Igalia, Microsoft, and Mozilla, running annually since 2021 (initially as “Compat 2021”). Each year, the participants agree on a set of web platform features, write shared test suites via the Web Platform Tests project, and publicly track each browser engine’s pass rate. The Interop dashboard reports a single “interop score”: the percentage of tests that pass in all browsers simultaneously.

The scores tell the story:

The low starting scores each year reflect the selection of new focus areas, not regression. Each iteration targets harder, more recent features. That Interop 2025 started at 29% and finished at 97% in stable releases means the browser vendors are converging on new features within a single calendar year.

WebKit’s review of Interop 2025 described the result directly: “Every browser engine invested heavily, and the lines converge at the top. That convergence is what makes the Interop project so valuable, the shared progress that means you can write code once and trust that it works everywhere.”

Interop 2026 launched in February 2026 with 20 focus areas including cross-document view transitions, scroll-driven animation timelines, and continued anchor positioning alignment. The initiative is now in its fifth consecutive year with no signs of winding down.

The practical consequence: if you write CSS and HTML to the current specifications, it works in Chrome, Firefox, Safari, and Edge. The “works in my browser but not yours” problem that drove an entire generation of tooling adoption is, for the features that matter most, solved.

CSS features that replace frameworks

Eight CSS features, all shipping between 2022 and 2026, collectively address the problems that justified Sass, Less, PostCSS, Tailwind, CSS-in-JS, and JavaScript positioning libraries.

Cascade Layers (@layer)

Cascade Layers provide explicit control over cascade priority, independent of selector specificity or source order. All major browsers shipped support within five weeks of each other in early 2022. @layer reached Baseline Widely Available in September 2024.

@layer reset, base, components, utilities;

@layer reset {
  * { margin: 0; box-sizing: border-box; }
}

@layer components {
  .card { padding: 1rem; border: 1px solid #ddd; }
}

@layer utilities {
  .hidden { display: none; }
}

Styles in later-declared layers always win over earlier layers, regardless of specificity. This replaces the specificity arms race that led to !important abuse, strict BEM naming conventions, and CSS-in-JS libraries whose primary value proposition was specificity isolation. Styles outside any @layer have the highest priority, which allows third-party CSS to be layered below application styles without modification.

CSS Nesting

CSS Nesting reached Baseline Newly Available in December 2023, when Chrome 120 and Safari 17.2 shipped the relaxed syntax (Firefox 117 had shipped in August 2023).

.card {
  padding: 1rem;

  h2 {
    font-size: 1.25rem;
  }

  &:hover {
    box-shadow: 0 2px 8px rgb(0 0 0 / 0.1);
  }

  @media (width >= 768px) {
    padding: 2rem;
  }
}

This is the feature that eliminated the most common reason for using Sass or Less. The relaxed nesting syntax (no & required before element selectors) matches what preprocessor users expect. Media queries and other at-rules can nest directly inside selectors.

Container Queries

Container Queries reached Baseline Widely Available in August 2025. Firefox 110 was the last browser to ship, completing Baseline in February 2023.

.card-container {
  container-type: inline-size;
}

@container (inline-size > 400px) {
  .card {
    display: grid;
    grid-template-columns: 200px 1fr;
  }
}

Media queries respond to the viewport. Container queries respond to the size of the containing element. This makes components genuinely reusable: a card component that switches from stacked to horizontal layout based on its container width, not the window width. Previously, achieving this required JavaScript ResizeObserver workarounds or abandoning the idea entirely.

Size container queries are the Baseline part. Style container queries (@container style(...)) remain Chromium-only as of early 2026.

The :has() selector

:has() reached Baseline Newly Available in December 2023, when Firefox 121 shipped (Safari had led in March 2022, Chrome followed in August 2022).

/* Style a card differently when it contains an image */
.card:has(img) {
  grid-template-rows: 200px 1fr;
}

/* Style a form group when its input is invalid */
.form-group:has(:invalid) {
  border-color: var(--color-error);
}

/* Style a section when it has no content */
section:has(> :only-child) {
  padding: 0;
}

:has() is the long-requested “parent selector,” though it is more general than that name implies. It selects an element based on its descendants, siblings, or any relational condition expressible as a selector. Before :has(), selecting a parent based on its children required JavaScript DOM traversal. Entire categories of conditional styling that needed classList.toggle() or framework-level reactivity can now be expressed in CSS alone.

@scope

@scope reached Baseline Newly Available in December 2025, when Firefox 146 shipped (Chrome 118 had led in October 2023, Safari 17.4 followed in March 2024).

@scope (.card) to (.card-footer) {
  p { margin-bottom: 0.5rem; }
  a { color: var(--card-link-color); }
}

@scope provides proximity-based style scoping with both an upper bound (the scope root) and an optional lower bound (the scope limit), creating a “donut scope” that prevents styles from leaking into nested sub-components. This addresses the problem that CSS Modules, BEM, and Shadow DOM each solved partially: keeping component styles from colliding. Unlike Shadow DOM, @scope does not create hard encapsulation boundaries, so styles remain inspectable and overridable when needed.

The cumulative effect

No single feature here replaces a framework. The replacement is structural.

In 2020, a developer building a component library needed: a preprocessor for nesting and variables (Sass), a naming convention or tooling for specificity management (BEM or CSS Modules), JavaScript for responsive component behaviour (ResizeObserver hacks), JavaScript for parent-based conditional styling (no :has()), and either strict discipline or a CSS-in-JS library to prevent style collisions.

In 2026, native CSS handles all of this. Nesting and custom properties replace the preprocessor. @layer replaces specificity management tooling. Container queries replace JavaScript resize detection. :has() replaces JavaScript conditional styling. @scope replaces CSS-in-JS scoping. The developer writes CSS, and it works across browsers.

HTML features that replace JavaScript UI primitives

The historical justification for React’s component model arose partly because HTML lacked native primitives for modals, tooltips, menus, and rich selects. Three of those gaps are now closed at Baseline. Two more are closing.

The <dialog> element

<dialog> reached Baseline Widely Available in approximately September 2024. Firefox 98 and Safari 15.4 completed cross-browser support in March 2022.

<dialog id="confirm-dialog">
  <h2>Delete this item?</h2>
  <p>This action cannot be undone.</p>
  <form method="dialog">
    <button value="cancel">Cancel</button>
    <button value="confirm">Delete</button>
  </form>
</dialog>

A modal <dialog> (opened via showModal()) provides focus trapping, top-layer rendering, backdrop styling via ::backdrop, the Escape key to close, and <form method="dialog"> for declarative close actions. These are the behaviours that every custom modal library (Bootstrap Modal, React Modal, a11y-dialog) reimplements in JavaScript. The native element provides them with correct accessibility semantics, including the dialog ARIA role and proper focus restoration on close, out of the box.

The Popover API

The Popover API reached Baseline Newly Available in January 2025 (Safari 18.3 resolved a light-dismiss bug on iOS that had delayed the designation).

<button popovertarget="menu">Options</button>
<div id="menu" popover>
  <a href="/settings">Settings</a>
  <a href="/profile">Profile</a>
  <a href="/logout">Log out</a>
</div>

The popover attribute gives any element top-layer rendering, light dismiss (click outside or press Escape to close), and automatic accessibility wiring. popover="auto" provides light dismiss; popover="manual" requires explicit close. This replaces Tippy.js, Bootstrap Popovers, and the custom JavaScript that every dropdown menu previously required.

The popover="hint" variant (for hover-triggered tooltips) is an Interop 2026 focus area and not yet Baseline.

Invoker Commands

Invoker Commands (command and commandfor attributes) reached Baseline Newly Available in early 2026, with Safari 26.2 completing cross-browser support after Chrome 135 (April 2025) and Firefox 144.

<button commandfor="my-dialog" command="show-modal">Open</button>
<dialog id="my-dialog">
  <p>Dialog content</p>
  <button commandfor="my-dialog" command="close">Close</button>
</dialog>

Invoker Commands connect a button to a target element declaratively: commandfor names the target, command specifies the action. Built-in commands include show-modal, close, and request-close for dialogs, and toggle-popover, show-popover, hide-popover for popovers. No JavaScript required for these interactions.

Combined with <dialog> and the Popover API, Invoker Commands eliminate the last bit of JavaScript glue that modals and popovers previously required. A dialog can be opened, populated, and closed entirely through HTML attributes and server-rendered content, which is exactly what HDA needs.

Gaps still closing

Two features listed in the outline remain Chromium-only as of February 2026:

Customizable <select> (appearance: base-select). Chrome 134+ and Edge 134+ ship full CSS styling of <select> elements, including custom option rendering via exposed pseudo-elements (::picker(select), selectedoption). Firefox and Safari are implementing but have not shipped to stable. This feature replaces React Select, Select2, and the entire category of custom dropdown libraries that exist because native <select> has been unstyled. The opt-in (appearance: base-select) means browsers without support simply show the default <select>, making it safe to adopt as progressive enhancement.

Speculation Rules API. Chrome 121+ supports declarative prefetch and prerender rules via <script type="speculationrules">. WordPress and Shopify have deployed it at scale. Firefox’s standards position is positive for prefetch but neutral on prerender; Safari has published no position. Non-supporting browsers ignore the <script> block entirely, so it can be deployed today without harm. For HDA applications, speculation rules offer the multi-page navigation speed that SPA prefetching provides, without any client-side routing framework.

Both features work as progressive enhancement: they improve the experience in supporting browsers without breaking others.

Progressive enhancement as the architectural default

The features above share a property: they degrade gracefully. A <dialog> without JavaScript still renders its content. A popover without support becomes a static element. A <select> without appearance: base-select falls back to the native control. This is not accidental. The web platform is designed around progressive enhancement.

Native HTML elements carry built-in ARIA semantics, focus management, and keyboard handling. A <dialog> opened with showModal() traps focus, responds to Escape, announces itself to screen readers, and restores focus to the triggering element on close. A <button> with commandfor and command attributes communicates its relationship to the target element through the accessibility tree. These behaviours are defined by the specification and implemented by the browser.

SPA component libraries must reimplement all of this. A React modal component needs explicit focus-trap logic, an Escape key handler, ARIA attributes, a portal to render in the correct DOM position, and focus restoration on unmount. Libraries like Radix UI and Headless UI exist specifically because implementing accessible interactive components in React is difficult. The native elements provide the same behaviours correctly by default.

In HDA, progressive enhancement is the structural default. The baseline is server-rendered HTML with standard links and forms. htmx attributes enhance but are not required; a form with hx-post and hx-swap still submits normally via the browser’s native form handling if htmx fails to load. In SPA frameworks, progressive enhancement is opt-in and, under deadline pressure, frequently abandoned.

No-build JavaScript

ES Modules (<script type="module">) have been supported in all major browsers since 2018 and are Baseline Widely Available. Import Maps reached Baseline Widely Available in approximately September 2025, with Safari 16.4 completing cross-browser support in March 2023.

Together, they enable npm-style bare specifier imports in the browser without npm, Node.js, or a bundler:

<script type="importmap">
{
  "imports": {
    "htmx": "/static/js/htmx.min.js",
    "alpinejs": "/static/js/alpine.min.js"
  }
}
</script>
<script type="module">
  import 'htmx';
</script>

Import maps resolve bare specifiers (import 'htmx') to URLs, the same job that webpack, Rollup, and esbuild perform during a build step. With import maps, the browser does this resolution at runtime. No bundler needed.

The trade-offs are real. There is no tree-shaking: unused code in imported modules ships to the client. No TypeScript compilation: types are stripped only if a build step runs. No code splitting: the browser loads entire modules rather than optimised chunks. For applications with large client-side dependency graphs, these costs matter.

For HDA applications, they do not. The client-side dependency count is typically small: htmx (14 KB gzipped), perhaps a date formatting library, perhaps a small charting library for a dashboard page. The total client-side JavaScript in an HDA application is measured in tens of kilobytes, not megabytes. HTTP/2 and HTTP/3 multiplexing further reduce the cost of serving a handful of small modules individually.

Some practitioners retain a build step for minification, but this is an optional optimisation, not an architectural requirement. The htmx project itself argues explicitly against build steps, distributing as a single file that can be included with a <script> tag. The no-build approach is not a compromise for HDA. It is the natural fit.

The supply chain security argument

The architectural choice to avoid npm is not only a simplicity argument. It is a security argument, grounded in the structural properties of the npm dependency graph and the empirical record of supply chain attacks against it.

The dependency graph problem

Zimmermann, Staicu, Tenny, and Pradel (Small World with High Risks: A Study of Security Threats in the npm Ecosystem, USENIX Security 2019) analysed npm’s dependency graph as of April 2018 and found small-world network properties: just 20 maintainer accounts could reach more than half of the entire ecosystem through transitive dependencies. Installing an average npm package implicitly trusts approximately 80 other packages and 39 maintainers. 391 highly influential maintainers each affected more than 10,000 packages.

A comparative study by Decan, Mens, and Grosjean (An Empirical Comparison of Dependency Network Evolution in Seven Software Packaging Ecosystems, Empirical Software Engineering, 2019) found npm had the highest transitive dependency counts among seven ecosystems. A more recent study by Biernat et al. (How Deep Does Your Dependency Tree Go?, December 2025) across ten ecosystems found that Maven now shows the highest mean amplification ratio (24.70x transitive-to-direct), with npm at 4.32x. npm is not the worst offender across all ecosystems, but it remains structurally exposed: 12% of npm projects exceed a 10x amplification ratio, and the absolute number of affected projects is enormous given npm’s scale.

The empirical record

The structural risk is not theoretical. Supply chain attacks against npm are recurring and escalating in sophistication.

event-stream (November 2018). A new maintainer, given publish access through social engineering, added a dependency on flatmap-stream containing encrypted malicious code targeting the Copay Bitcoin wallet. The package had approximately 2 million weekly downloads. The malicious code was live for over two months before a computer science student noticed it.

polyfill.io (June 2024). The polyfill.io CDN domain was acquired by a new owner in February 2024. Four months later, the CDN began serving modified JavaScript that redirected mobile users to scam sites. Over 380,000 websites were embedding scripts from the compromised domain. Andrew Betts, the original creator, had warned users when the sale occurred. Most did not act.

chalk/debug (September 2025). A phishing attack compromised the npm credentials of a maintainer of chalk, debug, and 16 other packages. The malicious versions contained code to hijack cryptocurrency transactions in browsers. The 18 affected packages accounted for over 2.6 billion combined weekly downloads. The malicious versions were live for approximately two hours.

These incidents share a structural cause: the npm ecosystem’s deep transitive dependency graphs mean that compromising a single package or maintainer account can reach thousands or millions of downstream projects. The risk scales with the number of dependencies.

The HDA alternative

An HDA application with vendored htmx eliminates this entire attack surface. htmx is 14 KB minified and gzipped, has zero dependencies, and is distributed as a single JavaScript file. There is no npm install step, no node_modules directory, no transitive dependency graph, and no exposure to registry-level supply chain attacks.

This is not an incremental improvement. A typical React application created with Vite installs approximately 270 packages, and projects using Create React App (now deprecated) routinely exceeded 1,500. Each package is a node in the dependency graph that the Zimmermann findings describe. Reducing that graph from hundreds of nodes to zero is a categorical change in supply chain risk profile.

The comparison is worth stating plainly. One architecture requires you to trust hundreds of packages, maintained by strangers, with update cadences you do not control, delivered through a registry that is a recurring target of supply chain attacks. The other architecture requires you to trust one 14 KB file that you can vendor, audit, and pin.

What this means for HDA

The web platform’s capability expansion between 2022 and 2026 is the material condition that makes hypermedia-driven architecture practical for production applications. The HDA model depends on three platform properties:

1. CSS is sufficient for production UI. Nesting, container queries, cascade layers, :has(), and @scope collectively provide the capabilities that previously required a preprocessor, a utility framework, or CSS-in-JS.

2. HTML provides interactive primitives. <dialog>, the Popover API, and Invoker Commands cover modals, tooltips, dropdowns, and declarative element interaction without JavaScript component libraries.

3. The browser is a capable module system. ES Modules and Import Maps enable dependency management without a build tool, and the small dependency footprint of HDA applications makes the trade-offs (no tree-shaking, no code splitting) irrelevant.

The Interop Project ensures these features work consistently across browsers. The backward-compatibility guarantee described in the previous section ensures they will continue to work. And the elimination of the npm dependency graph provides a supply chain security posture that no framework-dependent architecture can match.

The web platform was not always adequate for building rich applications without frameworks. It is now.

SPA vs HDA: A Side-by-Side Comparison

The previous sections argued for hypermedia-driven architecture on structural grounds: coupling, migration cost, backward compatibility. This section puts code next to code. What does the same feature actually look like when built both ways, and what do published migrations tell us about the difference at scale?

What real migrations show

The strongest published data comes from Contexte, a SaaS product for media professionals built with React. In 2022, developer David Guillot presented the results of porting the application from React to Django templates with htmx:

The port took roughly two months to rewrite a codebase that had taken two years to build. The team eliminated the hard split between frontend and backend developers. User experience did not degrade.

Contexte is a media-oriented application, exactly the kind of content-driven, read-heavy workload that hypermedia was designed for. The htmx project acknowledges this: “These sorts of numbers would not be expected for every web application.” A separate Next.js to htmx port showed a 17% reduction in written application code and over 50% reduction in total shipped code when accounting for dependency weight.

The pattern across these migrations is consistent. The JSON serialisation layer disappears. Client-side state management disappears. The build toolchain disappears. The dependency graph collapses. What remains is server-side code that got somewhat larger (Contexte’s Python grew from 500 to 1,200 lines) and a total codebase that got dramatically smaller.

The same feature, two architectures

Consider a searchable contact list with inline editing and deletion. The specification is identical for both implementations:

• Display contacts from a database
• Live search with debounce (300ms)
• Click a row to get an editable form
• Delete with confirmation
• All changes persist to the server

This is a bread-and-butter CRUD feature. Most web applications are made of features like this one.

SPA: React + Vite + REST API

The SPA approach requires two applications. A React client handles rendering and state. A server exposes JSON endpoints. They communicate through a serialisation boundary.

Search with debounce needs a custom hook or a library:

function useDebounce(value, delay) {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);
  return debounced;
}

function ContactList() {
  const [query, setQuery] = useState('');
  const [contacts, setContacts] = useState([]);
  const [editingId, setEditingId] = useState(null);
  const debouncedQuery = useDebounce(query, 300);

  useEffect(() => {
    fetch(`/api/contacts?q=${debouncedQuery}`)
      .then(res => res.json())
      .then(setContacts);
  }, [debouncedQuery]);

  // ... render logic, edit mode toggling, delete handlers
}

The component manages three pieces of state: the search query, the contact list, and which row is being edited. Each state change triggers a re-render. The search query flows through a debounce hook, which triggers a fetch, which deserialises JSON, which updates state, which triggers another re-render. The edit mode is a client-side toggle: clicking a row sets editingId, and the component conditionally renders either a display row or a form row based on that state.

Inline editing requires the client to manage form state, submit JSON to the API, handle the response, and update the local contact list to reflect the change:

async function handleSave(contact) {
  const res = await fetch(`/api/contacts/${contact.id}`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(contact),
  });
  const updated = await res.json();
  setContacts(prev =>
    prev.map(c => c.id === updated.id ? updated : c)
  );
  setEditingId(null);
}

The server side mirrors this with JSON endpoints:

app.get('/api/contacts', async (req, res) => {
  const contacts = await db.query(
    'SELECT * FROM contacts WHERE name ILIKE $1',
    [`%${req.query.q}%`]
  );
  res.json(contacts);
});

app.put('/api/contacts/:id', async (req, res) => {
  const { name, email } = req.body;
  const updated = await db.query(
    'UPDATE contacts SET name = $1, email = $2 WHERE id = $3 RETURNING *',
    [name, email, req.params.id]
  );
  res.json(updated[0]);
});

Every interaction crosses the serialisation boundary twice: the server serialises to JSON, the client deserialises, processes the data, and re-renders. The CORS configuration, the Content-Type headers, the JSON.stringify and res.json() calls are all infrastructure that exists solely because the client and server are separate applications communicating through a data format that carries no hypermedia controls.

The project also needs a build toolchain. A fresh React + Vite project installs Node.js, npm, Vite (which bundles esbuild for development and Rollup for production), a JSX transformer (Babel or SWC), and ESLint. The node_modules directory contains hundreds of transitive packages. Each is a separate project with its own release cycle.

HDA: Rust/Axum/Maud + htmx

The HDA approach is one application. The server handles everything: routing, data access, rendering, and interactivity declarations.

Search with debounce is a single HTML attribute:

fn search_input(query: &str) -> Markup {
    html! {
        input type="text" name="q" value=(query)
            hx-get="/contacts"
            hx-trigger="input changed delay:300ms"
            hx-target="#contact-list"
            placeholder="Search contacts...";
    }
}

No hook. No state. No effect. The hx-trigger attribute declares the debounce behaviour inline. When the user types, htmx waits 300ms after the last keystroke, sends a GET request, and swaps the response into #contact-list. The server returns an HTML fragment containing the filtered rows.

The search handler queries the database and renders HTML directly:

async fn list_contacts(
    State(pool): State<PgPool>,
    Query(params): Query<SearchParams>,
) -> Markup {
    let contacts = sqlx::query_as!(
        Contact,
        "SELECT * FROM contacts WHERE name ILIKE '%' || $1 || '%'",
        params.q.unwrap_or_default()
    )
    .fetch_all(&pool)
    .await
    .unwrap();

    html! {
        tbody#contact-list {
            @for contact in &contacts {
                (contact_row(contact))
            }
        }
    }
}

There is no JSON serialisation. The handler returns Markup, which Axum sends as an HTML response. The database result flows directly into the template. The query is checked at compile time by SQLx.

Inline editing is a template swap, not a state toggle. Clicking the edit button asks the server for an edit form:

fn contact_row(contact: &Contact) -> Markup {
    html! {
        tr {
            td { (contact.name) }
            td { (contact.email) }
            td {
                button hx-get={"/contacts/" (contact.id) "/edit"}
                    hx-target="closest tr"
                    hx-swap="outerHTML" { "Edit" }
            }
        }
    }
}

fn contact_edit_row(contact: &Contact) -> Markup {
    html! {
        tr {
            td {
                input type="text" name="name" value=(contact.name);
            }
            td {
                input type="text" name="email" value=(contact.email);
            }
            td {
                button hx-put={"/contacts/" (contact.id)}
                    hx-target="closest tr"
                    hx-swap="outerHTML"
                    hx-include="closest tr" { "Save" }
            }
        }
    }
}

The edit handler returns contact_edit_row, which replaces the display row. The save handler updates the database and returns contact_row, which replaces the edit form. No client-side state tracks which row is being edited. The server controls the UI by returning the appropriate HTML fragment.

The entire client-side dependency is htmx: a single 14 KB file (minified and gzipped) with zero dependencies. No build step. No node_modules. No package manager. Vendor the file and serve it from your Rust application.

Key observations

The comparison reveals differences that are structural, not incremental.

The JSON serialisation layer is eliminated entirely. In the SPA, every interaction crosses a serialisation boundary: JSON.stringify on the client, res.json() on the server, res.json() then setContacts() on the way back. In HDA, the handler returns HTML. The serialisation layer does not exist because the architecture does not need it.

Client-side state management disappears. The React component manages query, contacts, and editingId as state. Changes to any of these trigger re-renders. The htmx version has no client-side state at all. The server is the single source of truth, and every user action asks the server what to show next.

The dependency asymmetry is categorical. One side installs hundreds of packages through a package manager, maintained by hundreds of independent maintainers, each a potential supply chain risk. The other vendors a single file. The React runtime alone (~55 KB gzipped for React 19 + ReactDOM) is roughly four times the size of htmx (~14 KB gzipped), and that comparison ignores the entire build toolchain and its transitive dependencies.

The build toolchain is a complexity tax. The SPA needs Node.js, npm, Vite, esbuild, Rollup, and a JSX transformer to convert source files into something a browser can execute. The HDA serves HTML from a compiled Rust binary. The browser needs no build artefact because the server already produced what the browser understands natively: HTML.

What the SPA provides that HDA does not

The comparison above is favourable to HDA because this is a CRUD feature, and CRUD features are what HDA handles best. The SPA architecture has genuine strengths that should not be dismissed as irrelevant.

Component-level encapsulation with typed props. React components accept typed props and manage their own state in a well-defined scope. This composability model is genuinely powerful for building complex UIs. A component can be tested in isolation, rendered in a storybook, and reused across pages with different data. Maud functions provide similar composition, but the pattern is less formalised and has no equivalent to React’s developer tooling for component inspection.

React DevTools and the debugging experience. React DevTools lets you inspect the component tree, view props and state, trace re-renders, and profile performance. The htmx debugging experience is the browser’s network tab and the DOM inspector. For complex UIs, React’s tooling gives developers significantly better visibility into what the application is doing and why.

Client-side rendering avoids some server round-trips. When edit mode is a client-side state toggle, the UI updates instantly. No network request is needed to show a form. In HDA, clicking “Edit” sends a request to the server and waits for the response. On a fast connection, this difference is imperceptible. On a slow connection or for highly interactive interfaces, it matters.

The component library ecosystem is unmatched. Libraries like shadcn/ui and Radix provide production-quality, accessible UI primitives: dialogs, dropdowns, date pickers, data tables, command palettes. These components handle keyboard navigation, screen reader announcements, focus trapping, and edge cases that take significant effort to implement correctly. The HDA ecosystem has no equivalent at comparable maturity. If your application needs a complex, accessible data table with column sorting, filtering, pagination, and row selection, a React component library gives you that out of the box.

TypeScript provides end-to-end type checking. TypeScript catches errors across the entire client-side codebase: props, state, API response shapes, event handlers. In the SPA model, a type error in a component is caught before the code runs. Rust provides this same safety on the server side (and Maud catches malformed HTML at compile time), but the client-side interactivity in HDA is untyped HTML attributes. A typo in hx-target is a runtime error, not a compile-time error.

Hiring and ecosystem momentum. React dominates job postings and developer mindshare. Finding developers who know React is straightforward. Finding developers who know Rust, Axum, Maud, and htmx is harder. This is not a technical argument, but it is a practical one that affects team building and hiring timelines.

For most CRUD and content-driven features, these trade-offs favour HDA. The component ecosystem advantage matters most when building interfaces that require complex, accessible widgets. The typing advantage is real but narrower than it appears, because the majority of interactivity in an HDA is handled by a small set of well-tested htmx attributes rather than arbitrary JavaScript. The hiring argument is genuine and may be the strongest practical objection for many teams.

Rust-specific advantages

The contact list comparison used generic server code for the SPA side. The HDA side is Rust, and Rust brings specific advantages beyond the architectural ones.

Maud checks HTML at compile time. Most server-side template engines (Jinja2, ERB, Handlebars) parse templates at runtime. A typo in a variable name, a missing closing tag, or a type mismatch surfaces as a runtime error, sometimes only when that specific template path is hit in production. Maud’s html! macro is evaluated during compilation. If the template contains a syntax error or references a variable that does not exist, the code does not compile. This is a meaningful safety guarantee that most server-side frameworks cannot offer.

SQLx checks queries at compile time. The sqlx::query_as! macro verifies SQL against a live database during compilation. If a column name is wrong, a type does not match, or a table does not exist, the compiler catches it. Combined with Maud’s compile-time HTML checking, the Rust HDA stack catches errors at two boundaries (database-to-code and code-to-HTML) where most stacks only discover problems at runtime.

The combination delivers type safety comparable to TypeScript + React, but without the client-side dependency graph. TypeScript checks component props and state. Rust + SQLx + Maud checks database queries, handler types, and HTML output. Both approaches catch a broad category of errors before the code runs. The difference is that the Rust approach achieves this with a single compiled binary, while the TypeScript approach requires a build toolchain, a runtime, and hundreds of dependencies to deliver the same guarantee.

When to Use HDA (and When Not To)

HDA is not a universal prescription. It is an architecture that fits a specific, large class of web applications extremely well and fits others poorly. This section draws the boundary and describes how to handle the cases that fall on either side of it.

Where HDA excels

HDA is the natural architecture for any application where the primary interaction is reading, writing, and navigating server-managed data. This covers:

Content-heavy sites. Media publications, documentation platforms, blogs, knowledge bases, wikis. The content lives on the server. The user reads it. The server renders HTML. There is nothing to manage on the client. These applications gain nothing from a client-side framework and pay a real cost in complexity if they adopt one.

CRUD applications. Admin panels, CRM systems, ERP interfaces, internal tools, project management dashboards. The interaction pattern is: list records, view a record, edit fields, save. Every step is a request-response cycle that maps directly onto HTTP. htmx’s partial page replacement handles the dynamic parts (inline editing, live search, filtered lists) without requiring client-side state.

Form-heavy workflows. Onboarding sequences, multi-step applications, surveys, checkout flows, approval processes. Forms are native HTML. Validation can happen both in the browser (HTML5 attributes) and on the server. The Post/Redirect/Get pattern handles submission cleanly. Adding htmx provides progressive enhancement: inline validation, step transitions without full page reloads, conditional form sections that load from the server based on prior answers.

E-commerce. Catalogue browsing, product search, filtering, cart management, checkout. These are read-heavy with occasional writes. The product page is server-rendered content. The cart is server-managed state. Search is a server query. The few interactive elements (add to cart, quantity adjustment) are simple HTTP requests that return HTML fragments. Shopify, the largest e-commerce platform, serves server-rendered pages.

Dashboards with periodic data updates. Reporting interfaces, analytics dashboards, monitoring views. If the data refreshes on a cadence measured in seconds or minutes (not milliseconds), server-sent events or periodic htmx polling deliver updates without client-side state management. A dashboard that refreshes every 30 seconds does not need React.

The common thread: the server owns the data, the user interacts through standard HTTP patterns (links, forms, requests), and the UI is a representation of server state rather than an independent application with its own state model.

Where SPAs are genuinely superior

Some applications have interaction models that fundamentally require client-side state. For these, HDA is the wrong tool.

Real-time collaborative editing. Google Docs, Figma, and Linear all maintain local copies of document state on the client. Edits apply optimistically, synchronise with the server via WebSockets, and reconcile conflicts using operational transformation or CRDTs. Figma’s multiplayer system gives each document its own server process and maintains persistent WebSocket connections for every collaborating client. This is architecturally incompatible with request-response HTML. The client must own state because it must apply edits instantly and resolve conflicts locally before the server confirms them.

Offline-first applications. Applications that must function without a network connection need a complete client-side data model, a sync engine, and a conflict resolution strategy. Service workers and IndexedDB provide the storage. CRDTs or similar structures handle the merge logic. The server is not available to render HTML when the user is on an aeroplane, so the client must be a self-sufficient application.

Continuous manipulation interfaces. Drawing tools (Figma, Excalidraw), music production software, video editors, spreadsheets with real-time formula recalculation. These require sub-16ms frame rendering for smooth interaction. A server round-trip is physically incompatible with the latency budget. Many of these applications bypass the DOM entirely, rendering to <canvas> or WebGL because even DOM manipulation is too slow for their needs. Google Docs moved to canvas-based rendering to sidestep DOM performance constraints. Quadratic, an open-source spreadsheet, chose WebGL over HTML because the DOM cannot handle millions of cells.

Extreme latency sensitivity. In-browser IDEs need sub-50ms keystroke-to-render times. Trading dashboards require sub-second updates with client-side filtering across large datasets. Audio applications measure latency in single-digit milliseconds. Any architecture that routes through the server for UI updates cannot meet these constraints.

The common thread across all four: the client must own state because the interaction model is physically incompatible with server round-trips. This is not a preference or a trade-off. It is a hard constraint imposed by latency, connectivity, or rendering performance.

Steelmanning client-side frameworks

The SPA vs HDA comparison covered the technical strengths of client-side frameworks in detail: component encapsulation, developer tooling, TypeScript type checking, and the component library ecosystem. Those arguments are real and worth reading.

Beyond the technical merits, there are organisational strengths that matter for team decisions:

Hiring and ecosystem momentum. React appears in roughly 45% of developer survey responses. Job postings that require React are abundant. Job postings that require htmx are nearly nonexistent. Adopting HDA means training developers rather than hiring specialists. The htmx learning curve is shallow (it is a small library over standard HTML), but the absence of a recognised hiring category creates friction for teams accustomed to recruiting by framework name.

Established patterns for complex UIs. The React ecosystem has converged on well-documented patterns for routing, data fetching, state management, and component composition. A developer joining a React project finds familiar structure. The HDA ecosystem has fewer established conventions, and the patterns vary more between projects. This is improving (htmx’s own documentation is thorough, and this guide exists for the Rust stack), but it is not yet at parity.

The component library gap. This is worth repeating because it is the most concrete practical difference. Libraries like shadcn/ui and Radix provide accessible, production-quality date pickers, command palettes, data tables, comboboxes, and dropdown menus with keyboard navigation, focus trapping, and screen reader support built in. The HDA ecosystem has nothing at comparable maturity. Building an accessible combobox from scratch is significant work. If your application needs several such components, the React ecosystem delivers them faster today.

These are genuine advantages, not strawmen. For many teams, the hiring argument alone outweighs the architectural benefits of HDA. The right response is not to dismiss these concerns but to weigh them honestly against the structural costs documented in the preceding sections.

The islands pattern

Most applications are not purely one thing. A CRUD application might need a rich text editor on one page. A dashboard might need a real-time chart alongside otherwise static report content. A form workflow might need an interactive date range picker.

The answer is not to adopt an SPA framework for the entire application because one page needs a complex widget. The answer is islands: HDA as the default architecture, with isolated client-side components for the specific interactions that require them.

The concept is straightforward. The server renders the page as HTML. Most of the page is standard hypermedia, driven by htmx. One region of the page mounts a standalone JavaScript component, a chart library, a rich text editor, a custom date picker, whatever the specific interaction demands. That component owns its own state and manages its own rendering within its DOM region. The rest of the page is unaware of it.

Events are the integration mechanism. The island communicates with the surrounding hypermedia through DOM events. When the rich text editor saves, it dispatches a custom event. An htmx attribute on a nearby element listens for that event and triggers a server request. When the server needs to update the island, it can return an HTML fragment containing updated data- attributes or a <script> tag that the island picks up. The boundary between hypermedia and non-hypermedia is clean: HTML and HTTP on one side, JavaScript and local state on the other, with events bridging the gap.

This is not a compromise. It is the architecturally correct approach: matching the interaction style to the interaction requirements. Using htmx for a contact list is correct. Using a JavaScript charting library for a real-time visualisation is also correct. Using React for both, or htmx for both, optimises for consistency at the expense of fitness.

The practical implication is that an HDA project should have a clear policy for when an island is warranted. A reasonable threshold: if a component requires persistent client-side state that cannot be modelled as a series of server requests, it is an island. If it can be expressed as “user acts, server responds with HTML,” it is hypermedia. Most features in most applications fall into the second category.

The web’s actual composition

SPA frameworks dominate developer discourse, conference talks, blog posts, job listings, and tutorial ecosystems. This creates a perception that SPAs are the standard way to build for the web.

The data tells a different story. According to W3Techs, React is used on roughly 6% of all websites. Angular and Vue each account for 1-2%. Even granting that some sites use client-side frameworks not captured by these measurements, and that some React sites are server-rendered via Next.js, the total share of websites running as true single-page applications is well under 10%.

The remaining 90%+ is WordPress (43% of all websites alone), other CMS platforms (Shopify, Squarespace, Wix, Drupal, Joomla), static sites, and traditional server-rendered applications. The web is overwhelmingly server-rendered, content-oriented, and CRUD-driven.

This matters because the architecture you choose should match the architecture your application actually needs, not the architecture that dominates Hacker News. If you are building a collaborative design tool, use a client-side framework. If you are building a content site, an admin panel, a form workflow, a dashboard, or an e-commerce platform, you are building the kind of application that constitutes the vast majority of the web. HDA is the architecture designed for that majority.

Web Server with Axum

Axum is the HTTP framework for this stack. Built on Tower and Hyper, it provides type-safe request handling through extractors and uses the same Tower middleware that the rest of the Rust async ecosystem uses.

This section covers routing, handlers, extractors, shared state, middleware, static assets, and graceful shutdown. A complete runnable server is assembled at the end.

A minimal server

Add Axum and Tokio to your Cargo.toml:

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }

A server that responds to GET /:

use axum::{Router, routing::get};

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/", get(|| async { "hello" }));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    axum::serve(listener, app).await.unwrap();
}

axum::serve binds the router to a TCP listener. There is no separate Server type.

Handlers

A handler is an async function that receives zero or more extractors and returns something that implements IntoResponse:

use axum::response::Html;

async fn index() -> Html<&'static str> {
    Html("<h1>Home</h1>")
}

Axum provides IntoResponse implementations for common types: String, &str, StatusCode, Html<T>, Json<T>, and tuples that combine a status code with a body.

use axum::{http::StatusCode, response::IntoResponse};

async fn not_found() -> impl IntoResponse {
    (StatusCode::NOT_FOUND, Html("<h1>404</h1>"))
}

In a hypermedia-driven application, most handlers return Html. The JSON response types exist but are rarely the primary format.

Debugging handler signatures

Enable the macros feature and annotate handlers with #[debug_handler] during development. It produces clearer compiler errors when an extractor or return type is wrong:

axum = { version = "0.8", features = ["macros"] }

use axum::debug_handler;

#[debug_handler]
async fn index() -> Html<&'static str> {
    Html("<h1>Home</h1>")
}

Remove #[debug_handler] before release. It adds overhead that is only useful during compilation.

Extractors

Extractors pull data out of the incoming request. Axum calls FromRequestParts (for headers, path parameters, query strings) or FromRequest (for the body) on each handler argument. A body-consuming extractor must be the last argument.

Common extractors:

use axum::extract::{Path, Query, State};
use axum::response::Html;
use serde::Deserialize;

#[derive(Deserialize)]
struct SearchParams {
    q: Option<String>,
    page: Option<u32>,
}

async fn search(
    State(state): State<AppState>,
    Query(params): Query<SearchParams>,
) -> Html<String> {
    // use state.db and params.q to query and render results
    Html(format!("<p>Searching for {:?}</p>", params.q))
}

Path parameters use curly-brace syntax in route definitions. This changed in Axum 0.8; the older colon syntax (:id) no longer works:

// /{id} not /:id
app.route("/users/{id}", get(show_user));

async fn show_user(Path(id): Path<u64>) -> impl IntoResponse {
    Html(format!("<h1>User {id}</h1>"))
}

Application state

Shared state is how handlers access the database pool, configuration, and other application-wide resources. Define a struct, derive Clone, and pass it to the router with with_state:

use sqlx::PgPool;

#[derive(Clone)]
struct AppState {
    db: PgPool,
    config: AppConfig,
}

#[derive(Clone)]
struct AppConfig {
    app_name: String,
    base_url: String,
}

Wire the state into the router:

let state = AppState {
    db: PgPool::connect(&database_url).await.unwrap(),
    config: AppConfig {
        app_name: "My App".into(),
        base_url: "http://localhost:3000".into(),
    },
};

let app = Router::new()
    .route("/", get(index))
    .with_state(state);

Handlers extract it with State<AppState>:

async fn index(State(state): State<AppState>) -> Html<String> {
    Html(format!("<h1>{}</h1>", state.config.app_name))
}

Router<S> means the router is missing state of type S. Calling .with_state(state) produces Router<()>, meaning all state has been provided. Only Router<()> can be passed to axum::serve.

PgPool is internally reference-counted, so cloning AppState is cheap. For fields that need interior mutability (counters, caches), wrap them in Arc<RwLock<T>>.

Route organisation with nest

Router::nest mounts a sub-router under a path prefix. Use this to organise routes by feature or domain area:

fn user_routes() -> Router<AppState> {
    Router::new()
        .route("/", get(list_users).post(create_user))
        .route("/{id}", get(show_user))
        .route("/{id}/edit", get(edit_user_form).post(update_user))
}

fn admin_routes() -> Router<AppState> {
    Router::new()
        .route("/", get(admin_dashboard))
        .route("/users", get(admin_users))
}

let app = Router::new()
    .route("/", get(index))
    .nest("/users", user_routes())
    .nest("/admin", admin_routes())
    .with_state(state);

Requests to /users/42 reach show_user with the path /42. The prefix is stripped before the nested router sees the request. If a handler needs the full original URI, extract OriginalUri from axum::extract.

In a workspace with multiple crates, define route functions in each crate and assemble them in the binary crate:

// in src/main.rs
use users::user_routes;
use admin::admin_routes;

let app = Router::new()
    .nest("/users", user_routes())
    .nest("/admin", admin_routes())
    .with_state(state);

All nested routers must share the same state type. If a sub-router has its own state, call .with_state() on it before nesting:

let inner = Router::new()
    .route("/bar", get(inner_handler))
    .with_state(InnerState {});  // becomes Router<()>

let app = Router::new()
    .nest("/foo", inner)  // Router<()> nests into any parent
    .with_state(OuterState {});

Middleware

Axum uses Tower layers for middleware. The tower-http crate provides HTTP-specific layers that cover most common needs.

[dependencies]
tower = "0.5"
tower-http = { version = "0.6", features = ["trace", "compression-gzip"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

Request tracing

TraceLayer logs every request and response, integrating with the tracing crate:

use tower_http::trace::TraceLayer;
use tracing_subscriber::EnvFilter;

tracing_subscriber::fmt()
    .with_env_filter(EnvFilter::from_default_env())
    .init();

let app = Router::new()
    .route("/", get(index))
    .layer(TraceLayer::new_for_http());

Control log levels with the RUST_LOG environment variable: RUST_LOG=info for production, RUST_LOG=tower_http=trace during development.

Response compression

CompressionLayer compresses response bodies. Enable additional algorithms by adding features like compression-br or compression-zstd:

use tower_http::compression::CompressionLayer;

let app = Router::new()
    .route("/", get(index))
    .layer(CompressionLayer::new())
    .layer(TraceLayer::new_for_http());

Combining layers

Apply multiple layers with ServiceBuilder. Layers are listed top-to-bottom, and the first layer listed is the outermost (runs first on the request, last on the response):

use tower::ServiceBuilder;

let app = Router::new()
    .route("/", get(index))
    .layer(
        ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())
            .layer(CompressionLayer::new())
    )
    .with_state(state);

Here, tracing wraps compression: requests are logged before responses are compressed.

Sessions and CSRF

Session management (tower-sessions) and CSRF protection follow the same .layer() pattern. They are covered in the Authentication section.

Custom middleware

For application-specific middleware, use axum::middleware::from_fn. Write a plain async function that receives the request and a Next handle:

use axum::{
    middleware::{self, Next},
    extract::Request,
    response::Response,
    http::StatusCode,
};

async fn require_auth(
    State(state): State<AppState>,
    request: Request,
    next: Next,
) -> Result<Response, StatusCode> {
    // check auth, return Err(StatusCode::UNAUTHORIZED) if invalid
    Ok(next.run(request).await)
}

let app = Router::new()
    .route("/dashboard", get(dashboard))
    .route_layer(middleware::from_fn_with_state(
        state.clone(),
        require_auth,
    ))
    .with_state(state);

.route_layer() applies middleware only to matched routes. Unmatched requests fall through to the fallback without hitting this middleware. .layer() applies to all requests, including fallbacks.

Serving static assets

An HDA application typically serves a small set of CSS and JavaScript files. The rust-embed crate embeds an entire directory into the binary at compile time, producing a single self-contained executable.

[dependencies]
rust-embed = "8"
mime_guess = "2"

Define an embedded asset struct pointing at your assets directory:

use rust_embed::RustEmbed;

#[derive(RustEmbed)]
#[folder = "assets/"]
struct Assets;

Write a handler that serves embedded files:

use axum::{
    extract::Path,
    http::{header, StatusCode},
    response::IntoResponse,
};

async fn static_handler(Path(path): Path<String>) -> impl IntoResponse {
    match Assets::get(&path) {
        Some(file) => {
            let mime = mime_guess::from_path(&path).first_or_octet_stream();
            (
                [(header::CONTENT_TYPE, mime.as_ref())],
                file.data.to_vec(),
            )
                .into_response()
        }
        None => StatusCode::NOT_FOUND.into_response(),
    }
}

Mount it on the router:

let app = Router::new()
    .route("/", get(index))
    .route("/assets/{*path}", get(static_handler));

In debug builds, rust-embed reads files from disk, so changes to CSS and JavaScript appear without recompilation. In release builds, everything is baked into the binary.

If your project grows to include many large assets (images, fonts), consider tower-http’s ServeDir to serve from the filesystem instead, or move large files to object storage.

Graceful shutdown

axum::serve accepts a shutdown signal via .with_graceful_shutdown(). When the signal fires, the server stops accepting new connections and waits for in-flight requests to complete.

use tokio::signal;

async fn shutdown_signal() {
    let ctrl_c = async {
        signal::ctrl_c()
            .await
            .expect("failed to install Ctrl+C handler");
    };

    #[cfg(unix)]
    let terminate = async {
        signal::unix::signal(signal::unix::SignalKind::terminate())
            .expect("failed to install SIGTERM handler")
            .recv()
            .await;
    };

    #[cfg(not(unix))]
    let terminate = std::future::pending::<()>();

    tokio::select! {
        _ = ctrl_c => {},
        _ = terminate => {},
    }
}

Pass the signal to the server:

axum::serve(listener, app)
    .with_graceful_shutdown(shutdown_signal())
    .await
    .unwrap();

This handles both Ctrl+C (SIGINT) and SIGTERM, which is what Docker and most process managers send when stopping a container. In production, consider adding a TimeoutLayer from tower-http so that slow in-flight requests cannot block shutdown indefinitely.

Putting it together

A complete main.rs combining routing, state, middleware, static assets, and graceful shutdown:

use axum::{
    extract::{Path, State},
    http::{header, StatusCode},
    response::{Html, IntoResponse},
    routing::get,
    Router,
};
use rust_embed::RustEmbed;
use sqlx::PgPool;
use tokio::signal;
use tower::ServiceBuilder;
use tower_http::{compression::CompressionLayer, trace::TraceLayer};
use tracing_subscriber::EnvFilter;

// -- State --

#[derive(Clone)]
struct AppState {
    db: PgPool,
    config: AppConfig,
}

#[derive(Clone)]
struct AppConfig {
    app_name: String,
}

// -- Static assets --

#[derive(RustEmbed)]
#[folder = "assets/"]
struct Assets;

async fn static_handler(Path(path): Path<String>) -> impl IntoResponse {
    match Assets::get(&path) {
        Some(file) => {
            let mime = mime_guess::from_path(&path).first_or_octet_stream();
            ([(header::CONTENT_TYPE, mime.as_ref())], file.data.to_vec())
                .into_response()
        }
        None => StatusCode::NOT_FOUND.into_response(),
    }
}

// -- Handlers --

async fn index(State(state): State<AppState>) -> Html<String> {
    Html(format!(
        r#"<html>
  <head><link rel="stylesheet" href="/assets/style.css"></head>
  <body><h1>{}</h1></body>
</html>"#,
        state.config.app_name
    ))
}

// -- User routes --

fn user_routes() -> Router<AppState> {
    Router::new()
        .route("/", get(list_users))
        .route("/{id}", get(show_user))
}

async fn list_users() -> Html<&'static str> {
    Html("<h1>Users</h1>")
}

async fn show_user(Path(id): Path<u64>) -> Html<String> {
    Html(format!("<h1>User {id}</h1>"))
}

// -- Shutdown --

async fn shutdown_signal() {
    let ctrl_c = async {
        signal::ctrl_c()
            .await
            .expect("failed to install Ctrl+C handler");
    };

    #[cfg(unix)]
    let terminate = async {
        signal::unix::signal(signal::unix::SignalKind::terminate())
            .expect("failed to install SIGTERM handler")
            .recv()
            .await;
    };

    #[cfg(not(unix))]
    let terminate = std::future::pending::<()>();

    tokio::select! {
        _ = ctrl_c => {},
        _ = terminate => {},
    }
}

// -- Main --

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::from_default_env())
        .init();

    let database_url =
        std::env::var("DATABASE_URL").expect("DATABASE_URL must be set");

    let state = AppState {
        db: PgPool::connect(&database_url).await.unwrap(),
        config: AppConfig {
            app_name: "My App".into(),
        },
    };

    let app = Router::new()
        .route("/", get(index))
        .nest("/users", user_routes())
        .route("/assets/{*path}", get(static_handler))
        .layer(
            ServiceBuilder::new()
                .layer(TraceLayer::new_for_http())
                .layer(CompressionLayer::new()),
        )
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();

    tracing::info!("listening on {}", listener.local_addr().unwrap());

    axum::serve(listener, app)
        .with_graceful_shutdown(shutdown_signal())
        .await
        .unwrap();
}

The corresponding dependencies:

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
tower = "0.5"
tower-http = { version = "0.6", features = ["trace", "compression-gzip"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
sqlx = { version = "0.8", features = ["runtime-tokio", "postgres"] }
rust-embed = "8"
mime_guess = "2"
serde = { version = "1", features = ["derive"] }

HTML Templating with Maud

Maud is a compile-time HTML templating library for Rust. Its html! macro checks your markup at compile time and expands it to efficient string-building code, so there is no runtime template parsing, no template files to deploy, and no possibility of a missing closing tag appearing in production.

The Web Server with Axum section used Html<String> with format! for responses. That works for trivial cases, but it gives you no structure, no escaping, and no compile-time checking. Maud replaces it entirely. Handlers return Markup instead of Html<String>, and the compiler catches template errors before the server starts.

Setup

Add Maud to your Cargo.toml with the axum feature:

[dependencies]
maud = { version = "0.27", features = ["axum"] }

The axum feature implements IntoResponse for Maud’s Markup type, so handlers can return markup directly. It targets axum-core 0.5, which corresponds to Axum 0.8.

The html! macro

The html! macro is the core of Maud. It takes a custom syntax that resembles HTML but follows Rust conventions, and returns a Markup value:

use maud::{html, Markup};

let greeting = "world";
let page: Markup = html! {
    h1 { "Hello, " (greeting) "!" }
};

Elements

Elements with content use curly braces. Void elements (those that cannot have children) use a semicolon:

html! {
    h1 { "Page title" }
    p {
        strong { "Bold text" }
        " followed by normal text."
    }
    br;
    input type="text" name="query";
}

Non-void elements that need no content still use braces:

html! {
    script src="/static/app.js" {}
    div.placeholder {}
}

Attributes

Attributes appear after the element name, before the braces or semicolon:

html! {
    input type="email" name="user_email" required placeholder="you@example.com";
    a href="/about" { "About" }
    article data-id="12345" { "Content" }
}

Classes and IDs have a shorthand syntax, chained directly onto the element:

html! {
    input #search-input .form-control type="text";
    div.card.shadow-sm { "Card content" }
}
// Produces:
// <input id="search-input" class="form-control" type="text">
// <div class="card shadow-sm">Card content</div>

A class or ID without an element name produces a div:

html! {
    #main { "Main content" }
    .sidebar { "Sidebar content" }
}
// Produces:
// <div id="main">Main content</div>
// <div class="sidebar">Sidebar content</div>

Quote class names that contain characters Maud’s parser would choke on:

html! {
    div."col-sm-6" { "Column" }
}

Dynamic values with splices

Parentheses insert a Rust expression into the output. Maud automatically escapes HTML special characters:

let username = "Alice <script>alert('xss')</script>";
html! {
    p { "Hello, " (username) "!" }
}
// Output: <p>Hello, Alice &lt;script&gt;alert('xss')&lt;/script&gt;!</p>

Any type implementing std::fmt::Display can be spliced. This includes strings, numbers, and any type with a Display implementation.

For dynamic attribute values, use parentheses for a single expression or braces for concatenation:

let user_id = 42;
let base = "/users";

html! {
    // Single expression
    span data-id=(user_id) { "User" }

    // Concatenation
    a href={ (base) "/" (user_id) } { "Profile" }
}

Boolean attributes and toggles

Square brackets conditionally toggle boolean attributes and classes:

let is_active = true;
let is_disabled = false;

html! {
    button disabled[is_disabled] { "Submit" }
    a.nav-link.active[is_active] href="/" { "Home" }
}
// Produces:
// <button>Submit</button>
// <a class="nav-link active" href="/">Home</a>

Optional attributes

Attributes that take an Option value render only when Some:

let tooltip: Option<&str> = Some("More info");
let label: Option<&str> = None;

html! {
    span title=[tooltip] { "Hover me" }
    span aria-label=[label] { "No aria-label rendered" }
}

Control flow

Prefix control structures with @:

let user: Option<&str> = Some("Alice");
let items = vec!["Bread", "Milk", "Eggs"];

html! {
    // if / else
    @if let Some(name) = user {
        p { "Welcome, " (name) }
    } @else {
        p { a href="/login" { "Log in" } }
    }

    // Loops
    ul {
        @for item in &items {
            li { (item) }
        }
    }

    // Let bindings
    @for (i, item) in items.iter().enumerate() {
        @let label = format!("{}. {}", i + 1, item);
        p { (label) }
    }

    // Match
    @match items.len() {
        0 => { p { "No items." } },
        1 => { p { "One item." } },
        n => { p { (n) " items." } },
    }
}

DOCTYPE

Maud provides a DOCTYPE constant:

use maud::DOCTYPE;

html! {
    (DOCTYPE)
    html lang="en" {
        head { title { "My App" } }
        body { h1 { "Hello" } }
    }
}
// Outputs: <!DOCTYPE html><html lang="en">...