htmx-go-templates

Files (8)

• SKILL.md
• evals.json · evals/
• board.tmpl · evals/fixtures/
• layout.tmpl · evals/fixtures/
• server.go · evals/fixtures/
• client.md · references/
• responses.md · references/
• templates.md · references/

SKILL.md (first lines)

# htmx on Go html/template

The server owns state; a template only presents it; htmx moves HTML between the two. Most drift
in these apps comes from that split being decided ad hoc, per handler and per template: seven ways
to detect an htmx request, the same four attributes hand-copied across files, errors that vanish.
The rules below make each of those decisions once.

This skill holds the general rules. The repo's AGENTS.md holds what only the repo knows: its
swap-target ids, the names of its shared partials, and the htmx version it vendors. Read it first.

## Where to look

| If you're working on… | Load |
|---|---|
| A handler: choosing page / fragment / redirect, htmx headers, `Vary`, 303, error responses | `references/responses.md` |
| A template: partials, repeated attribute bundles, forms, live regions, conditionals | `references/templates.md` |
| Any client JS: whether you need it at all, islands, htmx glue, polling guards, `aria-busy` | `references/client.md` |

## The rules

1. **htmx headers go through one helper set, never hand-typed strings.**
   A typo in `"HX-Request"` or a check for `""` instead of `"true"` fails silently; one package
   of constants and predicates makes the wrong spelling unrepresentable. If the repo has no such
   set yet, introduce it the first time a handler you touch needs an htmx header — `Vary` included.
2. **Every route declares its response shape — page, fragment or redirect — in one place.**
   A handler that sniffs headers inline grows a new branch per feature. When one URL can return
   either a page or a fragment, set `Vary: HX-Request`, or a cache or the back button can serve
   the bare fragment as a page. A history-restore request (`HX-History-Restore-Request: true`)
   always gets the full page.
3. **A non-htmx form POST answers 303 to a GET; an htmx one answers `HX-Location` or a fragment.**
   303 stops a refresh from resubmitting. A 303 to an htmx request is followed by the XHR and the
   whole redirected page gets swapped into the target, which is never what you want.
4. **Forms work without JavaScript.** Real `action` and `method`, a real submit button; htmx
   attributes layer on top. The non-JS path is also the path the 303 rule serves.
5. **A repeated attribute bundle becomes a named `{{define}}` partial.** Four attributes copied to
   seventeen links drift the moment one copy changes. One partial, one place to change it.
   (`codebase-design` has the vocabulary for why: one deep module beats many shallow copies.)
6. **Polling never fights the user.** `hx-sync` on every polling element, a guard that skips the
   poll while the user is focused or typing inside the target, and a target that never contains
   an input the user may be editing.
7. **Errors reach the user.** htmx 2.x does not swap 4xx/5xx bodies by default, so a refused
   action looks like nothing happened. Fix it in two halves: a `responseHandling` entry that swaps
   the status you use (typically 422), *and* `HX-Retarget` / `HX-Reswap` from the server so the
   error lands in a known region. That region is a persistent `aria-live` container.
8. **In-flight state is visible.** `hx-disabled-elt` on submit controls so a double-click cannot
   double-submit; `hx-indicator` or `aria-busy` on the region being replaced.
9. **Client JS is the exception, and it is never inline.** Before writing any, ask whether the
   server can own it (a preference, a re-rendered region) or HTML can (`<details>`, `<dialog>`,
   `popover`). A widget with real client state becomes an island in the repo's frontend framework,
   mounted through `htmx.onLoad` and unmounted on swap. The only other JS is a fixed set of htmx
   glue listeners. No `<script>` blocks, `onclick` or `hx-on` in templates: inline handlers are
   untestable and re-run unpredictably on swaps. htmx config goes in `<meta name="htmx-config">`
   with `"allowEval": false`, so htmx itself refuses `hx-on` and `js:` values.
10. **Templates branch on presentation only.** `{{if eq .Status "failed"}}` chains are domain
    logic in the wrong layer. Compute a view-model field in Go (`.Badge`, `.CanRetry`) and let the
    template read it.

## Choosing a response shape

```
request ──► HX-History-Restore-Request: true? ──yes──► page
               │ no
               ▼
            HX-Request: true? ──no──► POST? ──yes──► 303 to GET (or re-render page with 422 on invalid)
               │ yes                       └─no──► page
               ▼
            route declares: fragment ──► ExecuteTemplate(w, "<block>", vm)
                            page+select ──► page (template uses hx-select)
                            redirect ──► HX-Location (or HX-Redirect for a full reload)
```

`references/responses.md` has the helper set and a handler written both ways.

## htmx version

These rules target **htmx 2.x**. Check the version the repo vendors before relying on defaults.
If it is on 4.x, re-check rules 7 and 9 against the
[4.x migration notes](https://four.htmx.org/docs/whats-new-in-htmx-4):

- error responses swap by default, with per-status control through `hx-status`;
- attribute inheritance is explicit, so bundles that relied on inheriting `hx-target` break;
- event names changed, so listeners in the TS module need renaming.

## What not to do

- Don't reach for the `response-targets` extension to route errors. It moves a server decision
  into markup and adds a second mechanism next to `HX-Retarget`.
- Don't swap an `aria-live` region with `outerHTML`. Screen readers track the original node; a
  replaced live region announces nothing. Swap its `innerHTML`.
- Don't render into the `ResponseWriter` directly. Execute into a buffer first, so a template
  error becomes a 500 rather than a half-written 200.
- Don't add `hx-boost` to fix a navigation problem. Declare the nav-link partial instead; boost
  changes every link and form under it at once.
- Don't restate the htmx attribute reference here or in the repo; link
  [htmx.org/reference](https://htmx.org/reference/).

From O-Marsters-1997/my-claude-code, MIT.

More from O-Marsters-1997/my-claude-code