htmx Endpoint Design

htmx Endpoint Design

Use this skill when the hard part is the server/browser contract: which element makes the request, which endpoint handles it, what HTML comes back, and where that HTML lands.

Contract First

Define the endpoint contract before writing attributes:

• Request source: the element that sends the request.
• HTTP method: GET for safe reads; POST, PUT, PATCH, or DELETE for mutations when the server/framework supports them.
• Input data: normal form fields, included elements, path params, or explicit values.
• Response shape: full page, partial fragment, empty response, redirect, or event-only response.
• Swap target: the element to replace or update.
• Follow-up effects: events, out-of-band fragments, URL changes, focus changes, and messages.

Endpoint Workflow

1. Run the same auth, permission, and data-loading logic for full-page and htmx requests.
2. Branch late on whether the request is an htmx request.
3. Reuse the same partial in the full-page render and the htmx response.
4. Return a fragment whose root matches the intended hx-target when using outerHTML.
5. Use response headers or events for cross-component effects instead of coupling unrelated targets.
6. Test the normal request and the htmx request separately.

Requests

• Prefer normal form encoding so server validation, CSRF, and file limitations are explicit.
• Keep mutation requests same-origin unless the project has a deliberate CORS and CSRF design.
• Use hx-include when one control must submit data from a nearby form or filter panel.
• Use hx-vals only for small explicit values. Avoid secrets and avoid executable js: values; prefer form fields, hidden inputs, or URL parameters instead.
• Debounce or throttle chatty triggers such as keyup, input, and polling.
• Use real links and forms when possible, then enhance them with htmx attributes.

Responses

Choose the smallest response that keeps the UI honest: