How to Debug JSAR Applications: Chrome DevTools, ADB, and Native Debugging

You can debug JSAR applications using Chrome DevTools via the Chrome DevTools Protocol (CDP), Android Debug Bridge (ADB) for mobile devices, or LLDB/VS Code for native C++ debugging.

The m-creativelab/jsar-runtime provides a comprehensive debugging ecosystem that treats each application as an isolated Node.js process with a built-in inspector server. When compiled with inspector support, the runtime exposes a CDP endpoint that supports JavaScript debugging, DOM inspection, and performance profiling, alongside native debugging capabilities for the underlying C++ runtime.

Chrome DevTools for JavaScript Debugging

JSAR implements a subset of the Chrome DevTools Protocol (CDP) through a V8 Inspector server, enabling familiar browser-based debugging workflows.

Enabling the Inspector Server

To activate debugging capabilities, build the runtime with the INSPECTOR=yes flag:

make darwin INSPECTOR=yes

# Or for Android:

make android INSPECTOR=yes

When the inspector is enabled, the runtime initializes a CDP server in src/client/per_process.cpp, which calculates the listening port using the formula 9229 + id - 1 for custom builds. Official builds use port 9423 by default. The runtime logs the WebSocket endpoint at startup:

Debugger listening on ws://0.0.0.0:9229/<session-id>

Connecting from Desktop Chrome

Open Chrome and navigate to chrome://inspect#devices:

1. Click Configure and add localhost:9423 (official builds) or localhost:9229 (custom builds)
2. Wait for the JSAR application to appear in the Remote Target list
3. Click inspect to open the DevTools interface

The CDP connection supports JavaScript breakpoints, DOM tree inspection, CSS debugging, network monitoring, and memory heap snapshots.

Debugging on Android with ADB

For Android deployments, use ADB (Android Debug Bridge) to forward the device's inspector port to your development machine.

First, enable debugging on the device:

adb shell setprop jsar.debug.enabled yes
adb shell setprop jsar.renderer.graphics.debug yes

Then forward the CDP port and connect:

adb forward tcp:9229 tcp:9229

Open chrome://inspect in your desktop Chrome browser. The forwarded port makes the remote JSAR process appear as a local debugging target, allowing full DevTools access to applications running on physical devices or emulators.

Native C++ Debugging with LLDB and VS Code

For build-time crashes, memory issues, or GPU command-buffer investigation, debug the native C++ layer using LLDB through VS Code.

The repository includes a pre-configured launch configuration in .vscode/launch.json that automatically loads debug symbols from .dSYM files (on macOS) or debug directories (on Linux). To debug native code:

1. Build a Debug configuration with symbols enabled (-g -fno-limit-debug-info flags as documented in docs/development.md)
2. Open the project in VS Code: code .
3. Press F5 and select the "Debug JSAR (lldb)" configuration

This attaches LLDB to the running JSAR process, allowing you to set breakpoints in the C++ source, inspect variables, and analyze crash dumps from the native runtime layer.

Specialized Debugging Tools

Beyond standard JavaScript and native debugging, JSAR provides specialized inspection capabilities for graphics rendering and the Universal Rendering Server.

Graphics Debugging with KHR_debug

Enable OpenGL ES debugging on Android devices to capture GPU command buffers and rendering statistics:

adb shell setprop jsar.renderer.graphics.debug yes

This activates the KHR_debug extension, logging detailed graphics pipeline information to logcat.

Universal Rendering Server Inspector

For debugging the rendering backend, use the web-based inspector located at fixtures/inspector-client/jsar_universal_rendering_server_debugger.html:

open "file:///path/to/jsar-runtime/fixtures/inspector-client/jsar_universal_rendering_server_debugger.html"

Click Connect in the web UI to establish a CDP connection and query command buffers using the custom domain JSAR.UniversalRenderingServer.getCommandBuffers. This tool exposes internal renderer state that is not visible through standard DevTools panels.

Summary

• Build with INSPECTOR=yes to enable the V8 Inspector server in src/client/per_process.cpp
• Use Chrome DevTools connected to ws://localhost:9229 (or port 9423 for official builds) for JavaScript debugging
• Forward ports via ADB (adb forward tcp:9229 tcp:9229) to debug Android devices from desktop Chrome
• Attach LLDB through VS Code using the provided .vscode/launch.json for native C++ debugging
• Enable graphics debugging via jsar.renderer.graphics.debug system properties and the Universal Rendering Server web UI for GPU-specific issues

Frequently Asked Questions

How do I enable debugging in JSAR?

Build the runtime from source with the INSPECTOR=yes flag: make darwin INSPECTOR=yes or make android INSPECTOR=yes. Then set the runtime property jsar.debug.enabled to yes when running your application.

What port does the JSAR inspector use?

Official builds use port 9423, while custom builds calculate the port dynamically as 9229 + id - 1 in src/client/per_process.cpp. The actual WebSocket URL is printed to stdout when the application starts.

Can I debug JSAR applications running on Android devices?

Yes. Use adb forward tcp:9229 tcp:9229 to forward the device's inspector port to your development machine, then open chrome://inspect in desktop Chrome to access the DevTools interface for the remote application.

How do I debug native C++ crashes in JSAR?

Build a Debug configuration with symbols enabled per docs/development.md, then use the LLDB integration in VS Code via the .vscode/launch.json configuration. This allows you to step through the C++ runtime code and inspect the GPU command buffer state.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}