Introduction

Electron main process functionality module. Provides application lifecycle management (electronApp, createElectron) and window management (getMainWindow, createMainWindow, restoreMainWindow, etc.). All Electron-related APIs are re-exported or wrapped by the framework.

Important

All Electron-related APIs cannot be used in child processes (jobs) or renderer processes. They are only available in the main process.

Import

// CJS
const {
  electronApp,
  createElectron,
  getMainWindow,
  createMainWindow,
  restoreMainWindow,
  setCloseAndQuit,
  getCloseAndQuit,
  loadServer,
} = require('ee-core/electron');

// ESM
import {
  electronApp,
  createElectron,
  getMainWindow,
  createMainWindow,
  restoreMainWindow,
  setCloseAndQuit,
  getCloseAndQuit,
  loadServer,
} from 'ee-core/electron';

Electron App

electronApp

Description: The Electron app module, re-exported for convenience. Provides all standard Electron app APIs. Use electronApp to access paths, names, versions, lifecycle methods, and other standard app module functionality.

Returns: Electron.App — the Electron app module object

Example:

import { electronApp } from 'ee-core/electron';

electronApp.getPath('exe')       // executable path
electronApp.getPath('home')      // user home directory
electronApp.getPath('userData')  // user data directory
electronApp.getName()            // application name
electronApp.getVersion()         // application version
electronApp.isPackaged           // whether packaged
electronApp.whenReady()          // app ready promise

Official documentation: https://www.electronjs.org/docs/latest/api/app

---

createElectron()

Description: Create and start the Electron application. Execution flow:

1. Check single instance lock (config.singleLock=true prevents running multiple instances simultaneously; quits current instance if another is already running)
2. Wait for app.whenReady() to complete
3. Create main window, emit Preload event, load service page, emit ElectronAppReady event
4. Register system event listeners: window-all-closed (quit app on non-macOS), before-quit (clean up cross-process services and child jobs)

Returns: void

Note

This function is called internally by loadElectron() at the end of the Application.run() startup flow. You typically do not need to call it directly.

---

loadElectron()

Description: Load Electron main process functionality. Calls createElectron() to create the application and register system events. Called last by Application.run() in the framework startup flow.

Returns: void

Note

This function is called internally by the framework. It is not typically used directly by application code.

Electron Window

getMainWindow()

Description: Get the main window instance. Returns a BrowserWindow that is guaranteed non-null after the WindowReady lifecycle event.

Returns: BrowserWindow — the main window instance

Throws: Throws Error if called before mainWindow was created (i.e., before WindowReady event). This indicates a lifecycle ordering bug.

Example:

import { getMainWindow } from 'ee-core/electron';

const win = getMainWindow();
win.setSize(800, 600);
win.center();
win.setMenuBarVisibility(false);

Note

Changed from v5: getMainWindow() now returns BrowserWindow (not BrowserWindow | null). No need for null checks after the WindowReady lifecycle event. If called before window creation, it throws an Error indicating a lifecycle ordering bug.

---

createMainWindow()

Description: Create the main application window using config.windowsOption configuration. When openDevTools=true in config, automatically opens developer tools after the page finishes loading. Emits WindowReady lifecycle event after window creation.

Returns: BrowserWindow — the created window instance

Note

This function is called internally by createElectron(). You typically do not need to call it directly unless you are implementing custom window creation logic.

---

restoreMainWindow()

Description: Restore the main window if it is minimized, then show and focus it. Used when a second instance starts (single instance lock scenario) to activate the existing instance's window.

Returns: void

Example:

import { electronApp, restoreMainWindow } from 'ee-core/electron';

electronApp.on('second-instance', () => {
  restoreMainWindow();
});

---

setCloseAndQuit(flag)

Description: Set a flag to control window exit behavior. When flag=true, the application will quit after the window closes. Useful for tray icon scenarios where closing the window should not quit the app.

Parameters:

Parameter	Type	Required	Description
flag	boolean	Yes	true means the app will quit after window closes

Returns: void

Example:

import { getMainWindow, setCloseAndQuit } from 'ee-core/electron';

const win = getMainWindow();
win.on('close', (e) => {
  const closeAndQuit = getCloseAndQuit();
  if (!closeAndQuit) {
    e.preventDefault();
    win.hide(); // hide to tray instead of quitting
  }
});

// When user explicitly wants to quit
setCloseAndQuit(true);

---

getCloseAndQuit()

Description: Get the current close-and-quit flag value. Default is true.

Returns: boolean — the closeAndQuit flag

See also: setCloseAndQuit()

---

loadServer()

Description: Load service page content based on configuration and environment. Selects page loading strategy:

1. Remote mode (config.remote.enable=true) -> Load remote URL directly via loadURL
2. Development environment -> Load frontend dev server (poll to wait for ready), show loading page first, show failure page on timeout
3. Production + cross takeover (config.mainServer.takeover) -> Wait for cross-process service (Go/Python backend) to be ready, then load its URL
4. Production (default) -> Load locally packaged HTML file via loadFile

In dev mode with HTTP URL: shows a loading page (if config.dev.electron.loadingPage is configured), polls the frontend dev server up to 60 retries (3 retries if force=true), and shows a failure page if the server is not reachable.

In cross takeover mode: shows loading page, polls the cross-process service URL, and shows a cross-failure page on timeout.

Returns: Promise<void>

Note

This function is called internally by createElectron(). You typically do not need to call it directly unless implementing custom page loading logic.