Htmx Endpoint Design
Developmenthtmx-endpoint-designHtmx Endpoint Design is an Agent Skill for development published in the hashgraph-online/awesome-codex-plugins repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Design and review htmx endpoint contracts for server-rendered HTML fragments. Use when adding or debugging hx-get, hx-post, hx-put, hx-patch, hx-delete, hx-target, hx-swap, hx-select, out-of-band swaps, HX-Trigger events, partial template responses, redirects, retargeting, or response headers.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/hashgraph-online/awesome-codex-plugins/blob/HEAD/plugins/LVTD-LLC/skills/skills/htmx-endpoint-design/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/htmx-endpoint-design, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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:
GETfor safe reads;POST,PUT,PATCH, orDELETEfor 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
- Run the same auth, permission, and data-loading logic for full-page and htmx requests.
- Branch late on whether the request is an htmx request.
- Reuse the same partial in the full-page render and the htmx response.
- Return a fragment whose root matches the intended
hx-targetwhen usingouterHTML. - Use response headers or events for cross-component effects instead of coupling unrelated targets.
- 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-includewhen one control must submit data from a nearby form or filter panel. - Use
hx-valsonly for small explicit values. Avoid secrets and avoid executablejs: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:
| Situation | Response |
|---|---|
| Replace one component | Return that component fragment |
| Update several unrelated components | Return primary fragment plus hx-swap-oob fragments |
| Mutation succeeds and another element should refresh | Return 204 plus an event/header when supported |
| Validation fails | Return the bound form fragment with errors |
| Browser should navigate | Return a normal redirect for non-htmx, and an htmx redirect/location response for htmx |
| Server needs a different target/swap | Use framework helpers or htmx response headers where available |
Targeting And Swapping
- Use stable IDs for durable targets and keep them unique.
- Use
hx-target="this"for self-contained components. - Use
outerHTMLwhen replacing the target element itself. - Use
innerHTMLwhen preserving the target shell and replacing only its contents. - Use insert swaps such as
beforeendfor appending rows, log entries, or feed items. - Use
hx-selectwhen the server returns a larger document but the client should extract one fragment. - Do not swap a parent that contains long-lived local browser state unless that state is intentionally reset.
Out-Of-Band Updates
Use out-of-band swaps for shared chrome and secondary facts:
- flash messages
- cart counts
- notification badges
- summary totals
- list counters
- modal shells outside the main target
Keep out-of-band fragments small and predictable. If many out-of-band updates are required for one action, consider returning the larger owner component instead.
Events
Use events to decouple server results from browser-local behavior:
- Fire a server-triggered event after save/delete when another component should refresh.
- Listen for htmx lifecycle events for instrumentation, custom confirmation, and cleanup.
- Use custom events as boundaries between htmx and Alpine, plain JavaScript, or
_hyperscript. - Keep event names domain-specific, such as
invoice:savedorfilters:changed.
Status Codes
- Use
200for normal fragment replacement, including many invalid form responses. - Use
204when no visible fragment should be swapped. - Use redirects deliberately; do not let htmx silently insert a login page into a small target.
- For polling, use the framework or htmx convention that stops polling when the server says the job is done.
Testing Checklist
- Assert status code and key response headers.
- Assert the partial contains the intended root element.
- Assert the partial omits full-page chrome when it should.
- Assert invalid forms render errors into the expected target.
- Assert out-of-band fragments are present when secondary UI must change.
- Assert redirects or client events are represented in headers, not only in body text.
Avoid
- Do not create one endpoint that performs unrelated actions based on arbitrary request parameters.
- Do not let templates become the authorization layer.
- Do not return raw JSON for htmx UI updates unless the same endpoint must serve a real API client.
- Do not use broad selectors that can hit multiple targets by accident.
- Do not mix server-rendered truth with stale client-side copies of the same state.