ELECTRON_DEFAULT_ERROR_MODE on Windows
ELECTRON_DEFAULT_ERROR_MODE shows the Windows's crash dialog when Electron crashes. This environment variable will not work if the crashReporter is started.
app/runtime
95 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
ELECTRON_OVERRIDE_DIST_PATH environment variable
When running from the electron package, ELECTRON_OVERRIDE_DIST_PATH tells the electron command to use the specified build of Electron instead of the one downloaded by npm install. Example: export ELECTRON_OVERRIDE_DIST_PATH=/Users/username/projects/electron/out/Testing
ELECTRON_INSTALL_PLATFORM environment variable
ELECTRON_INSTALL_PLATFORM manually overrides the platform used by the electron package during an install. This is useful if you are on one platform but want to download binaries for another platform. Example: ELECTRON_INSTALL_PLATFORM=darwin npm install
ELECTRON_INSTALL_ARCH environment variable
ELECTRON_INSTALL_ARCH manually overrides the architecture used by the electron package during an install. This is useful if you are on one arch but want to download binaries for another arch. Note that this will not work under Rosetta. Example: ELECTRON_INSTALL_ARCH=arm64 npm install
netLog methods available after app ready event
All netLog methods can only be used after the 'ready' event of the app module gets emitted, unless otherwise specified.
netLog command-line switch
The --log-net-log command-line switch can be used to log network events throughout the app's lifecycle.
powerSaveBlocker precedence behavior
When multiple power save blockers are active with different types, prevent-display-sleep has higher precedence over prevent-app-suspension. Only the highest precedence type takes effect. For example, if blocker A requests prevent-app-suspension and blocker B requests prevent-display-sleep, prevent-display-sleep will be used until B stops its request, after which prevent-app-suspension is used.
--inspect-brk command line switch pauses on first line
The --inspect-brk=[port] switch is like --inspect but pauses execution on the first line of JavaScript, allowing you to debug from the start.
DevTools cannot debug main process JavaScript
The DevTools in an Electron browser window can only debug JavaScript executed in that window (web pages). To debug JavaScript in the main process, you must use an external debugger.
--inspect command line switch for main process debugging
Use the --inspect=[port] command line switch to enable debugging of the main process. Electron listens for V8 inspector protocol messages on the specified port. The default port is 9229. Example: electron --inspect=9229 your/app
Chrome DevTools can debug Electron main process
Chrome can be used to debug the Electron main process by visiting chrome://inspect and selecting the launched Electron app present there.
V8 inspector protocol required for external debuggers
An external debugger used for main process debugging must support the V8 inspector protocol.
Alternative graphical debugging on macOS
Xcode can be used as a graphical interface for debugging Electron instead of using LLDB from the command line.
macOS debugging requirements
To debug Electron on macOS, you need: a testing build of Electron (ideally built from source to avoid compiler optimizations that obscure debugging), Xcode with command line tools installed, and an ~/.lldbinit configuration file.
LLDB source mapping setup
Create or edit ~/.lldbinit with the following content to enable proper source mapping for Chromium code: script sys.path[:0] = ['<path/to/electron/src/tools/lldb>'] followed by script import lldbinit. Replace the path placeholder with the actual path to your electron source tools/lldb directory.
Why downloaded Electron builds are harder to debug
Downloaded Electron builds are heavily optimized, making debugging substantially more difficult. The debugger cannot show the content of all variables and the execution path appears strange due to compiler optimizations like inlining and tail calls. Building from source produces a testing build that is easier to debug.
Attaching LLDB to Electron
Start LLDB by running 'lldb ./out/Testing/Electron.app' from the terminal, passing the path to the non-release build of Electron. LLDB will set the current executable and you can then set breakpoints and run the debugger.
Setting breakpoints in LLDB
Use the breakpoint command to set breakpoints at specific source locations. Example: 'breakpoint set --file browser.cc --line 117' sets a breakpoint at line 117 in browser.cc. Electron source files are located in ./shell/.
Inspecting variables during LLDB debugging
Use the 'frame variable' command (or 'fr v' shorthand) to show the arguments and local variables for the current frame during debugging.
LLDB stepping commands
Use 'step' (or 's') to do a source level single step in the currently selected thread, stepping into function calls. Use 'next' (or 'n') to step over function calls without entering them.
LLDB process control commands
Use 'process continue' to resume execution after hitting a breakpoint. Use 'thread until 100' to continue execution until a specific line (100 in this example) is reached in the current thread, or until the current frame is left.
Missing source code in LLDB debugger
If source code is not displayed during debugging when expected, verify that the ~/.lldbinit configuration file has been created and properly configured for source mapping.
Setting breakpoints in Visual Studio without project file
Electron source code can be opened in Visual Studio as files without a project file. Visual Studio will automatically figure out that the source code matches the code running in the attached process and break at set breakpoints accordingly. Relevant code files are found in ./shell/
ProcMon tool for observing process operations
ProcMon is a free SysInternals tool that allows inspection of a process's parameters, file handles, and registry operations. It captures File, Registry, Network, Process, and Profiling details of processes and attempts to log all events occurring, making it valuable for understanding what and how an application is doing to the operating system.
Visual Studio with C++ Tools required for Windows debugging
Visual Studio with C++ Tools is required for debugging Electron on Windows. The free community editions of Visual Studio 2013 and Visual Studio 2015 both work. After installation, you must configure Visual Studio to use Electron's Symbol server, which enables Visual Studio to better understand what happens inside Electron and present variables in a human-readable format.
Debug build of Electron required for debugging
To debug Electron on Windows, you need a debug build of Electron rather than a downloaded version. Downloaded Electron builds are heavily optimized, making debugging substantially more difficult because the debugger cannot show the content of all variables and the execution path can seem strange due to inlining, tail calls, and other compiler optimizations. The easiest way to obtain a debug build is to build it yourself using the build instructions for Windows.
Viewing all user processes in Visual Studio debugger
When attaching to a process in Visual Studio, if Electron is running under a different user account, you must select the 'Show processes from all users' check box. Depending on the number of BrowserWindows opened, you will see multiple Electron.exe entries - one for the main process and one for each renderer process.
Main process vs renderer process code execution location
Code executed within the main process (code found in or eventually run by the main JavaScript file) runs inside the main process, while other code executes inside its respective renderer process.
Debugging renderer process with WinDbg
It is possible to debug crashes and issues in the renderer process using WinDbg. To use WinDbg for debugging, add --renderer-startup-dialog as a command line flag to Electron, then launch the app and a dialog box will appear with the renderer process ID.
WinDbg renderer debugging procedure
To debug a renderer process with WinDbg: (1) Add --renderer-startup-dialog as a command line flag to Electron, (2) Launch the app, (3) Note the pid from the dialog that appears showing 'Renderer starting with pid: [number]', (4) Launch WinDbg and choose 'File > Attach to process', (5) Enter the pid from the dialog, (6) The debugger will be in a paused state with a command line, (7) Type 'g' into the command line to start the debuggee, (8) Press enter to continue the program, (9) Go back to the dialog box and press 'ok'.
Attaching Visual Studio debugger to running process
To attach the Visual Studio debugger to a running process, click Debug / Attach to Process or press CTRL+ALT+P to open the Attach to Process dialog box. This capability allows debugging apps running on local or remote computers and debugging multiple processes simultaneously.
Starting Electron debug build from PowerShell/CMD
To start a debugging session, open PowerShell or CMD and execute your debug build of Electron with the application path as a parameter. The command format is: ./out/Testing/electron.exe ~/my-electron-app/
Debugger attachment timing in Electron renderer
Because the debugger attaches to the renderer process after it starts, the first lines of code may be skipped as the debugger won't have time to connect before they execute. Work around this by refreshing the page or setting a timeout before executing code in development mode.
Process platform detection
Use Node's process.platform variable to run code conditionally on certain platforms. There are only three possible platforms that Electron can run in: 'win32' (Windows), 'linux' (Linux), and 'darwin' (macOS).
VS Code debugging configuration for Electron
To debug an Electron application in VS Code, attach VS Code to both the main and renderer processes. Create a .vscode/launch.json file with configurations for 'Main' (type: node), 'Renderer' (type: chrome, request: attach), and a compound configuration 'Main + renderer' that runs both simultaneously. The main process should expose port 9222 for remote debugging using --remote-debugging-port=9222.