@rubenverg/electron-util

@rubenverg/electron-util

An electron-util port for modern Electron.

Switching from electron-util

Since I renamed some functions to be clearer, you can use @rubenverg/electron-util/compat instead. All APIs have exactly the same name there and work exactly the same (except for darkMode which has other features)

Using in renderer

Assuming nodeIntegration is off (as it should be), you can expose the utils via the preload script. You might also want to use @rubenverg/electron-util/safe that removes the api exposure that allows access to all main functions from the renderer. Note that this depends on electron.remote, which is deprecated. I'll try switching to ipc messages.

API

This is the API documentation for @rubenverg/electron-util. safe has the same API except for the lack of api, and compat uses the electron-util naming scheme.

about

function about(options: {
  icon?: string,
  copyright?: string,
  website?: string,
  text?: string,
  title?: string
}): void

Shows an about window for the app. Note that not all options are used for all platforms, see electron-util for more detail.

aboutMenuItem

function aboutMenuItem(options: {
  icon?: string,
  copyright?: string,
  website?: string,
  text?: string,
  title?: string
}): electron.MenuItem

Returns a MenuItem named ${title || 'About'} ${appName} that calls about(options) on click.

activeWindow

function activeWindow(): electron.BrowserWindow | null

Returns the currently focused window.

activeWindowOrFirst

function activeWindowOrFirst(): electron.BrowserWindow | null

Returns the currently focused window, or the first one (in BrowserWindow.getAllWindows) if none is focused.

api

Access to the electron api, whether from main or renderer. Uses electron.remote if in a renderer process. Currently not available outside compat, as it's deprecated and doesn't really work.

centerWindow

function centerWindow(options: {
  window?: electron.BrowserWindow,
  size?: electron.Size,
  useFullBounds?: boolean,
  animated?: boolean
})

Centers the current window.

chromeVersion

const chromeVersion: string

Chromium version

nativeTheme

nativeTheme.isEnabled

const isEnabled: boolean

Is the app in dark mode? (Only available for compatibility, deprecated in favor of nativeTheme.dark)

nativeTheme.dark

const dark: boolean

Is the app in dark mode?

nativeTheme.highContrast

const highContrast: boolean

Is the app in high contrast mode?

nativeTheme.inverted

const inverted: boolean

Is the app in inverted colors mode?

onChange

function onChange(callback: () => unknown): (() =>  void)

Call callback on native theme change. Returns a function that can be called to remove the callback.

debugInfo

Returns some info useful for debugging.

disableZoom

function disableZoom(window: electron.BrowserWindow = activeWindow): void

Disables zooming window.

electronVersion

const electronVersion: string

Electron version

fixPathAsar

function fixPathAsar(path: string): string

Fixes the path to point to the unpacked Asar if an Asar packed app.

getWindowBoundsCentered

function getWindowBoundsCentered(options: {
  window?: electron.BrowserWindow,
  size?: electron.Size,
  useFullBounds?: boolean
})

Gets the bounds of options.window as if it were centered on the screen.

is

is.macos

const macos: boolean

Is the current OS macOS?

is.linux

const linux: boolean

Is the current OS Linux?

is.windows

const windows: boolean

Is the current OS Windows?

is.main

const main: boolean

Is this a main process?

is.renderer

const renderer: boolean

Is this a renderer process?

is.macAppStore

const macAppStore: boolean

Is this a Mac App Store app?

is.windowsStore

const windowsStore: boolean

Is this a Windows Store app?

is.usingAsar

const usingAsar: boolean

Is this app Asar packaged?

is.development

const development: boolean

Is this Electron app in development mode?

firstLaunch

function firstLaunch(): boolean

Is this the first time the app is ran? (Works by storing a file in app.getPath('userData'), so only counts the first time the function, or the electron-util one, is called)

githubIssue

function githubIssue(options: {
  body?: string,
  title?: string,
  template?: string,
  labels?: string[],
  milestone?: string,
  assignee?: string,
  projects?: string[],

  repoUrl: string,
  // or
  user: string,
  repo: string
}): void;

Opens in the user's browser a page to create a GitHub issue. Refer to new-github-issue-url for option documentation.

urlMenuItem

function urlMenuItem(options: electron.MenuItemConstructorOptions & { url: string }): electron.MenuItem

Returns a MenuItem that, when clicked, takes to options.url in a browser. Takes the same options as new electron.MenuItem, plus a mandatory url.

byPlatform

export function platform<T>(switcher: {
  aix?: T | (() => T),
  android?: T | (() => T),
  macos?: T | (() => T),
  freebsd?: T | (() => T),
  linux?: T | (() => T),
  openbsd?: T | (() => T),
  sunos?: T | (() => T),
  windows?: T | (() => T),
  cygwin?: T | (() => T),
  netbsd?: T | (() => T),
  default?: T | (() => T)
}): T

Returns a T by process.platform (windows instead of win32 and macos instead of darwin). Alternatively takes a function to the same type, if you do need a function to be returned use () => (yourFunction)

executeJavaScript

function executeJavaScript(code: string, window: electron.BrowserWindow = activeWindow()): Promise<any>

Executes code in window.

withCsp

function withCsp(csp: string, session: electron.Session): Promise<void>

Forces the content security policy csp on the session. For some reason, lines in csp must end with a semicolon. Don't ask me why, it's compatibility :)

macPreferences

// This is a bit of a hard type, here's the simplified version:
function macPreferences(pane?: string, section?: string): Promise<void>
// Or if you're a TypeScript geek:

interface SystemPreferencesPanes {
  universalaccess:
    | 'Captioning'
    | 'Hearing'
    | 'Keyboard'
    | 'Media_Descriptions'
    | 'Mouse'
    | 'Seeing_Display'
    | 'Seeing_VoiceOver'
    | 'Seeing_Zoom'
    | 'SpeakableItems'
    | 'Switch';
  security:
    | 'Advanced'
    | 'FDE'
    | 'Firewall'
    | 'General'
    | 'Privacy'
    | 'Privacy_Accessibility'
    | 'Privacy_Advertising'
    | 'Privacy_AllFiles'
    | 'Privacy_Assistive'
    | 'Privacy_Automation'
    | 'Privacy_Calendars'
    | 'Privacy_Camera'
    | 'Privacy_Contacts'
    | 'Privacy_DesktopFolder'
    | 'Privacy_Diagnostics'
    | 'Privacy_DocumentsFolder'
    | 'Privacy_DownloadsFolder'
    | 'Privacy_LocationServices'
    | 'Privacy_Microphone'
    | 'Privacy_Photos'
    | 'Privacy_Reminders'
    | 'Privacy_ScreenCapture';
  speech:
    | 'Dictation'
    | 'TTS';
  sharing:
    | 'Internet'
    | 'Services_ARDService'
    | 'Services_BluetoothSharing'
    | 'Services_PersonalFileSharing'
    | 'Services_PrinterSharing'
    | 'Services_RemoteAppleEvent'
    | 'Services_RemoteLogin'
    | 'Services_ScreenSharing';
}
function macPreferences<Pane extends keyof SystemPreferencesPanes>(pane?: Pane, section?: SystemPreferencePanes[Pane]): Promise<void>

Shows the macOS System Preferences, optionally with pane pane and section section visible.

openUrl

function openUrl(url: string): void

Opens url in the user's browser. Mainly for safe mode where api.shell isn't available.