agent-cache
add
← all posts

why i chose htmx over react for agent cache


when developers hear "web app," they reach for react. or next.js. or vue.

i chose htmx + hono + server-rendered html. no spa. no client-side framework. no build step.

for a documentation extraction tool, this was the right call. here's why.

what the app actually needs

agent cache is a simple web app:

  • a form where you paste a docs url
  • a status page that streams extraction progress
  • a results page showing extracted docs with a download link
  • that's it

there are no real-time dashboards. no drag-and-drop. no complex state. no user accounts. no reactive data grid.

it's a form, a terminal-like stream, and a download button. that's the whole ui.

a form and a progress stream don't need a spa

spas are for apps with lots of client-side interactivity. dashboards with real-time charts. collaborative editors. image editors. anything where the ui state changes constantly based on user input.

agent cache has none of that.

what do you get with a spa for a simple app? extra javascript bundle. extra build step. extra complexity. extra dependencies that need updating. extra attack surface.

what do you lose? nothing this app needs.

htmx: html over the wire

htmx lets you add interactivity to server-rendered html without writing javascript.

want a form to submit without a page reload? add hx-post="/api/extract" to the form.

want a div to update when extraction progresses? add hx-get="/api/status" with polling.

want to stream progress from the server? server-sent events (sse) with hx-sse.

the server sends html fragments. the browser swaps them into the dom. no javascript state management. no virtual dom. no diffing.

bun and hono on the server, htmx in the browser

  • bun: fast typescript runtime. starts instantly.
  • hono: ultra-lightweight web framework. middleware-based. handles sse natively.
  • htmx: html-over-the-wire for the frontend. no build step.
  • turso: serverless sqlite for job metadata. zero ops.
  • r2: cloudflare object storage for zip files. zero egress fees.

total client-side javascript bundle: 0 bytes.

htmx is loaded from a cdn script tag: <script src="https://unpkg.com/[email protected]"></script>.

that's the entire frontend.

what i gave up (and don't miss)

component libraries. no shadcn, no radix, no material ui. just server-rendered html with inline tailwind classes.

npm ecosystem for frontend. no webpack, no vite, no rollup. no bundle configuration. no tree-shaking.

type safety across the api boundary. no tRPC, no graphql. hono has typed routes, which covers most of it.

offline capabilities. not relevant. this app needs the server.

client-side routing. not relevant. each page is a separate route. /, /job/:id, /docs/:id.

what i gained

speed. the first meaningful paint is under 100ms. no javascript to download, parse, execute. html arrives. it's rendered.

simplicity. the entire frontend is server-rendered html fragments. if something looks wrong, i check the server response. not the react devtools. not the console. the actual html.

reliability. fewer moving parts. fewer dependencies. fewer things to break. the server generates html. the browser displays it. that's layer zero.

cost. no frontend build pipeline. no cdn for js bundles. no dependency upgrades. the "frontend" is a script tag and some html.

deployment. bun runs the server. that's it. no "build" step that can fail. no webpack drama. no node_modules resolution hell.

when react would be better

react would be better if agent cache had:

  • a real-time dashboard with charts
  • drag-and-drop file uploads (well, i have a simple form)
  • offline mode
  • complex client-side state (filters, search, sorting)
  • user accounts with client-side navigation

none of these exist. so react would be solving problems i don't have.

results: performance numbers

metric react approach (estimated) htmx approach (actual)
time to first paint 300-500ms ~80ms
client js bundle 100-300 KB 0 KB
total dependencies 1000+ ~50
build time 5-15s 0s (no build)
server response same same

the server doesn't change. it's hono either way. the difference is what's sent to the browser.

should you use htmx?

use htmx if your app is:

  • content-heavy (blogs, dashboards, admin panels)
  • form-heavy (wizards, configuration, settings)
  • real-time state is handled by the server (sports scores, extraction progress, logs)
  • you want instant start times and zero client bundle

use react (or similar) if your app is:

  • interaction-heavy (image editors, spreadsheets, games)
  • needs offline capabilities
  • has complex client-side state that the server doesn't manage
  • requires real-time collaboration between users

for agent cache, the choice was obvious. it's a server-heavy app with minimal interactivity. server-rendered html + htmx is exactly the right abstraction.

htmx is enough for this server-rendered app

developers reach for react by default. that's a habit, not a requirement.

for a simple server-rendered app, htmx + hono is the pragmatic choice. zero client bundle. zero build step. zero regrets.


related: