"What if the web already has
an application protocol —
and we just stopped reinventing it?"

JSON API → JS Framework → Pixels

The standard architecture for a modern web app.

6 layers of indirection to turn database rows into something the user can see. Each layer has its own abstractions, error handling, caching, and testing strategy.

What you're actually building.

HTTP request → HTML fragment

One layer. The server composes the data, renders the HTML, and sends it.

4 steps, zero codegen, zero client state. The browser's native rendering engine does what React does — for free.

The same app. Two architectures.

HTML over the wire.
Compute at the edge.

Click the button. Watch the fragment swap.

One button. One GET request. The server returns an HTML fragment. HTMX swaps it in. That's it.

Add, toggle, delete. Try it.

Every action sends a request. The server returns updated HTML. The list re-renders. Zero client state.

<button
  hx-put="/api/todos/1/toggle"
  hx-target="#todo-list"
  hx-swap="innerHTML"
>✓</button>

<form hx-post="/api/todos"
  hx-target="#todo-list">
  <input name="text"/>
  <button>Add</button>
</form>

Server-Sent Events. Words appearing live.

The server opens an SSE connection and pushes HTML fragments word by word. The browser applies them as they arrive. This is Datastar's model.

"Hypermedia is only for simple stuff." Watch this.

High-frequency UI.
30 updates a second.

SSE + Durable Objects.
No WebSocket complexity.

Server-Sent Events give you realtime updates with native browser support. Durable Objects give you stateful coordination at the edge.

Effect TS: typed errors,
composable services.

Every handler runs inside an Effect pipeline — tagged error unions, dependency injection, structured concurrency, observability for free.

const renderError = Effect.catchTags({
  NotFoundError: (e) =>
    html(<EmptyState title={...} />),
  ValidationError: (e) =>
    html(<FormErrors fields={...} />),
  RateLimitedError: (e) =>
    html(<RateLimitBanner />),
  ...// missing a tag? Compile error.
});

// Production: D1 database
const Live = UserService.Live

// Test: in-memory fixtures
const Test = UserService.Test

// Same routes, same type signatures
// — different backing services
app.get("/api/users/:id",
  authenticate(),
  async (c) => {
    const program = Effect.gen(function* () {
      const svc = yield* UserService;
      const user = yield* svc.getProfile(id);
      return c.html(<Profile {...user} />);
    }).pipe(renderError);
  }
);

Every error is a rendered response.

In a hypermedia architecture, error handling is just rendering. The server always returns HTML.

Same requirements. Less complexity.

Same feature. Half the code.

// 1. Schema
export const op = {
  input: z.object({ id: z.string() }),
  output: MetricsSummary,
  policy: { roles: ['admin'] },
};
// 2. Codegen'd hook (auto)
function useMetrics() { ... }
// 3. React component
function Panel() {
  const { data, error } = useMetrics();
  if (error) return <Error />;
  return <View data={data} />;
}
// 4. API seam
export async function POST(req) {
  const actor = await resolve(req);
  enforce(actor, schema.policy);
  return backend.metrics(input);
}

// 1. HTML
<div
  hx-get="/api/metrics"
  hx-trigger="load, refresh from /sse"
  hx-swap="innerHTML"
>Loading...</div>

// 2. Route handler
app.get("/api/metrics",
  authenticate(),
  authorize('admin'),
  async (c) => {
    const data = yield* svc.getMetrics(id);
    return c.html(
      <MetricsPanel {...data} />
    );
  }
);

Nothing is free. Here are the costs.

The bet is that fewer moving parts outweighs the loss of compile-time wire types. In 25 years of building production systems, that bet has paid off more often than not.

"The web already has
an application protocol.
Use it."

Stu Kennedy
HTMX Core Contributor · stu@stukennedy.com

Built with conviction. Open to being wrong.