@designbycode/alpine-debug
v1.0.0
Published
A singleton debug bar UI for Alpine.js applications, providing an interactive, tabbed panel to inspect reactive data or any arbitrary debug information live in the browser.
Readme
Alpine Debug Bar Plugin
A singleton debug bar UI for Alpine.js applications, providing an interactive, tabbed panel to inspect reactive data or any arbitrary debug information live in the browser.
What It Does
This plugin adds a persistent debug bar fixed at the bottom of the page. It allows you to create multiple tabs dynamically, each showing formatted JSON debug information related to different Alpine.js components or any JavaScript expression.
- Displays component data or custom debug data in a clean, readable JSON format
- Supports multiple tabs with custom or default names
- Toggleable visibility with a button showing a bug icon or chevron
- Automatically updates panels as underlying data changes reactively
- Removes tabs and panels when associated DOM elements are removed
- Use a singleton pattern to manage a single debug bar instance globally
- Works as an Alpine.js directive for easy integration
Use Cases
- Debugging reactive Alpine.js component states in development
- Inspecting complex nested objects and functions visually
- Monitoring data changes live in the browser without console logging
- Quickly switching between multiple debug contexts or components
- Developing and debugging Alpine.js plugins or complex UI logic
Installation
Install Alpine.js (v3+) if not already installed:
npm install alpinejsAdd the debug bar plugin script to your project (assuming you saved it as alpine-debug.ts):
import Alpine from 'alpinejs'
import AlpineDebug from './alpine-debug'
Alpine.plugin(AlpineDebug)
Alpine.start()Usage
Use the x-debug directive on any element within an Alpine.js component.
Basic - Debug component data
<div x-data="{ count: 0 }" x-debug>
<button @click="count++">Increment</button>
</div>This will create a debug tab showing the component’s reactive data.
Custom debug expression and tab name
<div x-data="{ user: { name: 'Alice', age: 30 } }" x-debug="user">
<!-- Displays user object in debug panel -->
</div>
<div x-data x-debug.tab="'User Info'">
<!-- Displays entire component data stack with tab named 'User Info' -->
</div>- Without the
.tabmodifier, thex-debugexpression is evaluated and displayed in the panel and used as the tab name. - With
.tabmodifier, the expression is treated as the literal tab name, and the entire component data stack is displayed.
Features
- Singleton debug bar appended to the document body
- Toggle button to show/hide debug bar (bug icon / chevron)
- Tabs dynamically created for each debug block with selectable activation
- Reactive updates of debug content when Alpine data changes
- Safe JSON serialization with custom replacer to handle functions, undefined, symbols, and class instances
- Clean UI styled with scoped CSS for easy customization
- Automatically removes debug blocks when their DOM elements are removed
- Disabled in production unless URL contains
?debug=true
Example
<body>
<div x-data="{ message: 'Hello world', count: 0 }" x-debug>
<button @click="count++">Count: <span x-text="count"></span></button>
</div>
<div x-data="{ user: { name: 'Bob', loggedIn: true } }" x-debug.tab="'User Info'">
<p>User component</p>
</div>
<script type="module">
import Alpine from 'alpinejs'
import AlpineDebug from './alpine-debug'
Alpine.plugin(AlpineDebug)
Alpine.start()
</script>
</body>Open the page, and the debug bar appears at the bottom showing tabs for each debug block. Click tabs to switch between data views, toggle the bar’s visibility with the bug icon, and watch reactive data update live.
License
MIT License