htmx has gained some traction in the past year as an alternative to popular JavaScript frontend frameworks. I have been playing with it in a Rust toy project to better understand the technology, its tradeoffs and where to put it in my developer tool belt.

This article summarizes what I have learned so far using it. This is not intended to be a step by step guide on how to use htmx within a Rust application but you can find the code of the toy project I built here (spoiler, it is the dreadful todo app).

Why I wanted to test building an htmx-based application

The last fullstack application I built uses a Svelte client (SvelteKit with the static adapter to be precise) that exchanges data with a JSON-based API written in Rust. They live in the same repository and can be deployed simultaneously.

Both were tightly coupled: I had no intent on exposing and maintaining a public API from the Rust application, but I still had to maintain an implicit private API when serializing and deserializing data between the client and the backend. You can easily have type-safety on both sides (with serde in Rust and zod in Svelte/JavaScript) but this leads to code duplication and feels like an unnecessary impedance mismatch (i.e. having to deal with different data models like representing Rust’s enums in JavaScript).

When your application grows you then have to invest in some costly and brittle end-to-end testing if you want to catch discrepancies between both sides of this private API. Another alternative would be to use a fullstack framework like SvelteKit, but it forces you to use JavaScript on your backend which you might not want and/or be able to.

In this context, htmx appealed to me as it’s a language-agnostic way of building a web application on top of HTML: all you have to serve to your clients are plain HTML pages with some custom htmx attributes on your HTML elements. Instead of having to serialize data for your clients, you can send HTML fragments that can replace part of a page in order to give the same interactivity without full page reloads you would have using a JavaScript framework like React or Svelte.

In doing so the implicit private API disappears as you directly build your htmx pages and fragments from within your backend code, without leaving the safety of your type system. This removes the need for end-to-end testing solely to catch API discrepancies (but more on end-to-end testing later).

As with all things, there are some tradeoffs as htmx cannot emulate all client-side interactions you would easily do with a JavaScript frontend framework.

Goals of this proof of concept/toy project

These were the points I wanted to explore and test with this proof of concept:

  • How to integrate an htmx templating/view layer in a Rust application without introducing coupling with the business logic,
  • How to expose a JSON-based API alongside the htmx-based application, without duplicating code,
  • How to integrate Tailwindcss and daisyui,
  • How to do WebSocket with htmx,
  • What testing strategies to use,
  • Overall developer experience (DX) compared to popular JavaScript-based framework (hot reload in particular).

The proof of concept consists in a basic CRUD todo application and a live chat to test the WebSocket part. You can find the repository with the final code here.

Some technical decisions

This section lists, in no particular order, the technical decisions I made and the eventual tradeoffs I encountered.

Templating crate

While you could generate your htmx fragments by hand using standard string formatting, it is advised to use a templating engine to prevent common XSS attacks.

From the available options I chose maud as it seems to have the best ergonomics regarding type safety. You can easily define component-like fragments for reusability.

pub fn todos_list_view(todos: &[Todo]) -> Markup {
    html! {
        ul.list.bg-base-100.rounded-box.shadow-md.m-6 id="todos-list" {
            @for todo in todos {
                (todo_view(todo)) /// Separate a single todo view from the list of all todos
            }
        }
    }
}

pub fn todo_view(todo: &Todo) -> Markup {
    /// Fragment for a single todo
}

Vendoring htmx.min.js and Tailwind CSS

The htmx doc explicitly advises to vendor the htmx source code directly within your project. This plays nicely when using a non JS-based backend as you don’t have to add another package manager and/or build step.

If using tailwindcss/daisyui to style your application, you can use the same strategy with the tailwind CLI (and daisyui) to generate an output.css file that contains only the classes you’re actually using. Though unlike for the htmx source code, I chose not to commit this file but instead generate it during the build process. The tailwind CLI also provides hot reload for your styles when developing.

Developer experience and hot-reloading

To have some form of hot-reloading I used two commands:

  • the tailwind CLI: npx @tailwindcss/cli -i ./input.css -o ./assets/style/output.css --watch to watch for changes in the CSS of the application,
  • bacon CLI bacon run-long to recompile and run the application on code (and template) change. But this does not propagate the reload event to connected clients, so you have to reload them yourself.

Serving a JSON API alongside htmx

We can use standard content negotiation to choose what representation to send back to the client (htmx or JSON) based on the Accept header of the request.

pub async fn create_todo(
    State(state): State<ApiState>,
    headers: HeaderMap,
    ContentNegotiator(payload): ContentNegotiator<CreateTodoRequest>,
) -> impl IntoResponse {
    let mut state = state.write().await;
    let todo = state.todos.add_todo(payload);

    // Use the request's Accept header to determine response format
    match headers.get("Accept").and_then(|h| h.to_str().ok()) {
        Some("application/json") => Json(todo).into_response(),
        _ => todo_view(todo).into_response(), // Matching htmx template
    }
}

