• Stars
    star
    1,188
  • Rank 37,497 (Top 0.8 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created almost 7 years ago
  • Updated 11 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Useful utilities for Electron apps and modules

electron-util

Useful utilities for Electron apps and modules

You can use this module directly in both the main and renderer process.

This package is not compatible with Electron v12 and later.

Install

$ npm install electron-util

Requires Electron 5 or later.

Usage

const {is} = require('electron-util');

console.log(is.macos && is.main);
//=> true

API

Contents

api

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.

is

Type: object

Check for various things:

  • macos - Running on macOS
  • linux - Running on Linux
  • windows - Running on Windows
  • main - Running on the main process
  • renderer - Running on the renderer process
  • development - Running in development, not in production
  • usingAsar - The app is using ASAR
  • macAppStore - The app is an Mac App Store build
  • windowsStore - The app is a Windows Store AppX build

electronVersion

Type: string
Example: '1.7.9'

Electron version.

chromeVersion

Type: string
Example: '62.0.3202'

Chrome version in Electron.

platform(choices)

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
	})
});

activeWindow()

Type: Function

Returns the active window.

runJS(code, 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.

fixPathForAsarUnpack(path)

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.unpacked/node_modules/foo/binary

enforceMacOSAppLocation() macOS

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:

menuBarHeight() macOS

Returns the height of the menu bar on macOS, or 0 if not macOS.

getWindowBoundsCentered(options?)

Get the bounds of a window as if it was centered on the screen.

options

Type: object

window

Type: BrowserWindow
Default: Current window

The window to get the bounds of.

size

Type: object
Default: Size of window

Set a new window size. Example: {width: 600, height: 400}

useFullBounds

Type: boolean
Default: false

Use the full display size when calculating the position. By default, only the workable screen area is used, which excludes the Windows taskbar and macOS dock.

centerWindow(options?)

Center a window on the screen.

options

Type: object

window

Type: BrowserWindow
Default: Current window

The window to center.

size

Type: object
Default: Size of window

Set a new window size. Example: {width: 600, height: 400}

animated

Type: boolean
Default: false

Animate the change.

useFullBounds

Type: boolean
Default: false

Use the full display size when calculating the position. By default, only the workable screen area is used, which excludes the Windows taskbar and macOS dock.

disableZoom(window?)

Disable zooming, usually caused by pinching the trackpad on macOS or Ctrl+ on Windows.

window

Type: BrowserWindow
Default: Current window

appLaunchTimestamp

Type: number

A timestamp (Date.now()) of when your app launched.

isFirstAppLaunch()

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.

darkMode

Requires Electron 7

Type: object

const {darkMode} = require('electron-util');

console.log(darkMode.isEnabled);
//=> false

darkMode.onChange(() => {
	console.log(darkMode.isEnabled);
	//=> true
});

isEnabled

Type: boolean

Whether the macOS dark mode is enabled.

On Windows and Linux, it's false.

onChange(callback)

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.

setContentSecurityPolicy(policy, options?)

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';
`);

policy

Type: string

You can put rules on separate lines, but lines must end in a semicolon.

options

Type: object

session

Type: Session
Default: electron.session.defaultSession

The session to apply the policy to.

openNewGitHubIssue(options)

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'
});

openUrlMenuItem(options)

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);

showAboutWindow(options)

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.

The about window on Ubuntu

const {showAboutWindow} = require('electron-util');

showAboutWindow({
	icon: path.join(__dirname, 'static/Icon.png'),
	copyright: 'Copyright © Sindre Sorhus',
	text: 'Some more info.'
});

options

Type: object

icon Linux Windows

Type: string

An absolute path to the app icon.

copyright

Type: string

The copyright text.

text

Type: string

Some additional text if needed. Shown below copyright info.

website Linux

Type: string

The URL to the app's website.

title Linux Windows

Type: string
Default: 'About'

Customizable for localization. Used in the menu item label.

The app name is automatically appended at runtime.

aboutMenuItem(options) Linux Windows

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);

debugInfo()

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
*/

appMenu(menuItems?) macOS

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.

menuItems

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);

openSystemPreferences(pane?, section?): Promise macOS Windows

Type: Function

Open the System Preferences on macOS and Windows 10.

This method does nothing on Linux.

A list of available options can be found here.

On macOS, optionally provide a pane and section.

pane

Type: string

Which pane of the System Preferences to open.

const {openSystemPreferences} = require('electron-util');

openSystemPreferences('security');

section macOS

Type: string

Optional section within the pane.

const {openSystemPreferences} = require('electron-util');

openSystemPreferences('security', 'Firewall');

Node.js API

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
}

isElectron

Type: boolean

Check if you're running in an Electron app.

electronVersion

Type: string
Example: '1.7.9'

Electron version. Returns 0.0.0 when not in an Electron app.

isUsingAsar

Type: boolean

Check if the Electron app you're running in is using ASAR.

fixPathForAsarUnpack(path)

Same as the above Electron version.

Related

More Repositories

1

awesome

😎 Awesome lists about all kinds of interesting topics
270,042
star
2

awesome-nodejs

⚡ Delightful Node.js packages and resources
52,854
star
3

awesome-electron

Useful resources for creating apps with Electron
25,164
star
4

quick-look-plugins

List of useful Quick Look plugins for developers
17,497
star
5

got

🌐 Human-friendly and powerful HTTP request library for Node.js
TypeScript
13,714
star
6

type-fest

A collection of essential TypeScript types
TypeScript
12,930
star
7

pure

Pretty, minimal and fast ZSH prompt
Shell
12,391
star
8

ky

🌳 Tiny & elegant JavaScript HTTP client based on the browser Fetch API
TypeScript
11,367
star
9

pageres

Capture website screenshots
TypeScript
9,573
star
10

ora

Elegant terminal spinner
JavaScript
8,591
star
11

github-markdown-css

The minimal amount of CSS to replicate the GitHub Markdown style
CSS
7,421
star
12

np

A better `npm publish`
JavaScript
7,395
star
13

screenfull

Simple wrapper for cross-browser usage of the JavaScript Fullscreen API
HTML
6,891
star
14

caprine

Elegant Facebook Messenger desktop app
TypeScript
6,816
star
15

Gifski

🌈 Convert videos to high-quality GIFs on your Mac
Swift
6,807
star
16

fkill-cli

Fabulously kill processes. Cross-platform.
JavaScript
6,782
star
17

query-string

Parse and stringify URL query strings
JavaScript
6,453
star
18

execa

Process execution for humans
JavaScript
6,019
star
19

modern-normalize

🐒 Normalize browsers' default style
TypeScript
5,038
star
20

css-in-readme-like-wat

Style your readme using CSS with this simple trick
5,013
star
21

awesome-npm

Awesome npm resources and tips
4,315
star
22

promise-fun

Promise packages, patterns, chat, and tutorials
4,277
star
23

electron-store

Simple data persistence for your Electron app or module - Save and load user preferences, app state, cache, etc
JavaScript
4,165
star
24

awesome-scifi

Sci-Fi worth consuming
4,057
star
25

create-dmg

Create a good-looking DMG for your macOS app in seconds
JavaScript
3,950
star
26

speed-test

Test your internet connection speed and ping using speedtest.net from the CLI
JavaScript
3,882
star
27

ow

Function argument validation for humans
TypeScript
3,779
star
28

eslint-plugin-unicorn

More than 100 powerful ESLint rules
JavaScript
3,765
star
29

file-type

Detect the file type of a Buffer/Uint8Array/ArrayBuffer
JavaScript
3,438
star
30

meow

🐈 CLI app helper
JavaScript
3,305
star
31

p-queue

Promise queue with concurrency control
TypeScript
3,202
star
32

open

Open stuff like URLs, files, executables. Cross-platform.
JavaScript
2,976
star
33

Plash

💦 Make any website your Mac desktop wallpaper
Swift
2,735
star
34

alfy

Create Alfred workflows with ease
JavaScript
2,570
star
35

trash

Move files and directories to the trash
JavaScript
2,512
star
36

fast-cli

Test your download and upload speed using fast.com
JavaScript
2,484
star
37

guides

A collection of succinct guides - Public Domain
2,424
star
38

globby

User-friendly glob matching
JavaScript
2,376
star
39

slugify

Slugify a string
JavaScript
2,357
star
40

emoj

Find relevant emoji from text on the command-line 😮 ✨ 🙌 🐴 💥 🙈
JavaScript
2,311
star
41

cli-spinners

Spinners for use in the terminal
JavaScript
2,255
star
42

on-change

Watch an object or array for changes
JavaScript
1,946
star
43

devtools-detect

Detect if DevTools is open and its orientation
HTML
1,924
star
44

touch-bar-simulator

Use the Touch Bar on any Mac
Swift
1,892
star
45

gulp-imagemin

Minify PNG, JPEG, GIF and SVG images
JavaScript
1,888
star
46

notifier-for-github

Browser extension - Get notified about new GitHub notifications
JavaScript
1,760
star
47

editorconfig-sublime

Sublime Text plugin for EditorConfig - Helps developers maintain consistent coding styles between different editors
Python
1,757
star
48

capture-website

Capture screenshots of websites
JavaScript
1,670
star
49

emittery

Simple and modern async event emitter
JavaScript
1,664
star
50

Defaults

💾 Swifty and modern UserDefaults
Swift
1,661
star
51

electron-boilerplate

Boilerplate to kickstart creating an app with Electron
JavaScript
1,632
star
52

pageres-cli

Capture website screenshots
JavaScript
1,620
star
53

is

Type check values
TypeScript
1,605
star
54

clipboardy

Access the system clipboard (copy/paste)
JavaScript
1,598
star
55

gulp-rev

Static asset revisioning by appending content hash to filenames: `unicorn.css` → `unicorn-d41d8cd98f.css`
JavaScript
1,538
star
56

pify

Promisify a callback-style function
JavaScript
1,494
star
57

boxen

Create boxes in the terminal
JavaScript
1,458
star
58

Actions

⚙️ Supercharge your shortcuts
Swift
1,437
star
59

multiline

Multiline strings in JavaScript
JavaScript
1,424
star
60

hyper-snazzy

Elegant Hyper theme with bright colors
JavaScript
1,412
star
61

amas

Awesome & Marvelous Amas
1,392
star
62

LaunchAtLogin

Add “Launch at Login” functionality to your macOS app in seconds
Swift
1,346
star
63

refined-twitter

Browser extension that simplifies the Twitter interface and adds useful features
JavaScript
1,313
star
64

KeyboardShortcuts

⌨️ Add user-customizable global keyboard shortcuts (hotkeys) to your macOS app in minutes
Swift
1,313
star
65

iterm2-snazzy

Elegant iTerm2 theme with bright colors
1,313
star
66

del

Delete files and directories
JavaScript
1,305
star
67

electron-context-menu

Context menu for your Electron app
JavaScript
1,297
star
68

p-limit

Run multiple promise-returning & async functions with limited concurrency
JavaScript
1,294
star
69

Settings

⚙ Add a settings window to your macOS app in minutes
Swift
1,282
star
70

trash-cli

Move files and folders to the trash
JavaScript
1,244
star
71

is-online

Check if the internet connection is up
JavaScript
1,181
star
72

ponyfill

🦄 Like polyfill but with pony pureness
1,136
star
73

conf

Simple config handling for your app or module
TypeScript
1,109
star
74

anatine

[DEPRECATED] 🐦 Pristine Twitter app
JavaScript
1,097
star
75

electron-dl

Simplified file downloads for your Electron app
JavaScript
1,087
star
76

log-update

Log by overwriting the previous output in the terminal. Useful for rendering progress bars, animations, etc.
JavaScript
1,027
star
77

pretty-bytes

Convert bytes to a human readable string: 1337 → 1.34 kB
JavaScript
1,022
star
78

grunt-sass

Compile Sass to CSS
JavaScript
1,020
star
79

mem

Memoize functions - an optimization technique used to speed up consecutive function calls by caching the result of calls with identical input
TypeScript
1,019
star
80

DockProgress

Show progress in your app's Dock icon
Swift
1,003
star
81

wallpaper

Manage the desktop wallpaper
JavaScript
996
star
82

p-map

Map over promises concurrently
JavaScript
996
star
83

public-ip

Get your public IP address - very fast!
JavaScript
979
star
84

gulp-app

[DEPRECATED] Gulp as an app
JavaScript
961
star
85

grunt-shell

Run shell commands
JavaScript
952
star
86

load-grunt-tasks

Load multiple grunt tasks using globbing patterns
JavaScript
940
star
87

hasha

Hashing made simple. Get the hash of a buffer/string/stream/file.
JavaScript
934
star
88

pretty-ms

Convert milliseconds to a human readable string: `1337000000` → `15d 11h 23m 20s`
JavaScript
929
star
89

terminal-image

Display images in the terminal
JavaScript
923
star
90

object-assign

ES2015 Object.assign() ponyfill
JavaScript
919
star
91

copy-text-to-clipboard

Copy text to the clipboard in modern browsers (0.2 kB)
JavaScript
858
star
92

System-Color-Picker

🎨 The macOS color picker as an app with more features
Swift
842
star
93

get-port

Get an available TCP port
JavaScript
817
star
94

atom-editorconfig

Helps developers maintain consistent coding styles between different editors
JavaScript
815
star
95

normalize-url

Normalize a URL
JavaScript
807
star
96

grunt-concurrent

Run grunt tasks concurrently
JavaScript
799
star
97

dot-prop

Get, set, or delete a property from a nested object using a dot path
JavaScript
777
star
98

p-progress

Create a promise that reports progress
TypeScript
751
star
99

gulp-changed

Only pass through changed files
JavaScript
747
star
100

generator-nm

Scaffold out a node module
JavaScript
742
star