Electron - Debugging

Electron - Debugging Your Application

Electron applications consist of at least two types of processes: the main process and one or more renderer processes. Debugging techniques differ slightly for each.

Debugging Renderer Processes

Renderer processes are essentially web pages running in an Electron BrowserWindow. Therefore, you can use the familiar Chrome DevTools for debugging their JavaScript, inspecting the DOM, analyzing network requests, and more.

To open DevTools for a specific BrowserWindow:

• Programmatically: Call win.webContents.openDevTools() in the main process (where win is your BrowserWindow instance).
• Manually: When the window has focus, press Ctrl+Shift+I (on Windows/Linux) or Cmd+Option+I (on macOS). The F12 key may also work.

Once DevTools is open, it will be attached to that renderer process. You can use the ‘Sources’ tab to set breakpoints, ‘Console’ to view logs and execute commands, etc. For more on using Chrome DevTools, refer to the official Chrome DevTools documentation.

When DevTools is opened, your application window will typically split to show the DevTools panel, or DevTools might open in a separate window depending on its settings.

Debugging the Main Process

The main process runs Node.js and doesn’t have a visible window with DevTools attached by default. To debug the main process, you need to use a Node.js debugger.

Using Chrome DevTools for Main Process

You can instruct Electron to listen for a debugger on a specific port using command-line switches:

• --inspect=[port]: Enables the inspector agent and listens on the specified port (default is 9229). The script will start execution immediately.
• --inspect-brk=[port]: Similar to --inspect, but execution will pause on the first line of code, allowing you to set breakpoints before anything runs.

Example: To start your app with the debugger listening on port 9229 and breaking at the start:

$ electron --inspect-brk=9229 .

Then, open Google Chrome and navigate to chrome://inspect. Click on “Configure…” next to “Discover network targets” and ensure localhost:<port> (e.g., localhost:9229) is listed. Your Electron application should appear as a remote target. Click “inspect” under your application’s target to open a dedicated DevTools window for the main process.

Using Visual Studio Code (VS Code)

VS Code has excellent built-in support for debugging Node.js applications, including Electron’s main process. You’ll need to configure a launch.json file in your project’s .vscode directory.

Create or open .vscode/launch.json and add a configuration like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "type": "pwa-node", // Or "node"
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      // On Windows, use this path for runtimeExecutable if installed locally:
      // "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}\\node_modules\\.bin\\electron.cmd"
      },
      // Pass the main script (e.g., main.js or your project root) as an argument
      // If your package.json's "main" field points to your entry script,
      // you can often use "." to tell Electron to load the current directory.
      "args": ["."],
      // Alternatively, if your main script is always main.js:
      // "program": "${workspaceFolder}/main.js",
      "outputCapture": "std"
    }
  ]
}

Notes on the configuration:

• type: pwa-node is the modern debugger type, node can also work.
• runtimeExecutable: Points to the Electron executable within your project’s node_modules. Adjust if Electron is installed globally (though local install is recommended).
• args: ["."] tells Electron to start the app in the current working directory (cwd), respecting the main field in your package.json. If your entry script is named something else and not specified in package.json, you can use "program": "${workspaceFolder}/your-main-script.js" instead of args.
• outputCapture: Shows console.log from the main process in VS Code’s Debug Console.

After setting up launch.json, go to the ‘Run and Debug’ view in VS Code (usually a play button icon with a bug), select “Debug Main Process” from the dropdown, and click the green play button or press F5. You can now set breakpoints in your main.js (or other main process scripts), step through code, inspect variables, and use the Debug Console.

When a breakpoint is hit in main.js using VS Code, the editor will highlight the line, and you’ll see call stacks, variables, and watch expressions in the debug panel, providing a powerful environment to identify and resolve issues in your main process logic.