acton-htmx

Status: 🟢 Phase 1 Complete - Documentation & Examples (Week 12)

Opinionated Rust web framework for server-rendered HTMX applications

acton-htmx is a production-grade web framework that gets you from idea to deployment in minutes, not days. Built on battle-tested components from the Acton ecosystem, it combines Axum's performance with HTMX's hypermedia-driven architecture.

Design Principles

1. Convention Over Configuration - Smart defaults everywhere, no decision paralysis
2. Security by Default - CSRF protection, secure sessions, security headers enabled out-of-the-box
3. HTMX-First Architecture - Response helpers and patterns designed for hypermedia
4. Type Safety Without Ceremony - Compile-time guarantees via Rust's type system
5. Idiomatic Excellence - Generated code exemplifies Rust best practices

Features

• ✅ Zero-configuration setup - acton-htmx new myapp and you're running
• ✅ HTMX response helpers - Type-safe wrappers for HX-Redirect, HX-Trigger, HX-Swap-OOB, etc.
• ✅ Session-based authentication - Secure HTTP-only cookies with automatic CSRF protection
• ✅ Template integration - Compile-time checked Askama templates with automatic partial rendering
• ✅ Form handling - Declarative forms with validation and HTMX-aware error rendering
• ✅ Background jobs - Type-safe actor-based job system (acton-reactive)
• ✅ Flash messages - Automatic coordination via actors with OOB swaps
• ✅ Security headers - HSTS, CSP, X-Frame-Options, and more
• ✅ Production-ready - OpenTelemetry, health checks, graceful shutdown
• ✅ CLI tooling - Project scaffolding, dev server, database migrations

Quick Start

# Install CLI
cargo install acton-htmx-cli

# Create new project
acton-htmx new blog
cd blog

# Set up database
createdb blog_dev
acton-htmx db migrate

# Start development server with hot reload
acton-htmx dev

Visit http://localhost:3000 to see your app running!

Example: HTMX Handler

use acton_htmx::prelude::*;
use askama::Template;

#[derive(Template)]
#[template(path = "posts/index.html")]
struct PostsIndexTemplate {
    posts: Vec<Post>,
}

pub async fn index(
    State(state): State<ActonHtmxState>,
    HxRequest(is_htmx): HxRequest,
) -> impl axum::response::IntoResponse {
    let posts = sqlx::query_as!(Post, "SELECT * FROM posts ORDER BY created_at DESC")
        .fetch_all(&state.db_pool)
        .await
        .unwrap();

    // Automatically returns full page or partial based on HX-Request header
    PostsIndexTemplate { posts }.render_htmx(is_htmx)
}

pub async fn create(
    State(state): State<ActonHtmxState>,
    mut session: SessionExtractor,
    Form(form): Form<PostForm>,
) -> Result<HxRedirect, FormError> {
    form.validate()?;

    let post_id = sqlx::query_scalar::<_, i64>(
        "INSERT INTO posts (title, body) VALUES ($1, $2) RETURNING id"
    )
    .bind(&form.title)
    .bind(&form.body)
    .fetch_one(&state.db_pool)
    .await?;

    session.add_flash(FlashMessage::success("Post created!"));

    Ok(HxRedirect(format!("/posts/{post_id}").parse().unwrap()))
}

Architecture

acton-htmx reuses 60-70% of production infrastructure from the Acton ecosystem:

From acton-service

• Configuration (XDG + figment)
• Observability (OpenTelemetry + tracing)
• Middleware (compression, CORS, rate limiting)
• Connection pools (PostgreSQL via SQLx, Redis)
• Health checks

From acton-reactive

• Actor runtime for background jobs
• Session state management via agents
• Flash message coordination
• Real-time features (SSE)
• Cache coordination

HTMX-specific (new in acton-htmx)

• Response helpers (HxRedirect, HxTrigger, HxSwapOob, etc.)
• Template integration (Askama with automatic partials)
• Form handling with CSRF protection
• Session-based authentication with Argon2id
• Security headers middleware

Documentation

User Guides

• Getting Started - Your first acton-htmx application
• HTMX Responses - Complete guide to HTMX response types
• Templates - Askama integration and patterns
• Authentication - Sessions, passwords, and security
• Forms - Validation and HTMX patterns
• Deployment - Production deployment guide

Examples

• Blog with CRUD - Complete blog application example

Architecture

• Vision Document - Project goals and philosophy
• Architecture Overview - System design
• Implementation Plan - Development roadmap
• Technical Decisions - ADR log

API Documentation

# Generate and view API documentation
cargo doc --no-deps --open

What's Included

A generated project includes:

