Useful utilities for Electron apps and modules
You can use this module directly in both the main and renderer process.
$ npm install electron-util
Requires Electron 5 or later.
const {is} = require('electron-util');
console.log(is.macos && is.main);
//=> true
api
is
electronVersion
chromeVersion
platform()
activeWindow()
runJS()
fixPathForAsarUnpack()
enforceMacOSAppLocation()
menuBarHeight()
getWindowBoundsCentered()
centerWindow()
disableZoom()
appLaunchTimestamp
isFirstAppLaunch()
darkMode
setContentSecurityPolicy
openNewGitHubIssue()
openUrlMenuItem()
showAboutWindow()
aboutMenuItem()
debugInfo()
appMenu()
openSystemPreferences()
Type: object
Access the Electron APIs in both the main and renderer process without having to care about which one you're in.
For example, in the renderer process:
api.app.quit();
The app
API is usually only available in the main process.
Type: object
Check for various things:
macos
- Running on macOSlinux
- Running on Linuxwindows
- Running on Windowsmain
- Running on the main processrenderer
- Running on the renderer processdevelopment
- Running in development, not in productionusingAsar
- The app is using ASARmacAppStore
- The app is an Mac App Store buildwindowsStore
- The app is a Windows Store AppX build
Type: string
Example: 1.7.9
Electron version.
Type: string
Example: 62.0.3202
Chrome version in Electron.
Type: Function
Accepts an object with the keys as either macos
, windows
, linux
, or default
, and picks the appropriate key depending on the current platform. If no platform key is matched, the default
key is used if it exists. If the value is a function, it will be executed, and the returned value will be used.
init({
enableUnicorn: util.platform({
macos: true,
windows: false,
linux: () => false
})
});
Type: Function
Returns the active window.
Type: Function
Run some JavaScript in the active or given window.
Returns a promise for the result of the executed code or a rejected promise if the result is a rejected promise.
Type: Function
ASAR is great, but it has limitations when it comes to executing binaries. For example, child_process.spawn()
is not automatically handled. So you would have to unpack the binary, for example, with the asarUnpack
option in electron-builder
. This creates a problem as the path to the binary changes, but your path.join(__dirname, 'binary')
is not changed. To make it work you need to fix the path. That's the purpose of this method.
Before:
/Users/sindresorhus/Kap.app/Contents/Resources/app.asar/node_modules/foo/binary
After:
/Users/sindresorhus/Kap.app/Contents/Resources/app.asar.unpack/node_modules/foo/binary
Type: Function
On macOS, for security reasons, if an app is launched outside the Applications folder, it will run in a read-only disk image, which could cause subtle problems for your app. Use this method to ensure the app lives in the Applications folder.
It must not be used until the app.whenReady()
promise is resolved.
It will be a no-op during development and on other systems than macOS.
It will offer to automatically move the app for the user:
Returns the height of the menu bar on macOS, or 0
if not macOS.
Get the bounds of a window as if it was centered on the screen.
Type: object
Type: BrowserWindow
Default: Current window
The window to get the bounds of.
Type: object
Default: Size of window
Set a new window size. Example: {width: 600, height: 400}
Type: object
Type: BrowserWindow
Default: Current window
The window to set the bounds of.
Type: boolean
Default: false
Animate the change.
Center a window on the screen.
Type: object
Type: BrowserWindow
Default: Current window
The window to center.
Type: object
Default: Size of window
Set a new window size. Example: {width: 600, height: 400}
Type: boolean
Default: false
Animate the change.
Disable zooming, usually caused by pinching the trackpad on macOS or Ctrl + on Windows.
Type: BrowserWindow
Default: Current window
Type: number
A timestamp (Date.now()
) of when your app launched.
Returns a boolean
of whether it's the first time your app is launched.
It works by writing a file to app.getPath('userData')
if it doesn't exist and checks that. That means it will return true the first time you add this check to your app.
Requires Electron 7
Type: object
const {darkMode} = require('electron-util');
console.log(darkMode.isEnabled);
//=> false
darkMode.onChange(() => {
console.log(darkMode.isEnabled);
//=> true
});
Type: boolean
Whether the macOS dark mode is enabled.
On Windows and Linux, it's false
.
The callback
function is called when the macOS dark mode is toggled.
Returns a function, that when called, unsubscribes the listener.
Calling it on Window and Linux works, but it just returns a no-op function.
Set a Content Security Policy for your app.
Don't forget to validate the policy after changes.
const {setContentSecurityPolicy} = require('electron-util');
setContentSecurityPolicy(`
default-src 'none';
script-src 'self';
img-src 'self' data:;
style-src 'self';
font-src 'self';
connect-src 'self' https://api.example.com;
base-uri 'none';
form-action 'none';
frame-ancestors 'none';
`);
Type: string
You can put rules on separate lines, but lines must end in a semicolon.
Type: object
Type: Session
Default: electron.session.defaultSession
The session to apply the policy to.
Opens the new issue view on the given GitHub repo in the browser. Optionally, with some fields like title and body prefilled. The options are passed to the new-github-issue-url
package.
const {openNewGitHubIssue} = require('electron-util');
openNewGitHubIssue({
user: 'sindresorhus',
repo: 'playground',
body: 'Hello'
});
Accepts the same options as new MenuItem()
in addition to a url
option.
If you specify the click
option, its handler will be called before the URL is opened.
Returns a MenuItemConstructorOptions
that creates a menu item, which opens the given URL in the browser when clicked.
const {Menu} = require('electron');
const {openUrlMenuItem} = require('electron-util');
const menu = Menu.buildFromTemplate([
{
label: 'Help',
submenu: [
openUrlMenuItem({
label: 'Website',
url: 'https://sindresorhus.com'
})
]
}
]);
Menu.setApplicationMenu(menu);
Shows an 'About' window. On macOS and Linux, the native 'About' window is shown, and on Windows, a simple custom dialog is shown.
On macOS, the icon
, text
, title
, and website
options are ignored. For icon
, it already defaults to the app icon. For title
, you don't need it as the native about window doesn't have a title.
On Linux, the text
option is ignored.
It will show Electron
as the app name until you build your app for production.
const {showAboutWindow} = require('electron-util');
showAboutWindow({
icon: path.join(__dirname, 'static/Icon.png'),
copyright: 'Copyright © Sindre Sorhus',
text: 'Some more info.'
});
Type: object
Type: string
An absolute path to the app icon.
Type: string
The copyright text.
Type: string
The URL to the app's website.
Type: string
Some additional text if needed.
Type: string
Default: About
Customizable for localization. Used in the menu item label and window title (Windows-only).
The app name is automatically appended at runtime.
Accepts the same options as .showAboutWindow()
.
Returns a MenuItemConstructorOptions
that creates a menu item, which shows the about dialog when clicked.
const {Menu} = require('electron');
const {aboutMenuItem} = require('electron-util');
const menu = Menu.buildFromTemplate([
{
label: 'Help',
submenu: [
aboutMenuItem({
icon: path.join(__dirname, 'static/Icon.png'),
copyright: 'Copyright © Sindre Sorhus',
text: 'Some more info.'
})
]
}
]);
Menu.setApplicationMenu(menu);
Returns a string with debug info suitable for inclusion in bug reports.
For example, use this in the body
option of the .openNewGitHubIssue()
method.
const {debugInfo} = require('electron-util');
console.log(debugInfo());
/*
AppName 2.21.0
Electron 3.0.6
darwin 18.2.0
Locale: en-US
*/
Creating the app menu (the first menu) on macOS requires a lot of boilerplate. This method includes the default boilerplate and lets you add additional menu items in the correct place.
Type: MenuItem[]
Menu items to add below the About App Name
menu item.
Usually, you would add at least a Preferences…
menu item:
const {Menu} = require('electron');
const {appMenu} = require('electron-util');
const menu = Menu.buildFromTemplate([
appMenu([
{
label: 'Preferences…',
accelerator: 'Command+,',
click() {}
}
])
]);
Menu.setApplicationMenu(menu);
Type: Function
Open the System Preferences on macOS.
This method does nothing on other systems.
Optionally provide a pane and section. A list of available options can be found here.
Type: string
Which pane of the System Preferences to open.
const {openSystemPreferences} = require('electron-util');
openSystemPreferences('security');
Type: string
Optional section within the pane.
const {openSystemPreferences} = require('electron-util');
openSystemPreferences('security', 'Firewall');
This is for non-Electron code that might be included in an Electron app. For example, if you want to add special support for Electron in a vanilla Node.js module.
const electronUtil = require('electron-util/node');
if (electronUtil.isElectron) {
// Electron workaround
} else {
// Normal code
}
Type: boolean
Check if you're running in an Electron app.
Type: string
Example: 1.7.9
Electron version. Returns 0.0.0
when not in an Electron app.
Type: boolean
Check if the Electron app you're running in is using ASAR.
Same as the above Electron version.
- electron-store - Save and load data like user preferences, app state, cache, etc
- electron-debug - Adds useful debug features to your Electron app
- electron-context-menu - Context menu for your Electron app
- electron-dl - Simplified file downloads for your Electron app
- electron-unhandled - Catch unhandled errors and promise rejections in your Electron app