electron-debug: keyboard shortcuts for DevTools in Electron apps

Three shortcuts, three different jobs

The package does one thing, and the README describes it as adding useful debug features to an Electron app. Concretely it installs three keyboard shortcuts. DevTools toggles with Cmd Alt I on macOS, Ctrl Shift I on Linux and Windows, or F12 anywhere. Reload force reloads the window with Cmd R on macOS, Ctrl R on Linux and Windows, or F5. The element inspector opens DevTools and focuses the Element Inspector tool, with Cmd Shift C on macOS and Ctrl Shift C on Linux and Windows. That last one is the most useful of the three in practice, since clicking an element in a running app and having the inspector land on it saves a lot of hunting through the DOM tree. The set is deliberately small. There is no logging framework here, no state inspection panel and no profiler, which is what keeps the dependency list down to a single runtime package.

The shortcuts stop working once DevTools has focus

The README has a section titled Known limitations, and it contains one entry, which is worth reading before anything else. The shortcuts only work while the app window has focus, because Electron does not deliver keyboard input to the DevTools web contents, so there is no way to detect the shortcut while DevTools itself has focus. The advice given is to click the app window first, then use the shortcut. This is an Electron limitation rather than a choice made by the package, and the package cannot work around it. The practical effect is that a developer who has DevTools open and then wants to reload has to click back into the app window first, and a developer working mostly inside DevTools will find these shortcuts almost useless, which is an important caveat for a package aimed at people who spend a lot of time in DevTools.

debug() attaches to windows that already exist

The main entry point is a function called debug that takes an optional options object. Its documented behaviour is specific: install the keyboard shortcuts and optionally activate DevTools on each BrowserWindow, including the ones that already exist when the call is made. That last clause is the part that makes the call order forgiving. A typical Electron main process creates its window inside an async whenReady handler, and a naive debug helper registered too early would never see that window. Because the call also picks up existing windows, you can place it before or after the window is created without rearranging your startup code. The showDevTools option defaults to true, so DevTools opens on every window by default, and the devToolsMode option decides where it docks, accepting the values undocked, left, right, bottom, previous and detach, with previous as the default.

Development-only by default, but the switch is per window

The API section states that the package only runs in development, unless the isEnabled option overrides that, and adds that there is no need to guard it for production. The development check comes from the electron-is-dev package, which is the single runtime dependency. Two details are easy to miss here. First, the default is a boolean option, so a developer who wants debug shortcuts in a packaged build for a bug report from a user can set isEnabled to true explicitly. Second, the filtering happens per window through the windowSelector option, a function that receives the window and must return one of three things: true to enable debug for that window with the global options, false to disable debug for that window, or a partial options object that overrides the global options for that window through a shallow merge. A partial object can therefore turn DevTools off for a specific window while keeping the shortcuts.

Three separate functions for one-off control

Beyond the setup call, the package exports three imperative functions that operate on a window or on the focused one. devTools toggles DevTools, refresh reloads the window, and openDevTools opens it. Each accepts an optional BrowserWindow argument and defaults to the focused window. These are for wiring your own menu items or IPC handlers to the same behaviours the shortcuts trigger, and they are the part of the API that a more complete debug menu would be built on. The design is coherent in that the shortcuts and the functions are the same mechanism reached two ways, and it leaves the door open for a project to expose, say, a reload command in an application menu without reimplementing anything. The README does not describe the return values of these functions, so a caller that depends on a returned value would be going beyond what the documentation supports.

Installation is one npm command and a strict version floor

The install step is a single command, and it requires Electron 44 or later:

npm install electron-debug

The usage example shows the whole integration, calling debug before the window is created:

import {app, BrowserWindow} from 'electron';
import debug from 'electron-debug';

debug();

let mainWindow;
(async () => {
	await app.whenReady();
	mainWindow = new BrowserWindow();
})();

The package is an ES module, with type set to module and an exports map pointing at index.js with types from index.d.ts. Node 22 or later is the stated engine requirement, and the development dependency list pins Electron at 44.4.3. The version floor is the part of adoption that deserves a check, since a project on an older Electron cannot install the current release at all, and the jump from v4.1.0 to v5.0.0 is where the requirement moved.

A different job from a reloader or a logging utility

The README lists sibling projects that solve adjacent problems, and two of them make the difference clear. electron-reloader is a simple auto-reloading utility for Electron apps during development, which is a different thing from what this package does: electron-debug gives you a manual force reload and manual DevTools control, not a file watcher that rebuilds the page. electron-unhandled catches unhandled errors and promise rejections, and electron-util is a general collection of development utilities. The approach difference is worth naming precisely. A reloader reacts to your filesystem, while electron-debug reacts to you. For a project that wants a stable build and an explicit way to reproduce a bug on a user's machine, the manual approach is the point, and a watcher-based workflow would not give that. What this package does not offer is any visibility into application state, so it complements a logging or unhandled-rejection handler rather than replacing one.

v5.0.0 landed after a two year gap

The release record is short and shows a clear break. The current version is v5.0.0, published on 2026-09-20, and the last push to the repository is also on 2026-09-20. Before that, the previous release was v4.1.0 from 2024-10-14, with v4.0.1 from 2024-08-12 before it. A major version bump after roughly two years is a signal that something in the public surface changed, and the current README documents the requirements that a v4 user would not have had to meet, namely Node 22 and Electron 44. The licence is MIT, which means the code can be reused and modified with attribution and no warranty attached, and the package publishes only two files, index.js and index.d.ts. The repository also ships fixtures for devtools mode, shortcut matching, toggle behaviour and the window selector, plus a test script that runs xo and the node test runner.

Editorial conclusion

electron-debug is a good fit for an Electron application that ships to users and still needs a usable debug path in a production build, since it attaches to every window and the isEnabled option is the only switch required. It is the wrong tool for a project that already has a debug menu or an app that never leaves development, and it cannot help with a shortcut pressed while DevTools itself holds focus, because Electron does not deliver keyboard input to the DevTools web contents. Before adopting version 5, check that your app runs on Node 22 or later and on Electron 44 or later, both stated as requirements, and confirm that the windowSelector function returns what you intend for each window. The last push was on 2026-09-20 and the current release is v5.0.0 from the same day, with v4.1.0 dating from 2024-10-14.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sindresorhus/electron-debug on GitHub