Coder Legion - Recent posts tagged htmx

htmx 4: What's New, What Breaks, Why It's Not latest

Sat, 29 Aug 2026 07:27:27 +0000

htmx 4.0.0 shipped today, August 28, 2026. The ajax core now runs on fetch() instead of XMLHttpRequest, attribute inheritance is explicit, the back button issues a real request instead of restoring a cached snapshot, and error responses can be routed by status code. It is a major release that breaks real things, on purpose. And it comes with an unusual instruction: nobody has to move. On npm, 2.x keeps the latest dist-tag until early 2027, 4.0 lives under next, and htmx 2 stays supported indefinitely.

TL;DR

Every request htmx makes now goes through fetch(); XMLHttpRequest is out, along with the XHR-specific events.
Attribute inheritance is explicit: attributes like hx-confirm reach descendants only when you add the :inherited modifier.
The history DOM cache is gone. The back button re-fetches the page from the server instead of restoring a stored snapshot.
Error responses swap by default, and the new hx-status attribute routes 4xx and 5xx responses by status code to their own targets.
On npm, htmx 2.x keeps the latest dist-tag until early 2027, and 4.0 lives under the next dist-tag, so nobody upgrades by accident.

What changed in htmx 4

htmx 4 is a ground-up rework of the library's internals and a cleanup of its accumulated defaults. Carson Gross, htmx's creator, announced it in an essay called The fetch()ening in November 2025, together with the first alpha. A string of betas followed through 2026, and the final release landed today.

The big majors I covered this year, Astro 7 and pnpm v12, rewrote their engines precisely so that nothing would change for you: same surface, faster internals. htmx 4 is the other kind of major. Moving to fetch() gave the project a reason to revisit design decisions that had been locked in for years, and the team took it. Implicit inheritance, the history cache, silently ignored error responses: all gone. That is why the release strategy matters as much as the feature list, and I will get to it.

The fetch() rewrite

Every request htmx makes now goes through fetch() rather than XMLHttpRequest. You do not call either API yourself when you write htmx, so on a quiet day you will not notice. The visible consequences are at the edges:

XHR-specific events are gone. htmx:xhr:loadstart, htmx:xhr:progress, and htmx:xhr:abort have no fetch() equivalent and were removed.
Events follow a new htmx:phase:action naming scheme. If you listen to htmx lifecycle events in JavaScript, every listener needs a rename.
A default request timeout exists now. Requests time out after 60 seconds; in 2.x they could hang forever. The config option moved from timeout to defaultTimeout.

The event renames look like this:

htmx 2.x	htmx 4
`htmx:beforeRequest`	`htmx:before:request`
`htmx:afterRequest`	`htmx:after:request`
`htmx:beforeSwap`	`htmx:before:swap`
`htmx:afterSwap`	`htmx:after:swap`
`htmx:configRequest`	`htmx:config:request`
`htmx:sendError`, `htmx:swapError`, `htmx:targetError`, `htmx:timeout`	`htmx:error`

That last row is a real simplification: four error events collapse into one htmx:error.

Extensions changed even more. The announcement puts it plainly: "Switching to fetch() internally let us rethink how extensions can and should work." The old htmx.defineExtension() API is replaced by htmx.registerExtension(), and the hx-ext attribute is gone entirely: loading an extension's script is enough. There is a dedicated extension migration guide for authors. The payoff is streaming: new first-party extensions stream HTML into the page over server-sent events (hx-sse), WebSockets (hx-ws), and multipart/mixed responses (hx-multipart).

Attribute inheritance is now explicit

In htmx 2, attributes like hx-confirm and hx-target silently inherited from parent elements. Convenient until it wasn't: a hx-confirm on a container would attach confirmation dialogs to descendants you forgot about, and hx-disinherit existed purely to fight this. In htmx 4, inheritance only happens when you ask for it with the :inherited modifier:

<div hx-confirm:inherited="Are you sure?">
  <button hx-delete="/account">Delete my account</button>
