KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #dsh-plugin #deepseek-harness #windows #open-source #agent-skills #ai

htmx-devtools

★ 134 Open GitHub ↗

Browser DevTools extension for debugging HTMX applications

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Browser DevTools extension for debugging <a href="https://htmx.org">HTMX</a> applications. 
 Works with both htmx 2.x and htmx 4.0 alpha.

## Features

### Request Inspector

Capture the full HTMX request lifecycle with timing breakdown, headers, request/response body, and event trace.

- HTTP verb, URL, status, swap strategy
- Trigger and target element identification
- Visual timeline bar (Config > Send > Wait > Swap > Settle)
- HX-* request and response headers
- Record / Pause / Clear controls
- HTTP error detection (4xx/5xx shown as errors even on htmx 4 where they swap by default)

### Element Inspector

Live DOM tree showing all HTMX elements with their hierarchy, attributes, and resolved targets. Auto-refreshes in real time.

- Collapsible DOM tree filtered to HTMX-relevant nodes
- Click to inspect: shows `hx-*` attributes, resolved targets, internal data
- Element picker (Chrome DevTools style): click any element on the page
- Hover highlighting on the inspected page
- Request history per element (click to jump to Requests tab)

### Event Timeline

Filterable timeline of all HTMX events with category color coding and expandable detail payloads.

- Category filters: Init, Request, XHR, Response, Swap, OOB, History, Transition, Error
- Timestamps relative to first event
- Click to expand full `event.detail` JSON
- Request correlation (linked request ID)
- Per-tab search (filters reset when switching tabs)

### Swap Visualizer

Record DOM swaps with before/after snapshots and LCS-based diff view.

- Record / Pause controls
- Response HTML view
- Before / After DOM snapshots
- Line-by-line diff with add/remove highlighting (LCS algorithm)
- Swap strategy and target element info

### Error Panel

Surface silent HTMX failures grouped by error type with badge counts.

- HTTP errors (4xx, 5xx) detected automatically
- Target not found errors
- Network timeouts and swap errors
- Click to jump to associated request

---

## htmx 4.0 Support

Version 0.2.0 adds full support for the htmx 4.0 alpha. The extension auto-detects which version is running and adapts transparently.

| | htmx 2.x | htmx 4.0 |
|---|---|---|
| **Event format** | `htmx:configRequest` | `htmx:config:request` |
| **Request tracking** | XHR WeakMap | ctx object WeakMap |
| **Detail structure** | `detail.elt`, `detail.xhr` | `detail.ctx.sourceElement`, `detail.ctx.response` |
| **Error events** | 10 separate events | Unified `htmx:error` + synthetic HTTP errors |
| **Attributes** | `hx-ext`, `hx-request` | `hx-action`, `hx-method`, `hx-config`, `hx-status` |
| **Version badge** | Blue pill | Purple pill |

Both versions work simultaneously. No configuration needed.

---

## Installation

### From source

```bash
git clone https://github.com/atoolz/htmx-devtools.git
cd htmx-devtools
npm install
npm run build:chrome
```

**Chrome / Edge / Brave / Arc:**

1. Open `chrome://extensions`
2. Enable **Developer mode**
3. Click **Load unpacked**
4. Select the `dist/` folder

**Firefox:**

```bash
npm run build:firefox
```

1. Open `about:debugging#/runtime/this-firefox`
2. Click **Load Temporary Add-on**
3. Select `dist/manifest.json`

---

## Live Demo

Try the extension with interactive demo pages (no server needed):

- **[htmx 2.x Demo](https://atoolz.github.io/htmx-devtools/v2/)** (XHR mock)
- **[htmx 4.0 Demo](https://atoolz.github.io/htmx-devtools/v4/)** (fetch mock)

Install the extension, open a demo, press F12, and go to the HTMX tab.

---

## How it works

```
Page Script          Content Script       Service Worker       DevTools Panel
(MAIN world)         (isolated)           (background)         (Preact UI)

Captures htmx    ->  Relays via        -> Routes messages,  -> Renders 5 tabs
events on            postMessage +         maintains state      with real-time
document             runtime.sendMessage   per tab              updates
```

- **Page Script** runs in the page's JS context via `"world": "MAIN"` content script. Listens to all `htmx:*` events (both 2.x and 4.x names), serializes element data, tracks requests via XHR/ctx WeakMaps, and batches messages every 50ms.
- **Content Script** bridges page and extension contexts via `window.postMessage` and `chrome.runtime.sendMessage`.
- **Background Service Worker** manages per-tab state, tracks request lifecycles with canonical event name mapping, correlates events to requests, synthesizes HTTP errors for 4xx/5xx, and routes data to the panel.
- **Panel** is a Preact + Signals app (~55KB) rendered inside `chrome.devtools.panels.create()`.

---

## Development

```bash
npm run dev            # Watch mode (rebuilds on changes)
npm run build          # Production build
npm run build:chrome   # Build + copy Chrome manifest + icons
npm run build:firefox  # Build + copy Firefox manifest + icons
npm run typecheck      # TypeScript type check
```

### Local test server

```bash
node test/e2e/fixtures/test-server.js
# Open http://localhost:3456
```

Covers: GET/POST/PUT/DELETE, error scenarios (404, 500, timeout), all swap strategies, OOB swaps, polling, search with delay, contact editor (click-to-edit), and todo list.

---

## Tech Stack

| | |
|---|---|
| **Language** | TypeScript |
| **Build** | Vite (multi-entry, IIFE outputs for content/page/background scripts) |
| **UI** | Preact + @preact/signals (3KB gzipped) |
| **Manifest** | Chrome MV3 (also Firefox MV3 128+) |
| **Target** | Chrome, Edge, Brave, Arc, Opera, Firefox |
| **Dependencies** | 7 devDependencies, 0 runtime dependencies |

---

## License

MIT

htmx-devtools

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README