htmx-devtools-extension

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTMX DevTools Extension

HTMX DevTools扩展

Skill by ara.so — Devtools Skills collection.

由ara.so开发的工具 — 属于Devtools工具集合。

Overview

概述

HTMX DevTools is a browser extension that provides a comprehensive debugging interface for HTMX applications. It captures the full request lifecycle, tracks DOM elements with htmx attributes, visualizes swaps, monitors events, and surfaces errors. Supports both htmx 2.x and htmx 4.0 alpha with automatic version detection.

HTMX DevTools是一款浏览器扩展，为HTMX应用提供全面的调试界面。它捕获完整的请求生命周期，追踪带有htmx属性的DOM元素，可视化Swap过程，监控事件并显示错误。支持htmx 2.x和htmx 4.0 alpha版本，可自动检测版本。

Key Features

核心功能

Request Inspector: Full lifecycle tracking with timing breakdown, headers, and event trace
Element Inspector: Live DOM tree filtered to htmx elements with click-to-inspect
Event Timeline: Filterable timeline of all htmx events with category color coding
Swap Visualizer: Before/after snapshots with LCS-based diff view
Error Panel: Automatic detection of HTTP errors, target not found, timeouts, and swap errors

请求检查器：完整生命周期追踪，包含时间分解、请求头和事件轨迹
元素检查器：实时DOM树，筛选出带有htmx属性的元素，支持点击查看详情
事件时间线：可筛选的所有htmx事件时间线，按类别进行颜色编码
Swap可视化工具：基于LCS差异视图的前后快照对比
错误面板：自动检测HTTP错误、目标元素未找到、超时及Swap错误

Installation

安装

Installing the Extension

安装扩展

From Source (Development):

bash

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

Chrome/Edge/Brave/Arc:

Navigate to
```
chrome://extensions
```
Enable Developer mode (toggle in top right)
Click Load unpacked
Select the
```
dist/
```
folder from the cloned repository

Firefox:

bash

npm run build:firefox

Navigate to
```
about:debugging#/runtime/this-firefox
```
Click Load Temporary Add-on
Select
```
dist/manifest.json
```

从源码安装（开发环境）：

bash

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

Chrome/Edge/Brave/Arc浏览器：

打开
```
chrome://extensions
```
启用开发者模式（右上角开关）
点击加载已解压的扩展程序
选择克隆仓库中的
```
dist/
```
文件夹

Firefox浏览器：

bash

npm run build:firefox

打开
```
about:debugging#/runtime/this-firefox
```
点击加载临时附加组件
选择
```
dist/manifest.json
```
文件

Verifying Installation

验证安装

Open a page with htmx loaded
Press
```
F12
```
or open DevTools
Look for the HTMX tab in the DevTools panel
The version badge (blue for 2.x, purple for 4.0) should appear automatically

打开加载了htmx的页面
按
```
F12
```
或打开DevTools
在DevTools面板中查找HTMX标签
版本标识（2.x为蓝色，4.0为紫色）会自动显示

Using the Extension

使用扩展

Request Inspector

请求检查器

Monitor all HTMX requests with detailed lifecycle information:

Key Information Displayed:

HTTP method, URL, status code
Trigger element and target element
Visual timeline: Config → Send → Wait → Swap → Settle
All
```
HX-*
```
request and response headers
Request and response bodies
Correlated event trace

Controls:

Record (●): Capture new requests
Pause (❚❚): Stop capturing while preserving current data
Clear (🗑): Remove all captured requests

Example HTMX Request:

html

<!-- This request will appear in the Request Inspector -->
<button hx-get="/api/users" 
        hx-target="#user-list"
        hx-swap="innerHTML">
  Load Users
</button>

<div id="user-list"></div>

When clicked, the inspector shows:

Method:
```
GET
```
URL:
```
/api/users
```
Target:
```
#user-list
```
Swap:
```
innerHTML
```
Timing breakdown for each phase
HTTP headers including
```
HX-Request: true
```
,
```
HX-Target: user-list
```

监控所有HTMX请求，查看详细的生命周期信息：

显示的关键信息：

HTTP方法、URL、状态码
触发元素和目标元素
可视化时间线：配置 → 发送 → 等待 → Swap → 稳定
所有
```
HX-*
```
请求头和响应头
请求体和响应体
关联的事件轨迹

控制按钮：