</div>

Without the modifier, the attribute applies only to the element it sits on. hx-inherit and hx-disinherit are both removed, since explicit inheritance makes them pointless. If your codebase leans heavily on the old behavior, setting implicitInheritance to true in the htmx config restores it while you migrate.

Of everything in this release, this is the change I would have asked for. Implicit inheritance was the closest thing htmx had to action at a distance, and debugging it meant walking up the DOM tree in your head.

The back button is a real request now

htmx 2 handled history by snapshotting the DOM into browser storage (localStorage originally, sessionStorage since 2.0.5) and restoring the snapshot on back navigation. That cache is exactly the kind of client-side state that drifts from reality, and InfoWorld's coverage of the 4.0 line put it bluntly: "It turned out to be brittle."

htmx 4 drops the cache entirely. Per the announcement, on back navigation htmx re-fetches the page from the server and swaps it into <body>. Your back button now shows what the server says the page is, not what the page happened to look like when you left it. The hx-history attribute and historyCacheSize config are gone with it. If you genuinely need snapshot behavior, an hx-history-cache extension brings it back as an opt-in.

Route error responses with hx-status

htmx 2 refused to swap 400 and 500 responses by default, which meant server-rendered validation errors needed workarounds. htmx 4 flips the default: 4xx and 5xx responses swap like any other (only 204 and 304 are no-swap by default), and a new hx-status attribute routes specific status codes to their own target and swap behavior:

<form
  hx-post="/signup"
  hx-status:422="target:#validation-errors"
  hx-status:5xx="target:#server-error"
  hx-status:503="swap:none"
></form>

Matching goes from specific to general: an exact code like 503 wins over a single-digit wildcard like 50x, which wins over a range wildcard like 5xx. A 422 with the form's field errors rendered server-side can now land in the right spot with one attribute, which is what hypermedia apps do all day. If you depended on the old ignore-errors behavior, setting the noSwap config to [204, 304, '4xx', '5xx'] restores it.

What else is new in htmx 4

The what's new page lists more than I can cover, but a few stand out. Morph swaps are built in: innerMorph and outerMorph use the idiomorph algorithm and need no extension. New swap styles textContent and delete join the existing set. A new <hx-partial> element lets one response update several targets, with each partial carrying its own target and swap. View Transitions support is there but disabled by default; flip the transitions config option to turn it on.

The one that caught my eye: a new hx-query attribute issues an HTTP QUERY request, the safe-reads-with-a-body method I wrote about in July after RFC 10008 landed. Watching a brand-new HTTP verb show up as a first-class attribute in a hypermedia library within months is the spec pipeline working the way it should.

The breaking changes in htmx 4

The migration guide is thorough, and the headline breaking changes are the three above: explicit inheritance, error responses swapping by default, and server round-trip history. Beyond those:

Two attributes trade names, and order matters. hx-disable becomes hx-ignore, and hx-disabled-elt becomes hx-disable. The old name gets reused, so the guide says to rename hx-disable to hx-ignore first or you will migrate one attribute into the other.
Removed attributes: hx-ext, hx-inherit, hx-disinherit, hx-history, hx-vars (use hx-vals with the js: prefix), hx-params (use the htmx:config:request event), hx-request, and hx-prompt (now an extension).
Config options were renamed or culled. timeout is defaultTimeout, defaultSwapStyle is defaultSwap, globalViewTransitions is transitions. A long list of options is simply gone, including historyCacheSize, defaultSwapDelay, and the settling-class options.
Validation events are removed. htmx:validation:validate, failed, and halted are out; native browser validation is the path forward.
Every event listener needs the new names. See the table above.

htmx ships a scanner that finds most of this for you:

npx htmx.org@4.0.0 upgrade-check -- ./path/to/project/root

It walks your templates and prints deprecated patterns with file and line numbers. Run it before deciding how big your migration actually is; for a small app the answer may be an afternoon.

