npm package: @rubenverg/electron-util
Description: A port of `electron-util` that works in modern Electron
Author: RubenVerg
Latest version: 1.2.0

# @rubenverg/electron-util

An [`electron-util`](https://github.com/sindresorhus/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`

```typescript
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`

```typescript
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`

```typescript
function activeWindow(): electron.BrowserWindow | null
```

Returns the currently focused window.

### `activeWindowOrFirst`

```typescript
function activeWindowOrFirst(): electron.BrowserWindow | null
```

Returns the currently focused window, or the first one (in `BrowserWindow.getAllWindows`) if none is focused.

### <strike>`api`</strike>

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`

```typescript
function centerWindow(options: {
  window?: electron.BrowserWindow,
  size?: electron.Size,
  useFullBounds?: boolean,
  animated?: boolean
})
```

Centers the current window.

### `chromeVersion`

```typescript
const chromeVersion: string
```

Chromium version

### `nativeTheme`

#### <strike>`nativeTheme.isEnabled`</strike>

```typescript
const isEnabled: boolean
```

Is the app in dark mode? (Only available for compatibility, deprecated in favor of `nativeTheme.dark`)

#### `nativeTheme.dark`

```typescript
const dark: boolean
```

Is the app in dark mode?

#### `nativeTheme.highContrast`

```typescript
const highContrast: boolean
```

Is the app in high contrast mode?

#### `nativeTheme.inverted`

```typescript
const inverted: boolean
```

Is the app in inverted colors mode?

#### `onChange`

```typescript
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`

```typescript
function disableZoom(window: electron.BrowserWindow = activeWindow): void
```

Disables zooming `window`.

### `electronVersion`

```typescript
const electronVersion: string
```

Electron version

### `fixPathAsar`

```typescript
function fixPathAsar(path: string): string
```

Fixes the `path` to point to the unpacked Asar if an Asar packed app.

### `getWindowBoundsCentered`

```typescript
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`

```typescript
const macos: boolean
```

Is the current OS macOS?

#### `is.linux`

```typescript
const linux: boolean
```

Is the current OS Linux?

#### `is.windows`

```typescript
const windows: boolean
```

Is the current OS Windows?

#### `is.main`

```typescript
const main: boolean
```

Is this a main process?

#### `is.renderer`

```typescript
const renderer: boolean
```

Is this a renderer process?

#### `is.macAppStore`

```typescript
const macAppStore: boolean
```

Is this a Mac App Store app?

#### `is.windowsStore`

```typescript
const windowsStore: boolean
```

Is this a Windows Store app?

#### `is.usingAsar`

```typescript
const usingAsar: boolean
```

Is this app Asar packaged?

#### `is.development`

```typescript
const development: boolean
```

Is this Electron app in development mode?

### `firstLaunch`

```typescript
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`

```typescript
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`](https://github.com/sindresorhus/new-github-issue-url) for option documentation.

### `urlMenuItem`

```typescript
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`

```typescript
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`

```typescript
function executeJavaScript(code: string, window: electron.BrowserWindow = activeWindow()): Promise<any>
```

Executes `code` in `window`.

### `withCsp`

```typescript
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`

```typescript
// 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`

```typescript
function openUrl(url: string): void
```

Opens `url` in the user's browser. Mainly for safe mode where `api.shell` isn't available.