We can use the same strategy to extract data from the request’s body with different representations. For instance for a POST /todo route, we can either receive the new todo content as application/json, or as application/x-www-form-urlencoded and write an axum extractor that abstracts away this logic in order to have a single handler for both.

pub struct ContentNegotiator<T>(pub T);

impl<S, T> FromRequest<S> for ContentNegotiator<T>
where
    S: Send + Sync,
    T: for<'de> Deserialize<'de> + Send,
{
    type Rejection = StatusCode;

    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
        let content_type = req
            .headers()
            .get(header::CONTENT_TYPE)
            .and_then(|v| v.to_str().ok())
            .unwrap_or("");

        // Check content type to determine how to parse
        if content_type.starts_with("application/json") {
            // Parse as JSON
            let Json(payload) = Json::<T>::from_request(req, state)
                .await
                .map_err(|_| StatusCode::BAD_REQUEST)?;

            return Ok(ContentNegotiator(payload));
        }

        // Default to form data
        let Form(payload) = Form::<T>::from_request(req, state)
            .await
            .map_err(|_| StatusCode::BAD_REQUEST)?;

        Ok(ContentNegotiator(payload))
    }
}

An alternative to content negotiation would be to maintain one route per representation (api/json/todo and /todo for instance), but it has its own set of compromises.

WebSocket + htmx

I thought the WebSocket part would be one of the hardest points of the PoC but it was actually pretty straightforward thanks to the WebSocket extension since once the connection is established you use regular htmx syntax.

You can refer to the actual implementation here for more details.

Testing strategy

Testing was probably one of the less ergonomic parts of using htmx. Since your application only generates HTML fragments, writing tests for those fragments is limited to testing basic behavior like “is there the expected number of elements in this list ?”, “does this button point to the correct action/URL ?”, etc.

#[test]
fn test_view_done_todo() {
    let todo = Todo {
        content: "done todo".to_owned(),
        done: true,
        id: 0,
    };
    let fragment = Html::parse_fragment(&todo_view(&todo).into_string());
    let selector = Selector::parse("span").unwrap();

    let span = fragment
        .select(&selector)
        .find(|el| el.inner_html() == "done todo")
        .expect("span should be present");

    // Basic assertion on CSS class
    assert!(span.value().attr("class").unwrap().contains("line-through"));
}

If you want to test more complex behavior you quickly have to write end-to-end tests, even for behavior scoped to a single component. To write those tests I used the fantoccini crate that allows you programmatically interact and run assertions with a headless web browser.

Testing was the biggest letdown of using htmx, especially compared to the excellent options available in the JavaScript world like testing-library. I don’t think it is due to a lack of tooling, but rather is inherent to how htmx works and the inability to have a component in isolation (more on that in the following section on locality).

A word on locality

One recurring argument when reading about htmx is the concept of locality of behavior that roughly states that the closer a component’s elements (view, styling and behavior) are to each other, the easier it is to understand and maintain the component. Think HTML, CSS and JavaScript in a single file rather than in dedicated separated files.

The canonical example, taken from the htmx docs, shows that the following button is easy to understand as its behavior is colocated within the <button> element: clicking the button will make a GET request to /clicked.

<button hx-get="/clicked">Click Me</button>

While I do agree that htmx favors locality at the component/fragment level, I found that it is less true when you start assembling fragments into bigger components or pages. Because of how htmx works, you often have to reference other elements or fragments from a fragment.

For instance in the following snippet we want to append the fragment returned by the call to POST /todo to the element with the ID todos-list located elsewhere in the page.

pub fn todo_form() -> Markup {
    html!(
        div {
            form
                hx-post="/todo"
                hx-target="#todos-list"
                hx-swap="beforeend" {
                /// Actual form content
            }
        }
    )
}

We could have passed the values for hx-target and hx-swap as arguments to todo_form() to improve the reusability of this particular component, but this does not remove the necessary coupling between this component and its surroundings.

If this coupling is manageable for small components, I found that it scales poorly, very fast. I think it is inherent to the way htmx is intended to work, as there is no integration layer or component you would normally use to localize this coupling between components (think molecules and organisms in atomic design).

Some final thoughts

Overall I think htmx is a valuable tool to have in your tool belt. It can be enough for simple applications (think a form and some content that updates) and can avoid the unnecessary complexity that comes with using a JavaScript framework.

That being said, this toy project made me realize the ceiling of htmx for interaction complexity is lower than I expected, at least for the applications I typically build. I agree it is probably possible to increase this ceiling by becoming more proficient with it. But the poor testing experience and the inherent coupling between fragments/components for complex applications are deal breakers for me. Moving forward I will probably stick with the compromise of using a dedicated JavaScript-based frontend I outlined in the introduction.