录制 (●)：捕获新请求
暂停 (❚❚)：停止捕获，保留当前数据
清除 (🗑)：移除所有已捕获的请求

HTMX请求示例：

html

<!-- 该请求会显示在请求检查器中 -->
<button hx-get="/api/users" 
        hx-target="#user-list"
        hx-swap="innerHTML">
  加载用户
</button>

<div id="user-list"></div>

点击按钮后，检查器会显示：

方法：
```
GET
```
URL：
```
/api/users
```
目标：
```
#user-list
```
Swap方式：
```
innerHTML
```
各阶段的时间分解
HTTP请求头，包括
```
HX-Request: true
```
、
```
HX-Target: user-list
```

Element Inspector

元素检查器

Explore the live DOM tree filtered to htmx-relevant elements:

Features:

Auto-refreshing tree view showing element hierarchy
Click any element to see:
- All
```
hx-*
```
  attributes
- Resolved target selectors
- Internal htmx data
- Request history for that element
Element Picker (🎯): Click to select any element on the page
Hover over tree nodes to highlight elements on the page

Example Element Tree:

html

<body>
  <div hx-boost="true">
    <form hx-post="/api/contact" hx-target="#result">
      <input name="email" hx-validate="true">
      <button type="submit">Submit</button>
    </form>
    <div id="result" hx-swap-oob="true"></div>
  </div>
</body>

Inspector displays:

▼ body
  ▼ div [hx-boost="true"]
    ▼ form [hx-post="/api/contact", hx-target="#result"]
      • input [hx-validate="true"]
      • button
    • div#result [hx-swap-oob="true"]

浏览实时DOM树，筛选出与htmx相关的元素：

功能：

自动刷新的树状视图，展示元素层级
点击任意元素可查看：
- 所有
```
hx-*
```
  属性
- 解析后的目标选择器
- htmx内部数据
- 该元素的请求历史
元素选择器 (🎯)：点击后可选择页面上的任意元素
悬停树节点时，页面上对应的元素会高亮显示

元素树示例：

html

<body>
  <div hx-boost="true">
    <form hx-post="/api/contact" hx-target="#result">
      <input name="email" hx-validate="true">
      <button type="submit">提交</button>
    </form>
    <div id="result" hx-swap-oob="true"></div>
  </div>
</body>

检查器显示：

▼ body
  ▼ div [hx-boost="true"]
    ▼ form [hx-post="/api/contact", hx-target="#result"]
      • input [hx-validate="true"]
      • button
    • div#result [hx-swap-oob="true"]

Event Timeline

事件时间线

Filter and explore all htmx events with expandable details:

Event Categories:

Init:
```
htmx:load
```
,
```
htmx:configRequest
```
Request:
```
htmx:beforeRequest
```
,
```
htmx:afterRequest
```
XHR:
```
htmx:xhr:loadstart
```
,
```
htmx:xhr:progress
```
Response:
```
htmx:beforeSwap
```
,
```
htmx:afterSwap
```
Swap:
```
htmx:beforeSwap
```
,
```
htmx:swapError
```
OOB:
```
htmx:oobBeforeSwap
```
,
```
htmx:oobAfterSwap
```

History:

htmx:historyRestore

htmx:pushedIntoHistory

Transition:
```
htmx:beforeTransition
```
,
```
htmx:afterSettle
```

Error:

htmx:responseError

htmx:sendError

htmx:targetError

Example Event Flow:

typescript

// For this htmx request:
// <button hx-get="/data" hx-target="#output">Get Data</button>

// Timeline shows:
// 1. htmx:configRequest (Init) - Request configured
// 2. htmx:beforeRequest (Request) - About to send
// 3. htmx:xhr:loadstart (XHR) - XHR started
// 4. htmx:beforeSwap (Response) - Response received, about to swap
// 5. htmx:afterSwap (Swap) - DOM swapped
// 6. htmx:afterSettle (Transition) - Settling complete

Click any event to expand

event.detail

JSON payload.

筛选并浏览所有htmx事件，展开查看详情：

事件类别：

初始化：
```
htmx:load
```
、
```
htmx:configRequest
```
请求：
```
htmx:beforeRequest
```
、
```
htmx:afterRequest
```
XHR：
```
htmx:xhr:loadstart
```
、
```
htmx:xhr:progress
```
响应：
```
htmx:beforeSwap
```
、
```
htmx:afterSwap
```
Swap：
```
htmx:beforeSwap
```
、
```
htmx:swapError
```
OOB：
```
htmx:oobBeforeSwap
```
、
```
htmx:oobAfterSwap
```

