Introduction

Configuration module that loads, merges, and provides runtime configuration. Supports two loading modes: bundle mode (reads from globalThis.__EE_CONFIG_REGISTRY__ pre-registered by esbuild) and dev mode (loads from filesystem). Configuration files can export functions that receive an appInfo parameter for dynamic configuration based on environment.

Import

// ESM
import { loadConfig, getConfig, setConfig, getAppInfo } from 'ee-core/config';
// CJS
const { loadConfig, getConfig, setConfig, getAppInfo } = require('ee-core/config');

Note: loadConfig, getConfig, and setConfig are also available from the top-level entry (ee-core), but getAppInfo is only available from the sub-path (ee-core/config).

// Top-level (no getAppInfo)
import { loadConfig, getConfig, setConfig } from 'ee-core';
const { loadConfig, getConfig, setConfig } = require('ee-core');

API

loadConfig()

Description: Load and merge configuration files. Called once during framework startup by ElectronEgg.init(). Uses ConfigLoader to deep-merge framework defaults with business configuration. Loading order: defaultConfig (framework built-in) → config.default (business defaults) → config.{env} (environment-specific overrides).

Parameters: None

Returns: void — Configuration is stored internally and later retrieved via getConfig()

Example:

import { loadConfig } from 'ee-core/config';
loadConfig(); // typically called automatically by ElectronEgg.init()

See also: ElectronEgg.init()

---

getConfig()

Description: Retrieve the final merged runtime configuration object. If configuration has not been loaded yet (e.g. called before loadConfig()), loading is automatically triggered. Typically used after framework startup to read configuration values.

Parameters: None

Returns: Config — Complete runtime configuration object containing all merged settings

Example:

import { getConfig } from 'ee-core/config';

const config = getConfig();
console.log(config.logger.level);    // 'info'
console.log(config.httpServer.port); // 7071
console.log(config.mainServer.protocol); // 'file://'

See also: Config type definition

---

setConfig(cfg)

Description: Set the runtime configuration object directly. Used by child processes to receive configuration from the main process, avoiding filesystem loading which may fail in child processes (e.g. bundle output directory lacks config files). Replaces any previously loaded configuration.

Parameters:

Parameter	Type	Required	Description
cfg	Config	Yes	Complete configuration object to set as the runtime configuration

Returns: void

Example:

import { setConfig } from 'ee-core/config';

// In a child process, receive config from main process via IPC
process.on('message', (msg) => {
  if (msg.type === 'config') {
    setConfig(msg.data);
  }
});

---

getAppInfo()

Description: Retrieve application metadata (name, directories, environment, etc.). Reads values from process.env global variables set by ElectronEgg constructor. This object is passed as the appInfo parameter to configuration file functions, allowing dynamic configuration based on environment.

Parameters: None

Returns: AppInfo — Application metadata object

Property	Type	Description
name	string	Application name
baseDir	string	Project root directory
electronDir	string	Electron source directory
env	string	Runtime environment ('dev' / 'prod' / 'test')
root	string	Log and runtime data root directory (usually appUserData)

Example:

import { getAppInfo } from 'ee-core/config';

const appInfo = getAppInfo();
console.log(appInfo.env);       // 'dev' or 'prod'
console.log(appInfo.baseDir);   // project root path
console.log(appInfo.root);      // data directory path

Example — Using appInfo in a config file:

// electron/config/config.default.js
const path = require('path');
module.exports = (appInfo) => {
  const config = {};
  config.logger = {
    dir: path.join(appInfo.root, 'logs'),
  };
  return config;
};

---

Config Type

The Config interface represents the final merged runtime configuration. It integrates all sub-module configurations and supports dynamic user-defined properties.

Key Sub-Configurations

Property	Type	Description
openDevTools	`boolean	OpenDevToolsOptions`
singleLock	boolean	Single instance lock
windowsOption	BrowserWindowConstructorOptions	Electron BrowserWindow options
logger	LoggerConfig	Pino logging configuration
socketServer	SocketServerConfig	Socket.IO service configuration
httpServer	HttpServerConfig	HTTP (Koa) service configuration
remote	RemoteConfig	Remote service configuration
mainServer	MainServerConfig	Main window content loading configuration
exception	ExceptionConfig	Exception handling configuration
jobs	JobsConfig	Background jobs configuration
cross	CrossConfig	Cross-process configuration

Configuration Loading Pipeline

Bundle mode (production): esbuild plugin scans electron/config/ → generates globalThis.__EE_CONFIG_REGISTRY__ with lazy-loaded modules → ConfigLoader._loadConfig() finds entries by filename → calls config functions with appInfo.

Dev mode (development): ConfigLoader._loadConfig() uses loadFile() to read from filesystem → config.default.js is loaded first → config.local.js (dev) or config.prod.js (prod) overrides → deep-merged via extend().

Default Configuration Values

Framework defaults are defined in default_config.ts and can be overridden by business configuration:

Config Key	Default	Description
openDevTools	false	DevTools disabled by default
singleLock	true	Single instance lock enabled
logger.level	'info'	Minimum log level
logger.rotator	'day'	Daily log rotation
logger.timezone	'UTC'	Log timestamp timezone
socketServer.enable	false	Socket.IO disabled by default
socketServer.port	7070	Socket.IO default port
httpServer.enable	false	HTTP server disabled by default
httpServer.port	7071	HTTP default port
mainServer.protocol	'file://'	Load local file by default
exception.mainExit	false	Main process exceptions do not exit

See also: app, logger, socket, types