AGENT SKILL

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

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: 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:

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 outerHTML when replacing the target element itself.
  • Use innerHTML when preserving the target shell and replacing only its contents.
  • Use insert swaps such as beforeend for appending rows, log entries, or feed items.
  • Use hx-select when 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:saved or filters:changed.

Status Codes

  • Use 200 for normal fragment replacement, including many invalid form responses.
  • Use 204 when 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

hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

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.

★ 1.6k