htmx-endpoint-design
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.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- htmx-endpoint-design
- license
- MIT
- metadata
- { "tags": "htmx,endpoints,html,server-driven-ui,frontend", "version": "0.1.0", "category": "Frontend", "displayName": "htmx Endpoint Design" }
- description
- 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.
- compatibility
- Codex, Claude Code, and other Agent Skills-compatible clients.
02 资源文件 2
- 参考文档agents/openai.yaml315 B
- 资产文件assets/icons8-code.svg460 B
03 SKILL.md 正文
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.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.