Why 4.0 is not latest on npm

Here is the part I find genuinely rare. As of today, the htmx.org package has latest pointing at 2.0.10 and 4.0.0 published under next. That is deliberate, and the announcement spells out why:

we are not marking 4.0 as latest in NPM because we do not want to force-upgrade users who are relying on non-versioned CDN URLs for htmx. Instead, 2.x will remain latest and the 4.0 line will remain next until some point in early 2027.

Plenty of production sites load htmx from a CDN URL that resolves whatever latest is. Flipping the tag on release day would silently ship breaking changes to all of them. So the tag waits several more months while 4.0 is, by every other measure, released and stable today.

The announcement frames the whole release this way: "we have made explicit choices that we feel will put htmx-based applications in a good spot for being 100-year web services." You can roll your eyes at the century talk, but the mechanics back it up. htmx 2 "will continue to be supported indefinitely so don't feel any pressure to upgrade," per the same announcement. Compare that with the upgrade treadmill most of the ecosystem runs on, where staying one major behind makes you a straggler within months. htmx is telling you the old version is fine, forever, and meaning it.

Should you upgrade to htmx 4?

For a new project, start on 4. The defaults are better: explicit inheritance, error responses you can actually handle in hypermedia, history that cannot go stale. Install it with npm install htmx.org@next or pin the 4.0.0 CDN URL, since latest will hand you 2.x until early 2027.

For an existing app, there is no clock. Run the upgrade-check scanner to size the work, and if the report is short, do the migration in an isolated git worktree and shake out the event renames. If the report is long, htmx 2 remains supported and maintained, and the team has said so in writing.

The technical changes are good. The release discipline is the story I will remember: a project that shipped a breaking major and then deliberately kept it off the latest tag so nobody gets upgraded by accident. That is what taking backwards compatibility seriously looks like.

Testing HTMX apps in the real browser with TWD

Fri, 24 Jul 2026 09:04:43 +0000

HTMX apps are refreshingly simple: the server returns HTML fragments, and HTMX swaps them into the page in response to hx-get, hx-post, and friends. There is usually no bundler and no client framework. That simplicity is the point, and it is also why the usual testing tools feel wrong. A jsdom unit test cannot see an HTMX swap, and a full end-to-end runner is a lot of machinery to bolt onto an app that deliberately avoids machinery.

twd-js fits the HTMX model well. It runs tests inside the real browser, so it sees exactly what HTMX does to the DOM, and it installs from a CDN with an import map, so it adds no build step of its own.

Setup: load both from a CDN

Load HTMX as usual, then add an import map for TWD next to it. esm.sh resolves TWD's internal dependency, so there is nothing else to wire up.

<script src="https://unpkg.com/htmx.org@2.0.10/dist/htmx.min.js"></script>
<script type="importmap">
  {
    "imports": {
      "twd-js": "https://esm.sh/twd-js@1.8.2",
      "twd-js/runner": "https://esm.sh/twd-js@1.8.2/runner",
      "twd-js/bundled": "https://esm.sh/twd-js@1.8.2/bundled"
    }
  }
</script>

Your markup stays pure HTMX:

<button hx-get="/api/todos" hx-target="#todo-list" hx-swap="innerHTML">Load todos</button>
<ul id="todo-list"></ul>

Test against the real backend

The important design choice for HTMX is what to assert against. Because HTMX endpoints return HTML fragments rather than JSON, the cleanest approach is to run the tests against your real HTML-returning backend and reset it between tests, rather than mocking. This is the same pattern the Nuxt example uses for real-backend testing.

A tiny dev-only reset endpoint gives every test a clean starting point:

import { twd, userEvent, screenDom } from 'twd-js';
import { describe, it, beforeEach } from 'twd-js/runner';

