Home › htmx › htmx + server-rendered HTML AGENTS.md

htmx + server-rendered HTML AGENTS.md

AGENTS.md for htmx 2 apps with server-rendered templates (any backend), partials, and progressive enhancement.

AGENTS.mdhtmx

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md: htmx 2 hypermedia app

## Principles
- The server returns HTML, not JSON. Each interactive area has a template partial the server can render alone.
- Pages must work without JavaScript first: real `<a href>` and `<form action method>`; htmx attributes enhance them (`hx-boost`, `hx-get`, `hx-post`).
- Check the `HX-Request` header to return a partial vs. the full page from the same route.
- Target precisely: `hx-target` with an id, `hx-swap="outerHTML"` for replacing a component, `hx-swap-oob` for side updates like counters or flash messages.
- Show progress with `hx-indicator`; disable double submits with `hx-disabled-elt="this"`.
- Validation errors re-render the form partial with status 422 and messages next to fields (configure htmx to swap 4xx responses if the project does).
- Redirect after a mutation with the `HX-Redirect` or `HX-Location` response header.
- Small client behavior: htmx events plus a few lines of vanilla JS or Alpine.js. No SPA framework.

## Security
- Escape all output through the template engine; never build HTML strings by hand.
- CSRF token on every non-GET request (via `hx-headers` on `<body>` or a hidden input).

## Don't
- Don't add React/Vue, client-side routing, or JSON endpoints just for htmx.

## Done
Click through the changed flow with JS on and off, then run the backend test suite.