my-app/
├── src/
│   ├── main.rs              # Application entry point with actor runtime
│   ├── handlers/            # Request handlers
│   │   ├── home.rs         # Home page
│   │   └── auth.rs         # Login, register, logout
│   └── models/
│       └── user.rs          # User model with SQLx
├── templates/               # Askama templates
│   ├── layouts/
│   │   ├── base.html       # Base HTML layout with HTMX
│   │   └── app.html        # App layout with nav/footer
│   ├── auth/
│   │   ├── login.html      # Login form
│   │   └── register.html   # Registration form
│   ├── partials/
│   │   ├── nav.html        # Navigation component
│   │   └── flash.html      # Flash messages
│   └── home.html           # Welcome page
├── static/                  # CSS, JS, images
│   └── css/
│       └── app.css         # Complete stylesheet
├── config/                  # Configuration files
│   ├── development.toml    # Dev settings
│   └── production.toml     # Production settings
├── migrations/              # SQLx database migrations
│   └── 001_create_users.sql
└── Cargo.toml              # Dependencies configured

Development Status

Phase 1 Complete: ✅ Foundation & Documentation (Weeks 1-12)

Completed Features

Week 1-2: Foundation

• ✅ Workspace structure
• ✅ CI/CD pipeline
• ✅ Configuration system (XDG + figment)
• ✅ Observability (OpenTelemetry)

Week 3-4: HTMX Layer

• ✅ axum-htmx integration
• ✅ Out-of-band swaps (HxSwapOob)
• ✅ All HTMX response types
• ✅ Comprehensive test coverage

Week 5-6: Templates

• ✅ Askama integration
• ✅ Automatic partial/full page rendering
• ✅ Template helpers (CSRF, flash messages)
• ✅ Base layouts and components

Week 7-8: Authentication

• ✅ Session management via actors
• ✅ Argon2id password hashing
• ✅ Authenticated/OptionalAuth extractors
• ✅ Flash message coordination
• ✅ Login/register/logout handlers

Week 9-10: Security

• ✅ CSRF protection with automatic rotation
• ✅ Security headers middleware
• ✅ Input validation (validator crate)
• ✅ Rate limiting integration

Week 11: CLI

• ✅ acton-htmx new - Project scaffolding
• ✅ acton-htmx dev - Development server
• ✅ acton-htmx db:migrate - Database migrations
• ✅ acton-htmx db:reset - Database reset
• ✅ Complete template generation (22 files)

Week 12: Documentation

• ✅ User guides (Getting Started, HTMX, Templates, Auth, Forms, Deployment)
• ✅ Example applications (Blog with CRUD)
• ✅ API documentation (rustdoc)
• ✅ Comprehensive README

Phase 2 Preview

After Phase 1, Phase 2 will add:

• CRUD scaffold generator (acton-htmx scaffold crud)
• Background job scheduling
• File upload handling
• Email sending (transactional)
• OAuth2 providers (Google, GitHub)
• Advanced authorization (policy-based)
• Admin panel generator

Comparison to Other Frameworks

Contributing

We welcome contributions! See Development Workflow for setup instructions.

Development Standards:

• Zero unsafe code (enforced via #![forbid(unsafe_code)])
• Clippy pedantic + nursery (zero warnings)
• 90%+ test coverage goal
• Conventional Commits specification
• API documentation for all public items

Building from Source

# Clone repository
git clone https://github.com/yourusername/acton-htmx
cd acton-htmx

# Build workspace
cargo build

# Run tests
cargo test

# Run clippy
cargo clippy -- -D warnings

# Generate documentation
cargo doc --no-deps --open

Performance

acton-htmx is built on Axum and inherits its excellent performance:

• < 5 microseconds framework overhead
• Zero-copy template rendering with Askama
• Connection pooling for database and Redis
• Actor-based background jobs (non-blocking)
• Compile-time optimization with LTO

Security

Security is a first-class concern:

• CSRF protection - Automatic token generation and validation
• Secure sessions - HTTP-only, Secure, SameSite cookies
• Password hashing - Argon2id with configurable parameters
• Security headers - HSTS, CSP, X-Frame-Options, etc.
• Input validation - Compile-time form validation
• SQL injection prevention - Parameterized queries via SQLx
• Rate limiting - Built-in support for auth endpoints

License

MIT

Credits

Built on:

• Axum - Web framework
• acton-service - Microservice infrastructure
• acton-reactive - Actor runtime (v5.0)
• Askama - Template engine
• HTMX - Hypermedia library
• axum-htmx - HTMX integration
• SQLx - Database toolkit

Community

• GitHub: acton-htmx repository
• Issues: Report bugs and request features
• Discussions: Ask questions and share ideas

Ready to build? Start with the Getting Started Guide!

Sponsor

Govcraft is a one-person shop—no corporate backing, no investors, just me building useful tools. If this project helps you, sponsoring keeps the work going.