describe('Todo List (HTMX)', () => {
  beforeEach(async () => {
    await fetch('/api/reset', { method: 'POST' });
  });

  it('loads the seeded todos', async () => {
    await twd.visit('/');

    const loadButton = await screenDom.getByRole('button', { name: 'Load todos' });
    await userEvent.click(loadButton);

    // HTMX swaps asynchronously, so use findBy* (which waits) rather than getBy*.
    const todo = await screenDom.findByText('Learn TWD');
    twd.should(todo, 'be.visible');
  });
});

The one detail worth internalizing: HTMX swaps happen after an async request, and there is no mock to await, so query with Testing Library's findBy* (which retries until the element appears) instead of the synchronous getBy*.

A note on mocking

TWD's service worker will happily intercept HTMX's requests, the same as any fetch or XHR. Today twd.mockRequest serializes responses as JSON, which is a natural fit for JSON APIs but not for HTML fragments, so for HTMX we recommend the real-backend approach above. First-class HTML-fragment mocking for hypermedia frameworks is on the roadmap.

Try it

A complete example, an HTMX todo list with load, create, and delete, a small Express backend with a reset endpoint, in-browser tests, and CI, lives in twd-htmx. It is served as static files with TWD loaded straight from the CDN, so you can read the whole thing top to bottom without a build step in sight.

Agentic AI: Good Upfront Design Pays You Back Later

Wed, 08 Jul 2026 00:00:41 +0000

I spend a lot of time preaching architecture and constraints, so it is always nice when a side project gives me receipts. Adding this new feature to DumbQuestion.ai was a good reminder that a well-structured first version lets you spend your next iteration on value, not repair.

Below, you will find a few relatively simple challenges and how thoughtful, upfront design made the changes effortless.

To vibe or not to vibe ...

Many developers jump right in and just rip out an app, ship fast, let the coding agent sort it out, come back and deal with it later. To be fair, that absolutely can get you to first release faster. But even on a solo project, a little proper SDLC discipline pays back later when you want to extend the product without turning every feature into a rescue mission, which is a theme that already runs through how I have been building DumbQuestion.ai.

Extend this to the enterprise and you turn a little upfront effort into potential huge savings on token spend

Roasting starup pitches (for sport) ...

The core idea for Startup Roast was simple enough: take a startup pitch, roast it, and add a reality-check section so the output is not just mockery for mockery’s sake. To illustrate (and avoid just vaguely describing the feature) I picked a random but highly upvoted pitch from Product Hunt: Vida.

Vida, which pitches itself as an “AI clone” that learns how you work, remembers what matters, and becomes a “second you,” with early use cases like Reply Rescue, Prompt Rescue, Resume Rescue, Workspace Cleanup, and Daily Wrap. This is a pretty common target use case of agentic AI making it a solid candidate.

If you want to skip ahead, here's an example roast for Vida.

Combining a preliminary web "market search" into the content yielded a result that was not just sarcastic, but informed. The roast hit the obvious AI-clone positioning, questioned whether the product was really a clone versus a macro suite, and then turned the market context into a sharper Reality Check about integration bugs, weak retention, and the risk of becoming yet another chat-wrapper-style productivity startup.

Challenge 1: Prompt Size / Parameterization

DumbQuestion.ai originally dealt with a short question (< 100 characters). The startup roast feature deals with a whole pitch, which is a very different shape of input, with more context, more structure, and more ways for the prompt to get noisy. The Vida example alone is long enough to make that obvious.

This is where boring code quality decisions start paying rent, something likely caught in a code review: use configuration or constants insead of hardcoded literals. If prompt limits, prompt assembly, and related values are already treated like configurable extension points instead of scattered magic numbers, adapting to longer input becomes an iteration problem instead of a rewrite problem.

This was an instant code and unit test change. This led to an even better refactor to make the limit parametric instead of constant.

Challenge 2: Search Phrases and Market Context

