LiveDebugger Documentation

LiveDebugger is a browser-based tool designed for debugging Phoenix LiveView applications. Once running (defaulting to http://localhost:4007), it provides the following capabilities:

• LiveComponents tree: Visualize the hierarchy of your components.
• Assigns inspection: View the current state of assigns.
• Callback tracing: Trace and filter the execution of callbacks.
• Element inspection: Inspect DOM elements within the context of LiveView.

The SuccessorDiscoverer service is designed to maintain a smooth debugging experience when LiveViews are destroyed and immediately replaced.

In scenarios like a webpage reload, the existing LiveView hosting the page is killed, but a new LiveView is immediately instantiated to display the page again. SuccessorDiscoverer detects these new 'successor' LiveViews within a given browser window, ensuring that debugging tools can transition to the new LiveView instance without interruption.

The Components Tree feature allows you to visualize the arrangement of LiveComponents within a debugged LiveView. LiveDebugger monitors state changes in the LiveView processes and automatically refreshes the tree to reflect the current structure.

Key characteristics:

• Root: The tree root is the LiveView being debugged.
• Children: Children are identified as LiveComponents using their unique Phoenix.LiveComponent.CID.
• Auto-collapse: To maintain readability, the tree automatically collapses branches when there are too many elements.
• Conditional Rendering: You can use the tree to observe the addition and removal of components that are rendered conditionally based on application state.

LiveDebugger uses two separate JS/CSS bundles that serve different purposes and run in different environments. They are bundled independently using esbuild via LiveDebugger Mix tasks.

• app/: This is the LiveDebugger UI itself. It is served at the debugger endpoint and is loaded by app/web/layout.ex. It includes Tailwind v4.
• client/: This is a tiny bundle injected into the debugged application's pages. It is responsible for gathering information and rendering overlays, tooltips, and the debug button. It uses scoped CSS (with class prefixes) to prevent styles from leaking into the host application.

assets/
├── app/        # the LiveDebugger UI itself (served at the debugger endpoint)
└── client/     # injected into the *debugged* application's pages

The client bundle communicates with the LiveDebugger app via a bidirectional Phoenix channel.

During the installation process, LiveDebugger injects a meta tag into every page of the debugged application. This meta tag enables the creation of a separate Phoenix socket, which allows the client to join a channel and establish bidirectional communication with the LiveDebugger UI.

For complex pages (like Debugger.Web.DebuggerLive), use independent nested LiveViews mounted via live_render/3. This pattern allows each child component to subscribe to its own topics directly, avoiding the need to manually propagate messages from the parent LiveView to its children.

Best Practice: Nested LiveViews should expose a live_render component to simplify usage and handle initial assigns automatically.

Components Highlighting provides visual feedback to link your component tree to the actual DOM. By hovering over component names in the Components Tree, the corresponding DOM elements in your application will be highlighted.

Note: This feature requires JavaScript injection and is enabled by default.

Use Elements Inspection to select and inspect LiveViews or LiveComponents directly from the rendered page using your mouse.

Key capabilities:

• Two activation methods: a Debug Button or an Inspect Element button.
• Hover previews that show element information.
• Click-to-inspect functionality to drill down into specific nodes.
• Visual highlighting of elements during the selection process.
• Compatible with both standalone mode and the DevTools extension.

Use Callback Tracing to monitor the execution flow of your application. It provides detailed information on how functions are being called, including timing and arguments.

Key capabilities:

• Monitor all Phoenix.LiveView and Phoenix.LiveComponent callbacks.
• Filter traces by callback type, execution time, or specific search terms.
• Inspect arguments in detail via a fullscreen view.
• Copy callback arguments for terminal/IEx processing.

When writing new end-to-end tests for LiveDebugger, follow these conventions:

• Handling Global State: If a test mutates global state (such as settings or tracer configuration) that could cause race conditions with other tests, name the file using the *.serial.spec.ts suffix.
• Locators: Prefer using getByRole, getByText, or locator over raw CSS selectors to ensure tests are more resilient to UI changes.

The Components Tree allows you to examine the structural arrangement of LiveComponents within a debugged LiveView. The tree displays the complete hierarchy from the LiveView root down to all nested components, including their unique CIDs.

Key capabilities:

• Automatic tree updates whenever the state changes.
• Discovery of nested LiveView relationships and application structure.