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

> Learn to debug JSAR applications effectively. Explore Chrome DevTools for web debugging, ADB for mobile, and native debugging with LLDB/VS Code. Master JSAR runtime.

- Repository: [M Creative Lab/jsar-runtime](https://github.com/m-creativelab/jsar-runtime)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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:

```bash
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`](https://github.com/m-creativelab/jsar-runtime/blob/main/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:

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

```

Then forward the CDP port and connect:

```bash
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`](https://github.com/m-creativelab/jsar-runtime/blob/main/.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`](https://github.com/m-creativelab/jsar-runtime/blob/main/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:

```bash
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`](https://github.com/m-creativelab/jsar-runtime/blob/main/fixtures/inspector-client/jsar_universal_rendering_server_debugger.html):

```bash
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`](https://github.com/m-creativelab/jsar-runtime/blob/main/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`](https://github.com/m-creativelab/jsar-runtime/blob/main/.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`](https://github.com/m-creativelab/jsar-runtime/blob/main/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`](https://github.com/m-creativelab/jsar-runtime/blob/main/docs/development.md), then use the LLDB integration in VS Code via the [`.vscode/launch.json`](https://github.com/m-creativelab/jsar-runtime/blob/main/.vscode/launch.json) configuration. This allows you to step through the C++ runtime code and inspect the GPU command buffer state.