历史记录：

htmx:historyRestore

、

htmx:pushedIntoHistory

过渡：
```
htmx:beforeTransition
```
、
```
htmx:afterSettle
```

错误：

htmx:responseError

、

htmx:sendError

、

htmx:targetError

事件流示例：

typescript

// 针对以下htmx请求：
// <button hx-get="/data" hx-target="#output">获取数据</button>

// 时间线显示：
// 1. htmx:configRequest（初始化）- 请求已配置
// 2. htmx:beforeRequest（请求）- 即将发送
// 3. htmx:xhr:loadstart（XHR）- XHR已启动
// 4. htmx:beforeSwap（响应）- 已接收响应，即将执行Swap
// 5. htmx:afterSwap（Swap）- DOM已完成交换
// 6. htmx:afterSettle（过渡）- 已稳定

点击任意事件可展开

event.detail

JSON负载。

Swap Visualizer

Swap可视化工具

Record and analyze DOM changes with before/after comparison:

Controls:

Record (●): Start capturing swaps
Pause (❚❚): Stop capturing
Click any swap entry to view details

Views:

Response HTML: Raw HTML received from server
Before: DOM state before swap
After: DOM state after swap
Diff: Line-by-line comparison with add/remove highlighting

Example Swap:

html

<!-- Before -->
<div id="content">
  <p>Old content</p>
</div>

<!-- Server responds with (hx-swap="innerHTML") -->
<p>New content</p>
<p>Additional paragraph</p>

<!-- After -->
<div id="content">
  <p>New content</p>
  <p>Additional paragraph</p>
</div>

Diff view shows:

diff

<div id="content">
-  <p>Old content</p>
+  <p>New content</p>
+  <p>Additional paragraph</p>
</div>

记录并分析DOM变化，进行前后对比：

控制按钮：

录制 (●)：开始捕获Swap操作
暂停 (❚❚)：停止捕获
点击任意Swap条目查看详情

视图：

响应HTML：从服务器接收的原始HTML
交换前：Swap操作前的DOM状态
交换后：Swap操作后的DOM状态
差异对比：逐行对比，高亮显示新增/删除内容

Swap示例：

html

<!-- 交换前 -->
<div id="content">
  <p>旧内容</p>
</div>

<!-- 服务器响应（hx-swap="innerHTML"） -->
<p>新内容</p>
<p>附加段落</p>

<!-- 交换后 -->
<div id="content">
  <p>新内容</p>
  <p>附加段落</p>
</div>

差异视图显示：

diff

<div id="content">
-  <p>旧内容</p>
+  <p>新内容</p>
+  <p>附加段落</p>
</div>

Error Panel

错误面板

Automatically surfaces HTMX failures grouped by type:

Error Types Detected:

HTTP Errors: 4xx and 5xx responses (even in htmx 4.0 where they swap by default)
Target Not Found:
```
hx-target
```
selector doesn't match any element
Network Timeouts: Request exceeds timeout threshold
Swap Errors: DOM swap operation fails

Example Error Detection:

html

<!-- This will trigger a "Target Not Found" error -->
<button hx-get="/data" hx-target="#missing-element">
  Click Me
</button>

<!-- This will trigger an "HTTP Error" if server returns 404 -->
<button hx-get="/nonexistent" hx-target="#output">
  Load Missing
</button>

Errors appear with:

Badge count per error type
Click to jump to associated request in Request Inspector
Full error details and context

自动按类型汇总HTMX失败情况：

检测到的错误类型：

HTTP错误：4xx和5xx响应（即使在htmx 4.0中默认会执行Swap）
目标未找到：
```
hx-target
```
选择器未匹配到任何元素
网络超时：请求超过超时阈值
Swap错误：DOM交换操作失败

错误检测示例：

html

<!-- 会触发“目标未找到”错误 -->
<button hx-get="/data" hx-target="#missing-element">
  点击我
</button>

<!-- 如果服务器返回404，会触发“HTTP错误” -->
<button hx-get="/nonexistent" hx-target="#output">
  加载不存在的资源
</button>

错误信息包含：

每种错误类型的标识计数
点击可跳转到请求检查器中对应的请求
完整的错误详情和上下文

Architecture

架构

Extension Components

扩展组件