A generic roast is funny once. A roast that feels aware of the market is a better product artifact. In the Vida example, adding in a quick prelminary web search using search phrases like “top competitors to AI work clone or AI agent that learns your habits startup” and “reasons AI personal assistant or productivity agent startups fail,” were added to the context to shape the final output. It moved the result to something more specific than just "ha ha, another AI startup.”

To support that, I added a preliminary LLM pass to extract search phrases as a JSON array, then routed those through my existing multi-provider web search capability and used the results to prefill the final LLM prompt. The point here is not that this was especially hard. The point is that it was not hard because search was already isolated as a reusable feature instead of buried inside one specific interaction path.

The pay back was immediate. If search is a first-class capability, a new feature can borrow it immediately. The architectural work already happened earlier. The new work is mostly deciding how to apply it.

Challenge 3: Markdown Output

Once the responses got richer, plain text stopped being enough. Roast plus Reality Check wants structure. The Vida output is a good example because it has a clear voice shift from mockery into analysis, and that reads much better when the response can preserve formatting cleanly. Different models chose different formats and whether or not to pepper in emojis.

Again, this is where earlier organization matters more than raw cleverness. If your HTMX partials and rendering boundaries are reasonably clean, adding markdown support is much lower impact than it would be in a tangled UI layer. Pull in a Go lib dependency, apply it in a single, small partial, update a focused unit test and very few tokens were needed to wrap up this feature.

Quiet structural decisions like that are what let a new feature stay contained.

A key lesson here for sure: nearly all first runs with a coding agent generate "balls of mud" in the UI instead of well organized components. Nip this one in your first code review if not sooner.

Challenge 4: Prompt Injection Tuning

The moment you let people paste startup pitches into an LLM tool, you are no longer just handling simple, earnest user input. You are also handling jokes, garbage, hostile instructions, and people trying to be clever because of course they are. That was already true in DumbQuestion.ai, but longer, richer pitch inputs make it even more relevant.

I already had prompt injection handling in place, but Startup Roast needed the tuning adjusted. Because the detection and response behavior were already parameterized instead of hard-coded into a pile of special cases, tuning it became a smaller, more contained change. Better thresholds, better handling, smaller git diff, fewer tokens.

Challenge 5: Model and Persona Tuning

Startup pitches are a different input class than dumb questions, so I wanted to re-test model speed, quality, and instruction adherence under longer prompts and a different tone. Luckily, I had already built an eval harness for comparing models, so adding startup-pitch cases was an easy extension instead of a new side quest. This was already incorporated into my unit, e2e and integration tests so even for a solo project, this paid off.

The persona side worked out the same way. Because the personas were already packaged to be open for extension, adding new instructions and persona-specific CTAs was low impact. That let me spend time tuning tone and usefulness instead of untangling brittle prompt logic.

For the curious, here's the same pitch roasted across the four personas: Weary, Overqualified, Compliant, \[REDACTED\].

I always like the insane positivity The Compliant brings to the table.

The Payback

Focus on value add

Good upfront design changes what kind of work you get to do next. It lets you spend your energy on product judgment instead of repair work. It turns feature additions into focused passes on value: better prompts, better search context, better output formatting, better guardrails.

Design efficiency = Token efficiency

It also makes coding agents more useful and more efficient. AI coding agents are great at implementation, but they are much more effective when the system already has clean extension points, isolated responsibilities, and tunable behavior. A prompt-length constant is an extension point. Multi-provider search reuse is an extension point. Modular rendering is an extension point. Parametric prompt-injection tuning is an extension point. Those are not giant innovations. They are just design decisions that compound later.

Team of One / Team of Many

That is why I still believe even solo projects deserve at least a little SDLC respect. Not enterprise ceremony. Not fifty approval gates. Just enough thought, structure, and code quality that future-you is allowed to work on the interesting part.

If it pays off a little for a team of one, it can pay off a lot for a team of many.

For this feature, the interesting part was not fighting the code. It was thinking about how to make the roast more specific, more grounded, and more shareable. The Vida example was a nice reminder that good architecture really does buy that freedom later.