htmx Foundations

htmx Foundations

Use this skill before implementation details get scattered across endpoints, templates, and browser scripts. The goal is to keep the server in charge of durable state while htmx adds targeted interactivity through HTML attributes.

Core Model

• The server owns persistence, authorization, validation, and rendered HTML.
• The browser sends normal HTTP requests from annotated HTML elements.
• Endpoints return HTML fragments when updating part of a page and full pages when supporting direct navigation.
• htmx swaps response HTML into a selected target instead of expecting JSON plus client-side rendering.
• Add browser-side JavaScript only for local state, specialized widgets, or imperative integration points.

When htmx Fits

Use htmx when the workflow is mostly:

• Forms, CRUD, search, filtering, pagination, inline editing, modals, dashboards, or admin UI.
• Server-authoritative data with existing auth, permissions, and validation.
• HTML-first pages where direct load, refresh, and non-JavaScript fallback matter.
• Small interactive islands rather than a full client-side application shell.

Consider a richer client app when the product needs:

• Offline-first behavior, heavy canvas/WebGL interaction, complex local document editing, or deep client-side routing.
• Large amounts of optimistic state that must survive many server round trips before reconciliation.

Setup Checklist

1. Load htmx once in the base layout, preferably from a vendored static asset or a CDN with integrity protection.
2. Configure cross-cutting request headers once, such as CSRF headers in frameworks that need them.
3. Keep URLs meaningful. Every pushed or boosted URL should render a full page on direct load.
4. Create reusable server-rendered partials for fragments that htmx swaps.
5. Render the initial full page by including the same partials that htmx endpoints return.
6. Add tests for both the full-page path and the htmx partial path when they differ.

Attribute Mental Model