Page Script (MAIN world)
  ↓ postMessage
Content Script (isolated)
  ↓ chrome.runtime.sendMessage
Service Worker (background)
  ↓ chrome.runtime.sendMessage
DevTools Panel (Preact UI)

Page Script (

src/page-script/index.ts

Runs in page's JavaScript context via
```
"world": "MAIN"
```
Listens to all
```
htmx:*
```
events (both 2.x and 4.0 naming)
Serializes element data and tracks requests
Batches messages every 50ms

Content Script (

src/content-script/index.ts

Bridges page and extension contexts

Relays messages via

window.postMessage

and

chrome.runtime.sendMessage

Background Service Worker (

src/background/index.ts

Manages per-tab state
Tracks request lifecycles
Maps 2.x and 4.0 event names to canonical format
Synthesizes HTTP errors for 4xx/5xx
Routes data to DevTools panel

DevTools Panel (

src/panel/

Preact + Signals UI (~55KB)
Five tabs: Requests, Elements, Timeline, Swaps, Errors
Real-time updates via message listeners

页面脚本（MAIN环境）
  ↓ postMessage
内容脚本（隔离环境）
  ↓ chrome.runtime.sendMessage
服务工作线程（后台）
  ↓ chrome.runtime.sendMessage
DevTools面板（Preact UI）

页面脚本 (

src/page-script/index.ts

)：

通过
```
"world": "MAIN"
```
运行在页面的JavaScript环境中
监听所有
```
htmx:*
```
事件（兼容2.x和4.0的命名）
序列化元素数据并追踪请求
每50ms批量发送消息

内容脚本 (

src/content-script/index.ts

)：

作为页面和扩展环境的桥梁

通过

window.postMessage

和

chrome.runtime.sendMessage

转发消息

后台服务工作线程 (

src/background/index.ts

)：

管理每个标签页的状态
追踪请求生命周期
将2.x和4.0的事件名称映射为标准格式
为4xx/5xx响应生成HTTP错误
将数据路由到DevTools面板

DevTools面板 (

src/panel/

)：

Preact + Signals UI（约55KB）
五个标签页：请求、元素、时间线、Swap、错误
通过消息监听实现实时更新

Version Detection

版本检测

The extension auto-detects htmx version and adapts:

Feature	htmx 2.x	htmx 4.0
Event names	`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

扩展会自动检测htmx版本并适配：

功能	htmx 2.x	htmx 4.0
事件名称	`htmx:configRequest`	`htmx:config:request`
请求追踪	XHR WeakMap	ctx对象WeakMap
详情结构	`detail.elt` , `detail.xhr`	`detail.ctx.sourceElement` , `detail.ctx.response`
错误事件	10个独立事件	统一的 `htmx:error` + 合成事件

Development

开发

Build Commands

构建命令

bash

undefined

bash

undefined

Development mode with watch

开发模式，带监听

npm run dev

Production build

生产构建

npm run build

Chrome-specific build (copies manifest + icons)

Chrome专属构建（复制清单+图标）

npm run build:chrome

Firefox-specific build

Firefox专属构建

npm run build:firefox

TypeScript type checking

TypeScript类型检查

npm run typecheck

undefined

npm run typecheck

undefined

Project Structure

项目结构

htmx-devtools/
├── src/
│   ├── page-script/       # Injected into page context
│   ├── content-script/    # Bridge between page and extension
│   ├── background/        # Service worker for state management
│   ├── panel/             # Preact UI components
│   │   ├── components/    # UI components for each tab
│   │   ├── store/         # Signal-based state management
│   │   └── utils/         # Helper functions
│   └── shared/            # Shared types and utilities
├── public/                # Static assets (icons, manifests)
├── test/e2e/fixtures/     # Test server and demo pages
└── dist/                  # Build output

htmx-devtools/
├── src/
│   ├── page-script/       # 注入到页面环境
│   ├── content-script/    # 页面与扩展的桥梁
│   ├── background/        # 状态管理的服务工作线程
│   ├── panel/             # Preact UI组件
│   │   ├── components/    # 每个标签页的UI组件
│   │   ├── store/         # 基于Signal的状态管理
│   │   └── utils/         # 辅助函数
│   └── shared/            # 共享类型和工具
├── public/                # 静态资源（图标、清单）
├── test/e2e/fixtures/     # 测试服务器和演示页面
└── dist/                  # 构建输出

Local Test Server

本地测试服务器

Start a local test server with comprehensive htmx examples:

bash

node test/e2e/fixtures/test-server.js

Open http://localhost:3456 in your browser.

Test Scenarios Covered:

GET/POST/PUT/DELETE requests
Error scenarios (404, 500, timeout)
All swap strategies (innerHTML, outerHTML, beforebegin, etc.)
Out-of-band swaps
Polling with
```
hx-trigger="every 2s"
```
Search with debounce
Click-to-edit pattern
Todo list CRUD

启动本地测试服务器，包含全面的htmx示例：

bash

node test/e2e/fixtures/test-server.js

在浏览器中打开http://localhost:3456。

覆盖的测试场景：

GET/POST/PUT/DELETE请求
错误场景（404、500、超时）
所有Swap策略（innerHTML、outerHTML、beforebegin等）
带外（OOB）Swap
使用
```
hx-trigger="every 2s"
```
的轮询
防抖搜索
点击编辑模式
Todo列表CRUD

Adding Custom Test Cases

添加自定义测试用例

Create HTML files in

test/e2e/fixtures/

directory:

html

<!-- test/e2e/fixtures/my-test.html -->
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/htmx.org@2.0.0"></script>
</head>
<body>
  <button hx-get="/api/test" hx-target="#result">
    Test Button
  </button>
  <div id="result"></div>
</body>
</html>

Access at http://localhost:3456/my-test.html

在

test/e2e/fixtures/

目录下创建HTML文件：

html

<!-- test/e2e/fixtures/my-test.html -->
<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/htmx.org@2.0.0"></script>
</head>
<body>
  <button hx-get="/api/test" hx-target="#result">
    测试按钮
  </button>
  <div id="result"></div>
</body>
</html>

访问http://localhost:3456/my-test.html查看。

Common Patterns

常见调试模式

Debugging Request Issues

调试请求问题

Problem: Request not showing up in inspector

typescript

// Check if htmx is properly loaded
console.log(window.htmx); // Should not be undefined

// Verify extension is capturing events
// Open HTMX DevTools tab, click Record button
// Look for "Recording" indicator

// Check if element has valid htmx attributes
const el = document.querySelector('[hx-get]');
console.log(el.getAttribute('hx-get')); // Should show URL

Problem: Target element not updating

html

<!-- BAD: Target selector is invalid -->
<button hx-get="/data" hx-target="missing">Load</button>

<!-- GOOD: Target exists in DOM -->
<button hx-get="/data" hx-target="#content">Load</button>
<div id="content"></div>

Check Error Panel for "Target Not Found" errors.

问题：请求未显示在检查器中

typescript

// 检查htmx是否正确加载
console.log(window.htmx); // 不应为undefined

// 验证扩展是否正在捕获事件
// 打开HTMX DevTools标签，点击录制按钮
// 查看“正在录制”标识

// 检查元素是否有有效的htmx属性
const el = document.querySelector('[hx-get]');
console.log(el.getAttribute('hx-get')); // 应显示URL

问题：目标元素未更新

html

<!-- 错误：目标选择器无效 -->
<button hx-get="/data" hx-target="missing">加载</button>

<!-- 正确：目标元素存在于DOM中 -->
<button hx-get="/data" hx-target="#content">加载</button>
<div id="content"></div>

查看错误面板中的“目标未找到”错误。

Tracking Element State

追踪元素状态

Use Element Inspector to verify attribute resolution:

html

<div id="parent" hx-boost="true">
  <a href="/page1">Link 1</a>
  <a href="/page2">Link 2</a>
</div>

Element Inspector shows:

Both
```
<a>
```
elements inherit
```
hx-boost
```
behavior
Click either link to see request in Request Inspector
Request history shows all requests triggered by that element

使用元素检查器验证属性解析：

html

<div id="parent" hx-boost="true">
  <a href="/page1">链接1</a>
  <a href="/page2">链接2</a>
</div>

元素检查器显示：

两个
```
<a>
```
元素都继承了
```
hx-boost
```
行为
点击任意链接可在请求检查器中查看对应的请求
请求历史显示该元素触发的所有请求

Monitoring Swap Behavior

监控Swap行为

Enable Swap Visualizer before triggering swaps:

html

<!-- Test different swap strategies -->
<button hx-get="/content" hx-target="#out" hx-swap="innerHTML">innerHTML</button>
<button hx-get="/content" hx-target="#out" hx-swap="outerHTML">outerHTML</button>
<button hx-get="/content" hx-target="#out" hx-swap="beforebegin">beforebegin</button>

<div id="out">Original content</div>

Swap Visualizer shows:

Response HTML received from server
Before/After DOM snapshots
Diff highlighting exact changes
Swap strategy and target info

触发Swap操作前启用Swap可视化工具：

html

<!-- 测试不同的Swap策略 -->
<button hx-get="/content" hx-target="#out" hx-swap="innerHTML">innerHTML</button>
<button hx-get="/content" hx-target="#out" hx-swap="outerHTML">outerHTML</button>
<button hx-get="/content" hx-target="#out" hx-swap="beforebegin">beforebegin</button>

<div id="out">原始内容</div>

Swap可视化工具显示：

从服务器接收的响应HTML
交换前后的DOM快照
高亮显示具体变化的差异视图
Swap策略和目标信息

Filtering Event Timeline

筛选事件时间线

Use category filters to focus on specific event types:

typescript

// To debug swap issues, enable only Swap category
// Timeline shows: htmx:beforeSwap, htmx:afterSwap, htmx:swapError

// To debug request failures, enable Request + Error categories
// Timeline shows: htmx:beforeRequest, htmx:responseError, etc.

// Search bar filters within visible categories
// Example: Search "error" to find all error-related events

使用类别过滤器聚焦特定类型的事件：

typescript

// 调试Swap问题时，仅启用Swap类别
// 时间线显示：htmx:beforeSwap、htmx:afterSwap、htmx:swapError

// 调试请求失败时，启用请求+错误类别
// 时间线显示：htmx:beforeRequest、htmx:responseError等

// 搜索栏可在可见类别中筛选
// 示例：搜索“error”查找所有与错误相关的事件

Troubleshooting

故障排除

Extension Not Appearing in DevTools

扩展未在DevTools中显示

Issue: No HTMX tab in DevTools

Solution:

Verify extension is installed: Check
```
chrome://extensions
```
Ensure extension is enabled
Reload the page after installing extension
Check browser console for extension errors
Try refreshing DevTools (close and reopen)

问题：DevTools中没有HTMX标签

解决方案：

验证扩展已安装：查看
```
chrome://extensions
```
确保扩展已启用
安装扩展后重新加载页面
检查浏览器控制台中的扩展错误
尝试刷新DevTools（关闭后重新打开）

No Requests Being Captured

未捕获到任何请求

Issue: Request Inspector shows "No requests captured"

Solution:

typescript

// 1. Verify htmx is loaded on the page
console.log(window.htmx); // Should output htmx object

// 2. Check if Recording is enabled
// Click the red record button in Request Inspector

// 3. Verify htmx elements are properly configured
document.querySelectorAll('[hx-get], [hx-post], [hx-put], [hx-delete]');
// Should return NodeList with your htmx elements

// 4. Check for JavaScript errors blocking htmx
// Open browser console, look for errors

// 5. Test with simple example
const testBtn = document.createElement('button');
testBtn.setAttribute('hx-get', '/test');
testBtn.textContent = 'Test';
document.body.appendChild(testBtn);
htmx.process(testBtn);
testBtn.click();

问题：请求检查器显示“未捕获到请求”

解决方案：

typescript

// 1. 验证页面已加载htmx
console.log(window.htmx); // 应输出htmx对象

// 2. 检查是否已启用录制
// 点击请求检查器中的红色录制按钮

// 3. 验证htmx元素配置正确
document.querySelectorAll('[hx-get], [hx-post], [hx-put], [hx-delete]');
// 应返回包含htmx元素的NodeList

// 4. 检查是否有JavaScript错误阻止htmx运行
// 打开浏览器控制台，查看错误信息

// 5. 使用简单示例测试
const testBtn = document.createElement('button');
testBtn.setAttribute('hx-get', '/test');
testBtn.textContent = '测试';
document.body.appendChild(testBtn);
htmx.process(testBtn);
testBtn.click();

Element Inspector Not Showing Elements

元素检查器未显示元素

Issue: Element tree is empty

Solution:

Verify page has elements with
```
hx-*
```
attributes
Click the refresh icon in Element Inspector
Check if elements are dynamically loaded (wait for
```
htmx:load
```
event)
Use Element Picker (target icon) to directly select elements

问题：元素树为空

解决方案：

验证页面存在带有
```
hx-*
```
属性的元素
点击元素检查器中的刷新图标
检查元素是否是动态加载的（等待
```
htmx:load
```
事件）
使用元素选择器（目标图标）直接选择元素

Events Not Appearing in Timeline

事件未显示在时间线中

Issue: Timeline shows "No events captured"

Solution:

typescript

// 1. Ensure event listeners are not blocked
// Check for errors in background service worker

// 2. Verify htmx events are firing
document.addEventListener('htmx:afterRequest', (e) => {
  console.log('Request completed:', e.detail);
});

// 3. Check category filters in Timeline tab
// Ensure at least one category is enabled

// 4. Clear and re-record
// Click Clear button, then trigger a new htmx request

问题：时间线显示“未捕获到事件”

解决方案：

typescript

// 1. 确保事件监听器未被阻止
// 检查后台服务工作线程中的错误

// 2. 验证htmx事件正在触发
document.addEventListener('htmx:afterRequest', (e) => {
  console.log('请求完成:', e.detail);
});

// 3. 检查时间线标签中的类别过滤器
// 确保至少启用了一个类别

// 4. 清除并重新录制
// 点击清除按钮，然后触发新的htmx请求

Version Detection Issues

版本检测问题

Issue: Wrong version badge or features not working

Solution:

typescript

// Check actual htmx version
console.log(htmx.version);

// htmx 2.x: Returns string like "2.0.0"
// htmx 4.0: Returns string like "4.0.0-alpha1"

// Reload extension and page if version changed
// Extension detects version on page load

问题：版本标识错误或功能无法正常工作

解决方案：

typescript

// 检查实际的htmx版本
console.log(htmx.version);

// htmx 2.x：返回类似"2.0.0"的字符串
// htmx 4.0：返回类似"4.0.0-alpha1"的字符串

// 如果版本变更，重新加载扩展和页面
// 扩展在页面加载时检测版本

Performance Issues with Large Applications

大型应用性能问题

Issue: DevTools panel becomes slow

Solution:

Use Record/Pause controls to limit data capture
Clear old requests periodically
Filter Event Timeline to specific categories
Disable Swap Visualizer when not actively debugging swaps
Use search to narrow down large request lists

问题：DevTools面板运行缓慢

解决方案：

使用录制/暂停控制限制数据捕获
定期清除旧请求
筛选事件时间线到特定类别
不调试Swap时禁用Swap可视化工具
使用搜索缩小请求列表范围

Extension Updates

扩展更新

Issue: New version available but not updating

Solution (Development Mode):

bash

undefined

问题：有新版本可用但未更新

开发环境解决方案：

bash

undefined

Pull latest changes

拉取最新代码

git pull origin main

Rebuild extension

重新构建扩展

npm install npm run build:chrome # or build:firefox

npm install npm run build:chrome # 或build:firefox

Reload extension

重新加载扩展

1. Go to chrome://extensions

1. 打开chrome://extensions

2. Click reload icon on htmx-devtools extension

2. 点击htmx-devtools扩展的重新加载图标

3. Refresh pages with htmx

3. 刷新带有htmx的页面

undefined

undefined

Browser Compatibility

浏览器兼容性

Chrome: 88+ (Manifest V3 support)
Edge: 88+
Brave: Latest
Arc: Latest
Opera: 74+
Firefox: 128+ (Manifest V3 support in Firefox 128+)

Chrome: 88+（支持Manifest V3）
Edge: 88+
Brave: 最新版本
Arc: 最新版本
Opera: 74+
Firefox: 128+（Firefox 128+支持Manifest V3）

Resources

资源

Live Demo: https://atoolz.github.io/htmx-devtools/
htmx 2.x Demo: https://atoolz.github.io/htmx-devtools/v2/
htmx 4.0 Demo: https://atoolz.github.io/htmx-devtools/v4/
GitHub Repository: https://github.com/atoolz/htmx-devtools
htmx Documentation: https://htmx.org/docs/
htmx Events Reference: https://htmx.org/events/

在线演示: https://atoolz.github.io/htmx-devtools/
htmx 2.x演示: https://atoolz.github.io/htmx-devtools/v2/
htmx 4.0演示: https://atoolz.github.io/htmx-devtools/v4/
GitHub仓库: https://github.com/atoolz/htmx-devtools
htmx文档: https://htmx.org/docs/
htmx事件参考: https://htmx.org/events/