API reference

Full method-by-method reference for window.Electron, grouped by module — one page per src/main/*.ts file, matching how the source itself is organized (see Architecture). Read this page first: it explains the throwing vs .safe pattern every single method in this API follows, then indexes every module.

If you just want task-oriented examples and the React hooks, see Usage instead — this section is for looking up an exact method signature once you already know what you need.

How every call is built

electron/preload.ts calls createElectronBridge() (src/preload/index.ts), which builds one raw object first — every wrapped method on it resolves to an IpcResult<T> ({ ok: true, data } or { ok: false, error }) and never throws. That raw object is exposed as-is at window.Electron.safe.*. The default, throwing window.Electron.* surface is then derived from that same raw object by two small helpers in src/preload/ipc.ts:

// src/preload/ipc.ts (verbatim)
export function unwrap<T>(promise: Promise<IpcResult<T>>): Promise<T> {
  return promise.then((result) => {
    if (!result.ok) throw new IpcError(result.error.code, result.error.message);
    return result.data;
  });
}

export function unwrapAll<T extends object>(ns: T): UnwrapIpcResult<T> {
  /* wraps every method on ns with unwrap() */
}

export function unwrapSome<T extends object>(ns: T, keys: readonly (keyof T)[]): UnwrapIpcResult<T> {
  /* wraps only the named methods; everything else on ns is copied through as-is */
}

No method body is ever hand-duplicated between the two flavors — window.Electron.clipboard.readText() and window.Electron.safe.clipboard.readText() call the exact same main-process handler over the exact same IPC channel (clipboard:readText). The only difference is what happens to a { ok: false } result on the way back to your code:

Use the throwing default when a failure is exceptional and you're fine with a try/catch (or letting it bubble to an error boundary / onElectronError). Reach for .safe when a failure is a normal branch you want to check inline — the two most common cases are NOT_CONFIGURED (a feature you haven't turned on yet) and UNSUPPORTED_OS (a platform-gated method):

// Throwing default — try/catch
import { isIpcError } from '@devioarts/electron';

try {
  await window.Electron.autoLaunch.setEnabled(true);
} catch (e) {
  if (isIpcError(e) && e.code === 'UNSUPPORTED_OS') return; // expected on Linux
  throw e;
}

// .safe mirror — no try/catch, just check result.ok
const result = await window.Electron.safe.autoLaunch.setEnabled(true);
if (!result.ok) {
  if (result.error.code === 'UNSUPPORTED_OS') return; // expected on Linux
  console.error(result.error.message);
}

Both forms are always available side by side — .safe is not a config flag or a different bridge, it's the same window.Electron object with a safe property hanging off it.

Not every method has a .safe counterpart

A handful of methods are plain event subscriptions or fire-and-forget calls that can never fail in a way worth reporting — they have no IpcResult, and therefore no .safe variant, because there is nothing to unwrap either way. Calling them is inherently "safe": onDeepLink, onShortcut, onMenuAction, onPowerMonitorEvent, onScreenEvent, onElectronError, onAppStateChange, and updater.quitAndInstall(). These exist only on the default window.Electron.* surface (updater.on() is the one exception — see the Updater page — it's also mirrored onto .safe.updater.on() as the literal same function, since it never throws either).

Per-namespace .safe coverage

Some namespaces are fully wrapped (every method has a .safe twin); some are partially wrapped (the namespace mixes request/response methods with an on() event subscriber — only the request/response methods have a .safe twin, since subscribers never throw to begin with):

Error codes

Every IpcError (thrown) or IpcResult.error (from .safe) carries a machine-readable code: IpcErrorCode:

Modules

Next: Usage for the React hooks and extending the bridge, or Configuration for what to set in electron.config.ts to unlock the opt-in modules above.