Perform Line-by-Line Debugging with Vega Studio

Learn how to debug Vega apps and Turbo Modules with Vega Studio through GDB (GNU Debugger). Vega Studio provides built-in debugging capabilities that use GDB for native code debugging, allowing you to inspect running programs, set breakpoints, and step through code execution. Turbo Modules are native code components that extend React Native functionality.

For Chrome DevTools debugging, see Use Chrome DevTools for App Profiling.

Prerequisites

Before you can debug apps with Vega Studio, complete these setup requirements to ensure your development environment and target devices are properly configured.

1. (Optional) Review the VS Code debugging documentation.

2. (Optional) Learn about GDB (GNU Debugger).

3. Choose your debugging target: Kepler Virtual Device or Fire TV Stick.

4. Enable developer mode for your target:

   Vega Virtual Device

   1. Open VS Code.
   2. Select the Vega Studio extension icon from the activity bar.
   3. Navigate to Devices.
   4. Start the Vega Virtual Device.
   5. Open a terminal and run:

   Copy code Copied to clipboard.

   kepler exec vda shell vsm developer-mode enable
   

   Fire TV Stick

   1. Connect your Fire TV Stick to your development machine through USB.
   2. Enable developer mode following Run Your App on Fire TV Stick.

Configure the Vega Studio debugger

Set up debugging configurations to specify how Vega Studio should launch and connect to your app. You can use automatic configuration for quick setup or manual configuration for custom debugging scenarios.

Automatic configuration

Option 1: Use an open file or selected project

1. Open your project file or select it from the sidebar.

2. Choose Run and Debug from the VS Code activity bar.

   

3. Follow the steps in Debug your app.

Option 2: Use Show all automatic configurations

1. Go to Run and Debug in the VS Code activity bar.
2. Click Show all automatic debug configurations.

3. Select your desired debug configuration.

   

Manual configuration

1. Go to Run and Debug in the VS Code activity bar.
2. Click create a launch.json file.
3. Select a Kepler project from the prompt (skip if you only have one project).

4. Choose your debugger:

   • Kepler: For React Native for Kepler apps (JavaScript/TypeScript code)
   • KeplerNative: For Turbo Modules (native C++ code)

Kepler Studio creates a launch.json file with default configuration.

Specify your target device

When multiple devices are connected, specify your target device by setting the deviceId property:

• "${command:kepler.state.getSelectedDeviceId}" - Uses device selected from the sidebar
• "KeplerVirtualDevice" - Targets Kepler Virtual Device specifically
• Device serial ID - Targets specific physical device

Add configuration to launch.json

To add additional configurations to an existing launch.json file:

1. Open your app's launch.json file.
2. Select the Add Configuration button.
3. Choose your desired launch target from the available options.

4. Save your changes.

   

Set up breakpoints

Create breakpoints in your app by clicking in the left margin of the code editor next to line numbers.

Launch.json attributes

Sample configurations

Basic React Native for Vega app

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(script) Launch",
            "type": "kepler",
            "request": "launch",
            "keplerMode": "debug",
            "cwd": "${workspaceFolder}",
            "deviceId": "${command:kepler.state.getSelectedDeviceId}",
            "disableAppTimeout": true,
            "perf": {
                "startActivityMonitoring": false
            }
        }
    ]
}

Multi-device React Native for Vega app

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(script) Launch on selected device",
            "type": "kepler",
            "request": "launch",
            "keplerMode": "debug",
            "cwd": "${workspaceFolder}",
            "deviceId": "${command:kepler.state.getSelectedDeviceId}",
            "disableAppTimeout": true
        },
        {
            "name": "(script) Launch on Vega Virtual Device",
            "type": "kepler",
            "request": "launch",
            "keplerMode": "debug",
            "cwd": "${workspaceFolder}",
            "deviceId": "KeplerVirtualDevice",
            "disableAppTimeout": true
        }
    ]
}

Hybrid React Native and Turbo Module debugging

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(script) Attach",
            "type": "kepler",
            "request": "attach",
            "cwd": "${workspaceFolder}",
            "deviceId": "${command:kepler.state.getSelectedDeviceId}"
        },
        {
            "name": "(native) Attach",
            "type": "keplerNative",
            "request": "attach",
            "cwd": "${workspaceFolder}",
            "deviceId": "${command:kepler.state.getSelectedDeviceId}",
            "debugger": "gdb"
        }
    ],
    "compounds": [
        {
            "name": "Hybrid Debugger",
            "configurations": ["(native) Attach", "(script) Attach"]
        }
    ]
}

Configuration snippets

Debug your app

Once you've configured your debugger and set up breakpoints, start debugging your app on your chosen target device. The debugging process is similar for both devices, with device selection being the main difference.

Debug on Vega Virtual Device

1. Select Virtual Device from the sidebar.
2. Go to Run and Debug.
3. Select the (script) Launch config from the dropdown.
4. Click the play icon or press F5.

Vega Studio packages, loads, and executes your app on the Vega Virtual Device. When execution hits a breakpoint, VS Code enters debug mode and displays the Debug Toolbar.

Debug on Fire TV Stick

1. Select Fire TV Stick as your target.
2. Go to Run and Debug.
3. Select the (script) Launch config from the dropdown.
4. Click the play icon or press F5.

Vega Studio packages, loads, and executes your app on the Fire TV Stick. When execution hits a breakpoint, VS Code enters debug mode and displays the Debug toolbar.

Debug toolbar actions

The debug toolbar contains actions you can perform during a debugging session.

Troubleshooting

For debugging issues, see Fix Debugging Issues.

Related topics

• Use Chrome DevTools for App Profiling
• Monitor Network Traffic with Charles Proxy

Last updated: Sep 30, 2025