htmx-debugger

KO | EN

gitlite — search

#javascript #python #hacktoberfest #llm #go #golang #machine-learning #linux #windows #pytorch #security #mcp #openai #open-source

(★ 145)

a browser extension (Chrome and Firefox) debugging tool for htmx applications

File Explorer

Download Latest Version (.zip)

- - bug_report.md
  - feature_request.md
.build.ps1
.editorconfig
.gitignore
.prettierignore
background.js
bun.lock
CHANGELOG.md
content.js
devtools.html
devtools.js
eslint.config.mjs
htmx-debugger-logo-128.png
htmx-debugger-logo-16.png
htmx-debugger-logo-32.png
htmx-debugger-logo-48.png
htmx-panel-with-events.jpg
LICENSE
manifest-firefox.json
manifest.json
output.css
package.json
panel.html
panel.js
prettier.config.mjs
README.md
tailwind.config.mjs
tailwind.css
todo.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# htmx-debugger v1.2.1 - 2026-07-30

## Overview

htmx-debugger is a powerful browser extension (compatible with Chrome and Firefox) designed to help developers debug and analyze htmx applications. It provides a comprehensive and user-friendly interface for viewing htmx events, requests, and responses in real-time. This tool is essential for understanding and troubleshooting htmx-powered web applications, making the development process smoother and more efficient.

