Introduction

Framework entry module that initializes the runtime environment and starts the application. Provides the ElectronEgg class (framework bootstrap), EventBus singleton (lifecycle and custom events), Application singleton (startup orchestration), and five lifecycle constants (Ready, ElectronAppReady, WindowReady, BeforeClose, Preload).

Import

// ESM — from top-level entry
import { ElectronEgg, app, eventBus, EventBus, Ready, ElectronAppReady, WindowReady, BeforeClose, Preload } from 'ee-core';
// ESM — from app sub-path
import { ElectronEgg } from 'ee-core/app/boot';
import { eventBus, EventBus, Ready } from 'ee-core/app/events';
import { app, Application } from 'ee-core/app/application';

// CJS — from top-level entry
const { ElectronEgg, app, eventBus, EventBus, Ready } = require('ee-core');
// CJS — from app sub-path
const { ElectronEgg } = require('ee-core/app/boot');
const { eventBus } = require('ee-core/app/events');
const { Application, app } = require('ee-core/app/application');

API

ElectronEgg

Framework main class. Instantiates once in electron/main.js, collects Electron runtime environment info, writes global env variables, and initializes foundational features in a fixed order.

constructor()

Description: Collects environment info and initializes the framework. Execution flow: parse CLI args (env, debugger), resolve directories, build ElectronEggOptions, write key info to process.env, then call init().

Returns: ElectronEgg instance with options property set.

Example:

const electronEgg = new ElectronEgg();
// options.env, options.baseDir, options.electronDir, etc. are now populated

init()

Description: Initialize framework foundational features. Loading order is fixed and must not be changed: loadException → loadConfig → loadDir → loadLog.

Returns: void

register(eventName, handler)

Description: Register a lifecycle event handler. Delegates to app.register() which calls eventBus.register(). If the event name is already registered, the previous handler is overwritten and a warning is logged.

Parameters:

Parameter	Type	Required	Description
eventName	string	Yes	Lifecycle event name: Ready, ElectronAppReady, WindowReady, BeforeClose, or Preload
handler	(...args: unknown[]) => void	Yes	Event handler function; supports async functions

Returns: void

Example:

import { ElectronEgg, BeforeClose } from 'ee-core';

const electronEgg = new ElectronEgg();
electronEgg.register(BeforeClose, async () => {
  // cleanup logic before window closes
  console.log('App is about to close');
});
await electronEgg.run();

See also: EventBus.register

run()

Description: Start the application synchronously. Flow: loadController() (synchronous require()) → loadSocket() → emitLifecycle(Ready) → loadElectron(). Suitable for CJS projects.

Returns: Promise<void>

Example:

const electronEgg = new ElectronEgg();
await electronEgg.run();

runAsync()

Description: Start the application asynchronously. Same flow as run(), but controllers are loaded via dynamic import(). Suitable for ESM projects.

Returns: Promise<void>

Example:

const electronEgg = new ElectronEgg();
await electronEgg.runAsync();

ElectronEggOptions

Type definition for the options property on the ElectronEgg instance. Constructed during framework initialization; values do not change throughout the application lifecycle.

Property	Type	Description
env	string	Runtime environment identifier (e.g. 'dev', 'prod', 'test')
baseDir	string	Project root directory (where package.json is located)
electronDir	string	Electron main process source directory
appName	string	Application name from package.json
userHome	string	User home directory (os.homedir())
appData	string	System-level app data directory
appUserData	string	Electron user data directory (appData/appName)
appVersion	string	Application version from package.json
isPackaged	boolean	Whether packaged as an installer (app.isPackaged)
execDir	string	Executable directory; after packaging points to exe path

---

EventBus

Event bus class that manages lifecycle events and custom events separately. Exported as both the class and a pre-created singleton eventBus.

register(eventName, handler)

Description: Register a lifecycle event handler. Lifecycle events are triggered internally by the framework. If the same event name is already registered, the old handler is overwritten and a warning is logged.

Parameters:

Parameter	Type	Required	Description
eventName	string	Yes	Lifecycle event name (use constants: Ready, ElectronAppReady, WindowReady, BeforeClose, Preload)
handler	(...args: unknown[]) => unknown	Yes	Handler function; sync or async

Returns: void

emitLifecycle(eventName, ...args)

Description: Emit a lifecycle event. Sync handler errors propagate to the caller. Async handler errors are re-thrown as unhandled rejections (caught by the global exception handler).

Parameters:

Parameter	Type	Required	Description
eventName	string	Yes	Lifecycle event name
args	unknown[]	No	Arguments passed to the handler

Returns: void

on(eventName, handler)

Description: Register a custom event handler. Business code can freely define event names and trigger them via emit(). If the event name is already registered, the old handler is overwritten and a warning is logged.

Parameters:

Parameter	Type	Required	Description
eventName	string	Yes	Custom event name
handler	(...args: unknown[]) => unknown	Yes	Handler function; sync or async

Returns: void

Example:

import { eventBus } from 'ee-core';

eventBus.on('customEvent', (payload) => {
  console.log('Received:', payload);
});

emit(eventName, ...args)

Description: Emit a custom event. Both sync exceptions and async rejections from the handler are automatically caught and logged — a single handler error does not affect other logic.

Parameters:

Parameter	Type	Required	Description
eventName	string	Yes	Custom event name
args	unknown[]	No	Arguments passed to the handler

Returns: void

Example:

import { eventBus } from 'ee-core';
eventBus.emit('customEvent', { key: 'value' });

---

eventBus (singleton)

Pre-created EventBus instance, globally shared. Use this singleton directly rather than creating new EventBus instances.

---

Application

Framework startup flow orchestrator. Exported as both the class and a pre-created singleton app.

register(eventName, handler)

Description: Register a lifecycle event handler. Delegates to eventBus.register().

Parameters:

Parameter	Type	Required	Description
eventName	string	Yes	Event name (e.g. 'ready', 'before-close')
handler	(...args: unknown[]) => void	Yes	Handler function

Returns: void

run()

Description: Start the application synchronously. Flow: loadController() → loadSocket() → emitLifecycle(Ready) → loadElectron().

Returns: Promise<void>

runAsync()

Description: Start the application asynchronously. Same flow as run(), but controllers loaded via import().

Returns: Promise<void>

app (singleton)

Pre-created Application instance. Used internally by ElectronEgg; typically not used directly in business code.

---

Lifecycle Constants

Framework milestone event names, used as eventName arguments for register() and emitLifecycle().

Constant	Value	Description
Ready	'ready'	Framework foundational features loaded (controllers, communication services ready)
ElectronAppReady	'electron-app-ready'	Electron app.whenReady() completed
WindowReady	'window-ready'	Main window created
BeforeClose	'before-close'	Before window closes; can be used for cleanup operations
Preload	'preload'	Preload script injection timing

See also: config, controller, socket, electron