![htmx-debugger panel with events](https://raw.githubusercontent.com/NomadicDaddy/htmx-debugger/main/htmx-panel-with-events.jpg)

## Features

- Real-time capture and display of htmx events
- Support for htmx 2 and htmx 4 event names
- Intelligent grouping of related events for easier analysis
- Powerful search functionality to filter events
- One-click clear button to reset the debugger view
- Flexible event filtering (All, Request, Response)
- Collapsible event details for a cleaner interface
- Detailed timing information for request-response cycles
- Live connection status indicator
- Automatic periodic connection checks for improved stability
- Robust error handling and reporting

## Future

- Export functionality to save captured events as a JSON file
- Import capability to load and analyze events from a JSON file

## Installation

### Chrome Web Store (Recommended)

1. Visit the [htmx-debugger page](https://chrome.google.com/webstore/detail/fkpjmdhppdadklmcjbifffmjplgoboic) on the Chrome Web Store.
2. Click the "Add to Chrome" button.
3. Confirm the installation when prompted.

### Manual Chrome Installation

1. Clone this repository or download the source code.
2. Open Google Chrome and navigate to `chrome://extensions/`.
3. Enable "Developer mode" by toggling the switch in the top right corner.
4. Click on "Load unpacked" and select the directory containing the extension files.
5. The htmx-debugger extension should now appear in your list of installed extensions.

### Firefox Add-Ons (Recommended)

1. Visit the [htmx-debugger page](https://addons.mozilla.org/en-US/firefox/addon/htmx-debugger) on the Firefox Add-Ons website.
2. Click the "Add to Firefox" button.
3. Confirm the installation when prompted.

### Manual Firefox Installation

1. Download the latest release file for Firefox browsers.
2. Open Firefox and navigate to `about:debugging#/runtime/this-firefox`.
3. Click on "Load Temporary Add-on..." and select the downloaded release file.
4. The htmx-debugger extension should now appear in your list of installed extensions.

### Safari Coming Soon

## Usage

### Opening the Debugger

1. Navigate to a webpage that uses htmx.
2. Open Chrome DevTools (Right-click > Inspect or press F12).
3. Look for the "htmx" tab in the DevTools panel. If you don't see it, click on the ">>" icon to find it in the list of additional tools.

### Debugging htmx Events

The debugger automatically captures htmx events as they occur on the page. Each event is displayed with the following information:

- Event type
- Timestamp
- Target element details
- Event-specific details
- XHR information (for relevant events)

### Using the Debugger Features

1. **Connection Status**: Check the connection status indicator in the panel header to ensure the debugger is properly connected.
2. **Search**: Use the search bar at the top to filter events based on their content.
3. **Clear**: Click the "Clear" button to reset the debugger and remove all captured events.
4. **Event Filtering**: Use the filter buttons to show all events, only requests, or only responses.
5. **Expand/Collapse**: Click on an event header to expand or collapse its details.
6. **Timing Information**: For grouped events, the total duration is displayed at the bottom of the group.

## Troubleshooting

- If you don't see any events in the debugger, ensure that the webpage you're debugging is actually using htmx.
- If the htmx tab doesn't appear in DevTools, try reloading the page or reopening DevTools.
- Check the browser console for any error messages related to the extension.
- If the connection status shows "Disconnected", try reloading the page.
- If problems persist, try disabling and re-enabling the extension, reloading the webpage, or restarting Chrome.

## Development

### Key File Structure

- `background.js`: Background script for message handling and service worker setup
- `content.js`: Content script for capturing htmx events and communication with background script
- `devtools.html`: DevTools panel HTML
- `devtools.js`: DevTools panel functionality
- `manifest.json`: Extension configuration, permission or configuration changes
- `panel.html`: Panel HTML for displaying captured events and debugger controls
- `panel.js`: Panel functionality for handling event display and debugger features

There are many other build/development-related files in addtion to those listed above. If you're contributing or modifying for your own purposes you should recgonize these.

## Privacy Policy

htmx-debugger is committed to protecting user privacy and does not collect or use any personal user data. The extension operates solely within the context of the user's browser to provide debugging functionality for htmx applications.

### Permissions and Their Justifications

1. **alarms**: The alarms permission is used to schedule periodic connection checks, ensuring the debugger maintains a stable connection to the webpage. This improves the reliability of the debugging process.

### Single Purpose Description

The single purpose of htmx-debugger is to provide a comprehensive debugging tool for web developers working with htmx-powered applications. It captures, displays, and analyzes htmx events in real-time, offering insights into the behavior and performance of htmx interactions within web pages.

### Data Usage Compliance

htmx-debugger complies with both the Chrome Web Store Developer Program Policies and the Firefox Add-Ons policies regarding data usage. The extension:

- Does not collect any personal user data
- Does not transmit any captured debugging information outside of the user's browser
- Only processes information necessary for its core debugging functionality
- Stores data locally and solely for the purpose of improving the user's debugging experience

By using htmx-debugger, users can be assured that their privacy is respected and that the extension operates within the bounds of its stated purpose as a development tool for htmx applications.

## Version History

- v1.2.1 (2026-07-30): Fixed the console flood on pages that boost forms, quieted the content
  script's per-page logging, and removed the htmx.process wrapper that never ran
- v1.2.0 (2026-07-30): Added htmx 4 event support, replayed events captured before the DevTools
  panel opens, and cleaned up extension reload and rate-limit errors
- v1.1.1 (2026-07-29): Fixed the Tailwind v4 distribution build and aligned the browser manifest
  versions
- v1.1.0 (2026-07-29): Added parsed HTTP response headers to XHR event logging, added xhr:abort event capture, migrated build toolchain from npm to bun
- v1.0.6 (2024-10-22): Added HX attributes to target element details, added snapshot information, added error handling and reporting, further reduced console log output
- v1.0.5 (2024-10-11): Before/after request/response event capture, removed activeTab permission, reduced console log output
- v1.0.4 (2024-10-03): Fixed excessive permissions per Google review
- v1.0.3 (2024-10-02): Minor update and new Firefox release, fixed sanitization issue recommended by Firefox
- v1.0.0 (2024-09-30): Initial release, core features implemented, Chrome Web Store release

For a detailed changelog, see [CHANGELOG.md](CHANGELOG.md).

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Contact

For any questions, support, or feedback, please contact the author through standard channels.

## Repository

The source code for this project is available on GitHub:

https://github.com/NomadicDaddy/htmx-debugger

For bug reports or feature requests, please use the [issue tracker](https://github.com/NomadicDaddy/htmx-debugger/issues).

htmx-debugger

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

htmx-debugger

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README